garden tote with tools
 back link arrowPictools

Commands
 two beers
by Zweibieren
Up ArrowPhyspics
Up ArrowAnnals of ZB

This page details the commands and scripts noted in the overview. Along the way we will encounter these types of files, as denoted by their extensions.

.html - A web page.

.hin - This is the pictools extension for HTML source files. They must be processed through genhtml to create the .html file.

.tpl - this file is in .html format, but will serve as a template to be expanded. Templates are inputs to genhtml, gensite, and gendirs.

.jpg .gif .png .bmp - image files. Photographs are usually .jpg files because consideable file compression is possible in that file format. However, this format discards some of the original detail. The capitalized names are okay, too: .JPG .GIF .PNG .BMP.

"thumbs" - a thumb, or thumbnail, image is just a smaller version of a larger image. Typically one page will show thumbs for many images and clicking a thumb will show a larger version of the same image.

.cap - A captions file, with multiple segments. See next section.

.deps .hdeps -  MakeTargets generates these dependency files. They are included by MakeTargets itself to ensure that rebuilds happen when antecedent files change. .deps is for pictures from a DIGESTDIR; .hdeps is the dependencies of .html files generated from .hin files.

Captions files - xxx.cap

A captions file, xxx.cap, is references to pictures, grouped in segments. Each segment generates a webpage of thumbnail images. A segment begins with a header line:
file: segmentname title of segment
(The space after "file:" is mandatory.) For gensite, each segment  generates page segmentname.html. For gendirs, the segment is an entire directory named segmentname containing a webpage named index.html. 

Each line after a segment header corresponds to one image file. The format of a line is
[imagefilename] caption-text
The caption text will appear as the caption on the large-size image and the rollover text for the thumbnail. The images are those in the directory named in the DIGESTDIR variable in the Makefile for the directory containing the captions file.

Example captions.cap file (for physpics.com/annals/Korea2006/pix/):
file: apartment.txt Our apartment and its view
[100_2194.JPG] Kitchen as seen through living room.
[100_2207.JPG] June 23, View from our balcony. Hazy as usual.
[100_3097.JPG] July 11, Our balcony on a rare sunny morning.

The default name for a captions file is captions.cap. Any Makefile using MakeTargets has the target newpix. It creates file newpix.cap, but only if there is not already such a file. It is best to remove the contents of newpix.cap and insert them as an additional segment in captions.cap.

Tool: genhtml

Genhtml is a macro expander for generating web pages with build time macro expansion. Macros begin with a dollar-sign; non-macro dollar-signs must be written as two dollar-signs: $$.

Invocation
genhtml [options] [-o outfile] [infile]
Copies infile to outfile, replacing $xxx as noted below. If no infile is given,  copy stdin. If there is an infile, but no outfile, then a name is generated for outfile using the same name as infile, but  in the current directory and the extension changed to ".html". If neither infile nor outfile is given, genhtml copies stdin to stdout.

Command line options
-n ncols number of columns in table of pictures,
default 3
-c captionsfile captions file to expand for $pictures
(default: captions.cap)
-t "title string"
 value for $title. Default is one of infile, captionsfile, or "Untitled". Equivalent to
    -Dtitle="title string" -Dcity="title string"
Indeed, with -D, $city and $title can be given different values.
-f fdir $pictures() inserts in the file a table of thumbnails. Each links to a larger image with the same name, but in a different directory. fdir is the relative location of that directory. The link from a thumb image is to fdir/imagename.html. Usually fdir is a relative directory. Default is ".."
-Dsym=value Give sym the value.  (Example: -Dpicdir="..")
-depend
 Generates to the output file a list of files on which this one depends. This is intended mainly for use by MakeTargets, which uses it to be sure to regenerate a .html file when an antecedent has changed.

Macros

There are three basic forms of macro. Variants are described in the table in the next section.
variable values:  $name
  
The name is found in the symbol table. The entire macro call is replaced with the value found in the symbol table. A few variables have pre-defined values. Other variables may be given values with assignments (below) or on the command line with -Dsym=value
function calls: $name(argument)

The name must be one of the predefined functions. The argument is passed as text to the function and the value of the function replaces the entire macro call.
assignments: $name=(value)

This macro is replaced with the empty string. But first the name is entered into the symbol table with the given value.

