(This file was last written for SBWG version 0.9.0. SBWG and 
its README are works in progress. The list of features and other details may have been changed by now.)

SBWG (steeph's bash website generator) is a bash script that generates a static HTML website from raw text files.

SBWG is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar.
See http://www.wtfpl.net/txt/copying/ for more details.

# Features

* Generates static HTML structure from a source file structure
* Simple image galleries
* Weblog/Blog generation
    * Categorised posts with multiple levels
    * Blog entries can be additionally categorised as topics for an index view
    * Classical blog view, filterable by category, topic, author, language or author AND one of the others
    * Support for multi-author weblogs with the option to split off entries from single authors into separate weblog sites
    * Attached image galleries
* Stylesheet templates
* Modifications/Additions to the generation process on a per-web-site basis with hooks and a sourced settings file
* Easy staging
* Simple RSS feed


## Feature Ideas And Requested Features

I will work on these when I'm satisfied with the state of the current feature set and have some time.

* Audio attachements/postcast support, audio player
* Video attachement support
* Video support in galleries
* Support for more image file formats
* Easy image embedding, entry images
* Directory structure in the source directories (directory trees for entries and pages)
* ATOM feeds and multiple RSS feeds for single tags, categories or topics
* Interactive use of the script
* Parallel processing in the generation process
* Caching of once generated web site data, option to only generate new content/skip generating cached content
* Interactive setup script
* Easier management of menu items
* Generating of web books


The following feature ideas and requests have been decided against. They will not be implemented by me any time soon or any time soon after soon.

* Generate gopher hole and/or gemini capsule at the same time as a web site.
    - They are too different and deserve a different, much simpler generator script if one is needed at all.

* SBWG specific tags in content, e.g. for embedding image files, linking to entries on the same site.
    - This would require parsing the content of entry files, which is a line in complexity of the script that I'm not willing to cross. Everything that could be
      done with custom tags like in web bulletin boards would also be possible with regular HTML. I choose to keep it simple in that case.

* Cut off the content of entries when they are displayed on a tagpage. Click "Read More" or the title to view the whole entry on an individual page.
    - This would leave HTML tags that are opened before the cutoff point but closed after it, opened on tagpages. Fixing this problem would go against the idea of
      not parsing the content of entry files.

* Templates for the HTML structure or an option/setting for different levels of HTML granularity.
    - This would add a huge amount of flexability and eliminate the problem that either the script itself has to edited or relatively complicated hooks and overwrite
      functions have to be used to make some customisations to the generated HTML structure. But it would also add a great amount of complexity. It is not worth it
      for a script that is still mainly for generating my own web site. You can do a great deal with hooks in a site's settings file. And you actually can edit the
      script to customise HTML output or replace a function with your own version by overwriting it in the site's settings file if you want.


## Known Issues And Bugs

* The script is written in bash, which is not a good choice for such a project. This will not be fixed.
* Parallelisation (option -P/--parallel) is experimental and not really functional yet.
* Force mode (option -F/--force) might be necessary to force the script to continue despite suspected problems that aren't actually problems.


# Installation

You can get the latest published version from https://log.steeph.de/SBWG.html

There is currectly no setup script. Installation is straightforward though if you understand how SBWG works. **There are short instructions in the INSTALL file** if
not. **Those install instructions are sufficient to get started.** The README file (yes, this one here) contains complete descriptions of SBWGs functionality. So,
if you just want to quickly set up a web site using the example web site as a starting point, head over the the INSTALL file now. If you want to know more than you
need to know to get started, read on.

After installation of SBWG and during setting up/editing of a web site you might find useful tips in the HOWTO file.


## Requirements:

* bash 4 (This script is not tested with other shells.)
* imagemagick (or compatible `convert`; only needed for image gallery generation)
* This file does not go into installing a web server. SBWG only generates web sites. It does not make them accessible over a network. Please refer to instructions on
  how to install a web server for your operating system.
* The style sheets included in the example website make use of CSS 3. This is not an issue. I just thought I better mention it.
* The same goes for the generated HTML, which assumes HTML 5 support.
* Coreutils


## Setting Up The Script

* Extract the package to a location outside of your web root
* Move the files to a directory in PATH or add the SBWG directory path to your PATH.
* Check if the file 'sbwg' (and optionally the file 'genentry') is executable, make it executable if it is not already.


## Setting Up A New Web Site

The steps necessary to create a new web site depend very much on what you wish your web site to be. SBWG is sort of flexible. You can change variables and add your
own code on a per-website basis in the 'settings' file of a web site. But you don't have to get into the details of what SBWG can do and how it works, exactly.
If you have never created a web site with SBWG before, I recommend to copy the 'example' directory and make changes to the copied example according to your
requirements/wishes.


### Setting Up A New Web Site From The Example Template

The 'example' directory included in this package contains the complete source for a web site with a couple of pages, blog, a gallery and some other files. All of
the following steps are technically optional. Omitting one will simply mean that whatever you didn't set/change will stay as it was set for the example web site.
 
* Copy the 'example' directory to a suitable location, e.g. ~/my_website
* Edit the 'settings' file to change your website's title, url/domain name, style template choice, default output directory, etc.
* If you have not changed the default output directory, create a symlink called 'html' to point to your web root.
* Edit the 'footer' file to include any HTML code that you want to be included at the bottom of every generated HTML page.
* Edit or replace the logo.svg file with you web site's logo.
* Place any other miscellaneous files needed by your web site in the 'files' directory.
* Create or edit CSS files in the 'styles' directory according to your wishes. Which files are used is determined by the 'style=' setting in the settings file.
* Create and/or edit files in the 'pages' directory for "static" web pages not related to a weblog.
* Create blog entries in the 'entries' directory. You can use the 'genentry' script, write files from scratch or use a template file that you have filled with
    header lines that you regularly use.
* Add galleries in the 'galleries' directory, one directory per gallery. Simplyt place JPEG and PNG files in these directories.
* Run 'sbwg --complete' or 'sbwg -c' to create the HTML website in the default output directory with its default settings. Use the '-o'/'--output' option to
    specify a different output directory, e.g. for testing/a non-public preview.


### Setting Up A New Web Site From Scratch

If you've copied the example directory, you're fine and you don't need all these details described below. You may skip reading any or all of them.

Setting up a new web site source directory from scratch is something that is not currently explained well and complete in any of the help files. I suggest you
just copy the example or parts from it or look at how the example does things. Below I'll explain what a SBWG web site source directory consists of and what
settings and features exist, though. That should help if you really want to do it from scratch. It isn't complicated. It's just a matter of knowing what's what.


# (Files And Directories Of) A Web Site Source Directory

The following files and directories can be used to build a web site with SBWG. All except the `settings` file are optional. That means if there are no pages, no
galleries and no entries the scriipt will just prepare for generating an empty web site and may (depending on the contents of the settings file) actually produce
output in the output directory. Files and directories that are not listed below will simply be ignored by the script.


## settings

The `settings` file must exist in order for SBWG to recognise the directory as a SBWG web site source directory. SBWG will refuse to generate the website if this
file isn't there and it will assume that there is a valid SBWG web site source structure in the same directory if the file exists.

You can use the file to inject any Bash code that should be executed before the web site is generated. Commonly it is only used to set a few global variables and
declare hooks (see the "Hooks" section below). You can copy the settings file from the example directory or peek at it for explanations of the settings that should
be set for any new web site. I suggest that you include at least the 'sitename' and 'url' settings. There are more settings worth knowing about. Have a look at the
settings file in the example directory or see the short descriptions of all settings further down in this file under "Settings".


## files

The `files` directory can be used to store random and miscellaneous files that you would like to be publicly available. These can be JavaScript files used by the
web site, image files that you use somewhere in the site's content, files that you want to link to to be downloaded, or anything else really.

The directory just get copied to the output directory when generating the web site. This means that, unless prevented by web server settings, anything in this
directory will become publicly available on the resulting web site.


## header

The 'header' file does not exist in this version of SBWG. If it exists, it is ignored. The head section of the generated HTML pages can be influenced by using a
hook. (see the "Hooks" section below)


## footer

The contents of this file gets appended to every generated HTML file. The file has to end with:

  </body>
</html>

Before that you can put anything that should appear at the end of every HTML page. For example a `<footer>` tag with a copyright notice.

This file will likely be replaced by a hook in the future. But in this version it is still used and has to close the `<body>` and `<html>` tags. Without this file
(and the closing tags for body and html) the generated HTML will not be valid. (Although it would probably work in the most used browsers.)


## styles

There can be several files in this directory that can belong to one or more style sets. Depending on the settings and command line options one or more of these
files may be copied to the output directory and linked in every HTML file's head when the web site is generated. (See the "Styles" section below for more information
on style sets and custom CSS changes.)


