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
|