In parenthesized strings—$sym=(xxx) or $sym(xxx)—a backslash protects the next following character if it is one of 
)  ]  '  "  %  \
So a right parenthesis inside a parameter is written as \). The following conversions are also made:
\n ==> newline
\r ==> carriage return
\t ==> tab
Any other instance of backslash is an error.

Within parameters, whitespace characters are ignored immediately after the leading '('. Otherwise, whitespace is unchanged except newlines become spaces. A warning is printed for the first newline in a parameter because it may signal a missing ')'. Newlines can be hard to avoid with some html editors; one way to avoid them is the judicious insertion in the HTML source of comments containing newlines:
<!--
-->
Macros supported

The following macro calls may appear:
$date(fmt) is replaced with date formatted by strftime.
$date like $date, but uses the dfeault format "%c (%Z)", eg:
        Mon Apr 01 13:13:13 1992 (EST)
$[filename] is replaced with a thumb image linked to an image
$system(cmd) is replaced with the result of running popen(cmd, "r")
$title
$city		 is replaced with the value from the -t option. The default is infile or else captionsfile, without its extension
$include(file) the contents of file are processed through genhtml and the results replace the macro call. The current instance of genhtml, with all its string definitions, is used.
$includebody(
    htmlfile)
 reads the html file and extracts the contents between <body> and </body>. These contents replace the macro call.
$pictures(f) $pictures(f) generates a <table> of pictures. See below.
$picdir is the directory for $pictures; default: "."
$$ is replaced with a single '$'
$sym=(value) is replaced by the empty string; however, it causes variable sym to have value (a string) as its value.
$sym
$sym;
${sym}
$(sym)
 is replaced by the value of sym, if one has been given. Otherwise, a value is sought from the environment. If none is found there either, an error message is logged.  The name 'sym' must consist only of upper and lower case letters.

$pictures(f)

$pictures generates a <table> of thumbnail pictures each linked to a larger version. f is the name of a .cap file.  If (f) is omitted, the name is taken from the -c option. If that, too, has been omited, the default is "captions.cap."

A .cap file has segments of multiple lines where the first line is
    file: segmentname Segment description text
The lines within a segment each refer to a picture:
    [imagename.ext] caption
From this list of pictures, $pictures creates a <table> of cells.
Each cell is for one picture. There are ncell cells per row. (Default 3.)
Each cell is an expansion of a pictd.tpl file. This file may be named by setting the pictd variable with -D on the command line:
    -Dpictd=filename.tpl
Otherwise the used is the first found among ./pictd.tpl, $PICTOOLS/pictd.tpl, and an internal dummy value.
 
For expanding pictd, the following variables are defined
       $piccaption    the caption from the line in the .cap file
       $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
       $picthumbsdir  directory for thumbs, relative to output file
       $picthumbsize  dimensions of the thumb file (see below)

Picdir and picthumbsdir are relative to the server directory having the page itself. Their default values are . and ./thumbs.

For finding sizes, genhtml needs to know at build time where the thumbnail pictures are relative to the directory where genhtml is being run. That value can be given with -Dpicthumbshome=dir. Otherwise the default is ./thumbs because gendirs runs genhtml in the staging directory where both the pictures and the generated .html file reside. There is no other dependency from genhtml on the pictures or thumbs. They do not necessarily exist.

If the thumb exists as $picthumbshome/imagename.jpg and has width ww and height hhh, then $picthumbsize has the value
        width='www' height='hhh'
otherwise it is the empty string.
       
Link kludges

Mozilla composer has some funny notions about changing link and image locations. To compensate, genhtml has funny notions of its own. It inserts .. before the slash in any of href="/, href='/, src="/, or src='/. And it deletes all but the last slash of file:///.  So these strings cannot appear in a file.  The workaround is to define a variable to have a single slash as its value:
        $slash=(/)
Then $slash; replaces every terminal slash:
         file://$slash;


Tool: genthumbs

Genthumbs scans the current directory to find all its .jgp, .gif, and .png images. For each it creates a thumbnail of a given maximum dimension, storing those thumbnails in a subdirectory named with the size: e.g. thumbs-128 for maximum dimension 128. The output is always a .jpg file.

Invocation
genhtml [maxdimension]
In practice, genthumbs is also used to generate the "full-sized" images for display on the website. Original images from my camera are 2304x1728 pixels, too large for most screens and too slow to download.