## pages

This directory contains the web site's page source files, meaning content that will be turned into HTML and is not part of the weblog or galleries.


## entries

This directory contains the source files for the entries that make up the web site's weblog. If there will be no weblog on the site, the directory should be empty.
But please note that SBWG was made for creating a web site with a weblog and generating a site without any entries may currently still create empty heading and place
useless links in the generated HTML.

Subdirectories inside the `entries` directory are currently not supported. This is a feature on the todo list though.

An entry source file is basically just a text file with the contents of the blog entry in HTML. A simple text file with one or multiple lines is a valid entry source
file. But usually an entry source file consists of a source file header and the entry's content. The header can consist of one or many tags of different types,
specifying e.g. the entry's title, author, creation date and the categories and topics it's filed in. Please see the sections "Blog Entries" and "Tags" below for a
description of how the source file header and tags work. The important tag types are used in the blog entries that are contained in the example web site. Looking at
the headers of those entries is probably enough to get started.


## tagicons

In this dorectory you can place icons that should be displayed in place of tags in entries' headers. The file name has to be `tagtype:tagname.png`.


## html

By default this is the output directory if no other output directory was specified either in the web site's settings file or through the command line option
`--output` (`-o`). It is recommended to replace this directory with a symbolic link to your webserver's webroot. But this depends entirely on your preferences. By
default the generated website is placed in this directory. If it is not accessible by the webserver at the same time then you'll habe to copy it over manually in
order to publish the web site.

If a different directory is used as the output directory (see the sections "Settings" and "Generating a web site" below) then this directory is not needed.


# Settings

A setting in a web sites `settings` file is just a global variable that's set for the script before generating the web site. Therefore a setting can be set by
writing the setting name followed by a `=` followed by the value in an otherwise empty line. There may be no blank before or after the `=`. Values with some special
characters (e.g. spaces) have to be quoted (encloded in `"`s).

Examples:

`sitename="ExSite (The Example Web Site)"`
The Name of the web site needs to have a `"` before and one after in this case, because it contains spaces. Otherwise, an error will occur.

`thumbsize=200`
The value `200` does not contain any special characters. Therefore no `"` is needed. It doesn't matter whether the value is enclosed in them or not.

All settings are optional. If a setting is not set in the settings file, a default value is used. The following variables/settings are meant to be set in the
settings file. Additional settings can be declared in the same way if they don't have the same name as an existing global variable. Those additional variables can
then be used in hooks. (See the "Hooks" section below.)

`sitename` - The name/title of the website as displayed in the header and used in the browser window title bar/browser tabs.

`url` - The url is used when external documents that link to the web site are generated, e.g. the RSS feed.

`style` - The name of the style set that should be used if none is specified by command line option. See the "Styles" section below to learn which files this will include.

`odir` - The path of the output directory.
 
`thumbsize` - The maximum width and height of gallery image thumbnails when attached to blog entries.

`thumbsizemini` - The maximum width and height of gallery image thumbnails on gallery pages.

`previewsize` - The maximum width and height of gallery image previews as displayed on gallery pages. This should be large enough to view the image in full but doesn't need to be too large as the original image file will be linked for the case that somebody wants to download the full resolution.

`perpage` - The maximum number of entries that will be included in one HTML page when generating tagpages. When there are more entries that belong on the tagpage, it is devided into several HTML pages and a pager is added at the bottom.

`tagiconsize` - This setting is currently ignored. You may do the same with this line.

`duals` - This setting is currently ignored. You may do the same with this line.

`details` - This setting is obsolete and will be ignored by the script. You may do the same with this line.

`exclude` - This setting is currently ignored. You may do the same with this line.


## Hooks

A hook is a function that is declared in the settings file of a web site. It does not exist in the SBWG script and therefore is not executed if it is not included
in the settings file. No hook is required. There are many hooks that get executed at different points in the generation of a web site. Therefore they can be used to
inject code at certain points of the script for only the web site who's settings file contains the hook. This way the script does not need to be edited for
customisation and different web sites can be customised differently.

Inside a hook all variables that exist at the point at which the hook is executed can be read and changed. Output can be added to the file that is being generated at
that point, additional commands can be executed, and so on. This makes the settings file a very flexible tool for the customisation of a web site and SBWG itself,
and a possible source of errors when not used carefully.

When writing an elaborate new hook (as opposed to copying an example hook or hook from an existing settings file) you will probably not be able to avoid reading at
least some of the SBWG script to see how your goal can be accomplished. There are a couple of helper functions in the script that of course can also be used in
hooks, too. I will not explain here every part of the code that could possibly be of relevance when writing a new hook. I don't know what you want to do with you
hook, so I wouldn't know what to limit myself to.

The below table lists all hooks that currently exist in SBWG and the local variables that are accesible inside these hooks. Additionally there are a couple of
global variables that are accessible from inside every hook:

