treewebber - generate WWW pages from filesystem tree
How to get help: If one of the --help options is specified once a short overview will be printed; if specified twice you will get detailed information about command line options. --man gives you the whole manual.
treewebber [-a, --all] [--css FILE] [-f, --force] [--index-name STRING] [--sitemap-name STRING] [-v, --verbose STRING] DIRECTORY
treewebber -?, -h, --help | --man
treewebber -V, --version
The idea behind treewebber is to generate web pages automatically by traversing a directory tree and looking for so-called description files (see below). These files contain meta data and provide the information necessary to generate index pages and navigation between them.
The program starts its directory tree traversal in the given DIRECTORY and therein creates the web pages. Thus, if you are new to this program, make a backup of that directory first in order not to clobber any files by mistake.
For each file that you want to appear on the generated pages there must be a description file. The same holds true for directories. In this case the absence of a description file also prevents recursion into this directory so that nothing inside this directory is indexed.
Description files must have the same name as the file or directory they describe with an appended `.desc'. For example, the description file for `download.tar.gz' would be `download.tar.gz.desc'. And to include the directory `articles' there must be a file named `articles.desc' besides the directory itself. There is also one special case: following these rules it would be necessary to create a file one level above the given DIRECTORY if you wanted to add a description file for the root directory in which the program starts (i.e. ../DIRECTORY.desc). Do not do that. Instead, create a file simply named .desc within DIRECTORY.
The existence of such a description file suffices if you want a link to be generated, but in most cases you will at least add some lines of text that describe the file or directory. If the describing text is quite long you may structure it into paragraphs by using blank lines; this will enclose text blocks in html <p> elements. For further formatting, e.g. bold face or italics, you may also use HTML markup.
In the description files, all lines are regarded to be part of the descriptive text unless they start with one of the following keywords. If the first non-blank character of a line is the `at-character' then one of these keywords is expected; otherwise a warning is issued. These keywords allow you to set some options that are explained in the following paragraphs.
This table lists all valid keywords; some of them expect a value that is defined after an equal sign (`='). Spaces around the equal sign are optional. Some of these keywords are only allowed in description files for either files or directories, and some are valid for both types.
Keyword allowed in ... files directories
@LABEL = <string> X X
@SHORT = <string> X X
@POSITION = <integer> X X
@DEPRECATED X X
@NAVLABEL = <string> X
@OVERVIEW X
@TARGET = <string> X
@TEXT2HTML X
@VERSION = <string> X
This table shows which keywords can be used depending on the type of file that is described.
If @LABEL is set its value will be used as name for the generated link instead of the name of the linked file or directory.
@SHORT allows you to specify a short description that will be used if the @OVERVIEW keyword for the containing folder is set (see below). The overview table will contain that short description.
The @POSITION keyword can be used to specify the order in which the folder contents will be presented. This keyword's value must be a positive number or zero. The rule is: the smaller the number, the earlier the entry appears on the page. Entries that have no defined @POSITION will appear after all other entries that have this keyword set to some valid value. Entries that are on the same level of positioning, i.e. have the same @POSITION value or none at all, will be ordered in the following way: directories before files and then ordered lexically.
As a service for your website's visitors you can set the @DEPRECATED keyword for entries that you are planning to remove soon.
The @NAVLABEL keyword allows you to specify an alternate label for a directory that will be used in the navigation bars. For example, if one of your directory labels is `Miscellaneous' it might be desirable to create a navigation link labelled `Misc'. If this keyword is not set, @LABEL (or the directory name) will be used instead.
If @OVERVIEW is set in a directory description file the generated index page will start with an overview table that summarizes the page content (see also: @SHORT).
The @TARGET keyword makes it possible to create links that point to files located in folders that are not processed by treewebber. In the normal processing of a directory, the link points to the generated index file inside that directory. To change the index file, use the --index-name command line argument. By default, such a link's target will be <directory_name>/index.html. To make the index point to some other file, set @TARGET to any filename that exists inside the directory. The result is a link on the parent directory's index page along with some descriptive words pointing to the file you chose. Note that using the @TARGET keyword implicitly prevents treewebber from descending into the directory. In other words, a link to the specified target will be created but the contents of the directory will not be processed.
The @TEXT2HTML keyword specifies that the corresponding simple text file has preformatted content. If this keyword is set an HTML page will be generated from the original file. The original file will not be modified. The advantage of the HTML-based page is that it integrates well with the website's navigation and style. The actual page content will not be modified but rather included verbatim.
The @VERSION takes an arbitrary string that represents the file's version. Examples are 0.21 or 1.5 or 1.0pre5. This keyword can indicate the progress of a program or document.
The appearance of the generated pages can be influenced by using a style sheet file (see --css option below), which is highly recommended. Besides the usual style settings there are some special classes that are used by treewebber and therefore should be defined:
It is easily possible to include pages with arbitrary content into the generated web. For example, to include a contact page that is properly linked, has a navigation bar and has the same style as all other pages, follow these steps:
This paragraph describes the possible options that can be used to modify this program's behaviour. If a long option name requires an argument then the short form does so, too. Long names can be abbreviated but must stay unique.
If this option is omitted, treewebber tests whether one of the following files exist. It searches for the files in the order shown, and uses the first file found: style.css stylesheet.css style-sheet.css
The generated pages reference the style sheet file by relative paths. The pages can thus be correctly displayed on a local webserver as well as on some public webserver with an arbitrary domain name.
More specifically, without --force the following optimizations take place: (1) Index pages are updated only if their content has changed. (2) Files that have the @TEXT2HTML keyword in their description file are converted only if the plain text file is newer than the generated HTML. (3) Web pages based on HTML include files re-generated only if the include file is newer than the generated one.
Cases 2 and 3 depend on the files' modification time, so if your files' timestamps were modified by accident (e.g. you cp'ed the files without -p) you may need this option.
The site map is a page that visualizes the tree structure of the website and thus helps navigating. Each page contains a link to the site map in its navigation bar.
STRING defaults to INFO which means that all messages from the categories
FATAL, ERROR, WARN and INFO will be reported.
Possible values for STRING are:
FATAL ERROR WARN INFO MORE
Copyright (C) 2005 Joachim Jautz http://www.jay-jay.net/contact.html
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA