improve/rewrite man page and README - saait - the most boring static page generator
HTML git clone git://git.codemadness.org/saait
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
DIR commit 26cef250bc4609edcc5663540f3e4055738ca06b
DIR parent 82f2448a5181411d61e4763f45e1dfdbe6e8092b
HTML Author: Hiltjo Posthuma <hiltjo@codemadness.org>
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(-)
---
DIR 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 <.
+
+ # 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 example
+ 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 navigation menu
+ 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 *.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.
+
+ 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 <hiltjo@codemadness.org>
- $ 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/
DIR 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 <.
+.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 hiltjo@codemadness.org