* `$shellbase` - The path of the input directory - The directory of the web site that is being generated
* `$tmpdir` - The path of the temporary directory - This directory will be deleted after the script is done or when it fails.
* `$version` - The version of SBWG that is processing the website
* `$options` - A string of option letters that are set through command line options
* `$entrylist` - An array that contains all entry names that exist on the web site. Only available after the navigation bar has started to be generated.
* `$entrylists` - An associative array with all existing tag names as keys and lists of entry names as values. Only available after tagpage preparation.
* `$tagslist` - An array that contains all existing tags. Only available after the navigation bar has started to be generated.
* `$gallerylist` - An array that contains the names of all galleries on this web site that contain any supported image files. Only available after navbar generation.
* `$desired_entry` - The entry name, if one was passed to option -e (or --entry).
* `$desired_page` - The page name, if one was passed to option -p (or --page).
* `$desired_tagpage` - The name of the tagpage, if one was passed to option -t (or --tagpage).
* `$desired_gallery` - The name of the gallery, if one was passed to option -g (or --gallery).
* All variables that are declared in the settings file as well as the default values for settings that are not set in the settings file

   ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
   ┃ Function Name                      │ Called                                             │ Available Local Variables            │ Usage Examples                ┃
   ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
   ┃ hook_error                         │ When a fatal error has occured                     │ $@   The error message (usually just │ Clean-up before exit          ┃
   ┃                                    │ After the error message has been printed           │        one string, so $1)            │ Send out a notification       ┃
   ┃                                    │ Before the temporary directory gets cleared        │ $str The error message in one string │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_redirect                      │ When an HTML file is created that redirects to     │ $1 Path of created HTML file         │ Additional file operations    ┃
   ┃                                    │ another URL, before the file is written            │ $2 Relative path of target           │   related to HTML redirection ┃
   ┃                                    │                                                    │                                      │   (e.g. file system links)    ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_prepare                       │ After all preparations have been made              │ -                                    │ Create or copy files idepen-  ┃
   ┃                                    │ Before anything gets generated                     │                                      │   dantly of what SBWG will do ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_files                         │ When and after the web site's files directory gets │ -                                    │ Copy additional files when-   ┃
   ┃                                    │ copied from the source directory to the output dir │                                      │   ever SBWG copies files dir  ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_head                          │ When the head portion of an HTML file is generated │ $outfile  The HTML file that is cur- │ Inject tags into the HTML     ┃
   ┃                                    │ After the hardcoded tags in the <head> tag         │             rently being generated   │   <head> tag (e.g. link JS)   ┃
   ┃                                    │ Before the <head> tag is closed                    │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_start                   │ When an entry page gets generated                  │ $outfile  The HTML file that is cur- │ Additional preparations of an ┃
   ┃                                    │ After the entry file has been checked              │             rently being generated   │   entry before any HTML is    ┃
   ┃                                    │ After tags have been extracted from the entry file │ $entry    Name of the current entry  │   generated                   ┃
   ┃                                    │ Before any tags are processed                      │ $tags     List of the entry's tags   │                               ┃
   ┃                                    │ Before anything gets written to the HTML file      │ $author   Name of the entry's author │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_title_start             │ When an entry page gets generated                  │ See hook above.                      │ Inject HTML at the beginning  ┃
   ┃                                    │ Inside (at the beginning of) the title wrapper     │                                      │   of the title-wrapper of an  ┃
   ┃                                    │ After the title wrapper tag has been opened        │                                      │   entry page                  ┃
   ┃                                    │ Before the title and meta-information are printed  │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_title_tags_before       │ When an entry page gets generated                  │ See hook above.                      │ Inject HTML at the beginning  ┃
   ┃                                    │ Inside the title wrapper                           │ Additionally:                        │   of the tags in the title-   ┃
   ┃                                    │ After the created (and edited) date(s) are printed │ $created  The entry's created date v.│   wrapper of an entry page    ┃
   ┃                                    │ Before the tags are printed                        │ $edited   It's edited date value     │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_title_tag_before        │ When a tag gets printed inside the title wrapper   │ See hook above.                      │ Inject HTML before certain or ┃
   ┃                                    │   of an entry page                                 │ Additionally:                        │   all tags in the title-      ┃
   ┃                                    │ Before it was checked whether it is a tag that     │ $tag    The currently processed tag  │   wrapper of an entry page    ┃
   ┃                                    │   will be printed or not                           │                                      │                               ┃
   ┃                                    │ Before the its surrounding HTML tags are printed   │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_title_tag_after         │ When a tag gets printed inside the title wrapper   │ See hook above.                      │ Inject HTML after certain or  ┃
   ┃                                    │   of an entry page                                 │ Additionally:                        │   all tags in the title-      ┃
   ┃                                    │ After the tag has been printed                     │ $tag    The currently processed tag  │   wrapper of an entry page    ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_title_tags_after        │ When an entry page gets generated                  │ Same as three hooks above.           │ Inject HTML at the end of the ┃
   ┃                                    │ After the tags have been printed                   │   (hook_entry_title_tags_before)     │   tags in the title-wrapper   ┃
   ┃                                    │ Before the title wrapper is closed                 │                                      │   of an entry page            ┃
   ┃                                    │ Before the content is printed                      │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_before                  │ When an entry page gets generated                  │ Same as six hooks above.             │ Inject HTML at the beginning  ┃
   ┃                                    │ After the title wrapper is printed and closed      │   (hook_entry_start)                 │   of the content of the       ┃
   ┃                                    │ After the content div is opened                    │                                      │   content of an entry on the  ┃
   ┃                                    │ After the reference lines (if any) have been been  │                                      │   entry page                  ┃
   ┃                                    │   printed                                          │                                      │                               ┃
   ┃                                    │ Before the entry content is printed                │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_after                   │ When an entry page gets generate                   │ See hook above.                      │ Inject HTML at the end of the ┃
   ┃                                    │ After the entry content is printed                 │                                      │   content of an entry on the  ┃
   ┃                                    │ Before the content div is closed                   │                                      │   entry page                  ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entry_end                     │ When an entry page gets generated                  │ See hook above.                      │ Additional file operations    ┃
   ┃                                    │ After everything concerning this entry is done and │                                      │   after an entry page has     ┃
   ┃                                    │   the HTML file is completed and closed            │                                      │   been generated that don't   ┃
   ┃                                    │                                                    │                                      │   afftect generation          ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entries_start                 │ When generating entries                            │ -                                    │ Additional operations per-    ┃
   ┃                                    │ Before any entry has been generated or prepared    │                                      │   formed if and before any    ┃
   ┃                                    │                                                    │                                      │   entry pages are generated   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_entries_end                   │ When generating entries                            │ -                                    │ Additional operations per-    ┃
   ┃                                    │ After all entries have been generated/completed    │                                      │   formed if and after all     ┃
   ┃                                    │                                                    │                                      │   entry pages are generated   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_start                 │ When a gallery page gets generated                 │ $outfile  The HTML file that is cur- │ Additional changes or other   ┃
   ┃                                    │ After gallery generation has been prepared         │             rently being generated   │   preparations of the gallery ┃
   ┃                                    │ After the gallery has been checked                 │ $gallery  Name of the gallery that is│   before it is processed      ┃
   ┃                                    │ Before anything gets written to the HTML file      │             currently being generated│                               ┃
   ┃                                    │                                                    │ $images   List of file names of all  │ Exclude certain images con-   ┃
   ┃                                    │                                                    │             images in this gallery   │   ditionally, e.g. based on   ┃
   ┃                                    │                                                    │ $tags     If there is a corrospon-   │   file names                  ┃
   ┃                                    │                                                    │             ding entry: list of all  │                               ┃
   ┃                                    │                                                    │             tags of that entry       │ Add something to the gal-     ┃
   ┃                                    │                                                    │ $title    If there is a corrospon-   │   lery's title if its corros- ┃
   ┃                                    │                                                    │             ding entry: Entry's title│   ponding entry source file   ┃
   ┃                                    │                                                    │                                   l  │   contains a certain tag      ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_before                │ When a gallery page gets generated                 │ See hook above.                      │ Add text to the header of the ┃
   ┃                                    │ After the navigation bar and page header have been │                                      │   gallery above its thumb-    ┃
   ┃                                    │   generated                                        │                                      │   nails                       ┃
   ┃                                    │ Before the image thumbnails are written to the     │                                      │                               ┃
   ┃                                    │   HTML file                                        │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_image_before          │ When an image is placed in a gallery page          │ See hook above.                      │ Change from where the the     ┃
   ┃                                    │ After the image file has been checked              │ Additionally:                        │   file/which image file is    ┃
   ┃                                    │ Before the image preview is placed in the HTML file│ $image   Path and file name of the   │   embedded in the gallery     ┃
   ┃                                    │                                                    │            currently processed image │   (e.g. change the default    ┃
   ┃                                    │                                                    │ $img     Its file name without path  │   preview to a CDN source)    ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_image_after           │ When an image is placed in a gallery page          │ See hook above.                      │ Inject additional text or a   ┃
   ┃                                    │ After the image preview has been placed in the     │                                      │   link below all images or    ┃
   ┃                                    │   HTML file                                        │                                      │   certain images e.g. based   ┃
   ┃                                    │ Before the "Go to top" link is placed in the file  │                                      │   on the gallery title/name   ┃
   ┃                                    │                                                    │                                      │   or image file name          ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_after                 │ When a gallery page gets generated                 │ Same as three hooks above.           │ Add a footer to all or to     ┃
   ┃                                    │ After the last image has been placed in the        │   (hook_gallery_before)              │   certain galleries           ┃
   ┃                                    │   generated HTML output file                       │                                      │                               ┃
   ┃                                    │ Before the main section is closed and the footrer  │                                      │                               ┃
   ┃                                    │   printed to the generated HTML output file        │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_gallery_end                   │ When a gallery page gets generated                 │ See hook above.                      │ Additional image modifi-      ┃
   ┃                                    │ After the gallery page HTML file has been finished │                                      │   cations after the fact      ┃
   ┃                                    │ After everything conserning this gallery is done   │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_galleries_start               │ When image galleries are generated                 │ -                                    │ Additional operations before  ┃
   ┃                                    │ Before it gets decided which galleries will be     │                                      │   any gallery is generated    ┃
   ┃                                    │   generated                                        │                                      │                               ┃
   ┃                                    │ Before any of the galleries have been checked,     │                                      │ Modify the list of list of    ┃
   ┃                                    │   prepared or generated                            │                                      │   galleries before processing ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_galleries_end                 │ When image galleries are generated                 │ -                                    │ Additional operations to be   ┃
   ┃                                    │ After every gallery has been generated             │                                      │   performed if any galleriies ┃
   ┃                                    │                                                    │                                      │   are/have been generated     ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_start                    │ When a SBWG page gets generated                    │ $outfile  The HTML file that is cur- │ Modify the tags or content of ┃
   ┃                                    │ After the page file has been checked               │             rently being generated   │   the pge that is about to    ┃
   ┃                                    │ After tags have been extracted from the page file  │ $tags     List of the page's tags    │   be generated                ┃
   ┃                                    │ Before any tags are processed                      │ $title    The page's title if tag set│                               ┃
   ┃                                    │ Before anything gets written to the HTML file      │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_title_before             │ When a SBWG page gets generated                    │ See hook above.                      │ Inject HTML right before the  ┃
   ┃                                    │ If the page has a title tag                        │                                      │   title of a page if it was   ┃
   ┃                                    │ After the header and navigation bar have been      │                                      │   defined by a tagline        ┃
   ┃                                    │   added to the generated output file               │                                      │                               ┃
   ┃                                    │ Right before the title gets printed on the page    │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_title_after              │ When a SBWG page gets generated                    │ See hook above.                      │ Append text to the title of a ┃
   ┃                                    │ If the page has a title tag                        │                                      │   page if its title was de-   ┃
   ┃                                    │ Right after the title gets printed on the page     │                                      │   fined by a tagline          ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_content_before           │ When a SBWG page gets generated                    │ See hook above.                      │ Add text right before the     ┃
   ┃                                    │ Right before the content gets printed on the page  │                                      │   content of a page           ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_content_after            │ When a SBWG page gets generated                    │ See hook above.                      │ Add text right adfter the     ┃
   ┃                                    │ Right after the content gets printed on the page   │                                      │   content of a page           ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_page_end                      │ When a SBWG page gets generated                    │ See hook above.                      │ Additional operations after   ┃
   ┃                                    │ After everything concerning this page has been     │                                      │   a page's HTML file has been ┃
   ┃                                    │   done                                             │                                      │   generated                   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_pages_start                   │ When SBWG pages are generated                      │ -                                    │ Modify the list of pages that ┃
   ┃                                    │ Before any pages are prepared or generated         │                                      │   are about to be generated   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_pages_end                     │ When SBWG pages are generated                      │ -                                    │ Additional operations after   ┃
   ┃                                    │ After all pages have been generated                │                                      │   pages have been generated   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_start                  │ Before any HTML pages are generated                │                                      │ IDK TBH                       ┃
   ┃                                    │ If any HTML pages will be generated in this run    │                                      │                               ┃
   ┃                                    │ When the navigation bar is generated               │                                      │                               ┃
   ┃                                    │ Before any preparations for the navigation bar     │                                      │                               ┃
   ┃                                    │   generation have been done                        │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_before                 │ When the navigation bar is generated (once per     │ $outfile  Path of the navbar file in │ Add links to the beginning of ┃
   ┃                                    │   run of the script)                               │             the temporary directory  │   the nabigation bar          ┃
   ┃                                    │ After the <nav> tag has been opened                │             during the generation of │ Add HTML before the first     ┃
   ┃                                    │ Before anything gets printed to the navigation bar │             the navigation bar       │   navigation/menu item/link   ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_item_before            │ When the navigation bar is generated (once per     │ See hook above.                      │ Inject HTML at the beginning  ┃
   ┃                                    │   run of the script)                               │ Additionally:                        │   of every link in the menu/  ┃
   ┃                                    │ For each tag that occurs at least once in an entry │ $item   Tag that is currently being  │   naviation bar               ┃
   ┃                                    │ Before the tag type has been checked               │           processed (e.g. "cat:foo") │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_item_after             │ When the navigation bar is generated (once per     │ See hook above.                      │ Inject HTML after every menu  ┃
   ┃                                    │   run of the script)                               │                                      │   item/link in the navigation ┃
   ┃                                    │ For each tag that occurs at least once in an entry │                                      │   bar.                        ┃
   ┃                                    │ After the tag type has been checked and the tag    │                                      │                               ┃
   ┃                                    │   been processed if of a tag type that is included │                                      │                               ┃
   ┃                                    │   in the navigation bar by default                 │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_item_change            │ When the navigation bar is generated (once per     │ See hook above.                      │ Add a link at the end of a    ┃
   ┃                                    │   run of the script)                               │                                      │   list of items in the navi-  ┃
   ┃                                    │ For the last tag of each tag type that occurs at   │                                      │   gation bar (e.g. add custom ┃
   ┃                                    │   least once in an entry                           │                                      │   item/link in the link list  ┃
   ┃                                    │   least once in an entry                           │                                      │   category items              ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_galleries_before       │ When the navigation bar is generated (once per     │ Same as four hooks above.            │ Modify the list of galleries  ┃
   ┃                                    │   run of the script)                               │   (hook_navbar_before)               │   before it's used for the    ┃
   ┃                                    │ After all tags have been processed                 │                                      │   first time (e.g. add/remove ┃
   ┃                                    │ Right before the list of galleries is generated    │                                      │   galleries conditionally)    ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_gallery_before         │ When the navigation bar is generated (once per     │ See hook above. Additianlly:         │ Add HTML right before all or  ┃
   ┃                                    │   run of the script)                               │ $gallery  Name of the currently      │   certain gallery links in    ┃
   ┃                                    │ Before a gallery gets printed to the output file   │             being added to the list  │   the gallery link list in    ┃
   ┃                                    │                                                    │             in the navigation bar    │   the navigation bar          ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_gallery_after          │ When the navigation bar is generated (once per     │ See hook above.                      │ Add HTML right after all or   ┃
   ┃                                    │   run of the script)                               │                                      │   certain gallery links in    ┃
   ┃                                    │ After a gallery gets printed to the output file    │                                      │   the gallery link list in    ┃
   ┃                                    │                                                    │                                      │   the navigation bar          ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_galleries_after        │ When the navigation bar is generated (once per     │ Same as six hooks above.             │ Inject an additional link at  ┃
   ┃                                    │   run of the script)                               │   (hook_navbar_before)               │   the end of the list of gal- ┃
   ┃                                    │ After the list of galleries has been printed to    │                                      │   lery links in the navi-     ┃
   ┃                                    │   the generated HTML output file                   │                                      │   gation bar                  ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_after                  │ When the navigation bar is generated (once per     │ See hook above.                      │ Inject HTMl at the end of the ┃
   ┃                                    │   run of the script)                               │                                      │   navigation bar              ┃
   ┃                                    │ After all content that is included in the          │                                      │                               ┃
   ┃                                    │   navigation bar by default has been added to it   │                                      │ Add custom links after all    ┃
   ┃                                    │ Before the <nav> tag is closed                     │                                      │   others in the navigation bar┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_navbar_end                    │ When the navigation bar is generated (once per     │ See hook above.                      │ Execute additional commands   ┃
   ┃                                    │   run of the script)                               │                                      │   once per run if HTML output ┃
   ┃                                    │ After everything concerning the navigation bar     │                                      │   is generated                ┃
   ┃                                    │   generation has been processed                    │                                      │ Parse/alter navigation bar    ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_start                 │ When a tagpage is generated                        │ $outfile    Path of the tagpage HTML │                               ┃
   ┃                                    │ After the output file has been checked             │               file that is currently │                               ┃
   ┃                                    │ Before anything gets written to the generated      │               being generated        │                               ┃
   ┃                                    │  tagpage HTML output file                          │ $tag        Name of the tag for which│                               ┃
   ┃                                    │                                                    │               the tagpage is cur-    │                               ┃
   ┃                                    │                                                    │               rently being generated │                               ┃
   ┃                                    │                                                    │ $lastentry  Number of entries that   │                               ┃
   ┃                                    │                                                    │               are included on this   │                               ┃
   ┃                                    │                                                    │               tagpage                │                               ┃
   ┃                                    │                                                    │ $lastpage   Number of additional     │                               ┃
   ┃                                    │                                                    │               pages if this tagpage  │                               ┃
   ┃                                    │                                                    │               will have a pager/more │                               ┃
   ┃                                    │                                                    │               than one HTML page     │                               ┃
   ┃                                    │                                                    │ $pagecount  Number of the page that  │                               ┃
   ┃                                    │                                                    │               is currently being     │                               ┃
   ┃                                    │                                                    │               processed (out of      │                               ┃
   ┃                                    │                                                    │               $lastpage pages)       │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_before                │ When a tagpage is generated                        │ See hook above. Additionally:        │                               ┃
   ┃                                    │ After the heade and navigation bar of the          │ $secs    List of tags for which      │                               ┃
   ┃                                    │   generated HTML page have been generated          │            combined tagpages will    │                               ┃
   ┃                                    │ Right after the content <div> tag is opened        │            be generated (if any)     │                               ┃
   ┃                                    │ Before thr content of the tagpage is written       │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_top_before      │ When a topic tagpage is generated                  │ See hook above. Additionally:        │                               ┃
   ┃                                    │ Inside the title-wrapper div                       │ $entrycount   Number of the entry    │                               ┃
   ┃                                    │ Before the title of an entry is printed to HTML    │                 is currently being   │                               ┃
   ┃                                    │                                                    │                 processed (out of    │                               ┃
   ┃                                    │                                                    │                 $lastentry pages)    │                               ┃
   ┃                                    │                                                    │ $tags         List of all tag lines  │                               ┃
   ┃                                    │                                                    │                 of the currently     │                               ┃
   ┃                                    │                                                    │                 processed entry      │                               ┃
   ┃                                    │                                                    │ $author       Name of the author     │                               ┃
   ┃                                    │                                                    │                 of the current entry │                               ┃
   ┃                                    │                                                    │ $target       Name of an entry the   │                               ┃
   ┃                                    │                                                    │                 current entry will   │                               ┃
   ┃                                    │                                                    │                 redirect to (if any) │                               ┃
   ┃                                    │                                                    │ $entryname    Name of the cuttently  │                               ┃
   ┃                                    │                                                    │                 processed entry      │                               ┃
   ┃                                    │                                                    │ $created      Created date value of  │                               ┃
   ┃                                    │                                                    │                 the current entry    │                               ┃
   ┃                                    │                                                    │ $edited       Edited date value of   │                               ┃
   ┃                                    │                                                    │                 the current entry    │                               ┃
   ┃                                    │                                                    │ $title        Title of the current-  │                               ┃
   ┃                                    │                                                    │                 ly processed entry   │                               ┃
   ┃                                    │                                                    │ $sortby       Sort value of the      │                               ┃
   ┃                                    │                                                    │                 current entry        │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_top_after       │ When a topic tagpage is generated                  │ See hook above.                      │                               ┃
   ┃                                    │ Inside the title-wrapper div                       │                                      │                               ┃
   ┃                                    │ After the created and edited dates have been       │                                      │                               ┃
   ┃                                    │   printed to the generated HTML file               │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_title_before    │ When a tagpage (not topic tagpage) is generated    │ See hook above.                      │                               ┃
   ┃                                    │ For each entry that on this tagpage except for     │                                      │                               ┃
   ┃                                    │   stickied entries                                 │                                      │                               ┃
   ┃                                    │ Inside the title-wrapper div                       │                                      │                               ┃
   ┃                                    │ Before the entry's title is written to the HTML    │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_title_after     │ When a tagpage (not topic tagpage) is generated    │ See hook above.                      │                               ┃
   ┃                                    │ For each entry that on this tagpage except for     │                                      │                               ┃
   ┃                                    │   stickied entries                                 │                                      │                               ┃
   ┃                                    │ Inside the title-wrapper div                       │                                      │                               ┃
   ┃                                    │ After the entry's title is written to the HTML     │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_stickied        │ When a tagpage (not topic tagpage) is generated    │ See hook above.                      │                               ┃
   ┃                                    │ For each stickied entry on this tagpage            │                                      │                               ┃
   ┃                                    │ Before the entry's content is printed to the HTML  │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_content_before  │ When a tagpage (not topic tagpage) is generated    │ See hook above.                      │                               ┃
   ┃                                    │ Inside the entry-content-wrapper div               │                                      │                               ┃
   ┃                                    │ Before the entry's content is printed to the HTML  │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_entry_content_after   │ When a tagpage (not topic tagpage) is generated    │ See hook above.                      │                               ┃
   ┃                                    │ Inside the entry-content-wrapper div               │                                      │                               ┃
   ┃                                    │ After the entry's content is printed to the HTML   │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_after                 │ When a tagpage is generated                        │ Same as eight hooks above.           │                               ┃
   ┃                                    │ After all entries have been added to the generated │   (hook_tagpage_before)              │                               ┃
   ┃                                    │   HTML file in the output directory                │                                      │                               ┃
   ┃                                    │ Before content <div> tag has been closed           │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpage_end                   │ When a tagpage is generated                        │ See hook above.                      │                               ┃
   ┃                                    │ After all entries concerning this tagpage have     │                                      │                               ┃
   ┃                                    │   been processed                                   │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpages_entry                │ When tagpage generation is prepared                │ $entry    Name of entry currently    │ Influence tagpage sorting by  ┃
   ┃                                    │ For each entry that exists on the web site         │             being examined           │   changing $sortby of entries ┃
   ┃                                    │ After the entry source file has been checked       │ $tags     List of all tags of the    │                               ┃
   ┃                                    │ After some meta information has been retrieved     │             currently examined entry │                               ┃
   ┃                                    │   from the entry's tags                            │ $created  Created date value of the  │                               ┃
   ┃                                    │ After the entry's sorting value has been determined│             currently examined entry │                               ┃
   ┃                                    │ Before all tags have been checked                  │ $edited   Edited date value of the   │                               ┃
   ┃                                    │ Before the entry is assigned to any tagpage        │             currently examined value │                               ┃
   ┃                                    │ Before any tagpages get generated                  │ $author   Name of the author of the  │                               ┃
   ┃                                    │                                                    │             currently examined entry │                               ┃
   ┃                                    │                                                    │ $sortby    Sort value of the         │                               ┃
   ┃                                    │                                                    │             currently examined entry │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpages_start                │ When tagpages get generated                        │ -                                    │                               ┃
   ┃                                    │ After tagpage generation has been prepared         │                                      │                               ┃
   ┃                                    │ Before it is determined chich tagpages to generate │                                      │                               ┃
   ┃                                    │ Before any tagpages get generated                  │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_tagpages_end                  │ When tagpages get generated                        │ -                                    │                               ┃
   ┃                                    │ After all tagpagges that are generated in this run │                                      │                               ┃
   ┃                                    │   of the script have been completely generated     │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_rss_start                     │ When an RSS file gets generated                    │ $outfile    Path of the RSS file     │                               ┃
   ┃                                    │ Before anything is concerning the RSS feed         │               being generated        │                               ┃
   ┃                                    │ Before the RSS file is generated                   │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_rss_channel                   │ When an RSS file gets generated                    │ See hook above.                      │ Restrict which entries will   ┃
   ┃                                    │ After the blog's meta information have been added  │                                      │   be included (e.g. number    ┃
   ┃                                    │ Before any entries are added to the feed           │                                      │   of entries in the feed)     ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_rss_entry                     │ When an RSS file gets generated                    │ See hook above. Additionally:        │ Change the entry's name for   ┃
   ┃                                    │ For each entry that is added to the feed           │ $entry      URL of the entry file    │   the RSS feed.               ┃
   ┃                                    │ Before any data concerning this entry is added     │ $entryname  Name of the entry (file) │                               ┃
   ┃                                    │                                                    │ $tags       Newline separated list   │ Change how entries with no    ┃
   ┃                                    │                                                    │               of tags of the cur-    │   content are displayed in    ┃
   ┃                                    │                                                    │               rently processed entry │   RSS feeds.                  ┃
   ┃                                    │                                                    │ $author     Name of the author of    │                               ┃
   ┃                                    │                                                    │               the currently pro-     │ Determine how entries with no ┃
   ┃                                    │                                                    │               cessed entry           │   specified author (no author ┃
   ┃                                    │                                                    │ $title      Title of the currently   │   tag line) are displayed in  ┃
   ┃                                    │                                                    │               processed entry        │   the RSS feed.               ┃
   ┃                                    │                                                    │ $pubdate    Created date of the cur- │                               ┃
   ┃                                    │                                                    │               rently processed en-   │ Exclude certain entries from  ┃
   ┃                                    │                                                    │               try, Edited date if no │   the RSS feed e.g. based on  ┃
   ┃                                    │                                                    │               create date exists for │   tags or content.            ┃
   ┃                                    │                                                    │               the currently pro-     │                               ┃
   ┃                                    │                                                    │               cessed entry, $pubdate │                               ┃
   ┃                                    │                                                    │               is in RFC 2822 format; │                               ┃
   ┃                                    │                                                    │               The entry is omitted   │                               ┃
   ┃                                    │                                                    │               if pubdate does not    │                               ┃
   ┃                                    │                                                    │               start with a number    │                               ┃
   ┃                                    │                                                    │ $content    Content of the cuttently │                               ┃
   ┃                                    │                                                    │               processed entry        │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_rss_end                       │ When an RSS file gets generated                    │ See hook above.                      │ Add additional content        ┃
   ┃                                    │ After the last entry has been added to the feed    │                                      │   (channels, items/entries)   ┃
   ┃                                    │ Before the <rss> tag is closed                     │                                      │                               ┃
   ┠────────────────────────────────────┼────────────────────────────────────────────────────┼──────────────────────────────────────┼───────────────────────────────┨
   ┃ hook_end                           │ After everything that is generated in this run of  │ -                                    │ Perform additional operations ┃
   ┃                                    │   of the script has been done                      │                                      │   on the final product        ┃
   ┃                                    │ Before cleanup (removal of temporary files)        │                                      │ Send out a notification       ┃
   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Because the settings file is sourced in the script after all functions have been declared, you could also overwrite a function to replace it with a custom version
