created:2021-05-14
author:Foobär
top:README:Generating a web site
sort:003
title:Generating a web site (command line options)

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

<h3>Options For Generating (Parts Of) The Web Site</h3>

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

<ul>
<li><code>--page</code> or <code>-p</code> [PAGENAME]<br />
Generates/updates all SBWG pages from the pages/ directory. If PAGE is specified: Genertes/updates only that page.</li>

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

<li><code>--tagpage</code> or <code>-t</code> [TAGNAME]<br />
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.</li>

<li><code>--blog</code> or <code>-b</code><br />
Alias for -e -t -r. Generates/Updates entries, tagpages and the RSS feed.</li>

<li><code>--gallery</code> or <code>-g</code> [GALLERYNAME]<br />
Generates/Updates the gallery pages. If GALLERYNAME is specified: Generate only that gallery.</li>

<li><code>--rss</code> or <code>-r</code><br />
Generates/Updates the rss feed all.rss. Other feed formats might be added in the future.</li>

<li><code>--files</code> or <code>-f</code><br />
Copies the files from the files/directory to the root of the output directory.</li>

<li><code>--style</code> or <code>-s</code> [STYLESETNAME]<br />
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.</li>

<li><code>--complete</code> or <code>-c</code><br />
Alias for -p -e -t -r -g -f -s. Generates/updates the entire site.</li>

<p>If none of the above options is specified, nothing is generated.</p>

<h3>Other Options</h3>

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

<li><code>--input</code> or <code>-i</code> INPUTDIR<br />
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.</li>

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

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

<li><code>--perpage</code> or <code>-p</code> NUM<br />
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.</li>

<li><code>--author</code> or <code>-a</code> AUTHORNAME<br />
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.</li>

<li><code>--verbose</code> or <code>-v</code><br />
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).</li>

<li><code>--very-verbose</code> or <code>-vv</code><br />
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).</li>

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

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

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