> pictools > doc > properties
> pictools > doc > properties
Pictools: Building Sites and Pages
V3.3 (445)
Descriptions of all defined properties
usage: see propcon

Various sets of properties are defined and given default values in /Pictools.properties. This note describes those properties. They can be overridden as described in propertiesoverview.

Names in all-caps are property names. In Pictools.properties, names are always lower case. The propcon  tool converts them to all-caps for Makefiles and shell scripts.

Manager Identity

manager.name = ZweiBieren
This name appears as both the page maintainer and the copyright holder. You may wish to add properties to separate these roles.
manager.href = mailto: ZweiBieren@yahoo.com
Either a mailto: or a page URL The latter would allow you to log the message without forcing the user through an awkward transition to the user's mail agent. In at least one case where manager.href is used, the URL will include a query giving the page request that failed.

Directory Tree Properties

Directory and file names are relative to SRCROOT. They begin with a slash, and end without one. Allowed characters are letters, digits, dash, underline, and dot. Slash, colon, and tilde have their usual roles in path names.

The following properties are described at length and tested in MakeVars. They are usually given values in Pictools.properties. Directory paths must be in Cygwin form: they begin with /cygwin/ and separate names with slashes. A detailed description of these properties is in directories.php.

stagingarea = (edit /Pictools.properties to define this)
The path to the staging area created by 'make build'. Example value: /cygdrive/h/Fred/physpics.com
picsdir = (edit /Pictools.properties to define this)
A directory path on the server leading from the initial SSHDEST (or ftp if you haven't got ssh access) directory to the directory corresponding to SRCROOT. The value may be empty. Usually the value does not begin with a slash. Example for DreamHost: physpics.com   Example for Network Solutions: httpdocs
sshdest = (edit /Pictools.properties to define this)
User name and host name of server; separated with '@'. Example value: physpics@physpics.com

Pictures are organized in a tree on both local source web pages and the host server. The source picture tree structure is copied exactly into a subtree of the staging area and thence into a subtree on the server.

picturesroot = (edit /Pictools.properties to define this)
The root of the pictures tree on the local source pages. Example value: /cygdrive/p/DigestedPictures
pictreesubpath = /pictures
Server subtree for pictures. That is, the picture subtree resides in the staging area at $(STAGINGAREA)$(PICTREESUBPATH) and resides on the server at $(SSHDEST)$(PICSDIR)$(PICTREESUBPATH). Typical value: /pictures

Log Locations

The administrator /admin/command page shows information derived from the Apache server logs. These properties give the location of those logs.

log.http.access = (edit /Pictools.properties to define this)
Location of the Apache server access log for today. Example value: /home/physpics/logs/physpics.com/http/access.log
log.http.access0 = (edit /Pictools.properties to define this)
Location of the Apache server access log for yesterday. Example value: /home/physpics/logs/physpics.com/http/access.log.0
log.http.error = (edit /Pictools.properties to define this)
Location of the Apache server error log for today. Example value: /home/physpics/logs/physpics.com/http/error.log

Page layout properties

A Physpics page window is laid out in three rows, with three columns in the middle row. The middle cell of the middle row is the primary contents of the page. For the other cells, the properties shown here list the file(s) to be inserted.

— — page.toprow — —
(body cell)
— — page.bottomrow — —

The value of each property is a space-separated list of files. Before insertion into the page, initial "<link...>" lines are deleted (so css files can be available while editing the file). The actual page must make that stylesheet available.

page.toprow = /library/dirbar.php /library/titleandlogo.php
rows at top of page. dirbar.php is the Physpics logo and back links to parent pages titleandlogo.php has the title and page.mainlogo
page.leftcell = /library/blankleftcolumn.php
contents for left column on the page default is an empty column is placed inside <td class=leftcell>...</td>
page.rightcell = /library/adcolumn.php
contents for right column on the page is placed inside <td class=rightcell>...</td>
page.bottomrow = /library/copyright.php
the file used to generate the page trailer
page.bartitle =
word (or short phrase) to appear for this directory in dirbar.php. Default is the directory name. No HTML tags. #! private; is not inherited to descendant directories
page.maintitle =
title to appear on page (used in titleandlogo.php). Default, as set by beginpage, is "PhysPics " followed by the page's file name.
page.mainlogo = <img src=/images/null.GIF width=10 height=10 class=maintitlelogo />
logo to appear in titleandlogo.php. Uusually an <img.../>, but any HTML is allowed.. Default is an empty image
page.mainlogo.link =
URL destination for a click on page.mainlogo. Default: none.
tree.logo =
Alternate logo to display if there is no page.mainlogo. (However, most exisiting pages use page.mainlogo for the tree.)
bodytable.addtoclassattr =
A class name to be associated with <body> in a PhyspicsMain page the invocation is inside the value for the `class=' attribute.  However, a separate attribute can be added by putting a quote at the beginning of the value, as in:
bodytable.addtoclassattr:   attrname=attrvalue
One common usage is to add an onload attibute:
bodytable.addtoclassattr:   onload=loaded()

Picture pages and picture thumbs pages

Gendirs generates thumbs pages and frame pages. A thumbs page shows thumbnail versions of all the pictures in the segment. A frame page shows one picture per page.

thumbs.leftcell = &nbsp;
Left cell for thumbs.php
thumbs.rightcell = &nbsp;
Right cell for thumbs.php
thumbs.toprow: /library/dirbar.php /library/thumbstitle.php
The title bar layout for a thumbs index page.
thumbs.template = /library/thumbsparms.php
File that gendirs processes as the template for a thumbs page. (The expansion becomes segmentname/index.php.)
thumbs.wholepage = /library/thumbs.php
This page is instantiated (by segmentname/index.php on server) for a thumbs index page.
thumbs.pictd = /pictools/pictd.html
To make a thumbs page, genhtml macro-expands thumbs.pictd for each image; the expansion process replaces $xxx items with property values
thumbs.trailer = /library/picCopyright.php
Trailer (bottom row) for a thumbs index page.
frame.leftcell = &nbsp;
Left cell for frame.php
frame.rightcell = &nbsp;
Right cell for frame.php
frame.toprow: /library/frametitle.php
The title bar layout for a picture frame page.
frame.wholepage = /library/frame.php
The page instantiated for a picture frame page.
frame.trailer = /library/picCopyright.php
Trailer for a picture frame page.

Parameters for gendirs/genhtml

When a directory contains a captions file (xxx.cap) each file: line therein generates a directory in the staging area and on the web site. Generation is done by invoking gendirs.csh, which in turn calls genhtml for each segment. The following values control genhtml.

thumbscol = 5
How many columns of thumb images for gendirs to create.
imagescale = 648x648>
thumbscale = 144x144>
An ImageMagick rescaling parameter for pictures and thumbs. Examples: 33%, 768x768>, 576x576>. See ImageMagick's Image Geometry.

Prefetch Lists

If images are to change for mouseover, they must be prefetched to avoid a delay when the mouse first hits the image. If buttons appear on a page, the head area needs a prefetchlist call for each button set used. To facilitate this, SiteProps.php has a prefetchlist() method and several predefined sets of icons. The PhyspicsMain template suggests prefetching one set of icons by including the the line


This line is in an editable part of the template and should often be revised or deleted. Additional lines can be added to prefetch more than one set of icons. Here are the predefined sets. The first element in each list is the directory housing the icons.

prefetch.PIXBLOG = /images/ \
PIX.png PIXa.png PIXh.png PIXv.png BLOG.png   \
BLOGa.png BLOGh.png BLOGv.png
prefetch.PREVNEXT = /images/ \
NEXTbutton.png NEXTbuttong.png NEXTbuttonh.png \
PREVbutton.png PREVbuttong.png PREVbuttonh.png \
UPbutton.png UPbuttong.png UPbuttonh.png EMPTYbutton.png
prefetch.identitymarks = /images/ \
logos/logoh36.png logos/logoh36B.png \

Other Properties

#! private
downloadable = mime.xls mime.xls.gz
The point of the downloadable property is to forbid access to some files. A file is unrestricted if its extension is in a normally-downloadable set {bmp, css, gif, htm, html, ico, jpg, js, pdf, php, png, txt} or if its MIME type begins video or audio. Otherwise it can only be downloaded or viewed if allowed by the downloadable property for its directory. The propery value is a space-separated list of items. A file is eligible for download if its name appears in the list. It is also eligible if a list entry contains an asterisk and the beginning of the file's name matches the string before the asterisk while the end of the file's name matches the string after the asterisk. For instance, a list entry pix*xml makes downloadable any of these files:  pixA.xml, pixBB.xml, pixxml, and even pixml. (Check for yourself that the last precisely matches the definition.) (See also the downloadable function in mimetype.php.)
When a downloadable list applies only to the current directory the #!private pragma is appropriate. However, the pragma should be omited if, as in /Java/, the downloadable property contains an * entry, say *.jar, which is applicable to the entire dierectory subtree.
picscp = scp
The best way to send files to the server is with scp. (And see how get away without passwords.) If scp cannot be made to work, you may set picscp to fakescp to use ftp. (At this writing, fakescp is inapplicable to saving pictures and picture page because tar|ssh tar is used for copying the to the server. MakeTargets and MakeServerPix would have to be modified.)
picpass =
If picscp has the value fakescp, the ftp password must be supplied. It may be set
  • in response to a prompt from MakeVars
  • in a shell environment variable, PICPASS
  • as the value of this property, picpass
These three options are in decreasing order of security and increasing order of convenience. The first two are preferable. If you do choose to put the password in a file, I recommend Pictools.properties in your home directory (/home/your-cygwin-user-id/Pictools.properties); it is less likely to be uploaded by accident.
propcon.directory = (will be set by propcon)
The directory containing this instance of Pictools.properties. The propcon program itself inserts this definition into generated files.

Properties Usually Set Elsewhere

These first three properties must be set in the shell environment instead of a Pictools.properties file. Set the first two in $HOME/.login or $HOME/.profile. See step 6 of setup.php. The third can be set directly in the shhell where you are running make. See the Debugging section of pages.php.

Shell Environment Sample value 
   SRCROOT/cygwin/g/Fred/PhysPicsDirectory containing the root of the installation
   PICTOOLS/cygwin/g/Fred/PhysPics/pictoolsDirectory containing the pictools tools
   PICTOOLSDEBUG 1    When set, some build commands send info to /tmp/pictoolsdebug.log

The folllowing should usually be assigned values in a Makefile, because they apply to building only one directory. If they are to apply to an entire directory tree, they can be defined in Pictools.properties. For definitions see the description of MakeVars.

Optional VariablesSample valueSet these variables in a Makefile, if needed
   SUBDIRS images library ... Subdirectories to be processed for buildall
   COPYFILES file1 file2 ... Files to be copied to STAGE and then uploaded
   BUILDTOSTAGE file1 file2 ...Files to be built directly into STAGE
   BUILDONLY file1 file2 ...Files to be built locally (& not copied)
   DEFINES -Dv1=value1\
-DtripTitle="Spring, 2007"
Definitions for genhtml
  AFTERSSH sleep 10 Executed after each ssh command for upload; necessary for major uploads to DreamHost
   LOCALJUNK testout.txt *.o foo*Files to be deleted for make clean
Directory Variables Assigned ValueThese are set by MakeVars
   _SITEPATH (computed)Path from $(SRCROOT) to $(CURDIR), example /annals/2015
   STAGE ${STAGINGAREA}${_SITEPATH} 'build' places files in STAGE
   SERVER $(SSHDEST):$(PICSDIR)$(_SITEPATH)'upload' copies files from STAGE to SERVER
   SRC $(CURDIR)The initial current directory
Content listsDefault valueThese are set by MakeVars, but may be reset in a Makefile
   HTMLFILES *.htmlHTML files to be uploaded
   IMAGEFILES *.png *.PNG *.jpg *.JPG
*.gif *.GIF *.bmp *.BMP
Image files to be uploaded
   JSFILES *.jsJavaScript files to be uploaded
   CSSFILES *.cssCSS style files to be uploaded
   PHPFILES *.phpPHP files to be uploaded
   CAPFILE *.capCaptions file to be processed (only one is allowed)
   JUNKFILES *~ $(LOCALJUNK)Files to be deleted by 'make clean'
Copyright © 2023 ZweiBieren, All rights reserved. Feb 5, 2023 17:05 GMT Page maintained by ZweiBieren