of yours without editing the script file itself.


# Styles

The styles directory can contain several style sheet sets that are independent of each other. When generating a web site only one of these sets is used. By default
the style "style" is used unless a different style is specified either in the web site's settings file (see "Settings" section below) or through the command line
option `--style` (`-s`). That means that by defult all CSS files with a name starting with "style-"... and ending in ".css" as well as the file "style.css" will be
linked in the header of every generated HTML file. For example the following files will all be used if they exist:
style.css
style-colours.css
style-mobile.css
style-anything-that-you-want.css

If you want to make custom changes to the default style cheet, you can either edit the existing style.css or add a file named style-custom.css or similar.

If you want to create your own style set, you can specify its name in your web site's setting file or pass it with the --style option upon generation.

Example file names: If your style is set as "my_style" then the files
my_style.css
my_style-sidebar.css
my_style-awesomeness.css
my_style-something.css

and so on, will be linked in the header of every generated HTML file headers.

If you would like to link a CSS file on some but not all HTML file's headers or insert internal CSS into the header, you can use the hook `hook_head`. (See the
"Hooks" section above.)


# Pages

A page in SBWG terminology is a file consisting of a title and content, that will be turned into an HTML file but not linked to from other generated files
automatically. Typical uses for pages are the index page, a contact page, about page or any other HTML page that has to contain the header, sidebar, menu and footer
but is not part of the weblog. The page source files are placed in the `pages` directory in the web site's source directory. Each file represents one page. Their
filenames may not contain any characters that can not be used in URLs (reserved characters or otherwise problematic characters) or non-printable characters (newline,
NULL bytes, ...). Spaces are fine, though. Please note that if you use different file systems for the source directory, output directory, temporary directory or the
web server, no filename may be longer than the longest allowed filename on the file system with the shortest allowed filename minus five characters (for '.html'
extension).

