> pictools > doc > directories
> pictools > doc > directories
Pictools: Building Sites and Pages
V3.3 (445)
Directory structure on devlopment site and server

~ - 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

A pathname beginning with slash is relative to SRCROOT. (Prepend SRCROOT unless the pathname begins with /cygwin.)
SRCROOT must be defined in the shell environment. Other ALL-CAPS terms are properties defined in /Pictools.properties. See setup.php.

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.

Spaces in file or directory names will fail with Pictools.

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.

directory trees on the source platorm and the server

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:

relations among picture directories

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.)

The path to the tree of directories holding the source. Example value: /cygdrive/h/Fred/websrc.
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:

The path to the tree of directories holding the staging area. Example value: /cygdrive/h/Fred/physpics.com
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
User name and host name of server; separated with '@'. Example value: physpics@physpics.com
The root of the pictures tree on the local source pages. Example value:/cygdrive/p/DigestedPictures
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
Files in staging area STAGINGAREA/annals/2015/ index.php
Files on server SSHDEST/PICSDIR/annals/2015/ copies of the files in the staging area
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.

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.

Copyright © 2023 ZweiBieren, All rights reserved. Mar 19, 2023 15:03 GMT Page maintained by ZweiBieren