DocUtilsTable of Contents

Sprout Documentation UtilitiesIntroductionPublic MethodsAugmentCheckFileGetDirectoryModifyConfigFilePerlDocStylizeInternal UtilitiesSortIndexesPrivate Utilities_BuildAssignmentSprout Documentation UtilitiesIntroductionThis module processes documentation files. It can invoke pod2html to convert a P file to a POD document or stylize an existing HTML file.

Stylization is automatically performed on all POD documents. It involves two separat steps. First, it sorts the table of contents in alphabetical order; second, it inserts a style link to a specified cascading style sheet. This makes the POD document easie to read and easier to navigate.

Public MethodsPerlDocmy $newName = DocUtils::PerlDoc($inFile, $docDirectory, $style);

This method generates an HTML document for the specified PERL source file in th specified output directory. If a style file name is specified, it will be adde as a style link. The style file name should be specified relative to the outpu directory. So, for example

DocUtils::PerlDoc('lib/Sprout.pm', 'CGI/Html/pod_doc', '../Georgia.css');

would produce the POD documentation for Sprout.pm in the lib directory The output file would be CGI/Html/pod_doc/Sprout-pm.html, and it would referenc the style file CGI/Html/Georgia.css.

inFileName of the PERL source file.

docDirectoryOutput directory into which the HTML document should be placed.

style (optional)If specified, the name of the style file to be used, relative to the output directory.

RETURNReturns the file name given to the documentation file.

StylizeDocUtils::Stylize($inFile, $style, $outFile);

Dress up an HTML file. Dressing up the file includes putting a header line in fo the table of contents, adding a style link, and sorted the table of contents int alphabetical order for ease of maneuvering. The Table of Contents is identified b two HTML comment lines:

<!-- INDEX BEGIN -->

<!-- INDEX END -->

These are automatically inserted into the output of the pod2html program. The director is presumed to be in outline form, using ul and li tags. Only the lowest level o the outline is sorted.

inFileInput file name.

styleStyle file name, relative to the output file's directory. If null or undefined, no style link is added.

outFileOutput file name.

ModifyConfigFileDocUtils::ModifyConfigFile($targetFile, \%changes, \@inserts);

Modify the contents of a PERL configuration file. A PERL configuration file contains package statement followed by a set of assignments having the form

$var_name = "string";with optional comments. The caller passes in a hash keyed by variable name, and th configuration file will be updated to insure the variables mentioned in the hash hav the associated value in the specified configuration file. If the variables in the has already exist in the file, they will be replaced. If they do not exist they will b added before the first line beginning with 1;.

targetFileName of the configuration file to be changed.

changesReference to a hash mapping variable names to string values.

insertsReference to a list of lines to be inserted at the beginning.

AugmentDocUtils::Augment($inFile, $outDirectory, @statements);

Augment a PERL script file by adding a set of pre-defined statements. The statement will be added immediately after the shebang line, if one is present. Otherwise they wil be added to the beginning of the file. The augmented file will have the same nam as the original file but will be placed in the specified output directory.

inFileName of the input file.

outDirectoryName of the directory to contain the output file.

libsStatements to be added to the output file.

GetDirectorymy $fileHash = DocUtils::GetDirectory($directoryName);

Get a list of the files in the specified directory. The files will be returned a a hash of lists. The hash will map the various file extensions to the correspondin file titles. So, for example, if the directory contained Sprout.pm, DocUtils.pl Tracer.pm, Genome.pm, and Makefile, the hash returned would be

( pm => ['Sprout', 'Tracer', 'Genome'], pl => ['DocUtils'], '' => ['Makefile'] )

directoryNameName of the directory whose files are desired.

RETURNReturns a reference to a hash mapping each file extension to a list of the titles of files having that extension.

CheckFilemy $updated = DocUtils::CheckFile($inFile, $outDirectory, $suffix, $chgFlag);

This method compares the modification date of a specified file against th date of a similarly-named file in the specified output directory. I returns TRUE if the matching output file does not exist or has bee modified since the last modification of the matching file in the outpu directory.

inFileName of the input file.

outDirectoryDirectory to contain the output file.

suffix (optional)If specified, a suffix to be added to the input file name to create th output file name.

chgFlag (optional)If specified, the suffix will replace the input file name's suffix instead of bein appended.

Internal UtilitiesSortIndexesSort a POD index. The index is provided as a list and is returned as a list The index itself consists of <ul>, </ul>, and <li> lines. Each <ul> adds a indent level and each </ul> subtracts one. Only the <li> lines at the lowest level are sorted. This is not very general-purpose, but it is enough to handl the output from POD and the ERDB module.

This is a static method.

bufferList of lines making up the index.

RETURNA list of the same lines in a more useful order.

Private Utilities_BuildAssignmentmy $statement = _BuildAssignment($varName, $value, $comment);

Create an assignment statement out of the specified components.

varNameVariable name.

valueValue to be assigned to the variable (will be quoted).

commentComments or trailing characters.