It is recommended to at least have a file named `index` in this directory. It will be turned into an HTML page and placed as "index.html" in the root of the output
directory so that it will be the default index page if not specified otherwise by webserver settings. Respectively, all other text files that are directly in the
`pages` directory are turned into HTML files and placed directly in the output directory. It is currently not possible to have pages generated into subdirectories.
This is on the todo list though.

A page does not have to contain a source file header as it is recommended for entries (see the "entries" section below). But if a page source file starts with a line
that starts with `title:`, that title will be used as the heading. For example if the first line of a file in the `pages` directory is

`title:This Is The Tilte But It Has A Typo`

then the generated HTML page will turn that line into an `<h2>` heading. In the future, more tag types for page files will be added. But right now `title:` is the
only one.

## Example Of A Page Source File

    title:Interesting Title
    
    <p>This is just an example.</p>


# Blog Entries

Blog entries are stored in the `entries` directory of the web site. Each file represents one blog entry. Their filenames may not contain any characters that can not
be used in URLs (reserved characters or otherwise problematic characters) or non-printable characters (newline, NULL bytes, ...). Spaces are fine, though. Please
note that if you use different file systems for the source directory, output directory, temporary directory or the web server, no filename may be longer than the
longest allowed filename on the file system with the shortest allowed filename minus five characters (for '.html' extension).

