update January 7, 2020
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
  ~
  http://home.cc.umanitoba.ca/~psgendb
  http://www.umanitoba.ca/afs/plant_science/psgendb
  psgendb@cc.umanitoba.ca
  /home/psgendb
  psgendb
newstr
  ~
  http://home.cc.umanitoba.ca/~psgendb
  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 '~' 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/psgendb/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/psgendb. 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

There are two ways to protect lines from being changed.

1) DEPRECATED: Any line containing the HTML comment <!-- DON'T CHANGE -->  will be left unchanged.

2) An entire block of HTML can be protected

<HTML>
<BODY>
Any text here may be changed.
<!-- BEGIN PROTECT -->
Nothing in this section will be changed.
For example, the anchor tag below originally was on a single line, but the SeaMonkey Composer automatically splits up the anchor in the HTML code:

<a
   href="ftp://ftp.cc.umanitoba.ca/psgendb/BIRCH/data/blreads/genome">ftp://ftp.cc.umanitoba.ca/psgendb/BIRCH/data/blreads/genome</a>.

Thus, 'psgendb' would be changed to birch, at most BIRCH sites, which would break the link. The
PROTECT tags allow us to protect the entire block from change.
<!-- END PROTECT -->
</BODY>
</HTML>

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.
BUGS
1.  In Python2, very little checking was done to find encoding for text files.  Python3 is does more checking, and has a number of ways to handle encodings. The current approach used by customdoc.py is to explicitly set the encoding when opening a text file. For web pages in English, latin-1 usually works. All bets are off for other languages and Unicode encodings.  For a thorough discussion see:
http://python-notes.curiousefficiency.org/en/latest/python3/text_file_processing.html#files-with-a-reliable-encoding-marker
   

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