Introduction
Introduction Statistics Contact Development Disclaimer Help
improve/rewrite man page and README - saait - the most boring static page gener…
git clone git://git.codemadness.org/saait
Log
Files
Refs
README
LICENSE
---
commit 26cef250bc4609edcc5663540f3e4055738ca06b
parent 82f2448a5181411d61e4763f45e1dfdbe6e8092b
Author: Hiltjo Posthuma <[email protected]>
Date: Sun, 5 Jan 2020 14:10:51 +0100
improve/rewrite man page and README
add a step-by-step usage example to create a site.
Diffstat:
M README | 238 +++++++++++++++++++++++------…
M saait.1 | 203 +++++++++++++++++++++++++++++…
2 files changed, 374 insertions(+), 67 deletions(-)
---
diff --git a/README b/README
@@ -1,12 +1,12 @@
saait
-----
-the most boring static page generator
+The most boring static page generator.
Meaning of saai (dutch): boring
Pronounciation: site
-Some parts are intentionally hardcoded, C knowledge is required.
+Some parts are intentionally hardcoded in C for simplicity.
Build and install
@@ -19,102 +19,214 @@ $ make
Dependencies
------------
-- C compiler (C99), tested on gcc, clang.
+- C compiler (C99), tested on gcc and clang.
- libc
- POSIX make (optional).
+- mandoc for documentation: https://mdocml.bsd.lv/ (optional).
Tested and works on
-------------------
- OpenBSD
-- Linux (glibc)
-- Windows (mingw and cygwin)
+- Linux (glibc).
+- Windows (mingw and cygwin).
-Structure
----------
+Documentation
+-------------
-Directory structure for pages:
+See the man page of saait(1).
-- pages/file1.html
-- pages/file1.cfg
+Man page
+--------
-Directory structure for templates:
+NAME
+ saait the most boring static page generator
-- templates/<templatename>/item.ext
-- templates/<templatename>/header.ext
-- templates/<templatename>/footer.ext
+SYNOPSIS
+ saait [-c configfile] [-o outputdir] [-t templatesdir] pages...
-The files are saved as output/<templatename>.ext
+DESCRIPTION
+ saait writes HTML pages to the output directory.
-the templatename "page" is special and will be used per page.
+ The arguments pages are page .cfg files, which are processed in the given
+ order.
-otherwise the directory name is used as the output file, for example
-templates/atom.xml/templatefiles* will be: output/atom.xml
+ The options are as follows:
-the following filename prefixes for template blocks are detected:
+ -c configfile
+ The global configuration file, the default is "config.cfg". Each
+ page configuration file inherits the values from this file. The
+ values can be overwritten per page.
-"header." - header block.
-"item." - item block
-"footer." - footer block.
+ -o outputdir
+ The output directory, the default is "output".
-If a filename does not exist then the template block is not processed and will
-have the same result as an empty file.
+ -t templatesdir
+ The templates directory, the default is "templates".
+DIRECTORY AND FILE STRUCTURE
+ A recommended directory structure for pages, but the names can be
+ anything:
+ pages/001-page.cfg
+ pages/001-page.html
+ pages/002-page.cfg
+ pages/002-page.html
-Cfg file and template syntax
-----------------------------
+ The directory and files structure for templates must be:
+ templates/<templatename>/header.ext
+ templates/<templatename>/item.ext
+ templates/<templatename>/footer.ext
-Special variables set:
-htmlfile (if not already set) path to input HTML content filename.
-filename (can be overwritten) basename of output content HTML file.
+ The following filename prefixes are detected for template blocks and
+ processed in this order:
-Special variables used:
-index if set to 0 then don't list this page as an item for the
- templates except for the "page" template. This can be used to hide
- a page from the index.html and Atom feed.
+ "header."
+ Header block.
-Variables:
-${} escaped HTML/XML string.
-#{} literal string.
-%{} insert contents of file of variable value.
+ "item."
+ Item block.
+ "footer."
+ Footer block.
-Usage
------
+ The files are saved as output/<templatename>, for example
+ templates/atom.xml/* will become: output/atom.xml . If a filename does
+ not exist then the template block is not processed and will be the same
+ result as if it was an empty file.
+
+ Hidden template directories (starting with ".") are ignored.
+
+ The templatename "page" is special and will be used per page.
+
+CFG FILE
+ A .cfg file has a simple key=value configuration syntax, for example:
+
+ # an example page.
+ filename=example.html
+ title=Example page
+ description=This is an example page
+ created=2009-04-12
+ updated=2009-04-12
+
+ The following variables names are special with their respective default
+ values:
+
+ filename
+ The relative file path of the output HTML file for this page.
+ The path is relative to the outputdir.
+
+ htmlfile
+ Path to the input HTML content filename, by default this is the
+ path of the .cfg file with .cfg replaced to .html.
+
+ index If set to 0 then this page is not processed for templates except
+ for the "page" template. This can be used to hide pages from
+ templates such as index.html or from listing in an Atom feed.
+
+ A line starting with # is ignored and can be used as a comment.
+
+TEMPLATE SYNTAX
+ The variables set in a .cfg file can be used inside templates, but not
+ pages.
+
+ The possible operators for variables are:
+
+ $ Escapes a XML string, for example: < to the entity &lt;.
+
+ # Literal raw string value.
+
+ % Insert contents of file of the value of the variable.
+
+ For example in a HTML template:
+
+ <article>
+ <header>
+ <h1><a href="">${title}</a></h1>
+ <p>
+ <strong>Last modification on </strong>
+ <time datetime="${updated}">${updated}</time>
+ </p>
+ </header>
+ %{htmlfile}
+ </article>
+
+EXIT STATUS
+ The saait utility exits 0 on success, and >0 if an error occurs.
+
+EXAMPLES
+ A basic usage example:
+
+ 1. Create a directory for a new site:
+
+ mkdir newsite
+
+ 2. Copy the example pages, templates, global config file and exa…
+ stylesheets to a directory:
+
+ cp -r pages templates config.cfg style.css print.css newsite/
+
+ 3. Change the current directory to the created directory.
+
+ cd newsite/
+
+ 4. Adjust the values in the global config.cfg file which provides
+ defaults for all pages.
+
+ 5. If you want to modify parts of the header, like the navigatio…
+ items, you can change the following two template files:
+ templates/page/header.html
+ templates/index.html/header.html
+
+ 6. Create any new pages in the pages directory. For each …
+ there has to be a corresponding *.html file with the same basename.
+ They have to be placed in the same folder. Optionally they can be
+ overridden with the special variable "htmlfile". See the copied
+ example pages in this directory.
+
+ 7. Create an output directory:
+
+ mkdir -p output
+
+ 8. After any modifications the following commands can be used to
+ generate the output and process the pages in descending order:
+
+ find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
+
+ 9. Copy the modified stylesheets to the output directory also:
+
+ cp style.css print.css output/
+
+ 10. Open output/index.html locally in your webbrowser to review the
+ changes.
-1. Adjust the global config.cfg file which provides defaults for all pages.
-2. Call saait from a directory that is providing a config.cfg and a
- templates folder. Those are included in the source, so simply call it from
- the source directory.
-3. For each *.cfg file there has to be a corresponding *.html file with the
- same basename. They have to be placed in the same folder.
- optionally they can be overridden with the special variable "htmlfile".
-4. Saait is called naming an output directory and providing one or more *.cfg
- files as parameters.
-5. Modify the following two template files, in order to change the items
- displayed in the header (Blog, Git, Github, etc...):
+ 11. To synchronize files, you can securely transfer them via SSH using
+ rsync:
- templates/page/header.html
- templates/index.html/header.html
+ rsync -av output/ user@somehost:/var/www/htdocs/
+ Below is an example to use saait with Markdown. A possible method could
+ be to just convert the Markdown to HTML and to run saait after that as
+ usual.
-Usage examples
---------------
+ In this example it uses smu for the Markdown processor, available at:
+ https://github.com/Gottox/smu :
-this is a basic example:
+ cd pages
+ for f in *.md; do
+ smu -n < "$f" > "$(basename "$f" .md).html"
+ done
- $ saait -o /path/to/www /path/to/001-example.cfg
+TRIVIA
+ The most boring static page generator.
-this is an example for how it's used in practice and for many pages:
+ Meaning of saai (dutch): boring, pronunciation of saait: site
- $ saait -o /path/to/www /path/to/*.cfg
+SEE ALSO
+ find(1), sort(1), xargs(1)
-or:
+AUTHORS
+ Hiltjo Posthuma <[email protected]>
- $ mkdir -p output
- $ find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
- $ cp style.css print.css output/
- $ rsync -av output/ user@somehost:/var/www/htdocs/
diff --git a/saait.1 b/saait.1
@@ -1,17 +1,212 @@
-.Dd Nov 14, 2016
+.Dd January 5, 2020
.Dt SAAIT 1
.Os
.Sh NAME
.Nm saait
-.Nd static web page generator
+.Nd the most boring static page generator
.Sh SYNOPSIS
.Nm
.Op Fl c Ar configfile
.Op Fl o Ar outputdir
-.Op Fl t Ar templatedir
+.Op Fl t Ar templatesdir
.Ar pages...
.Sh DESCRIPTION
.Nm
-writes static HTML pages to the output directory.
+writes HTML pages to the output directory.
+.Pp
+The arguments
+.Ar pages
+are page .cfg files, which are processed in the given order.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl c Ar configfile
+The global configuration file, the default is "config.cfg".
+Each page configuration file inherits the values from this file.
+The values can be overwritten per page.
+.It Fl o Ar outputdir
+The output directory, the default is "output".
+.It Fl t Ar templatesdir
+The templates directory, the default is "templates".
+.El
+.Sh DIRECTORY AND FILE STRUCTURE
+A recommended directory structure for pages, but the names can be anything:
+.Bl -tag -width Ds -compact
+.It pages/001-page.cfg
+.It pages/001-page.html
+.It pages/002-page.cfg
+.It pages/002-page.html
+.El
+.Pp
+The directory and files structure for templates must be:
+.Bl -tag -width Ds -compact
+.It templates/<templatename>/header.ext
+.It templates/<templatename>/item.ext
+.It templates/<templatename>/footer.ext
+.El
+.Pp
+The following filename prefixes are detected for template blocks and processed
+in this order:
+.Bl -tag -width Ds
+.It Qo "header." Qc
+Header block.
+.It Qo "item." Qc
+Item block.
+.It Qo "footer." Qc
+Footer block.
+.El
+.Pp
+The files are saved as output/<templatename>, for example
+templates/atom.xml/* will become: output/atom.xml .
+If a filename does not exist then the template block is not processed and will
+be the same result as if it was an empty file.
+.Pp
+Hidden template directories (starting with ".") are ignored.
+.Pp
+The templatename "page" is special and will be used per page.
+.Sh CFG FILE
+A .cfg file has a simple key=value configuration syntax, for example:
+.Bd -literal
+# an example page.
+filename=example.html
+title=Example page
+description=This is an example page
+created=2009-04-12
+updated=2009-04-12
+.Ed
+.Pp
+The following variables names are special with their respective default values:
+.Bl -tag -width Ds
+.It filename
+The relative file path of the output HTML file for this page.
+The path is relative to the
+.Ar outputdir .
+.It htmlfile
+Path to the input HTML content filename, by default this is the path of
+the .cfg file with .cfg replaced to .html.
+.It index
+If set to 0 then this page is not processed for templates except for the
+"page" template.
+This can be used to hide pages from templates such as index.html or from
+listing in an Atom feed.
+.El
+.Pp
+A line starting with # is ignored and can be used as a comment.
+.Sh TEMPLATE SYNTAX
+The variables set in a .cfg file can be used inside templates, but not pages.
+.Pp
+The possible operators for variables are:
+.Bl -tag -width Ds
+.It $
+Escapes a XML string, for example: < to the entity &lt;.
+.It #
+Literal raw string value.
+.It %
+Insert contents of file of the value of the variable.
+.El
+.Pp
+For example in a HTML template:
+.Bd -literal
+<article>
+ <header>
+ <h1><a href="">${title}</a></h1>
+ <p>
+ <strong>Last modification on </strong>
+ <time datetime="${updated}">${updated}</time>
+ </p>
+ </header>
+ %{htmlfile}
+</article>
+.Ed
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+A basic usage example:
+.Bl -enum
+.It
+Create a directory for a new site:
+.Bd -literal
+mkdir newsite
+.Ed
+.It
+Copy the example pages, templates, global config file and example
+stylesheets to a directory:
+.Bd -literal
+cp -r pages templates config.cfg style.css print.css newsite/
+.Ed
+.It
+Change the current directory to the created directory.
+.Bd -literal
+cd newsite/
+.Ed
+.It
+Adjust the values in the global config.cfg file which provides defaults for
+all pages.
+.It
+If you want to modify parts of the header, like the navigation menu items,
+you can change the following two template files:
+.Bl -item -compact
+.It
+templates/page/header.html
+.It
+templates/index.html/header.html
+.El
+.It
+Create any new pages in the pages directory.
+For each *.cfg file there has to be a corresponding *.html file with the same
+basename.
+They have to be placed in the same folder.
+Optionally they can be overridden with the special variable "htmlfile".
+See the copied example pages in this directory.
+.It
+Create an output directory:
+.Bd -literal
+mkdir -p output
+.Ed
+.It
+After any modifications the following commands can be used to generate the
+output and process the pages in descending order:
+.Bd -literal
+find pages -type f -name '*.cfg' -print0 | sort -zr | xargs -0 saait
+.Ed
+.It
+Copy the modified stylesheets to the output directory also:
+.Bd -literal
+cp style.css print.css output/
+.Ed
+.It
+Open output/index.html locally in your webbrowser to review the changes.
+.It
+To synchronize files, you can securely transfer them via SSH using rsync:
+.Bd -literal
+rsync -av output/ user@somehost:/var/www/htdocs/
+.Ed
+.El
+.Pp
+Below is an example to use
+.Nm
+with Markdown.
+A possible method could be to just convert the Markdown to HTML and to
+run
+.Nm
+after that as usual.
+.Pp
+In this example it uses smu for the Markdown processor, available at:
+.Lk https://github.com/Gottox/smu
+:
+.Bd -literal
+cd pages
+for f in *.md; do
+ smu -n < "$f" > "$(basename "$f" .md).html"
+done
+.Ed
+.Sh TRIVIA
+The most boring static page generator.
+.Pp
+Meaning of saai (dutch): boring, pronunciation of saait: site
+.Sh SEE ALSO
+.Xr find 1 ,
+.Xr sort 1 ,
+.Xr xargs 1
.Sh AUTHORS
.An Hiltjo Posthuma Aq Mt [email protected]
You are viewing proxied material from codemadness.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.