An entry source file consists of a header and content. Both are technically optional. That means that any text file can be an entry file, too. The header of an entry
source file is made up of various tags that provide metadata to the entry, like the name of the author, the date when the entry was created, the categories it is
filed under, and so on. An entry file without a header will be included in the weblog view of the generated web site. But since there are no information about where
the entry should be placed, linked and sorted in the weblog, it is recommended to provide some basic information in each entry source file header.

The header ends where the content (lines of text that are not tags) starts. Everything below the header will be used as the content of the entry. The content part
will be copied to the generated HTML page un-parsed. You can use HTML tags in the content.


## Example Of An Entry Source File

    note:This tag can be used to make a note for readers of the source file.
    title:Interesting Blog Entry
    created:2021-05-05
    author:foobär
    cat:Example Entries
    top:Interesting Things
    cat:Another Category
    
    <p>This is the example entry's content. The paragraph tags are not necessary. Any HTML that belongs in an HTML body can be used here. All the above tags are
    optional. Their order does not matter. Multiple category (cat:) and topic (top:) tags can be used. The "Tags" section in the README file for more information
    about tags.</p>


## Tags

Tags assign meta information to an entry or page, such as their title, creation date, categories or the name of the author of an entry. They are written one per
line at the beginning of an entry or page source file. (See the sections "Blog Entries" and "Pages" above.)

All tags are optional. Some tag types are useful to use multiple times in a single entry header, others can only occur once. Some tag types you will rarely use and
some probably never. The section "Tags Types" below lists and explains all tag types that SBWG knows. If you use a tag that is not listed below, it will be ignored
by SBWG. But too many lines of non-existant tag types will make it look to the script like they are not part of the header anymore. In that case they and every
following line will be considered part of the page's/entry's content.

A tag line starts with the tag type, followed by a colon (":"), followed by the value of the tag. There may be no space before or directly after the colon. The value
of a tag can contain spaces and some other special characters, though. The value of a tag may not contain a colon, except when it is used to assign sub-tags. See
below for more forbidden characters and considerations for unwise characters in SBWG tags.

### Tag Value Limitations

Some characters are not allowed in tag values, due to different reasons, founded in both the way the script processes and saves the content and by the way the result
will be handled (web browsers). The maximum allowed length of file names and paths differs on different  file systems. If you don't know the limitations of the file
system(s) that you are/will be using or if you can't be sure which file systems will be used for generating or serving a web site in the future, use the general rule
of keeping tag values short and without special characters.

Not allowed in any tag type are: `:` (colon), the NULL byte and the newline character (Unicode U+000A).

In the tag types `cat:`, `top:`, `lang:` and `author:` `+` (plus sign), `#` (hash sign), `?` (question mark), `%` (percent sign), any characters that can not be part
of a URL or a file name on any file system that will be used by the script (that includes the input directory, the output directory ans the temprary directory) or
the web server must be avoided.

For file systems typically used by Linux and MacOS systems, avoid the `/` (slash) character additionally to the characters already named above. For Windows file
systems several common special characters are forbidden. Additionally some words are forbidden as file names in Windows. For a list of allowed/forbidden characters
and words please refer to the revant documentation or specifications depending on the system you are using. SBWG will add `.html` at the end of generated file names
of tagpages and the name of a second tag for combined tagpages. That means that, for example, for ext file systems with a maximum file name length of 255 bytes, the
longest allowed value of `author` tags is 118 bytes and for `top` tags 119 bytes if combined tag pages are generated. If the longest tag value of one of those tag
types is shorter, the other one can use longer values.

Several characters are to be avoided because they can or will cause problems when used in a URI/URL. Those problems can occur in different use cases of the URI and
the rules for problematic characters are deeper than I'm willing to explain here. For more information, see the Internet Engineering Tast Force's memo "Uniform
Resource Identifier (URI): Generic Syntax" (RFC3986) at https://datatracker.ietf.org/doc/html/rfc3986 (additionally older version RFC2396 at
https://datatracker.ietf.org/doc/html/rfc2396 if you want to serve old and obsolete client software). Please note that some webbrowsers may not be able to access
pages with URLs with non-prontable chracters and old browsers have trouble with characters that do not belong to the original set of accepted characters (unicode
emoticons and umlauts for examples).

If you want to be sure for all sorts of systems both of the server and client side, only use alphanumeric characters for `top:`, `cat:`, `author:` and `lang:` tags
and keep them short.


### Tag Types

The following tag types can be used in header of pagge source files as well as entry source files.

`note:`
This tag has no function. It is a valid tag but it is ignored by SBWG. It can be used to include a note in an entry or page source file header.
Example: `note:This is just a note.`

`title:`
The title of the entry or page
Example: `title:An Interesting Title`

`menu:`
This tag type does not exist, yet. It will be used in future versions of SBWG to place an entry (or page) at a certain point in a menu.
Example: `menu:Main:About:History` (not yet implemented)

The following tag types can only be used in entry source file headers.

`created:`
The date at which the entry was first created. Any string is accepted. Any numerical date format in descending order works for sorting of entries as long as every
entry uses the same format. It is recommented to use the ISO style date formt YYYY-MM-DD.
Example: `created:2020-12-29`

