title:README
<p>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. There is a newer version of this file in the package/directory of the script this web site was generated with.</p>
<p>SBWG (sweet bash website generator) is a bash script that generates a static HTML website from raw text files.</p>
<p>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 <a href="http://www.wtfpl.net/txt/copying/">http://www.wtfpl.net/txt/copying/</a> for more details.</p>
<h1 id="features">Features</h1>
<ul>
<li>Generates static HTML structure from a source file structure</li>
<li>Simple image galleries</li>
<li>Weblog/Blog generation
<ul>
<li>Categorised posts with multiple levels</li>
<li>Blog entries can be additionally categorised as topics for an index view</li>
<li>Classical blog view, filterable by category, topic, author, language or author AND one of the others</li>
<li>Support for multi-author weblogs with the option to split off entries from single authors into separate weblog sites</li>
<li>Attached image galleries</li>
</ul></li>
<li>Stylesheet templates</li>
<li>Modifications/Additions to the generation process on a per-web-site basis with hooks and a sourced settings file</li>
<li>Easy staging</li>
<li>Simple RSS feed</li>
</ul>
<h2 id="feature-ideas-and-requested-features">Feature Ideas And Requested Features</h2>
<p>I will work on these when I'm satisfied with the state of the current feature set and have some time.</p>
<ul>
<li>Audio attachements/postcast support, audio player</li>
<li>Video attachement support</li>
<li>Video support in galleries</li>
<li>Support for more image file formats</li>
<li>Easy image embedding, entry images</li>
<li>ATOM feeds and multiple RSS feeds for single tags, categories or topics</li>
<li>Interactive use of the script</li>
<li>Parallel processing in the generation process</li>
<li>Caching of once generated web site data, option to only generate new content/skip generating cached content</li>
<li>Interactive setup script</li>
<li>Easier management of menu items</li>
<li>Generating of web books</li>
</ul>
<p>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.</p>
<ul>
<li>Generate gopher hole and/or gemini capsule at the same time as a web site.
<ul>
<li>They are too different and deserve a different, much simpler generator script if one is needed at all.</li>
</ul></li>
<li>SBWG specific tags in content, e.g. for embedding image files, linking to entries on the same site.
<ul>
<li>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.</li>
</ul></li>
<li>Cut off the content of entries when they are displayed on a tagpage. Click &quot;Read More&quot; or the title to view the whole entry on a separate page.
<ul>
<li>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 decision of not parsing the content of entry files.</li>
</ul></li>
<li>Templates for the HTML structure or an option/setting for different levels of HTML granularity.
<ul>
<li>This would add a huge amount of flexability and eliminate the problem that either the script itself has to bd 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.</li>
</ul></li>
</ul>
<h2 id="known-issues-and-bugs">Known Issues And Bugs</h2>
<ul>
<li>Parallelisation (option -P/--parallel) is experimental and not really functional yet.</li>
<li>The last tagline from entry and page files may sometimes be included in the content part of the entry/page. Workaround: Add an empty line after the last tagline.</li>
<li>Error output of the script gets redirected together with stdout if output is redirected. Workaround: Use logging function (option --log or -l).</li>
<li>Generating a web site onto file systems that don't support filenames that are longer than 6 bytes excluding filename extension (very early FAT systems) is not supported.</li>
<li>The script is written in bash, which is not a good choice for such a project. This will not be fixed.</li>
</ul>
<h1 id="installation">Installation</h1>
<p>You can get the latest published version from <a href="https://log.steeph.de/SBWG.html">https://log.steeph.de/SBWG.html</a></p>
<p>There is currectly no setup script. Installation is straightforward though if you understand how SBWG works. <strong>There are short instructions in the INSTALL file</strong> if not. <strong>Those install instructions are sufficient to get started.</strong> 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 to the INSTALL file now. If you want to know more than you need to know to get started, read on.</p>
<p>After installation of SBWG and during setting up/editing of a web site you might find useful tips in the HOWTO file.</p>
<h2 id="requirements">Requirements:</h2>
<ul>
<li>bash 4.4 (This script is not tested with other shells. Bash &lt; v4 and other popular shells are definitely not supported out of the box.)</li>
<li>Coreutils</li>
<li>imagemagick (or compatible <code>mogrify</code>; only needed for image gallery generation)</li>
<li>Optionally: perl (source file filtering will not be as good if perl is not available. But SBWG does work without it.)</li>
<li>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.</li>
<li>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.</li>
<li>The same goes for the generated HTML, which assumes HTML 5 support.</li>
</ul>
<h2 id="setting-up-the-script">Setting Up The Script</h2>
<ul>
<li>Extract the package to a location outside of your web root</li>
<li>Move the files to a directory in PATH or add the SBWG directory path to your PATH.</li>
<li>Check if the file 'sbwg' (and optionally the other files starting with 'sbwg-') is executable, make it executable if it is not already.</li>
</ul>
<h2 id="setting-up-a-new-web-site">Setting Up A New Web Site</h2>
<p>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.</p>
<h3 id="setting-up-a-new-web-site-from-the-example-template">Setting Up A New Web Site From The Example Template</h3>
<p>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.</p>
<ul>
<li>Copy the 'example' directory to a suitable location, e.g. ~/my_website</li>
<li>Edit the 'settings' file to change your website's title, url/domain name, style template choice, default output directory, etc.</li>
<li>If you have not changed the default output directory, create a symlink called 'html' to point to your web root.</li>
<li>Edit the 'footer' file to include any HTML code that you want to be included at the bottom of every generated HTML page.</li>
<li>Place any other miscellaneous files needed by your web site in the 'files' directory.</li>
<li>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.</li>
<li>Create and/or edit files in the 'pages' directory for &quot;static&quot; web pages not related to a weblog.</li>
<li>Create blog entries in the 'entries' directory. You can use the 'sbwg-genentry' script, write files from scratch or use a template file that you have filled with header lines that you regularly use.</li>
<li>Add galleries in the 'gals' directory, one directory per gallery. Simplyt place JPEG and PNG files in these directories.</li>
<li>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.</li>
</ul>
<h3 id="setting-up-a-new-web-site-from-scratch">Setting Up A New Web Site From Scratch</h3>
<p>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.</p>
<p>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.</p>
<h1 id="files-and-directories-of-a-web-site-source-directory">(Files And Directories Of) A Web Site Source Directory</h1>
<p>The following files and directories can be used to build a web site with SBWG. All except the <code>settings</code> 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.</p>
<h2 id="settings">settings</h2>
<p>The <code>settings</code> 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.</p>
<p>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 &quot;Hooks&quot; 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 &quot;Settings&quot;.</p>
<h2 id="files">files</h2>
<p>The <code>files</code> 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.</p>
<p>The directory just gets 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.</p>
<h2 id="header">header</h2>
<p>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 &quot;Hooks&quot; section below)</p>
<h2 id="footer">footer</h2>
<p>The contents of this file gets appended to every generated HTML file. The file has to end with:</p>
<pre><code>  &lt;/body&gt;
&lt;/html&gt;</code></pre>
<p>Before that you can put anything that should appear at the end of every HTML page. For example a <code>&lt;footer&gt;</code> tag with a copyright notice.</p>
<p>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 <code>&lt;body&gt;</code> and <code>&lt;html&gt;</code> 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.)</p>
<h2 id="styles">styles</h2>
<p>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 &quot;Styles&quot; section below for more information on style sets and custom CSS changes.)</p>
<h2 id="pages">pages</h2>
<p>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. See chapter <code>Pages</code> below.</p>
<h2 id="entries">entries</h2>
<p>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 or not present. Each file in the entries directory represents one blog entry. Entry source files can optionally be placed in subdirectories for better overview of the file structure. This directory structure has no effect on the generated web site though. On the web site entries are categorised according to their tags, not the directories their source files are in.</p>
<p>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 &quot;Blog Entries&quot; and &quot;Tags&quot; 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.</p>
<h2 id="tagicons">tagicons</h2>
<p>In this dorectory you can place icons that should be displayed in place of tags in entries' headers. The file name has to be <code>tagtype:tagname.png</code>. Note that these image files are not resized by SBWG. They are intended to be small icons.</p>
<h2 id="html">html</h2>
<p>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 <code>--output</code> (<code>-o</code>). 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.</p>
<p>If a different directory is used as the output directory (see the sections &quot;Settings&quot; and &quot;Generating a web site&quot; below) then this directory is not needed.</p>
<h1 id="settings-1">Settings</h1>
<p>A setting in a web sites <code>settings</code> 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 <code>=</code> followed by the value in an otherwise empty line. There may be no blank before or after the <code>=</code>. Values with some special characters (e.g. spaces) have to be quoted (encloded in <code>&quot;</code>s).</p>
<p>Examples:</p>
<p><code>sitename=&quot;ExSite (The Example Web Site)&quot;</code> The Name of the web site needs to have a <code>&quot;</code> before and one after in this case, because it contains spaces. Otherwise, an error will occur.</p>
<p><code>thumbsize=200</code> The value <code>200</code> does not contain any special characters. Therefore no <code>&quot;</code> is needed. It doesn't matter whether the value is enclosed in them or not.</p>
<p>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 &quot;Hooks&quot; section below.)</p>
<p><code>sitename</code> - The name/title of the website as displayed in the header and used in the browser window title bar/browser tabs.</p>
<p><code>url</code> - The url is used when external documents that link to the web site are generated, e.g. the RSS feed.</p>
<p><code>style</code> - The name of the style set that should be used if none is specified by command line option. See the &quot;Styles&quot; section below to learn which files this will include.</p>
<p><code>odir</code> - The path of the output directory.</p>
<p><code>thumbsize</code> - The maximum width and height of gallery image thumbnails when attached to blog entries.</p>
<p><code>thumbsizemini</code> - The maximum width and height of gallery image thumbnails on gallery pages.</p>
<p><code>previewsize</code> - 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.</p>
<p><code>perpage</code> - 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.</p>
<p><code>tagiconsize</code> - This setting is currently ignored. You may do the same with this line.</p>
<p><code>duals</code> - This setting is currently ignored. You may do the same with this line.</p>
<p><code>details</code> - This setting is obsolete and will be ignored by the script. You may do the same with this line.</p>
<p><code>exclude</code> - This setting is currently ignored. You may do the same with this line.</p>
<h2 id="hooks">Hooks</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<ul>
<li><code>$shellbase</code> - The path of the input directory - The directory of the web site that is being generated</li>
<li><code>$tmpdir</code> - The path of the temporary directory - This directory will be deleted after the script is done or when it fails.</li>
<li><code>$version</code> - The version of SBWG that is processing the website</li>
<li><code>$options</code> - A string of option letters that are set through command line options</li>
<li><code>$entrylist</code> - An array that contains all entry names that exist on the web site. Only available after the navigation bar has started to be generated.</li>
<li><code>$entrylists</code> - An associative array with all existing tag names as keys and lists of entry names as values. Only available after tagpage preparation.</li>
<li><code>$tagslist</code> - An array that contains all existing tags. Only available after the navigation bar has started to be generated.</li>
<li><code>$gallerylist</code> - An array that contains the names of all galleries on this web site that contain any supported image files. Only available after navbar generation.</li>
<li><code>$desired_entry</code> - The entry name, if one was passed to option -e (or --entry).</li>
<li><code>$desired_page</code> - The page name, if one was passed to option -p (or --page).</li>
<li><code>$desired_tagpage</code> - The name of the tagpage, if one was passed to option -t (or --tagpage).</li>
<li><code>$desired_gallery</code> - The name of the gallery, if one was passed to option -g (or --gallery).</li>
<li>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</li>
</ul>
<table>
  <colgroup></colgroup>
  <colgroup></colgroup>
  <colgroup></colgroup>
  <colgroup></colgroup>
  <tr>
    <td><b>Function Name</b></td>
    <td><b>Called</b></td>
    <td><b>Available Local Variables</b></td>
    <td><b>Usage Examples</b></td>
  </tr>
  <tr>
    <td>hook_error</td>
    <td>When a fatal error has occured<br>After the error message has been printed<br>Before the temporary directory gets cleared</td>
    <td>$@ The error message (usually just one string, so $1)<br>$str The error message in one string</td>
    <td>Clean-up before exit<br>Send out a notification<br>Send message to stderr and exit cleanly</td>
  </tr>
  <tr>
    <td>hook_warning</td>
    <td>When an important but non-fatal error has been detected.<br>After the warning message has been printed</td>
    <td>$@ The warning message (usually just one string, so $1)<br>$str The error message in one string</td>
    <td>Send out warning message<br>Send out a notification<br>Send message to stderr without exiting</td>
  </tr>
  <tr>
    <td>hook_pathreducer</td>
    <td>Whenever the pathreducer function is called</td>
    <td>$1 The path or part of the path that should be reduced if pathreducer mode is in. A string of path elements separated by '/', the last one being a filename, all others being a directory name.<br>$maxfnl The maximum allowed filename length. Either an integer or two integers separated by a dot.</td>
    <td>Manipulate the path before itis processed<br>Replace the function always in specific cases</td>
  </tr>
  <tr>
    <td>hook_pathreducer_part_start</td>
    <td>For each path element (directory name and filename)<br>Before anything is done to the path element or anything is outputted</td>
    <td>Same as above. Additionally:<br>$part The currently processed path element</td>
    <td>Manupulate certain path elements before they are processed</td>
  </tr>
  <tr>
    <td>hook_pathreducer_part_before</td>
    <td>For each path element (directory name and filename)<br>After all unwanted characters have been removed<br>Before the part is shortened and the hash is added<br>Before the reduced path element is outputted</td>
    <td>Same as above. Additionally:<br>$newbase If $part is not the last path element (menaing it is a directory name): the reduced directory name. If it is the last path element (meaning it is a filename): The reduced filename's basename without a suffix/filename extension. (The complete reduced filename if there is no suffix.)<br>$newsuff The reduced suffix of the filename. Empty if $part is not the last path element (meaning it is a directory name) or the filename has no suffix.</td>
    <td>Further change the reduced basename and/or suffix before the path element gets shortened, the hash gets appended and the result gets printed<br>Override the standard way of how the path element gets reduced, e.g. allow more special characters or convert all letters to upper case</td>
  </tr>
  <tr>
    <td>hook_pathreducer_part_between</td>
    <td>For each path element (directory name and filename) if the element needs to be reduced<br>After the path element has been reduced/processed<br>Before the reduced path element is printed</td>
    <td>Same as above, with one change:<br>$newbase The reduced and shortened basename/directory name/ filename with a 6- character hash appended.</td>
    <td>Custom changes to the path element after it has been completely processed beforeit is outputted</td>
  </tr>
  <tr>
    <td>hook_pathreducer_part_after</td>
    <td>For each path element (directory name and filename)<br>After the path element has been processed and the reduced/processed path element has been outputted<br>Before the separating '/' gets outputted</td>
    <td>Same as above.</td>
    <td>Append custom string to the path element</td>
  </tr>
  <tr>
    <td>hook_redirect</td>
    <td>When an HTML file is created that redirects to<br>another URL, before the file is written</td>
    <td>$1 Path of created HTML file<br>$2 Relative path of target</td>
    <td>Additional file operations related to HTML redirection(e.g. file system links)</td>
  </tr>
  <tr>
    <td>hook_prepare</td>
    <td>After all preparations have been made<br>Before anything gets generated</td>
    <td>-</td>
    <td>Create or copy files idepen- dantly of what SBWG will do</td>
  </tr>
  <tr>
    <td>hook_files</td>
    <td>When and after the web site's files directory gets<br>copied from the source directory to the output dir</td>
    <td>-</td>
    <td>Copy additional files when- ever SBWG copies files dir</td>
  </tr>
  <tr>
    <td>hook_head</td>
    <td>When the head portion of an HTML file is generated<br>After the hardcoded tags in the &lt;head&gt; tag<br>Before the &lt;head&gt; tag is closed</td>
    <td>$outfile The HTML file that is cur- rently being generated</td>
    <td>Inject tags into the HTML &lt;head&gt; tag (e.g. link JS)</td>
  </tr>
  <tr>
    <td>hook_entry_start</td>
    <td>When an entry page gets generated<br>After the entry file has been checked<br>After tags have been extracted from the entry file<br>Before any tags are processed<br>Before anything gets written to the HTML file</td>
    <td>$outfile The HTML file that is cur- rently being generated<br>$entry Name of the current entry<br>$tags List of the entry's tags<br>$author Name of the entry's author</td>
    <td>Additional preparations of anentry before any HTML is generated</td>
  </tr>
  <tr>
    <td>hook_entry_title_start</td>
    <td>When an entry chunk gets generated<br>Inside (at the beginning of) the title wrapper<br>After the title wrapper tag has been opened<br>Before the title and meta-information are printed</td>
    <td>See hook above.</td>
    <td>Inject HTML at the beginning of the title-wrapper of an entry</td>
  </tr>
  <tr>
    <td>hook_entry_title_tags_before</td>
    <td>When an entry chunk gets generated<br>Inside the title wrapper<br>After the created (and edited) date(s) are printed<br>Before the tags are printed</td>
    <td>See hook above.<br>Additionally:<br>$created The entry's created date v.<br>$edited It's edited date value</td>
    <td>Inject HTML at the beginning of the tags in the title- wrapper of an entry</td>
  </tr>
  <tr>
    <td>hook_entry_title_tag_before</td>
    <td>When a tag gets printed inside the title wrapper of an entry<br>Before it was checked whether it is a tag that will be printed or not<br>Before the its surrounding HTML tags are printed</td>
    <td>See hook above.<br>Additionally:<br>$tag The currently processed tag</td>
    <td>Inject HTML before certain orall tags in the title- wrapper of an entry</td>
  </tr>
  <tr>
    <td>hook_entry_title_tag_after</td>
    <td>When a tag gets printed inside the title wrapper of an entry<br>After the tag has been printed</td>
    <td>See hook above.<br>Additionally:<br>$tag The currently processed tag</td>
    <td>Inject HTML after certain or all tags in the title- wrapper of an entry</td>
  </tr>
  <tr>
    <td>hook_entry_title_tags_after</td>
    <td>When an entry chunk gets generated<br>After the tags have been printed<br>Before the title wrapper is closed<br>Before the content is printed</td>
    <td>Same as three hooks above. (hook_entry_title_tags_before)</td>
    <td>Inject HTML at the end of thetags in the title-wrapper of an entry</td>
  </tr>
  <tr>
    <td>hook_above_entry_content</td>
    <td>When the section for notes above content is generated, whether there are any notes or not.<br>After all notes have been printed (if any exist).</td>
    <td>Same as six hooks above. (hook_entry_start)</td>
    <td>Same as next hook, actually.</td>
  </tr>
  <tr>
    <td>hook_entry_before</td>
    <td>When an entry page gets generated<br>After the title wrapper is printed and closed<br>After the content div is opened<br>After the reference lines (if any) have been been printed<br>Before the entry content is printed</td>
    <td>Same as seven hooks above. (hook_entry_start)</td>
    <td>Inject HTML at the beginning of the content of the content of an entry on the entry page</td>
  </tr>
  <tr>
    <td>hook_entry_after</td>
    <td>When an entry page gets generate<br>After the entry content is printed<br>Before the content div is closed</td>
    <td>See hook above.</td>
    <td>Inject HTML at the end of thecontent of an entry on the entry page</td>
  </tr>
  <tr>
    <td>hook_entry_end</td>
    <td>When an entry page gets generated<br>After everything concerning this entry is done andthe HTML file is completed and closed</td>
    <td>See hook above.</td>
    <td>Additional file operations after an entry page has been generated that don't afftect generation</td>
  </tr>
  <tr>
    <td>hook_entries_start</td>
    <td>When generating entries<br>Before any entry has been generated or prepared</td>
    <td>-</td>
    <td>Additional operations per- formed if and before any entry pages are generated</td>
  </tr>
  <tr>
    <td>hook_entries_end</td>
    <td>When generating entries<br>After all entries have been generated/completed</td>
    <td>-</td>
    <td>Additional operations per- formed if and after all entry pages are generated</td>
  </tr>
  <tr>
    <td>hook_gallery_start</td>
    <td>When a gallery page gets generated<br>After gallery generation has been prepared<br>After the gallery has been checked<br>Before anything gets written to the HTML file</td>
    <td>$outfile The HTML file that is cur- rently being generated<br>$gallery Name of the gallery that is currently being generated<br>$images List of file names of all images in this gallery<br>$tags If there is a corrospon- ding entry: list of all tags of that entry<br>$title If there is a corrospon- ding entry: Entry's title l</td>
    <td>Additional changes or other preparations of the gallerybefore it is processed<br>Exclude certain images con- ditionally, e.g. based on file names<br>Add something to the gal- lery's title if its corros-ponding entry source file contains a certain tag</td>
  </tr>
  <tr>
    <td>hook_gallery_before</td>
    <td>When a gallery page gets generated<br>After the navigation bar and page header have beengenerated<br>Before the image thumbnails are written to the HTML file</td>
    <td>See hook above.</td>
    <td>Add text to the header of thegallery above its thumb- nails</td>
  </tr>
  <tr>
    <td>hook_gallery_image_before</td>
    <td>When an image is placed in a gallery page<br>After the image file has been checked<br>Before the image preview is placed in the HTML file</td>
    <td>See hook above.<br>Additionally:<br>$image Path and file name of the currently processed image<br>$img Its file name without path</td>
    <td>Change from where the the file/which image file is embedded in the gallery (e.g. change the default preview to a CDN source)</td>
  </tr>
  <tr>
    <td>hook_gallery_image_after</td>
    <td>When an image is placed in a gallery page<br>After the image preview has been placed in the HTML file<br>Before the &quot;Go to top&quot; link is placed in the file</td>
    <td>See hook above.</td>
    <td>Inject additional text or a link below all images or certain images e.g. based on the gallery title/name or image file name</td>
  </tr>
  <tr>
    <td>hook_gallery_after</td>
    <td>When a gallery page gets generated<br>After the last image has been placed in the generated HTML output file<br>Before the main section is closed and the footrer printed to the generated HTML output file</td>
    <td>Same as three hooks above. (hook_gallery_before)</td>
    <td>Add a footer to all or to certain galleries</td>
  </tr>
  <tr>
    <td>hook_gallery_end</td>
    <td>When a gallery page gets generated<br>After the gallery page HTML file has been finished<br>After everything conserning this gallery is done</td>
    <td>See hook above.</td>
    <td>Additional image modifi- cations after the fact</td>
  </tr>
  <tr>
    <td>hook_galleries_start</td>
    <td>When image galleries are generated<br>Before it gets decided which galleries will be generated<br>Before any of the galleries have been checked, prepared or generated</td>
    <td>-</td>
    <td>Additional operations before any gallery is generated<br>Modify the list of list of galleries before processing</td>
  </tr>
  <tr>
    <td>hook_galleries_end</td>
    <td>When image galleries are generated<br>After every gallery has been generated</td>
    <td>-</td>
    <td>Additional operations to be performed if any galleriiesare/have been generated</td>
  </tr>
  <tr>
    <td>hook_page_start</td>
    <td>When a SBWG page gets generated<br>After the page file has been checked<br>After tags have been extracted from the page file<br>Before any tags are processed<br>Before anything gets written to the HTML file</td>
    <td>$outfile The HTML file that is cur- rently being generated<br>$tags List of the page's tags<br>$title The page's title if tag set</td>
    <td>Modify the tags or content ofthe pge that is about to be generated</td>
  </tr>
  <tr>
    <td>hook_page_title_before</td>
    <td>When a SBWG page gets generated<br>If the page has a title tag<br>After the header and navigation bar have been added to the generated output file<br>Right before the title gets printed on the page</td>
    <td>See hook above.</td>
    <td>Inject HTML right before the title of a page if it was defined by a tagline</td>
  </tr>
  <tr>
    <td>hook_page_title_after</td>
    <td>When a SBWG page gets generated<br>If the page has a title tag<br>Right after the title gets printed on the page</td>
    <td>See hook above.</td>
    <td>Append text to the title of apage if its title was de- fined by a tagline</td>
  </tr>
  <tr>
    <td>hook_page_content_before</td>
    <td>When a SBWG page gets generated<br>Right before the content gets printed on the page</td>
    <td>See hook above.</td>
    <td>Add text right before the content of a page</td>
  </tr>
  <tr>
    <td>hook_page_content_after</td>
    <td>When a SBWG page gets generated<br>Right after the content gets printed on the page</td>
    <td>See hook above.</td>
    <td>Add text right adfter the content of a page</td>
  </tr>
  <tr>
    <td>hook_page_end</td>
    <td>When a SBWG page gets generated<br>After everything concerning this page has been done</td>
    <td>See hook above.</td>
    <td>Additional operations after a page's HTML file has beengenerated</td>
  </tr>
  <tr>
    <td>hook_pages_start</td>
    <td>When SBWG pages are generated<br>Before any pages are prepared or generated</td>
    <td>-</td>
    <td>Modify the list of pages thatare about to be generated</td>
  </tr>
  <tr>
    <td>hook_pages_end</td>
    <td>When SBWG pages are generated<br>After all pages have been generated</td>
    <td>-</td>
    <td>Additional operations after pages have been generated</td>
  </tr>
  <tr>
    <td>hook_navbar_start</td>
    <td>Before any HTML pages are generated<br>If any HTML pages will be generated in this run<br>When the navigation bar is generated<br>Before any preparations for the navigation bar generation have been done</td>
    <td>$entrylist Array of entries that exist in the web site<br>$tagslist_unsorted Array of tags that exist in the web site</td>
    <td>Modify $entrylist or $tagslist_unsorted before they are used / Inject possibly fake entries or tags</td>
  </tr>
  <tr>
    <td>hook_navbar_before</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After the &lt;nav&gt; tag has been opened<br>Before anything gets printed to the navigation bar</td>
    <td>$outfile Path of the navbar file in the temporary directory during the generation of the navigation bar</td>
    <td>Add links to the beginning ofthe nabigation bar<br>Add HTML before the first navigation/menu item/link</td>
  </tr>
  <tr>
    <td>hook_navbar_item_before</td>
    <td>When the navigation bar is generated (once per run of the script)<br>For each tag that occurs at least once in an entry<br>Before the tag type has been checked</td>
    <td>See hook above.<br>Additionally:<br>$item Tag that is currently being processed (e.g. &quot;cat:foo&quot;)</td>
    <td>Inject HTML at the beginning of every link in the menu/ naviation bar</td>
  </tr>
  <tr>
    <td>hook_navbar_item_after</td>
    <td>When the navigation bar is generated (once per run of the script)<br>For each tag that occurs at least once in an entry<br>After the tag type has been checked and the tag been processed if of a tag type that is includedin the navigation bar by default</td>
    <td>See hook above.</td>
    <td>Inject HTML after every menu item/link in the navigationbar.</td>
  </tr>
  <tr>
    <td>hook_navbar_item_change</td>
    <td>When the navigation bar is generated (once per run of the script)<br>For the last tag of each tag type that occurs at least once in an entry least once in an entry</td>
    <td>See hook above.</td>
    <td>Add a link at the end of a list of items in the navi- gation bar (e.g. add customitem/link in the link list category items</td>
  </tr>
  <tr>
    <td>hook_navbar_galleries_before</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After all tags have been processed<br>Right before the list of galleries is generated</td>
    <td>Same as four hooks above. (hook_navbar_before)</td>
    <td>Modify the list of galleries before it's used for the first time (e.g. add/removegalleries conditionally)</td>
  </tr>
  <tr>
    <td>hook_navbar_gallery_before</td>
    <td>When the navigation bar is generated (once per run of the script)<br>Before a gallery gets printed to the output file</td>
    <td>See hook above. Additianlly:<br>$gallery Name of the currently being added to the list in the navigation bar</td>
    <td>Add HTML right before all or certain gallery links in the gallery link list in the navigation bar</td>
  </tr>
  <tr>
    <td>hook_navbar_gallery_after</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After a gallery gets printed to the output file</td>
    <td>See hook above.</td>
    <td>Add HTML right after all or certain gallery links in the gallery link list in the navigation bar</td>
  </tr>
  <tr>
    <td>hook_navbar_galleries_after</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After the list of galleries has been printed to the generated HTML output file</td>
    <td>Same as six hooks above. (hook_navbar_before)</td>
    <td>Inject an additional link at the end of the list of gal-lery links in the navi- gation bar</td>
  </tr>
  <tr>
    <td>hook_navbar_after</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After all content that is included in the navigation bar by default has been added to it<br>Before the &lt;nav&gt; tag is closed</td>
    <td>See hook above.</td>
    <td>Inject HTMl at the end of thenavigation bar<br>Add custom links after all others in the navigation bar</td>
  </tr>
  <tr>
    <td>hook_navbar_end</td>
    <td>When the navigation bar is generated (once per run of the script)<br>After everything concerning the navigation bar generation has been processed</td>
    <td>See hook above.</td>
    <td>Execute additional commands once per run if HTML outputis generated<br>Parse/alter navigation bar</td>
  </tr>
  <tr>
    <td>hook_tagpage_start</td>
    <td>When a tagpage is generated<br>After the output file has been checked<br>Before anything gets written to the generated<br>tagpage HTML output file</td>
    <td>$outfile Path of the tagpage HTML file that is currently being generated<br>$tag Name of the tag for which the tagpage is cur- rently being generated<br>$lastentry Number of entries that are included on this tagpage<br>$lastpage Number of additional pages if this tagpage will have a pager/more than one HTML page<br>$pagecount Number of the page that is currently being processed (out of $lastpage pages)</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_before</td>
    <td>When a tagpage is generated<br>After the heade and navigation bar of the generated HTML page have been generated<br>Right after the content &lt;div&gt; tag is opened<br>Before thr content of the tagpage is written</td>
    <td>See hook above. Additionally:<br>$secs List of tags for which combined tagpages will be generated (if any)</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_top_before</td>
    <td>When a topic tagpage is generated<br>Inside the title-wrapper div<br>Before the title of an entry is printed to HTML</td>
    <td>See hook above. Additionally:<br>$entrycount Number of the entry is currently being processed (out of $lastentry pages)<br>$tags List of all tag lines of the currently processed entry<br>$author Name of the author of the current entry<br>$target Name of an entry the current entry will redirect to (if any)<br>$entryname Name of the cuttently processed entry<br>$created Created date value of the current entry<br>$edited Edited date value of the current entry<br>$title Title of the current- ly processed entry<br>$sortby Sort value of the current entry</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_top_after</td>
    <td>When a topic tagpage is generated<br>Inside the title-wrapper div<br>After the created and edited dates have been printed to the generated HTML file</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_title_before</td>
    <td>When a tagpage (not topic tagpage) is generated<br>For each entry that on this tagpage except for stickied entries<br>Inside the title-wrapper div<br>Before the entry's title is written to the HTML</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_title_after</td>
    <td>When a tagpage (not topic tagpage) is generated<br>For each entry that on this tagpage except for stickied entries<br>Inside the title-wrapper div<br>After the entry's title is written to the HTML</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_stickied</td>
    <td>When a tagpage (not topic tagpage) is generated<br>For each stickied entry on this tagpage<br>Before the entry's content is printed to the HTML</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_content_before</td>
    <td>When a tagpage (not topic tagpage) is generated<br>Inside the entry-content-wrapper div<br>Before the entry's content is printed to the HTML</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_entry_content_after</td>
    <td>When a tagpage (not topic tagpage) is generated<br>Inside the entry-content-wrapper div<br>After the entry's content is printed to the HTML</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_after</td>
    <td>When a tagpage is generated<br>After all entries have been added to the generatedHTML file in the output directory<br>Before content &lt;div&gt; tag has been closed</td>
    <td>Same as eight hooks above. (hook_tagpage_before)</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpage_end</td>
    <td>When a tagpage is generated<br>After all entries concerning this tagpage have been processed</td>
    <td>See hook above.</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpages_entry</td>
    <td>When tagpage generation is prepared<br>For each entry that exists on the web site<br>After the entry source file has been checked<br>After some meta information has been retrieved from the entry's tags<br>After the entry's sorting value has been determined<br>Before all tags have been checked<br>Before the entry is assigned to any tagpage<br>Before any tagpages get generated</td>
    <td>$entry Name of entry currently being examined<br>$tags List of all tags of the currently examined entry<br>$created Created date value of the currently examined entry<br>$edited Edited date value of the currently examined value<br>$author Name of the author of the currently examined entry<br>$sortby Sort value of the currently examined entry</td>
    <td>Influence tagpage sorting by changing $sortby of entries</td>
  </tr>
  <tr>
    <td>hook_tagpages_start</td>
    <td>When tagpages get generated<br>After tagpage generation has been prepared<br>Before it is determined chich tagpages to generate<br>Before any tagpages get generated</td>
    <td>-</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_tagpages_end</td>
    <td>When tagpages get generated<br>After all tagpagges that are generated in this runof the script have been completely generated</td>
    <td>-</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_rss_start</td>
    <td>When an RSS file gets generated<br>Before anything is concerning the RSS feed<br>Before the RSS file is generated</td>
    <td>$outfile Path of the RSS file being generated</td>
    <td></td>
  </tr>
  <tr>
    <td>hook_rss_channel</td>
    <td>When an RSS file gets generated<br>After the blog's meta information have been added<br>Before any entries are added to the feed</td>
    <td>See hook above.</td>
    <td>Restrict which entries will be included (e.g. number of entries in the feed)</td>
  </tr>
  <tr>
    <td>hook_rss_entry</td>
    <td>When an RSS file gets generated<br>For each entry that is added to the feed<br>Before any data concerning this entry is added</td>
    <td>See hook above. Additionally:<br>$entry URL of the entry file<br>$entryname Name of the entry (file)<br>$tags Newline separated list of tags of the cur- rently processed entry<br>$author Name of the author of the currently pro- cessed entry<br>$title Title of the currently processed entry<br>$pubdate Created date of the cur- rently processed en- try, Edited date if no create date exists for the currently pro- cessed entry, $pubdate is in RFC 2822 format; The entry is omitted if pubdate does not start with a number<br>$content Content of the cuttently processed entry</td>
    <td>Change the entry's name for the RSS feed.<br>Change how entries with no content are displayed in RSS feeds.<br>Determine how entries with nospecified author (no authortag line) are displayed in the RSS feed.<br>Exclude certain entries from the RSS feed e.g. based on tags or content.</td>
  </tr>
  <tr>
    <td>hook_rss_end</td>
    <td>When an RSS file gets generated<br>After the last entry has been added to the feed<br>Before the &lt;rss&gt; tag is closed</td>
    <td>See hook above.</td>
    <td>Add additional content (channels, items/entries)</td>
  </tr>
  <tr>
    <td>hook_end</td>
    <td>After everything that is generated in this run of of the script has been done<br>Before cleanup (removal of temporary files)</td>
    <td>-</td>
    <td>Perform additional operationson the final product<br>Send out a notification</td>
  </tr>
</table>
<p>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.</p>
<h1 id="styles-1">Styles</h1>
<p>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 &quot;style&quot; is used unless a different style is specified either in the web site's settings file (see &quot;Settings&quot; section below) or through the command line option <code>--style</code> (<code>-s</code>). That means that by defult all CSS files with a name starting with &quot;style-&quot;... and ending in &quot;.css&quot; as well as the file &quot;style.css&quot; 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</p>
<p>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.</p>
<p>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.</p>
<p>Example file names: If your style is set as &quot;my_style&quot; then the files my_style.css my_style-sidebar.css my_style-awesomeness.css my_style-something.css</p>
<p>and so on, will be linked in the header of every generated HTML file headers.</p>
<p>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 <code>hook_head</code>. (See the &quot;Hooks&quot; section above.)</p>
<h1 id="pages-1">Pages</h1>
<p>A page in SBWG terminology is a file consisting of a title and content, that will be turned into an HTML file but not automatically linked to from other generated files. 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 <code>pages</code> 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).</p>
<p>It is recommended to at least have a file named <code>index</code> in this directory. It will be turned into an HTML page and placed as &quot;index.html&quot; 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 <code>pages</code> directory are turned into HTML files and placed directly in the output directory. Subdirectory below the pages/ directory that contain at least one page source file that is going to be generated will be also created in the root of the output directory, meaning the dorectory tree from the pages/ directory will be recreated in the output directory.</p>
<p>A page does not have to contain a source file header as it is recommended for entries (see the &quot;entries&quot; section below). But if a page source file starts with a line that starts with <code>title:</code>, that title will be used as the heading. For example if the first line of a file in the <code>pages</code> directory is</p>
<p><code>title:This Is The Tilte But It Has A Typo</code></p>
<p>then the generated HTML page will turn that line into an <code>&lt;h2&gt;</code> heading. In the future, more tag types for page files will be added. But right now <code>title:</code> is the only one.</p>
<h2 id="example-of-a-page-source-file">Example Of A Page Source File</h2>
<pre><code>title:Interesting Title

