> pictools > doc > genhtml
> pictools > doc > genhtml
Pictools: MakeFile Internals
V3.3 (428)
Macro-expander; used by gendirs
usage: genhtml [options] [-o outfile] [infile]

(The proper way to run genhtml is "make build" in a directory containing a "captions" file and a Makefile that includes MakeVars and MakeTargets.)

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

Expanding $pictures(f)

When it encounters $pictures(f), the genhtml scanner appplies another scan to generate the replacement value. It scans the file f, named in the argument. In the usual case, gendirs has created a directory for each segment in the captions file and has copied the lines from that segment to file localcaptions.cap in the segment's directory. That localcaptions file is the one supplied as f to be expanded. (To reiterate, the output of genhtml is going to be index.php in that same directory.) If (f) is omitted, the value from -c option is expanded.

f is a captions file. Its main contents are picture lines each having a picture filename in brackets followed by a caption:

[SAM10435.JPG] caption text describing the picture
screen dump for page http://physpics.com/annals/2012/LasVegas/index.php
Picture rows with subtitles
in green and text in white

The majority of the expansion for $pictures is a table of the thumbnails for these pictures. Paramenter/property ncols gives the number of table columns.

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.

When the genhtml scan of $pictures reaches a picture line, The picture cell contents are generated by expanding -/pictools/pictd.html, chosen because it is the value of the property thumbs.pictd. For that expansion, the following symbols are defined.

$piccaption the caption
$picalt the caption with <...> removed
$picimage name of image (html encoded, but no extension)
$picext extension on image name (not usually used)
$picdir directory of pictures, relative to output file
$subtitle current subtitle, if any
$picthumbsdir directory for thumbs, relative to output file

Copyright © 2016 ZweiBieren, All rights reserved. Jul 4, 2016 21:35 GMT Page maintained by ZweiBieren