`edited:`
The date at which the entry has been edited last. This is not updated automatically unless you use an editor that edits the line automatically. Any string is
accepted. Any numerical date format in descending order works for sorting of entries as long as every entry uses the same format. The value overwrites the created
date in sorting entries. It is recommented to use the ISO style date formt YYYY-MM-DD.
Example: `edited:2021-05-05`

`sort:`
A value that overwrites both the edited and the created date in sorting entries. The value is not displayed. Values from edited: and created: will be ignored when a
sort: tag is present. It is recommented to use the ISO style date formt YYYY-MM-DD when the sort tag is used to place an entry in between other entries that use
the same format for created/edited dates. If numerical values are used for created and edited dates, then a sort value that starts with a letter will sort an entry
on top of the blog view. If the value of a sort: tag starts with "about" or "stick" then the entry's title-wrapper is not included in the output file. This can be
used to create stickied entrys (paragraphs that are displayed above all entries on certain tagpages). See the "Sorting" section below for more details.
Example: `sort:stickied` will place the entry content (without meta information) above all other, non-stickied, content on the tagpages of every cat: tag that is
included in the header.

`cat:`
A category the entry will be filed under. An entry can have any number of category tags.
Example: `cat:Dogs` marks an entry that contains something relating to dogs. A tagpage that lists all entries with this tag will be generated.

`top:`
A topic that is adressed by this entry. An entry can have multiple topics and/or sub-topics. A sub-topic is assigned by adding another colon after a topic name, 
followed by the sub-topic name. Topic tagpages are indexes of entries with a specific topic tag or a sub-topic tag of that topic tag.
Example: `top:Science:Mathematics` will include the entry's title in the topic tagpages/indexes "Science" and "Science:Mathematics".

`lang:`
The language the entry is written in. Any string is accepted. You can use `lang:en` or `lang:English` or `lang:ENG` or whatever you like, as long as entries of the
same language use the same tag. Only one language tag per entry is allowed.
Example: `lang:gr` tags an entry as being written in Greek.

`author:`
The name of the author of the entry. If only one person is adding entries to the web site then it is best to ignore this tag type and not include it in any entry
header. Every author name that is used in at least one entry will be listed in the navigation bar to offer to display only entries written by this author.
Example: `author:Nickname7000`

`re:`
The name of an entry this entry is connected to. Includes a note at the top of the entry, linking to the entry named in the re: tag.
Example: `re:some_entry` links the entry that has this tag to the entry with the filename "some_entry".

`ref:`
The name of an entry this entry is referring to. Includes a note at the top of the entry, linking to the entry named in the ref: tag.
Example: `ref:entry0815` links the entry that has this tag to the entry with the filename "entry0815".

`reply:`
The name of an entry this entry is a reply to. Includes a note at the top of the entry, linking to the entry named in the reply: tag.
Example: `reply:Some Questions` links the entry that has this tag to the entry with the filename "Some Questions".

`redirect:`
The name of an entry this entry will redirect to. The content below the entry header will not be displayed on the web site (but will still be included in the RSS
feed). Visitng this entry's page will redirect the browser to the entry with the file name in the redirect: tag. On tagpages the entry will be substituted with the
entry it is redirecting to. This can for example be used to link multiple galleries to the same entry by creating dummy entries with the names of the galleries.
Example: `redirect:some_entry`


## Tagpages

A tagpage is an HTML page generated by SBWG that lists all entries that contain a certain tag. Tagpages are created for every `cat:`, `top:`, `lang:` and `author:`
tag that occures in at least one entry. If there is at least one entry that contains an author tag then combined tagpages for author+category are created, too.
Combined tagpages list all entries that contain two specific tags. For example the tagpage for `author:foobär+cat:wildlife` lists all entries authored by foobär that
are also tagged with cat:wildlife. If there are more entries with a certain tag than what is set for the `perpage` value in the settins file then the generated HTML is split into multiple files and a pager is placed at the bottom of the list. A link for every ggenerated tagpage is placed in the Topic list in the
navigation bar.

Tagpages for `cat:`, `top:` and `lang:` tags include the whole entries including its meta information above the content. The entries' `created:`, `edited:` and
`sort:` tags determine how the entries are sorted on the tagpage. Newer entries are places higher than entries with an older created or edited date. A `sort:`
tag can overwrite those values. (See the "Tag Types" section above and the "Sorting" section below.)

Taggpages for `top:` tags don't include
the content of the entries. They only list their titles and dates, serving as an automatically generated index for the topic. Topic tagpages include entries that
are tagged with that topic tag and entries that are tagged with sub-topic tags to the topic tag. For example the tagpage for `top:Projects` will list all entries
that are tagged with `top:Projects`, `top:Projects:Electronics`, `top:Projects:Art`, `top:Projects:DIY`, `top:Projects:Art:Wood Sculptures`,
`top:Projects:Art:Wood Sculptures:Wood Sculptures of Tony`, and so on, sorted alphabetically by sub-topic and title.


### Sorting

Entries are sorted differently on the two differend kinds of tagpages (Topic tagpages being one, all other tagpages the other). Since topic tagpages are meant to
represent an index of thewentries on a topic, entries are sorted by topic and sub-topic first, then alphabetically. Entries with the same sub-(sub-...-)topic are
listed together alphabetically.

All other tagpages (category, language, author and combined tagpages) are sorted by created date. If an entry does not have a `created:` tag, it is sorted at the
bottom of a list, at the end of a tag page (or at the end of the last page of a paged tagpage). If an entry has an `edited:` tag, this edited date overwrites its
created date, meaning entries that have been edited will be placed higher than they would otherwise. The `edited:` tag has to be placed in the header of an entry
source file manually when it is edited. This means for example that typos can simply be corrected in old entries without affecting where they are placed on tagpages.
But if substantial changes are made or a paragraph with an update is added to an entry, you have the choice of adding an edited tag with the current date to bump
the entry to the top of tagpages without faking its creation date.

A third tag that influences how entries are sorted is the sort: tag. It is meant for special cases where you would like created and/or edited dates present and
displayed but the entry sorted to a different place independently of those two tags. The sort: tag overwrites both the created: and edited: tags when it comes to
sorting on tagpages. This can be used to place an entry between others by using a fake date for the sort: tag or at the end of tagpages by setting sort: to 0, all
independently from what created or edited dste is displayed for the entry. It can also be used to place an entry at the top of tagpages, making it "stickied" so to
speak.

The value of the sort: tag is treated the same as the values for edited: and created:. It's just a way to overwrite both for a single entry. There are two special
values though that influence how an entry is displayed: Every value for the sort: tag that starts with either `stick` or `about` will remove the title-wrapper of
the entry on tagpages.

You may, for example, want something to appear above all entries on a specific tagpage, say the tagpage for the category "Miscellaneous" to explain what type of
content you put in this category. In that case you can create an entry that has the tags `cat:Miscellaneous` and `sort:stickied` (or `sort:about`) and the
explanation below. This will make the explanation appear on the top of the cat:Miscellaneous tagpage without a title, link or other meta information.

Only one occurance of each of the three tag types that influence sorting is expected per entry.

Sort criteria summary:

* Sort order for each of the tags is ABCDEFGHIJKLMNOPQRSTUVWXYZ9876543210

* `sort:` overwrites `edited:` and `created:`

* `edited:` overwrites `created:`

* `creted:` is used if no `edited:` or `sort:` tags are present


## Tagicons

By default In this dorectory you can place icons that should be displayed in place of tags in entries' headers. The file name has to be `tagtype:tagname.png`.

Examples:

If you place a file called `lang:en.png` in this directory, the image is inserted in the header of every entry that's tagged with `lang:en`. The text `lang:en` will
not be diplayed in the header, only the image.

If you place a file called `author:foobär.png` in this directory, the author foobär has an avatar that will be displayed instead of their name in the header of
posts tagged with `author:foobär`.

Make sure to resize all images placed in this folder to be of small, sensible dimensions. The image size is only restricted by CSS which means the original image
file is loaded regardless of its dimensions and size.

If you would like to add icons in addition to the tag name in text, it is suggested to use CSS. Every tag displayed in entry headers has its name as a class
selector.


# Entry Images

This is a requested feature that will be addded in an upcoming version of SBWG. It will allow for featured images and single images that can be attached to an entry
without writing the `<img>` tag yourself or abusing the gallery feature.


