NAME
customdoc.py - recursively descend through a
directory structure, changing HTML documentation files to correspond to
the directory structure on the local system.
SYNOPSIS
python customdoc.py oldstr newstr htmldir
DESCRIPTION
Files:
oldstr - strings that need to be changed in all HTML files
newstr - new strings to be substituted for strings in oldstr
htmldir - directories in which to begin the search.
customdoc.py begins in a high-level directory and recursively descends,
changing all HTML files. Symbolic links are not followed to avoid
redundant or unintended changes.
For every line in oldstr, there must be a corresponding line in
newstr.
Lines are read one at a time, and for each line, changes are made
consecutively, until all possible changes are made. For example, string
1 from oldstr is changed to string 1 from newstr, then string 2 from
oldstr is changed to string 2 from newstr, and so forth.
If no changes are made in a file, the file is left unmodified,
including date and filemode. If the file is changed, the old HTML file
is overwritten and the file mode is set to 644 (rw-r-r-).
EXAMPLE
Customizing BIRCH documentation files for a local
installation.
oldstr
%7E
http://home.cc.umanitoba.ca/~psgendb
http://www.umanitoba.ca/afs/plant_science/psgendb
psgendb@cc.umanitoba.ca
/home/psgendb
birch
newstr
~
file:///home/birch/public_html
file:///home/birch
birch@tux.mb.ca
/home/birch
birch
htmldir
/home/birch/public_html
In the example above, for each line, the first change made is to
convert '%7E' to '~' (tilda), just to keep things
consistent. Some HTML editors such as Netscape
Composer
will change tilda to ~, so this step just makes it easier to make
sure
that later changes will all be made. For BIRCH, the other lines above
are
as follows:
line 2 - Main URL for the BIRCH
system. This URL points to the directory for the main BIRCH Web site
eg.
/home/socs/birch/public_html. This is accessible through httpd in
oldstr,
and therefore is accessible to the world. In newstr, the 'file://'
string
tells a browser that this is a local file, only accessible to people
logged
into the local system. It all depends on how your local web site, if
any
is setup.
line 3 - This is an alternative URL pointing to
the BIRCH home directory. eg. /home/socs/birch. If symbolic links ARE
allowed,
you can simply make line 3 identical
to line 2. This works because symbolic links already exist within
public_html for important documentation directories such as doc, dat
and local.
line 4 - Email address for the BIRCH administrator. This will be
included in links from documentation so that users can mail the
sysadmin.
line 5 - The path for the BIRCH home directory
line 6 - userid for BIRCH system administrator
If your site DOES permit symbolic links in personal web sites
The symbolic link public_html/birchhomedir points to $BIRCH,
making
it easy to find documentation files by referencing the main $BIRCH
directory.
Thus, lines 2 and 3 in newstr should point to public_html
and
public_html/birchhomedir:
http://www.biology.abc.edu/~birch
http://www.biology.abc.edu/~birch/birchhomedir
Preventing lines from being changed
Any line containing the HTML comment <!-- DON'T CHANGE -->
will be left unchanged.
Tagging one or more lines to be omitted from the
output
When a line contains the HTML comment <!-- BEGIN DELETE -->,
customdoc.py deletes all lines until a line containing <!-- END
DELETE --> is found. For example,
<HTML>
<BODY>
This page will have only one line of text when processed.
<!-- BEGIN DELETE -->
The text in this section will
be deleted.
<!-- END DELETE -->
</BODY>
</HTML>
will be changed to
<HTML>
<BODY>
This page will have only one line of text when processed.
</BODY>
</HTML>
Replacing one or more lines with
HTML from another file
When a line contains the HTML comment
<!-- BEGIN REPLACE name="filename"
-->,
customdoc.py deletes all lines until a line containing <!-- END
REPLACE --> is found. For example,
<HTML>
<BODY>
This line won't be changed.
<!-- BEGIN REPLACE name="localident.html" -->
The text in this section will
be replaced.
<!-- END REPLACE -->
</BODY>
</HTML>
will be changed to
<HTML>
<BODY>
This line won't be changed.
<!-- BEGIN REPLACE name="localident.html" -->
This text was taken from the file localident.html
<!-- END REPLACE -->
</BODY>
</HTML>
Notes:
1. The path of filename is relative to the current directory.
2. customdoc.py does very primitive parsing of these pseudo-comment
lines. The pseudocomments must appear exactly as shown above. For
example, no blanks can appear between "name" and "=" or between "=" and
the filename.
AUTHOR
Dr. Brian Fristensky
Department of Plant Science
University of Manitoba
Winnipeg, MB Canada R3T 2N2
frist@cc.umanitoba.ca
http://home.cc.umanitoba.ca/~frist