~ - 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
.)
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, "m
ake 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.
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 |
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.