Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

Chapter 16 log_html_gen.pl

The log_html_gen.pl perl program is a Voyant specific tool for generating HTML documentation for our LOG messages.

Unmodified, the log_html_gen.pl tools may be of little use to you in your environment, because it relies on the pre-defined format of a company-internal source file.

Overview

Voyant has localized the definition of LOG messages from our product into a small handful of source text files. These files have unique syntax and formatting, which is why an unmodified version of the log_html_gen.pl tool may be of little use to you in your environment.

The requirements for Technical Publications were:

• Document the individual LOG messages.

• Don’t add any code bloat to the source files.

The source files have either comment lines or LOG message lines. Each LOG message is on a line of its own with fields delimited by a special character. The engineers left the last field on the line as a free-form field for Technical Publications.

Taking the command regarding code bloat at face value and knowing that sometimes the documentation could not be expected to fit (readably) on one line, we decided to insert XML tags into the source file and the comment fields. The XML tags then could point to XML tags located in external files to find the rest of the documentation.

It turns out, when the engineers said they didn’t want any code bloat as a result of documentation efforts, they really meant that they didn’t want natural groups of LOG messages interrupted with lengthy documentation blocks. They didn’t care about the size of the file. They permitted lengthy documentation blocks at the beginning of the file, at the end of the file, or in between groupings of LOG messages.

Hence, the XML tags in a LOG message comment could point to comment lines which contain destination XML tags and the (lengthy) description of the LOG message.

So, descriptions to LOG messages can be:

• in-line with the LOG message definition itself in the comment section.

• within the LOG message file somewhere, marked with an XML destination tag.

• in an external file somewhere marked with an XML destination tag.

This approach was chosen, because it puts the documentation much closer to the source (the engineers). More importantly, the engineers can change the syntax of the LOG messages at any point in time, which the documentation needs to keep up with. Generating the documentation is the only way to keep up with rapidly changing code (LOG messages).

The auto-generation of documentation extract the current syntax of the LOG message, create a template HTML document for the LOG message, and then trace the XML tags to locate the plain text descriptions. During the output phase, the LOG messages are sorted and appropriate entries for the index and table of contents files are generated.

Many of the key routines of log_html_gen.pl were generalized further and then extracted into globe.pm, because much of what the ini_html_gen.pl perl program required in terms of handling XML tags was identical.

Input

root_dir path to place the output files. This is generally something like doc_publish/cref_sysxini/ .

message_file is the input source file that has the LOG messages. This file has a pre-defined format with either comment lines or LOG message lines. The format of the LOG message lines is also pre-defined.

html_tmpl template for generated files. This is typically voyant_master_nav.html. The true template is internal to the tool, but this master has information for the <head>, top of <body>, and bottom of <body> which gives a standardize look-and-feel for the whole sub-project that can match the whole project.

Caution! Unmodified, the log_html_gen.pl tools may be of little use to you in your environment, because it relies on the pre-defined format of a company-internal source file (message_file).

Output

The log_html_gen.pl perl program generates a series of HTML files based on the individual entries of the LOG message file.

Each HTML file has a standard template format which is defined inside of the log_html_gen.pl perl program. It sorts the output alphabetically by LOG message name and adds appropriate information for browsing. In addition, an appropriate tree.script file is created that can be used by the Java TOC Applet.

The log_html_gen.pl perl program has the ability to create an appropriate index file. However, the voyant_nav.pl does a better job. Moreover, the voyant_nav.pl may have to be called at a later point in time with an updated voyant_master_nav.html in order to standardize the look-and-feel.

Caution! The voyant_nav.pl program does not generate a tree.script file that is the same as intended by the log_html_gen.pl program. Therefore, any shell scripts for creating LOG messages should first backup the tree.script, run voyant_nav.pl, and then overwrite the generated tree.script with the backed up tree.script. Likewise, subsequent shell scripts, such as 50_nav_update.b, should use 55_nav_cp.b on this project.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02