# Galleries

Creating a gallery is very simple, but there also isn't much control over how a gallery looks. Galleries can not have any metadata or a description on their own.
But they can be linked to a corrosponding entry that contains more information. If you are missing functionalities related to galleries, adding a hook may be a
solution. (See the "Hooks" section above.)

A gallery in SBWG simply consists of a directory that contains image files. The name of the directory is the name/title of the gallery. If an entry of the same name
exists on the same web site, a link to the entry will be placed on the gallery page and vice versa and thumbnails of the gallery's images will be included below the
entry. Currently only JPEG and PNG files are supported and the image file names need to have those extensions.

Upon generation of the web site, the images will be resized into three sizes:

The originals of the images will be copied to the output directory as well. The original image files will be linked to from their previews on the gallery page. This
way large original files are not loaded every time a gellery page is opened, but they are available to every visitor if they want to display or download it. If you
don't want to have the original images included on the pulished web site, you need to resize them manually beforehand or include a function that does this in the
settings file. `convert` or `mogrify` can be used for this.


# Generating A Web Site (Command Line Options)

The file name of the main script is `sbwg`. Calling it without any options will not do anything. When everything goes well (there are no errors) and you didn't set
a verbose mode, there is no output from the script.

There are options to tell the script what to do, how to do it ans which website to do it to. There is a short and long version for each option. To have the script
do anything, you need to add at least one option.

Short and long format option can be mixed.


## Options For Generating (Parts Of) The Web Site

The following options tell the script which parts of the website should be generated/updated in this run.

`--page` or `-p` [PAGENAME]
Generates/updates all SBWG pages from the pages/ directory. If PAGE is specified: Genertes/updates only that page.


`--entry` or `-e` [ENTRYNAME]
Generates/updates all entries from the entries/ directory but not the corrosponding tagpages. If ENTRY is specified: Generates/updates only that entry.


`--tagpage` or `-t` [TAGNAME]
Generates/updates tagpages (topic, category, language and author tagpages as well as combined tagpages) for all entries but not the entries themselves. If TAGNAME is
specified: Genertes/updates only the tagpage for that tag.


`--blog` or `-b`
Alias for -e -t -r. Generates/Updates entries, tagpages and the RSS feed.


`--gallery` or `-g` [GALLERYNAME]
Generates/Updates the gallery pages. If GALLERYNAME is specified: Generate only that gallery.

`--rss` or `-r`
Generates/Updates the rss feed all.rss. Other feed formats might be added in the future.

`--files` or `-f`
Copies the files from the files/directory to the root of the output directory.


`--style` or `-s` [STYLESETNAME]
Copy/update the CSS files for the style set specified in the settings file to the output directory. If STYLESRTNAME is specified: Copy/update the files belonging to
that style set to the output directory and use that style in the header of HTML files if any HTML files are generated in this run of the script.


`--complete` or `-c`
Alias for -p -e -t -r -g -f -s. Generates/updates the entire site.


If none of the above options is specified, nothing is generated.


## Other Options

The following options mainly specify how and from/to where the web site should be generated.


`--input` or `-i` INPUTDIR
Specifies the input directory - the directory that contains the source file structure of the web site. INPUTDIR can be a relative or absolute path to the directory.
If the option is omitted, SBWG will attempt to generate a web site from the file structure in the current working directory.


`--output` or `-o` OUTPUTDIR
Specifies the output directory - the directory where the generated HTML site will be placed. OUTPUTDIR can be a relative or absolute path to the directory. If the
option is omitted, the output directory specified in the settings file will be used. If not output directory is specified there, either, `html/` relative to the
input directory will be used.


`--webpath` or `-w`
This option is not fully implemented yet. It will be used to specify the path of a sub-directory below the web root under which the web site will be reachable.


`--perpage` or `-p` NUM
Specify the number of entries that will be displayed on one tagpage. If there are more than NUM entries for a tagpage, the tagpage will be split into several HTML
pages and pager links will be added at the bottom. This option will likely be removed/replaced in future versions of SBWG.


`--author` or `-a` AUTHORNAME
Specifies the name of an author who's entries should be generated. If this option is specified, all entries that do not have that author name specified in their
source file headers will be ignored. The web site will be generated as if it only contained entries by that author.


`--force` or `-F`
Forces SBWG to continue when an error occurs or a fault is suspected. This can be used to get around yet undiscovered bugs that prevent the script from generating a
web site or parts of a web site despite everything being okay. It is not advised to use this function unless you know why you use it and what it might do. If SBWG
detects an error, aborts the generation process or omits source files, it is always a good idea to check the related files first and correct any mistakes. If you
think that SBWG should not have aborted when it did or should have used a file it cautiously omited, please let me know so I can improve the script in future
versions. (See 'Other Remarks' at the end of this file for contact information.)


`--cache` or `-C`
If this flag is set, SBWG will generate cache files and store them in the `cache/` directory inside the web site's source directory. Once this cache is generated,
future generation processes can finish faster. Currently only some parts of the generated web site will be cached. Future versions of SBWG will make more use of this
option to speed up the generation process significantly. See option `--update-only`/`-U` for information about how these cache files are used.


`--update-only` or `--update` or `-U`
By default, SBWG will ignore any existing cache files and generate the web site at hand (or the requested parts of thw web site) completely, thus ignoring any
possibly existing cache files that were generated in a previous run of the script with option `--cache`/`-C`. Using the `--update-only` option means that changes to
the content or tags of already entries that were made after the last time they have been generated will not be visible in the generated web site. Currently this is
the only thing that is cached by option `--cache`, meaning that option `--update-only` can be used to quickly re-generating e.g. a weblog incl. the tags and other
links in the navbar. Future versions ob SBWG might introduce more agressive caching, resulting in a greater effect when using option `--update-only` both in speed
and parts of the web site not re-generated. Using this function is and will never be necessary. But as far as any plans go right now, this option is useful when you
want to quickly update a weblog after you have created a new entry but changed nothing else.


`--verbose` or `-v`
Enables verbose mode. When verbose mode is enabled the script will report progress at certain stages during the generation. If the option is specified more than once
very verbose mode will be enabled (see below).


`--very-verbose` or `-vv`
Enables very verbose mode. When very verbose mode is enabled the script will report in detail what it is currently doing and which item it will be working on next.
Very verbose mode includes verbose mode (see above).


`--debug` or `-d`
Enables debug output mode. Debug mode includes messages that are meant to help with debigging the script itself. This is mainly used during development versions.
In released version the debig mode just adds some additional information in the output that will likely not be of any use to you. Debig mode included very verbose
mode (see above).


`--log` or `-l` [LOGFILE]
Enables logging into file with highest verbosity value (debugging). If LOGFILE is not provided, the name set for $logfile in the settings file (or its fallback in
the script file) is used as a file name. It is recommended to set the log file name in the settings file and not use the command line option argument for this. If
the log file name set through a command line option argument differs from that set in the script or settings file, two files get created: one that contains only the
message noting the usage of option -l with an argument and one that contains the rest of the messages.


`--help` or `-h` [HELPPAGE]
Without an argument, this option prints short usage instructions and exits the script, ignoring all other options. Help on specific topics is available by adding
the name of an existing help pae after the option. A list of available topics is printed when no argument is provided.


## Example Commands

`sbwg -c`
Generates/updates the complete web site from the sources in the current working directory into its default output directory.


`sbwg -b -o /srv/stage`
Updates the parts of the web site from the current working directory that make up the weblog of the web site into the directory `/srv/stage`


`sbwg -vv --input "/home/user/my web site" --pages`
Updates only the static pages from the web site who's sources can be found in the directory `/home/user/my web site/` while displaying the progress of the generation
process.


`sbwg -p index --output ~`
Generate only the index page from the web site who's source is residing in the current working direcory, into the current working directory, resulting in the file
`~/index.html`.


# Other Remarks

SBWG is work in progress and I don't always publish new versions immedietely. Feel free to contact me via e-mail at a-sbwg@steeph.de for any requests, bug reports,
criticism, suggestions, wishes, complaints or declarations of love.

There is a HOWTO file included in this package where you can read more about how you can use SBWG and how you can accomplish specific things that have not been
mentioned in this README file.

There is no version control in use for SBWG. Feel free to put it on Github or whatever. Maybe I'll start to use it, too, some day.

SBWG is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar.
See http://www.wtfpl.net/txt/copying/ for more details.