Tool: gencaps

Gencaps finds all the image files (.jpg, .gif, .png) in a directory and creates a captions file listing them, though with blank captions.

Invocation
gencaps [-d picturesdir] [-p prefix] [outputfilename|-]

Picturesdir is the directory to search for picture files. Default: ./.

With -p prefix, image file names must start with the prefix. The ordering of lines in the output file is found by sorting the names numerically with the prefix removed. Thus for "-p Slide" files named Slide9.JPG, Slide10.JPG, and Slide11.JPG, will be listed in that order.

By convention, outputfilename has extension .cap. The default is captions.cap. If outputfilename is a single dash, output is to stdout.

The generated file has one line per image. It lists the image file name in square brackets followed by a space:
[imagename.ext] <one space>
This file needs to be manually edited to create captions. While editing, lines may be deleted or reordered to affect the order of images in the generated .html files.


Tool: genother

When editing captions files, it is common to reorder them and delete some. The deleted entries will be in the installed directory, but  orphaned, without a link to them. Genother finds all images that are not mentioned in .cap files and writes (to stdout) a new captions text that just lists those orphans.

Invocation
genother [-k] [[-d] picturesdir]
Compares the list of picture files mentioned in local *.cap files to the list of files in directory picturesdir, output a list of files not mentioned. Default picturesdir is ./ .

Each output line is of form
[imagefilename.ext] imagefilename
so the file name serves as the caption. If the -k switch appears, the name after the ']' is omitted.


Tool: splittxt

Splittxt reads a segmented captions file and produces one captions file for each segment. Segments start with a line
file: segmentname title words ...
and continue to before the next such line or end of file. The idea is that you edit a single captions file, include segment headers, and then the individual captions files for each segment are generated by splittxt.

Invocation
splittxt  captionsfile
where captionsfile is the segmented captions file.

Extensions on segmentname are ignored. The files created are named segmentname.cap. For each segment, splittxt also writes to stdout one line for each file. This line is suitable to be part of a list in HTML source. It has the form:
<li><a href="segmentname.html">title words</a>
where title words are those following segmentname on the "file:" line.


Tool: gensite

Gensite processes a segmented .cap file and produces an HTML file for each segment. The HTML file begins as a template and is expanded by genhtml to have a section derived from the segment's captions. Typically, in a template for gensite, a click on a thumb image will bring up the full image in a separate window; that window is reused for viewing all full-sized images. See, for example, my Semester at Sea pictures.

Invocation
gensite [-n ncols] [-w wrapperfile] captions.cap
where ncols and wrapperfile are passed along to genhtml. The default ncols is 3. The default wrapperfile name is template.tpl.

The captions.cap file is divided into its segments and for each is created a captions file: segmentname.cap. (Any pre-existing segmentname.cap file is erased, and the new one is also erased after being used.) Then the html file is generated by calling
genhtml [-n ncols] -c segmentname.cap -o segmentname.html \
        -t "title words ..."   -D...   wrappername
In otherwords, genhtml is told to process the wrapper and use segmentname.cap to generate the contents of the $picture macro.

The -D... is a set of variable definitions:
prev segmentname for previous segment
previmg name of icon (Prev.gif or Prev-gray.gif)
next segmentname for next segment
nextimg name of icon (Next.gif or Next-gray.gif)
    
For each segment gensite writes to stdout the html to refer to the new segmentname.html:
<li><a href="segmentname.html">title words...</a></li>


Tool: gendirs

Gendirs is similar to gensite, but creates a new subdirectory for each segment of the captions file. The subdirectory has a separate HTML file for each photo. When viewing at the full-size, the pages cycle through these individual pages. There are not two windows as for gensite. One example is my pictures of Korea.

Invocation
gendirs [-n ncols] [-w indextemplate] [-v picfiletemplate] [-x piccelltemplate] captions.cap
where ncols is passed to genhtml as the number of columns in the table; indextemplate and picfiletemplate are each passed to genhtml as the template for one of two calls to genhtml, see below; and captions.cap is the segmented captions file. The defaults for indextemplate, picfiletemplate, and  piccelltemplateare ./template.tpl, ./frame.tpl, and ./pictd.tpl, respectively. If one is missing, the default from ${PICTOOLS} is used. (MakeVars also checks existence to pass templates to gendirs.) The variables set when one of these templates is instantiated are described in the distribution in pictools/picsrc/: template.tpl, frame.tpl, pictd.tpl. 

