~ - The Home Directory

On my development box, I have three home directories, as defined by Windows, by Linux, and by me. Their locations in the two filesystems are:

defined by	Windows location	Cygwin location
Windows	C:\Users\Fred	/cygdrive/C/Users/Fred
Cygwin	C:\cygwin64\home\Fred	/home/Fred
me	U:\Fred	/cygdrive/U/Fred

By putting my own home, and thus my files, in the U: partition, I achieve some isolation of my files from the operating system. Rewriting the system files in C: will not affect files in the U:.

Unix commands expect the home directory to be named in the HOME environment variable. Initially Cygwin sets HOME to /home/user-name where the user-name is derived from Windows by dark magic. To cope, I have one .login file in /home/Fred and another in U:\Fred. The first is read initially; it resets

This note has numerous sections all attempting to say the same things. All you need to know is

• Page source files are in a tree of directories rooted at SRCROOT. Each directory has a Makefile.
• In a page source directory, "make build" copies or builds the local files into a corresponding directory in a staging area.
• And "make upload" copies files from the staging area to the corresponding directory on the server.
• Picture originals are in a separate tree of directories rooted at PICTURESROOT.
• A captions file in a page source directory designates one or more picture originals directories.
• In a page source directory that contains a captions file, "make upload" will install scaled versions of pictures from the designated picture originals directories into the staging area and thence to the server.

At any point below, when you've grasped the above, you can skip reading the rest of this note.

If you are curious, the staging area location is given by property STAGINGAREA and picture originals are scaled into the staging area at STAGINGAREA/PICTREESUBPATH. On the server, pages are under the directory named by SSHDEST/PICSDIR and scaled pictures are rooted at SSHDEST/PICSDIR/PICTREESUBPATH.

The tree of web pages

A web page URL, say physpics.com/pictools/doc/directories.php, has a domain name (here in blue) followed by a path (here in purple). The path is written as slashes and names. With Pictools a path name correspond directly to a directory and file name on the server. On the source platform, Pictools organizes the source files in the same directory structure. Development systems like DreamWeaver do the same; and saving a file on the source platform simultaneously saves it to the server.

With Pictools some files need to be constructed; they are constructed into a "staging" area on the source platform and copied from there to the server. The construction and upload are managed by a Makefile in the source directory. This diagram shows the source and staging directory trees on the source platform and the directory tree on the server. The developer creates files only in the SRC directory, shown in yellow; it must be a subdirectory of SRCROOT. The Makefile sets _SITEPATH by removing SRCROOT from the front of SRC. For target 'build', the Makefile copies or builds from SRCROOT/_SITEPATH to STAGINGAREA/_SITEPATH. For target 'upload', the Makefile copies from STAGINGAREA/_SITEPATH to SSHDIR/PICSDIR/_SITEPATH. The names in all-caps are properties; you need to know them only during Pictools setup or if you choose to modify MakeTargets.

Pictures reside on the source platform in their own tree rooted at PICTURESROOT. In MakeServerPix, _SITEPATH is the path from PICTURESROOT to the pictures source directory. MakeServerPix scales the pictures to a directory within the staging area and uploads them to the corresponding server directory. The stage and server directories reside under the main tree at the location given by property PICTREESUBPATH. Thus the 'build' target scales pictures from PICTURESROOT/_SITEPATH to STAGINGAREA/PICTREESUBPATH/_SITEPATH and 'upload' copies the scaled pictures from there to SSHDIR/PICSDIR/PICTREESUBPATH/_SITEPATH. All this is represented in this diagram:

Pictures on the website are displayed under control of captionFiles in source root directories. When a caption file mentions a picture tree directory, the pictures in that directory are scaled to the staging area and later uploaded. For a concrete example, letting PTSP_SP stand for PICTREESUBPATH/_SITEPATH:

