Automatically Generated Documentation for "autocontent"

This document was automatically generated from the extracted usage message and comments in the "autocontent" shell script, and was generated by the "autocontent" shell script.

To view the Shell Script Source Code for the "autocontent" script Click Here.

Program: autocontent

This utility parses a list of scripts, extracts the comments from within
each script in the list, and generates HTML formatted documentation from
the extracted comments and source code.

This utility reads a data file containing the location of local or
remote script files, and the location for the resulting documentation.
The data file also contains SSH communication information for both the
source and destination locations.

Usage: autocontent [-vV?] {-d|-h|-l|-f datafile} [-o] [-c|-u] [-p sshport]
                [-H] [-T TitleFile] [-F FooterFile]

  Where:
    -? = Display usage and help message
    -v = Verbose Mode
    -V = Very Verbose Mode
    -d = Use ./.autocontent.dat as the data file 
    -h = Use ~/.autocontent.dat as the data file from your home directory (Default)
    -l = Use /usr/local/AutoContent/AutoContent.dat as the data file
    -f datafile = Specify the AutoContent Data File
    -o = Send all HTML output to STDOUT
    -c = Generate code document only
    -u = Generate usage document only
    -p sshport = SSH Port number to use for file transfer (default:22)

    -H = Generate Standalone HTML files instead of SSI files (Default: SSI)
         Automatically includes ~/.autocontent_header.html and 
         ~/.autocontent_footer.html if they exist.

    -T titleFile  = Header file inserted at the Start of HTML Standalone files.
                    (Default: ~/.autocontent_header.html)
    -F footerFile = Footer file inserted at the End of HTML Standalone files.
                    (Default: ~/.autocontent_footer.html)

Author: Dana French (dfrench@mtxia.com) Copyright 2007-2015, All Rights Reserved

"AutoContent" enabled

Description:

This utility parses a list of scripts, extracts the comments from within the scripts, and builds HTML Server Side Include (SSI) files from the extracted comments and source code. Optionally this utility can also generate standalone HTML files, but the normal usage is to generate HTML SSI files. The HTML SSI file 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 for server-side include (SSI) files.

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 is 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 "AutoContent" script will generate documentation for shell scripts that exist on a local or remote server, and push the generated HTML documentation to a local or remote web server. Each line of the data file can be configured independently of every other line in the file. This means that each line can refer to a shell script on a different remote system, and can transfer the generated documentation to a different web server for each shell script. Or each shell script can exist on the same local or remote host, and transfer the generated documentation to the same local or remote web server. How and where is up to the user.

The data file consists of a series of lines, one record per line. A record consists of several fields specifying a SSH ports, Usernames, Hostnames, and full path file names, and an optional field whose contents are variable. Each record line is divided into source and destination portions which specify where to retrieve the script files, and where to place the generated documentation files.

Example data file records:

# SRCSSHPORT:srcuser@srcmachine:/source/file/location.sh:helpFlag|DESTSSHPORT:destuser@destmachine:/destination/directory
22:username@xyzmach:/usr/local/bin/script01.ksh:-?|22:apache@webserver:/www/httpd/html/scripts
22:username@xyzmach:/usr/local/bin/another02.sh:-?|22:apache@webserver:/www/httpd/html/scripts
22:username@xyzmach:/home/username/scripts/drscript.sh:-?|2022:wikisysop@wikiserver:/var/www/html/holding

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.

In the Data File, blank lines or lines beginning with a hash mark "#" are ignored.

Each line in the data file is divided into two parts separated by a pipe "|" symbol. The first part of the data line is the source file information, the second part is the destination location for the documentation.

The source portion of the data line is divided into the following components, separated by a colon ":" character

o SSH Port Number, followed by a colon ":" separator.

o Username on the remote machine for SSH access to retrieve source script file, followed by an "@" character.

o Remote hostname for SSH access to retrieve source script file, followed by a colon ":" separator.

o Full path file name to the remote script file to retrieve for documentation, optionally followed by a colon ":" separator or a pipe "|" symbol depending upon if a usage message should be retrieved from the script for the documentation.

o If a usage message can be retrieved from the remote script file using a "-? command line argument, then include a ":-?" after the full path file name to the remote script. This will cause the script to be executed with the "-?" command line argument to generate and capture the usage message.

The destination portion of the data line is divided into the following components, separated by a colon ":" character

o SSH Port Number on the remote web server machine, followed by a colon ":" separator.

o Username on the remote web server machine for SSH access to send documentation files, followed by an "@" character.

o Remote hostname of the web server for SSH access to send documentation files, followed by a colon ":" separator.

o Full path directory name to the remote web server to send generated 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.

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

Dependencies:

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 either an SSI HTML file or a stanalone HTML file. The HTML generated documentation contains the usage message and any additional comments extracted from the script. Also produced is a separate HTML SSI or standalone 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 performs file transfers between the system running this scripts and any number of remote systems and web servers. How the files generated by this script are utilized is beyond the scope of this script.

Details:

Read data line records:

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:

{SshPortNumber}:{Username}@{source machine name}:{Full Path File Name}[:-?] \ {pipe symbol "|"} \ {SshPortNumber}:{Username}@{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 (:).

Parse the "source" portion of the data line record:

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 pipe symbol in the line. The result contains the SSH port Number, the SSH User name, source machine name, the source file name, and possibly an option flag. The format of the result should have a colon (:) between the SSH Port Number and the User name, also between source machine name and the source file name, and if present, the help option flag.

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

Parse the "destination" portion of the data line record:

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 pipe symbol in the line. The result contains the SSH Port Number for the destination machine, Username, destination machine name and the destination directory. The format of the result should have a colon (:) between the SSH Port Number and Username, and between then destination machine name and the destination directory.

There should also be an "@" sign between the Username and the destination machine name.

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

Define the Command to Retrieve the Script File:

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 SSH Port number option and value, followed by the Username and "@" signe, followed by the source machine name. 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.

Create the Usage Document:

For each script, an HTML Server Side Include (SSI) 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.

Generate the Usage Message if applicable:

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.

Extract Additional Comments from the Script:

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.

Add the Date to the end of the Usage Document:

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

Create the Code Document:

Also for each script, an HTML SSI 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.

Translate special characters into HTML codes:

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.

Add the Date to the end of the Code Document:

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

Remove the Temporary Script File:

Remove the temporary script file which was copied or transfered from the source location. The HTML documents were generated using information from this file.

Create the Remote File Transfer Command:

Create the command to perform a remote transfer of the HTML documents to the web server.

Create the Copy Command:

If the destination machine name is the same as the local hostname, then perform a file copy instead of a remote file transfer. Create the command to perform a copy of the HTML documents to a directory on the local host. the web server.

Copy or Transfer the Usage Document:

Copy or transfer the usage document to the destination location, then remove the temporary file.

Copy or transfer the Code Document:

Copy or transfer the code document to the destination location, then remove the temporary file.

Environment Variables:

DD_TMP = Directory for storage of HTML SSI files

This file last modified 07/04/16