The captions.cap file has segment header lines of the form
file: segmentname title-words ...
For each segment, directory ./segmentname/ is created and populated with an index.html file and one file for each picture. The index.html is generated with this genhtml command:
genhtml -n ncols -c localsegmentname.cap -f segmentname \
    -t "title-words ..." -o segmentname/index.html indextemplate
(File localsegmentname.cap is temporary and is deleted.)
At the same time, gendirs writes to stdout the html to refer to the generated segmentname/index.html file:
        <li><a href="segmentname/index.html">title words ...</a></li>

While expanding indextemplate the following variables have these values
title Text following the segment name in the file: line.
city Same as $title.
prev, previmg, next, nextimg
 Links and button names to the previous and next segment.

The lines in segment localsegmentname.cap each have the form
 [imagename.ext] caption words ...
For each such line, an html file is generated in subdirectory segmentname/. This file is generated from picfiletemplate and piccelltemplate with this genhtml call:
genhtml -t "caption words ..." -D... \
  -o segmentname/imagename.html picfiletemplate
The -D... is a set of variable definitions:
caption caption words ... from the .cap line
index
 this is the indexth of the captions (the first is 1)
imagename imagename from the .cap line
imageext ext from the .cap line
prev, previmg, next, nextimg
 as for gensite
pictd
 piccelltemplate


Tools: nobg, nosur

Nobg and nosur are the halo removal tools. They process images to remove monochrome backgrounds.

Invocation
nobg  [-f fuzz-precent] [-b blur-spread] [-t] file [outfile]
nosur [-f fuzz-precent] [-b blur-spread] [-t] file [outfile]
Both scripts convert file to outfile, while making transparent the background (nobg) or surroundings (nosur). If outfile is omitted, the output is written to the file
fff-nobg.png  or  fff-nosur.png
where fff is the name file with its extension removed.

Command line options
-f fuzz-percent Percentage fuzz around transparency color.  All pixels having colors within this percent of the transparency color are also made transparent.  Default: 5
-b blur-spread A parameter to the ImageMagick blur operator. This operation blurs the edge of the non-transparent areas so they partially transparent. Form: RxS, where R is the blur radius and S the standard deviation. Either value may be a decimal value like 0.5. R can be made high without too much blurring of the image edges. S over 3 will blur image edges. For examples see the section on the Blur-Spread. Default: 10x2 
-t By default, images are trimmed to remove invisible outer rows or columns. The -t switch omits this step; so the image will remain its original size.


Tool: prerr

Prerr is a trivial C program that prints its command line argument to stderr. It is used for error messages in scripts whose output to stdout is usually redirected to a file.

Invocation
prerr text


Tool: gentransparencytable

The nobg and nosur scripts require a transparency table. This is created by running the gentransparencytable script. A version of the table is part of the distribution. This script merely regenerates it.

Invocation
gentransparencytable

Result is a file called transparencytable.png.

Tool: hex2rgb

Invocation
hex2rgb hexstring

Argument is six hex digits RRGGBB denoting a color. Result is the equivalent color denotation in the form
rgb(rrr, ggg, bbb)
where rrr is the decimal equivalent of RR, and similarly for ggg and bbb.

Tools:  tocyg,  towin

Convert between Unix and Windows file path syntax.

File path lists are delimited with these differences:

 Windows
 Cygwin
path list separator
 ;
 :
drive designation
 X:
 /cygdrive/X
directory separator
 \
 /
space
 (space)
 \(space)

Script towin converts from Cygwin to Windows and tocyg does the reverse.

Note that the path itself cannot be the argument to tocyg because spaces break up the argument and backslashes quote the next line.
So put the argument in single quotes and double all backslashes:
      tocyg 'c:\\foo\\goo hee;f:\\gee  whiz'
correctly produces
       /cygdrive/c/foo/goo\ hee:/cygdrive/f/gee\ \ whiz



Invocations
tocyg windows-pathlist
towin cygwin-pathlist
Copyright boilerplate for zweibieren
Copyright 2008, Zweibieren
8 Aug 2008  11:38 PM
Page maintained by Zweibieren  two steins of beer