Consider picture SAM324.JPG	with unscaled version in	PICTURESROOT/_SITEPATH/
Suppose SAM324.JPG	is mentioned in	SRCROOT/srcpath/caps.cap
under a picturesdir: line	whose value is directory	PICTREESUBPATH/_SITEPATH *
Then "make build" in SRCROOT/srcpath/	will run MakeServerPix build	in directory PICTURESROOT/_SITEPATH/ *
MakeServerPix build	scales SAM324.JPG into	STAGINGAREA/PTSP_SP/
and also	creates a thumbnail in	{ditto}/thumbs/
Later "make upload" in SRCROOT/srcpath/	will run MakeServerPix upload	in directory PICTURESROOT/_SITEPATH/ *
MakeServerPix upload	uploads the scaled SAM324.JPG to	SSHDEST/PICSDIR/PTSP_SP/
and also	uploads the thumbnail to	{ditto}/thumbs/
* Yes, The prefix is PICTREESUBPATH in the captions file, while the source location is PICTURESROOT.

Properties that must have values in the cygwin environment. (See setup.)

SRCROOT

The path to the tree of directories holding the source. Example value: /cygdrive/h/Fred/websrc.

PICTOOLS

The directory where Pictools are installed. The recommended installation has Pictools at SRCROOT/pictools. (But Pictools will not check that location; PICTOOLS must be set explicitly.)  The Pictools directory should also be listed in the environment's PATH value, so the tools can be executed without giving their path location.

Properties to be given values in Pictools.properties during setup:

stagingarea:

The path to the tree of directories holding the staging area. Example value: /cygdrive/h/Fred/physpics.com

picsdir:

A directory path on the server leading from the initial SSHDEST 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:

User name and host name of server; separated with '@'. Example value: physpics@physpics.com

picturesroot:

The root of the pictures tree on the local source pages. Example value:/cygdrive/p/DigestedPictures

pictreesubpath:

Subtree of pictures. That is, the picture subtree resides in the staging area at $(STAGINGAREA)$(PICTREESUBPATH) and on the server at $(SSHDEST)$(PICSDIR)$(PICTREESUBPATH). Example value: /pictures

Major Groups and Segments

Pictools displays pictures in "segments" within "major groups". A major group might be all the pictures for one year. Segments are topics within the group; perhaps one for each vacation trip. Each segment is displayed as a thumbnails page. In the source tree, there is a directory for each major group; it has at least an index file and a captions file. The index file is manually created and should have a link to each thumbnails page. The source tree has no files or directories for segments; these are generated automatically.

As an example, consider a single group, 2015, with two segments East and South. They are created because file 2015-captions.cap has the lines

file: East Title for the "East" files
     . . . (picture name-and-caption lines)
      file: South Our March getaway
    . . . (picture name-and-caption lines)

From these the Makefile creates files in the staging area and on the server, resulting in all these files:

description	location	contents
Group Source files	SRCROOT/annals/2015/	Makefile index.php 2015-captions.cap Pictools.properties
Files in staging area	STAGINGAREA/annals/2015/	index.php 2015-captions.cap East/index.php East/localcaptions.cap South/index.php South/localcaptions.cap
Files on server	SSHDEST/PICSDIR/annals/2015/	copies of the files in the staging area

The pictures themselves are in another tree of directories, rooted at PICTURESROOT. The captions file contains 'picturesdir:' lines gving the location of the pictures named in subsequent picture name-and-caption lines. A picturesdir: lines may appear anywhere in the captions file. For our example, all 2015 pictures are in directory PICTURESROOT/2015, so only a single picturesdir line is needed. It can be at the beginning of the captions file before the lines listed above.:

picturesdir: /pictures/2015

(For historical reasons, the picturesdir value begins "/pictures", which is where the pictures will later reside on the server. This name is the value of the property PICTREESUBPATH. On the source computer, pictures reside in the directory named by the PIcTURESROOT property.)

Suppose our example has source pictures IMG1.JPG, ... Then the Makefile generates sraging area and server pictures like this:

description	location	contents
Pictures source	PICTURESROOT/2015/	IMG1.JPG ...
Pictures in staging area	STAGINGAREA/pictures/2015/	scaled versions of IMG1.JPG ...
Thumbs in staging area	STAGINGAREA/pictures/2015/thumbs/	thumb-sized versions of IMG1.JPG ...
Pictures on server	SSHDEST/PICSDIR/pictures/2015/	duplicate of the staging area

The single Makefile for the group--listed above in the first table row--generates all the staging area and server files.