Program: autocontent

This utility parses a list of scripts, extracts the comments
from within the script, and builds HTML snippets from the
extracted comments and source code.
It uses a data file to specify the machine and full path
file name of the source file. Also specified in the data
file is the machine and directory location where the
HTML snippets will be placed.


Usage: autocontent {-d|-l|-f datafile} [-v] [-o] [-c|-u] [-?]

    Where -d = Use ./AutoContent.dat as the data file
          -l = Use /usr/local/AutoContent/AutoContent.dat as the data file
          -f datafile = Specify the AutoContent Data File
          -v = Verbose Mode
          -o = Send all HTML output to STDOUT
          -c = Generate code document only
          -u = Generate usage document only
          -? = Display usage and help message

Author: Dana French (dfrench@mtxia.com)

"AutoContent" enabled

Description:

This utility parses a list of scripts, extracts the comments from within the script, and builds HTML snippets from the extracted comments and source code. The HTML snippet is saved in a location designated by the user under a file name comprised of the original file name suffix up to the first dot ".", followed by ".content.shtml". The "shtml" extention is used because the HTML snippet is intended to be used as part of a server-side include document on a web server.

Operation of "AutoContent" is controlled by a data file that contains information about the files to be processed. Each line of the data file represents a record of information and is processed in sequence. Each line of data should be formatted into a "source" and "destination" portion. The source portion designates a file to be processed by "AutoContent" and the machine on which it resides. The destination portion of the data line designates a machine and directory location to place the results of the processing.

The data file consists of a series of lines, one record per line. A record consists of several fields specifying the source machine, full path file name, followed by an optional field whose contents are variable. The next field specifies the destination machine and should be separated from the previous set of "source" fields using a space, tab, pipe symbol or comma. Following the destination machine name should be the full path destination directory name.

Example data file records:

xyzmach:/usr/local/bin/script01.ksh:-? webserver:/www/httpd/html/scripts

xyzmach:/usr/local/bin/script02.ksh|webserver:/www/httpd/html/scripts

xyzmach:/usr/local/bin/script03.ksh:-?,webserver:/www/httpd/html/scripts

In the above examples, the optional field following the full path source file name contains the characters "-?". This causes "AutoContent" to execute this script with a "-?" option on the command line expecting to receive a usage message. The usage message is captured and added to the documentation.

Assumptions:

It is assumed that any file defined in the data file with the "-?" optional field, is an executable file, recognizes the "-?" option and generates a usage message if the script is executed with that option. Each file defined using the "-?" optional field WILL BE EXECUTED with the "-?" option to generate the usage message. If the script does not recognize the "-?" option, THE SCRIPT WILL EXECUTE as though no command line arguments were provided and perform whatever tasks it does under that condition. Be sure that any file referenced by "autocontent" using the "-?" optional field, recognizes the "-?" option.

The "autocontent" script generates its list of files for which it generates documentation from the files contained in the "/usr/local/AutoContent" directory. Scripts should NOT be stored in this directory, only a symbolic link to the script should exist in "/usr/local/AutoContent".

Additional documentation may be generated if the comments within the script conform to the "autocontent" technique of imbedding comments in scripts.

Dependencies:

The list of scripts for the HTML snippet documents are generated, is embedded within the "autocontent" script. To change the list, the "autocontent" script must be edited.

The "autocontent" script is a Korn Shell 93 script and must be executed using a Korn Shell 93 compliant script interpreter.

Products:

For each specified script, the "autocontent" script generates an HTML snippet file, that contains the usage message and any additional comments extracted from the script. Also produced is a separate HTML snippet file that contains the script itself enclosed in HTML tags to preserve formatting.

Configured Usage:

This script requires no arguments and can be run from the command line, scheduled, or executed from within another script. This script does not perform any file transfers. How the files generated by this script are utilized is beyond the scope of this script.

Details:

This script is primarily used to automatically generate documentation content in association with the Disaster Recovery scripts. However this is an arbitrary association, this script is generic and can be used with any scripts which conform to the rules by which "AutoContent" operates.

Data lines are read from a user designated file that contains information that controls the operation of "AutoContent". Each line of data should be formatted into a "source" and "destination" portion. The source portion designates a file to be processed by "AutoContent" and the machine on which it resides. The destination portion of the data line designates a machine and directory location to place the results of the processing.

Each line in the data file should be formatted as follows:

{source machine name}:{Full Path File Name}[:-?] {space, tab, comma or pipe} {destination machine name}:{Full Path Directory Name}

If the option flag "-?" is used at the end of a source file name, the file will be treated as as script and executed using the option flag as an argument. This assumes the option flag will cause the script to generate a usage message which will be captured and included in the generated documentation.

If used, the optional flag must be separated from the source file name using a colon (:).

The source portion of the data line is extracted from the data line by deleting the largest matching pattern from the end of the line that matches anything up to the first space, tab, comma, or pipe symbol in the line. The result contains the source machine name, the source file name, and possibly an option flag. The format of the result should have a colon (:) between the source machine name, the source file name, and if present, the option flag.

If the result is formatted correctly, it is separated in to its components. If the option flag is present, it is saved in a variable named "SRCFLAG".

The destination portion of the data line is extracted from the data line by deleting the largest matching pattern from the beginning of the line that matches anything up to the last space, tab, comma, or pipe symbol in the line. The result contains both the destination machine name and the destination directory. The format of the result should have a colon (:) between the destination machine name and the destination directory.

If the result is formatted correctly, it is separated in to its components.

Define the command to use to copy the source file from its original location into a temporary file. Assume the source file exists on a remote machine and define the copy command as a remote copy, followed by the source machine name, followed by a colon. Then test to see if the source machine name is the same as the local machine name or defined as "localhost". If so, reset the copy command to be a simple copy followed by a space.

After defining the copy command, perform the copy.

For each script, an HTML snippet file is created to contain the usage message and any additional "autocontent" compliant comments that can be extracted from the script. This file is named using the file name suffix of the original script up to but not including the first dot ".", followed by "doc.content.shtml".

The ".shtml" is used so the document may additionally use server-side includes.

Each Script is executed with the "-?" option to generate the usage message associated with the script. This usage message is saved in the documentation for the script.

Any "<" or ">" symbols generated by the usage message or extracted from the script in the additional comments, are converted to HTML recognizable codes that will be interpreted by the web browser when the page is displayed.

Additional comments may be extracted from the scripts if the comments conform to the "autocontent" technique of commenting scripts. This technique extracts only those comments embedded within a script which begin with four hash marks followd by a single space (#### ). This pattern must also occur at the beginning of the line. Any comments which begin with this pattern are extracted and reformatted as an HTML paragraph.

Multiple paragraphs may be designated within the script by using the (#### ) pattern with nothing following. This will be interpreted by the "autocontent" generated to mean "insert end of paragraph tag followed by a begin paragraph tag".

Any extracted comment line which ends with a colon ":" will be enclosed in HTML STRONG tags to make the text bold when displayed in a browser.

If "autocontent" generates multiple "End Paragraph - Begin paragraph" pairs, they will be collapsed into a single pair.

Also for each script, an HTML snippet file is created to contain the script source code. This file is named using the file name suffix of the original script up to but not including the first dot ".", followed by ".content.shtml".

The ".shtml" is used so the document may additionally use server-side includes.

Any "<" or ">" symbols generated by the usage message or extracted from the script in the additional comments, are converted to HTML recognizable codes that will be interpreted by the web browser when the page is displayed.

A server-side-include directive that displays the date when the document was generated is added to the end of each document.

Environment Variables:

DD_TMP = Directory for storage of HTML snippet files

This file last modified 02/04/09