&lt;p&gt;This is just an example.&lt;/p&gt;</code></pre>
<h1 id="blogweblog">Blog/Weblog</h1>
<p>The blog is the most complex part of a SBWG website. Having a blog is optional, as is pretty much any feature of the blog. The blog content is made up of entries, which are combined into HTML pages for every author, topic, category and language tag an entry contains. An individual HTML file for each entry is also generated.</p>
<h2 id="blog-entries">Blog Entries</h2>
<p>Blog entries are stored in the <code>entries</code> 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). The option <code>--reduce-paths</code> or <code>-R</code> can be used to shorten file names of the generated files.</p>
<p>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. Line breaks in the header have to be in the unix form (LF) unless the Bash environment SBWG in run in treats other characters as line breaks by default. 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.</p>
<p>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.</p>
<h2 id="example-of-an-entry-source-file">Example Of An Entry Source File</h2>
<pre><code>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

&lt;p&gt;This is the example entry&#39;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 &quot;Tags&quot; section in the README file for more information
about tags.&lt;/p&gt;</code></pre>
<h2 id="tags">Tags</h2>
<p>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 &quot;Blog Entries&quot; and &quot;Pages&quot; above.)</p>
<p>All tags are optional. Some tag types are useful to use multiple times in a single entry header, others should only occur once. Some tag types you will rarely use and some probably never. The section &quot;Tags Types&quot; 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.</p>
<p>A tag line starts with the tag type, followed by a colon (&quot;:&quot;), 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.</p>
<h3 id="tag-value-limitations">Tag Value Limitations</h3>
<p>The following paragraphs are still true, but since they have been written, many changes have been made to handle every possibility automatically by filtering and encoding characters where needed. In short: Avoid slashes ('/') tags of the type top, cat, lang and author. Avoid tab characters in tags of all types. Avoid non-existing unicode characters. If you do use any of those, expect them to be replaced or removed in the output that is generated by the script. Avoid any characters that can't be part of a filename on your filesystem(s) in tags of the type top, cat, lang and author. Alternatively use option -R/--reduce-paths to convert file names into a format that is supported by your filesystem(s).</p>
<p>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. If the web site you want to generate contains tag values or file names with characters that are not supported by at least one of the file systems you use, you can use the option --reduce-paths (-R) to reduce the length of and remove special characters from all generated directory names, file names and HTML links/anchors. See 'sbwg --help options' for more information.</p>
<p>Not allowed in any tag type are: <code>:</code> (colon), the NULL byte and the newline character (Unicode U+000A).</p>
<p>In the tag types <code>cat:</code>, <code>top:</code>, <code>lang:</code> and <code>author:</code> the following characters are not allowed: <code>+</code> (plus sign), <code>#</code> (hash sign), <code>?</code> (question mark), <code>%</code> (percent sign), <code>/</code> (slash). Additionally, 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 and the temporary directory) or the web server must be avoided.</p>
<p>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 <code>.html</code> 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 <code>author</code> tags is 118 bytes and for <code>top</code> 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.</p>
<p>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 &quot;Uniform Resource Identifier (URI): Generic Syntax&quot; (RFC3986) at <a href="https://datatracker.ietf.org/doc/html/rfc3986">https://datatracker.ietf.org/doc/html/rfc3986</a> (additionally older version RFC2396 at <a href="https://datatracker.ietf.org/doc/html/rfc2396">https://datatracker.ietf.org/doc/html/rfc2396</a> 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).</p>
<p>If you want to be sure for all sorts of systems both of the server and client side, only use alphanumeric characters for <code>top:</code>, <code>cat:</code>, <code>author:</code> and <code>lang:</code> tags and keep them short, or use the pathreducerer (option <code>--reduce-paths</code>/<code>-r</code>).</p>
<h3 id="tag-types">Tag Types</h3>
<p>The following tag types can be used in header of page source files as well as entry source files.</p>
<p><code>note:</code> This tag has no function. It is a valid tag but it is ignored by SBWG. It can be used to include a note/comment in an entry or page source file header. Multiple note tags can be used in a single file. Example: <code>note:This is just a note.</code></p>
<p><code>title:</code> The title of the entry or page If more than one title tag is present, the first one will be used. Example: <code>title:An Interesting Title</code></p>
<p><code>menu:</code> 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: <code>menu:Main:About:History</code> (not yet implemented)</p>
<p>The following tag types can only be used in entry source file headers.</p>
<p><code>created:</code> The date at which the entry was first created. Any string is accepted. Any alphanumerical 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. If more than one created tag is present, the first one will be used. Example: <code>created:2020-12-29</code></p>
<p><code>edited:</code> 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. If more than one edited tag is present, the first one will be used. Example: <code>edited:2021-05-05</code></p>
<p><code>sort:</code> 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 &quot;about&quot; or &quot;stick&quot; 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 &quot;Sorting&quot; section below for more details. If more than one sort tag is present, the first one will be used. Example: <code>sort:stickied</code> 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.</p>
<p><code>cat:</code> A category the entry will be filed under. An entry can have any number of category tags. Multiple cat tags can be used in a single file Example: <code>cat:Dogs</code> marks an entry that contains something relating to dogs. A tagpage that lists all entries with this tag will be generated.</p>
<p><code>top:</code> 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. Multiple top tags can be used in a single file Example: <code>top:Science:Mathematics</code> will include the entry's title in the topic tagpages/indexes &quot;Science&quot; and &quot;Science:Mathematics&quot;.</p>
<p><code>lang:</code> The language the entry is written in. Any string is accepted. You can use <code>lang:en</code> or <code>lang:English</code> or <code>lang:ENG</code> or whatever you like, as long as entries of the same language use the same tag. Only one language tag per entry is allowed. Multiple lang tags can be used in a single file Example: <code>lang:gr</code> tags an entry as being written in Greek.</p>
<p><code>author:</code> 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. Multiple author tags can be used in a single file Example: <code>author:Nickname7000</code></p>
<p><code>re:</code> 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. If more than one re tag is present, only the first one will be used. Example: <code>re:some_entry</code> links the entry that has this tag to the entry with the filename &quot;some_entry&quot;.</p>
<p><code>ref:</code> 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. If more than one ref tag is present, only the first one will be used. Example: <code>ref:entry0815</code> links the entry that has this tag to the entry with the filename &quot;entry0815&quot;.</p>
<p><code>reply:</code> 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. If more than one reply tag is present, only the first one will be used. Example: <code>reply:Some Questions</code> links the entry that has this tag to the entry with the filename &quot;Some Questions&quot;.</p>
<p><code>redirect:</code> 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. If more than one redirect tag is present, only the first one will be used. Example: <code>redirect:some_entry</code></p>
<h2 id="tagpages">Tagpages</h2>
<p>A tagpage is an HTML page generated by SBWG that lists all entries that contain a certain tag. Tagpages are created for every <code>cat:</code>, <code>top:</code>, <code>lang:</code> and <code>author:</code> 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 <code>author:foobär+cat:wildlife</code> 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 <code>perpage</code> 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.</p>
<p>Tagpages for <code>cat:</code>, <code>top:</code> and <code>lang:</code> tags include the whole entries including its meta information above the content. The entries' <code>created:</code>, <code>edited:</code> and <code>sort:</code> 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 <code>sort:</code> tag can overwrite those values. (See the &quot;Tag Types&quot; section above and the &quot;Sorting&quot; section below.)</p>
<p>Tagpages for <code>top:</code> 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 <code>top:Projects</code> will list all entries that are tagged with <code>top:Projects</code>, <code>top:Projects:Electronics</code>, <code>top:Projects:Art</code>, <code>top:Projects:DIY</code>, <code>top:Projects:Art:Wood Sculptures</code>, <code>top:Projects:Art:Wood Sculptures:Wood Sculptures of Tony</code>, and so on, sorted alphabetically by sub-topic and title.</p>
<h2 id="rss-feed">RSS Feed</h2>
<p>The only feed that is available for subscribing to blog entries is <code>all.rss</code>, a very simple RSS feed that contains all entries of the blog at once (except for stickied entries). The feed is updated with option <code>-r</code>/<code>--rss</code> (only the feed), <code>-b</code>/<code>--blog</code> (together with the rest of the blog) or <code>-c</code>/<code>--complete</code> (with a complete site generation). Please be aware that this is a very basic feed with a fixed language (en-uk), no rotation/paging and at least sub-par validity. (It will only validate if all entries have an author tag that contains an e-mail address. Additionally, the complete content of entries is used unparsed and unfiltered as the description of feed items.</p>
<p>Only slight improvements on the RSS feed are planned. Future versions if SBWG will probably generate better Atom feeds for individual authors, categories and topics. But right now <code>all.rss</code> is the only option.</p>
<h3 id="sorting">Sorting</h3>
<p>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.</p>
<p>All other tagpages (category, language, author and combined tagpages) are sorted by created date. If an entry does not have a <code>created:</code> 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 <code>edited:</code> tag, this edited date overwrites its created date, meaning entries that have been edited will be placed higher than they would otherwise. The <code>edited:</code> 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.</p>
<p>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 &quot;stickied&quot; so to speak.</p>
<p>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 <code>stick</code> or <code>about</code> will remove the title-wrapper of the entry on tagpages.</p>
<p>You may, for example, want something to appear above all entries on a specific tagpage, say the tagpage for the category &quot;Miscellaneous&quot; to explain what type of content you put in this category. In that case you can create an entry that has the tags <code>cat:Miscellaneous</code> and <code>sort:stickied</code> (or <code>sort:about</code>) 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.</p>
<p>Only one occurance of each of the three tag types that influence sorting is expected per entry.</p>
<p>Sort criteria summary:</p>
<ul>
<li><p>Sort order for each of the tags is ABCDEFGHIJKLMNOPQRSTUVWXYZ9876543210</p></li>
<li><p><code>sort:</code> overwrites <code>edited:</code> and <code>created:</code></p></li>
<li><p><code>edited:</code> overwrites <code>created:</code></p></li>
<li><p><code>creted:</code> is used if no <code>edited:</code> or <code>sort:</code> tags are present</p></li>
</ul>
<h2 id="tagicons-1">Tagicons</h2>
<p>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 <code>tagtype:tagname.png</code>.</p>
<p>Examples:</p>
<p>If you place a file called <code>lang:en.png</code> in this directory, the image is inserted in the header of every entry that's tagged with <code>lang:en</code>. The text <code>lang:en</code> will not be diplayed in the header, only the image.</p>
<p>If you place a file called <code>author:foobär.png</code> 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 <code>author:foobär</code>.</p>
<p>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.</p>
<p>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.</p>
<h1 id="entry-images">Entry Images</h1>
<p>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 <code>&lt;img&gt;</code> tag yourself or abusing the gallery feature.</p>
<h1 id="galleries">Galleries</h1>
<p>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 &quot;Hooks&quot; section above.)</p>
<p>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.</p>
<p>Upon generation of the web site, the images will be resized into three sizes:</p>
<p>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. <code>convert</code> or <code>mogrify</code> can be used for this.</p>
<h1 id="generating-a-web-site-command-line-options">Generating A Web Site (Command Line Options)</h1>
<p>The file name of the main script is <code>sbwg</code>. 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.</p>
<p>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.</p>
<p>Short and long format option can be mixed.</p>
<h2 id="actions-options-for-generating-parts-of-the-web-site">Actions (Options For Generating (Parts Of) The Web Site)</h2>
<p>The following options tell the script which parts of the web site should be generated/updated in this run.</p>
<p><code>--page</code> or <code>-p</code> [PAGENAME] Generates/updates all SBWG pages from the pages/ directory. If PAGE is specified: Genertes/updates only that page.</p>
<p><code>--entry</code> or <code>-e</code> [ENTRYNAME] Generates/updates all entries from the entries/ directory but not the corrosponding tagpages. If ENTRY is specified: Generates/updates only that entry.</p>
<p><code>--tagpage</code> or <code>-t</code> [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.</p>
<p><code>--blog</code> or <code>-b</code> Alias for -e -t -r. Generates/Updates entries, tagpages and the RSS feed.</p>
<p><code>--gallery</code> or <code>-g</code> [GALLERYNAME] Generates/Updates the gallery pages. If GALLERYNAME is specified: Generate only that gallery.</p>
<p><code>--rss</code> or <code>-r</code> Generates/Updates the rss feed all.rss. Other feed formats might be added in the future.</p>
<p><code>--files</code> or <code>-f</code> Copies the files from the files/directory to the root of the output directory.</p>
<p><code>--style</code> or <code>-s</code> [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.</p>
<p><code>--complete</code> or <code>-c</code> Alias for -p -e -t -r -g -f -s. Generates/updates the entire site.</p>
<p>If none of the above options is specified, nothing is generated.</p>
<h2 id="other-options">Other Options</h2>
<p>The following options mainly specify how and from/to where the web site should be generated.</p>
<p><code>--input</code> or <code>-i</code> 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.</p>
<p><code>--output</code> or <code>-o</code> 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, <code>html/</code> relative to the input directory will be used.</p>
<p><code>--webpath</code> or <code>-w</code> This option is obsolete and useless. It is not supported in current and future versions of SBWG. You may not use it.</p>
<p><code>--perpage</code> or <code>-p</code> 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.</p>
<p><code>--author</code> or <code>-a</code> 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.</p>
<p><code>--reduce-paths</code> or <code>-R</code> [NUM] Turn on pathreducer mode. If this option is supplied, the names of files that are generated by the script and of directories the script writes to are constructed in a way that minimises the risk that they will not meet the requirements of any target filesystem. They are converted to not contain any characters other than a-z, 0-9, underscore (_), dash (-) and a single dot (.) and are shortened if they would otherwise be longer than the specified maximum file name length. If NUM is given, that value is used as the maximum file name length in bytes. If the option is given without an argument, the value assigned to the variable <code>$maxfnl</code> in the web site's settings file will be used. If both aren't specified, the maximum file name length is set to 255 bytes. Files that are stored in the web site's <code>files/</code> directory will currently be copied into the output directory without change of filenames. The minimum value for the maximum file name length is 6 bytes. If the maximum filename lengh is specified as two numbers separated by a dot (.) (e.g. '8.3') the first number is used as the maximum basename length (maximum filename length without filename extension) and maximum directory name length and the second number is used as the maximum suffix length (length of the filename extension without the dot). Note that the paths generated with this option will differ from those of a web site that was generated without this option. Therefore using this option on a web site that previously was generated without this option, or changing the NUM value, may result in incompatible/dead links. This option slows down the generation process significantly.</p>
<p><code>--settings</code> or <code>-S</code> COMMANDS Commands supplied as an argument to this option are sourced by the script after the settings file has been sourced. COMMANDS can be one or more Bash commands (separated by semicolons but in a single word/string), like variable assignments, declarations of functions and so on. These settings complement or overwrite the settings contained in the settings file. This option can be used to temporarily add or change settings without editing the settings file, or to create different variants of a web site (e.g. with aliases for different commands for different settings).</p>
<p>A simple example would be to change the number of entries included per page in the weblog:</p>
<pre><code>sbwg --input ~/my_website --output /var/www --settings &#39;perpage=5&#39; --blog</code></pre>
<p>Another example would be to add or overwrite a hook:</p>
<pre><code>sbwg --input ~/my_website --output /var/www --settings &#39;hook_head() { o printf &quot;&lt;style&gt;p { color: #b05; }&lt;style&gt;&quot;; }&#39; --complete</code></pre>
<p>An advanced example would be to generate different parts of the web site using different web site names:</p>
<pre><code>sbwg --input ~/my_website --output /var/www --settings &#39;sitename=&quot;My Homepage&quot;&#39; --pages
sbwg --input ~/my_website --output /var/www --settings &#39;sitename=&quot;My Logbook&quot;&#39; --blog</code></pre>
<p>The <code>--settings</code> or <code>-S</code> option uses <code>eval</code> which can lead to problems with variable assignments in some rare cases. It is generally recommended to favour using the settings file over using this option. But it is an option for a quick hack or non-persistant changes to the settins.</p>
<p><code>--force</code> or <code>-F</code> 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 omitted, 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.)</p>
<p><code>--cache</code> or <code>-C</code> If this flag is set, SBWG will generate cache files and store them in the <code>cache/</code> directory inside the web site's source directory. Once this cache is generated, future generation processes can finish faster. But they also won't update any snipped for which a cache file still exists. 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. Cache files that have been generated with this option will also only be used with this option.</p>
<p><code>--update-only</code> or <code>--update</code> or <code>-U</code> (Not implemented, yet)</p>
<p><code>--verbose</code> or <code>-v</code> 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).</p>
<p><code>--very-verbose</code> or <code>-vv</code> 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).</p>
<p><code>--debug</code> or <code>-d</code> 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 debug mode just adds some additional information in the output that will likely not be of any use to you. Debug mode includes very verbose mode (see above).</p>
<p><code>--log</code> or <code>-l</code> [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. Log messages generated before the --log option was set (messages about enabling other options before the --log option) are not included in the log file. Every log message generated by SBWG includes a timestamp at the beginning of the line.</p>
<p><code>--help</code> or <code>-h</code> [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 page after the option. A list of available topics is printed when no argument is provided.</p>
<h2 id="example-commands">Example Commands</h2>
<p><code>sbwg -c</code> Generates/updates the complete web site from the sources in the current working directory into its default output directory.</p>
<p><code>sbwg -b -o /srv/stage</code> Updates the parts of the web site from the current working directory that make up the weblog of the web site into the directory <code>/srv/stage</code></p>
<p><code>sbwg -vv --input &quot;/home/user/my web site&quot; --pages</code> Updates only the static pages from the web site who's sources can be found in the directory <code>/home/user/my web site/</code> while displaying the progress of the generation process.</p>
<p><code>sbwg -p index --output ~</code> 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 <code>~/index.html</code>.</p>
<h1 id="other-remarks">Other Remarks</h1>
<p>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.</p>
<p>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. The HOWTO file didn't receive as much attention from me yet as this README file has. But it's there and will probably grow a lot in future versions.</p>
<p>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.</p>
<p>On security: Please keep in mind that all input from the command line, from a web site's source directory including its settings file and from the temporary directory is expected to be trustworthy. There are almost no measures in place that try to prevent exploitation of unintended possibilities deriving from the open design of this script. Tag values do get filtered to prevent them from breaking the generated HTML code. But even this can be circumvented by manipulating the cache files during the generation process. Code injection through the settings file is literally an intended feature and part of the concept that makes this script flexible, extendable and customisable for individual web sites.</p>
<p>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 <a href="http://www.wtfpl.net/txt/copying/">http://www.wtfpl.net/txt/copying/</a> for more details.</p>
