Thumbnails page with 3 subtitles and 2 text sections

Pictures appear variously in thumbnails pages, picture frame pages, and slide shows. All three are created from the captions file. Initial processing on the source platform is done by gendirs and genhtml. View-time processing on the server is described in Showing Pictures and Showing Slides.

In a captions file, each line that begins with "file: " starts a new segment. When "make build" is done in a captions file's source directory, the file is copied to the corresponding server directory, but generates no other files there. What is generated is one subdirectory for each segment. Each subdirectory has two files: index.php and localcaptions.cap. The latter is a copy of the lines for that segment in the original captions file. These files are sufficient for the server to generate the thumbnail page, the frame pages, and a slideshow.

A captions file has these kinds of lines:

• Text - plain or with embedded HTML.
• Keyword - keyword, colon, and a value for the keyword. A segment starts with a "file" keyword line
      file: Spring Spring Flowers
  (The first word after file: is the segment name; the rest is the segment title.)
• Property setting - very rarely it may be useful to change the value of a property. This line begins with a property name and an equal sign. The rest of the line is the value. The current (incorrect) implementation applies the property to the entire segment.
• Picture - picture file name and caption; like this
       [SAM01234.JPG] caption-text ...

Text, pictures, and captions are all combined in thumbnail pages; pictures are displayed in rows with text interspersed. Other types of pages display only pictures and captions. Note that if a newline precedes an attribute value assignment, the line looks like a Property setting line. Therefore a tag and its attributes must all appear on a single line.

Here's a bit of the segment for the thumbs page shown above. Note that  the pictures come from two different directories.

file: Spring Spring Flowers in Philadelphia and Pittsburgh
picturesdir: /pictures/2014/03-March
subtitle: Philadelphia Flower Show
Susan timed her talk at Rutgers to afford a visit to the flower show.
[IMG_20140303_162309.jpg] 
[IMG_20140303_125312.jpg] 
[IMG_20140303_125359.jpg] 
[IMG_20140303_142743.jpg] 
[IMG_20140303_163115.jpg] 

picturesdir: /pictures/2014/05-May
subtitle: Polinators in the Elizabethan Herb Garden
In 2008-9 I visited the herb garden daily, taking thousands of pictures. 
Now I'm taking pictures of pollinators for submission to 
<a href="http://bumblebeewatch.org/">Bumble Bee Watch</a>
[DSC03726.JPG] I'm back to taking pictures in the Herb Garden
[DSC03737.JPG] Now in the Herb Garden I'm taking pictures of polinators
[DSC03741.JPG] This guy was cruising all over the scotch broom
[DSC03793.JPG] Smaller bee or wasp
[DSC03769.JPG] Cricket sunning himself on a buttercup

On the source platform the above is just one segment in /annals/2014/captions.cap. On the server it generates the subdirectory /annals/2014/Spring and is stored in localcaptions.cap in that directory. (Note that on the server localcaptions.cap is a captions file for its own directory and does not generate a subdirectory.) In addition to the localcaptions.cap copies, the entire captions file is on the server at /annals/2014/captions.cap.

Here are the keywords:

file: segname Segment-Title-Words

Starts a new segment in the subdirectory named segname. The Segment-Title-Words appear as the title of the thumbnails page for this segment. (Any extension in segname is ignored.)

picturesdir: server-directory-for-pictures

Directory where subsequently named pictures will eventually reside on the server. The server location begins with the value of property PICTREESUBPATH, default value "/pictures". That start muist begin each server-directory-for-pictures. On the surce platform, pictures reside in subdirectories of PICTURESROOT. That name can be generated from the picturesdir value by substituting PICTURESROOT for PICTREESUBPATH.

 

Picturesdir lines may appear muliple times among the picture/caption lines, they can appear intermitently so they apply to multiple segments.

nextsegment: relative directory

Normally the next and back buttons from a thumbnails page point to adjacent segments in the captions file. This order may be revised with the nextsegment keyword. The value is relative to the containing directory; thus a sibling is written as just the name of the sibling.

prevsegment

Ala nextsegement, this keyword gives the relative location for the 'back' link from the thumbnails page.

subtitle

Text for a subtitle. These titles are displayed on green stripes between rows of thumbnails. The previous row may be incomplete.

any-property-name

Any property may have its value set by a keyword line. line continuation is not supported. One use of this is to vary the number of pictures in a row. A line to do so is simply "ncols: 3".

In captions, text, and keyword values, genhtml converts apostrophes and ampersands to &apos and &amp. Other entities are not processed (especially because embedded HTML is accepted); so you must write < where you want '<'.