Genhtml implements two related macro processoring scans.
At the outer level it copies infile to outfile,
replacing $xxx.
See Builtin Macros below.
At an inner level, when the scan of infile
encounters "$pictures", genhtml copies and expands a captions file into the outfile.
See Expanding $pictures below. In both scans, symbols are expanded. The $pictures scan adds special processing for text and references to pictures.
Usually genhtml is called from gendirs, once for each segment in the captions file. Gendirs is called by MakeTargets to process a directory's captions file.
In this case the infile is /library/thumbsparms.php, which gendirs chooses because it is the value of property thumbs.template. The outfile will be the index.php file in the segment's directory.
If called in some other situation and there is no infile, genhtml copies stdin.
If there is no outfile, but there is an infile,
its name is parsed into yyy/inname[.xxx] and the output file is created as ./inname.html.
If there is neither infile nor outfile, genhtml copies stdin to stdout.
Command line options
-n ncols |
number of columns in table generated for $pictures |
-c captionsfile |
name of file with captions to expand for $pictures (default: captions.cap) |
-t title |
value for $title, which may appear for subsitution in infile |
-Dsym=value |
give sym the value (Example: -Dpicdir="..") |
-Dpicdir=dir |
directory on server for pictures (default is ".", but this is incorrect for Physpics conventions) |
-Dpicthumbsdir=dir |
server directory for thumbnails; default picdir/thumbs |
Builtin Macros
In the infile there may appear macros in the form $xxx. Each is replaced as follows.
$$ |
replaced with a single $ |
$sym=(symvalue) |
replaced by nothing; however, sym is added to the symbol table
with the value symvalue |
$sym
$sym; |
$(sym)
${sym} |
four different syntaxes for replacement by the value of a symbol; see
Expanding symbols
|
$city |
synonym for $title |
$date(fmt) |
replaced with date formatted according to the strftime format given by fmt |
$date |
equivalent to $date("%c (%Z)"); example: Mon Apr 01 13:13:13 1992 (EST) |
$include(file) |
replaced with
preprocessed contents of file.
If the named file is absent an error is printed unless
the file name is preceded by a minus sign, - |
$includebody(file) |
includes
only the portion of the file within its <body> tag. |
$pictures(f) |
replaced with the expansion of the template file f, replacing builtin macros and adapting text into html. See Expanding $pictures |
$system(cmd) |
replaced
with the result of running popen(cmd, "r") |
$title |
replaced with the value
from the -t option.
The default is inname, if not empty,
or else captionsfile, without its extension. |
Expanding symbols
$sym or $sym; or $(sym) or ${sym} is replaced by the value of sym in the symbol table if there is one.
If sym is undefined, a value is sought from the environment;
otherwise the replacement is "$sym;" itself.
'sym' must consist only of upper and lower case letters.
Case is ignored--internally all symbols are converted to uppercase.
The value is macro-expanded just before insertion.
Symbols may be assigned values with $sym=(xxx). Characters are specially handled if preceded by backslash. If the next following character if it is one of ) ] ' " % \, the backslash is deleted and the character stays in place.
If the character is n, r, or t, the pair is converted to a new line, a carriage return or a tab, respectively. A backslash followed by any other character is an error.
Whitespace is stripped if it appears immediately after ( and [.
Otherwise, whitespace is unchanged except newlines become spaces.
A warning is printed for the first newline in a value
because that may signal a missing ')'.
(Newlines can be hard to avoid with some html editors;
one scheme is to insert strategically placed html comments
with embedded newlines).
The value returned by $(sym) or ${sym} can backslash-encoded for several diffeent contexts by preceding the closing bracket with colon and a code letter.
These codes are defined in src.c
:p - quote for PHP
:M - quote for Makefile
:j - quote for java
:c - quote for .c or .h or .C
:s - quote for within apostrophes in a shell script
Other caption file lines that begin "word: " provide values for subsequent lines. A line "picturesdir: directory-name" indicates where the pictures reside. A line "subtitle: text of subtitle" divides the table rows into groups or rows. In addition to "word:" lines and pictures, the captions file may contain text. Each text block is converted to html and inserted between rows of the picture table. If a subtitle or text block occurs before a table row is full, that row is completed with instances of /images/blackdot.png.
