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

Chapter 15 ini_html_gen.pl

The ini_html_gen.pl perl program is a special purpose tool for generating documentation for INI files. Although this is a Voyant specific tool for generating HTML documentation for our INI configuration files, those INI files are based on standards defined by others, such as Microsoft and SUN.

Overview

The ini_html_gen.pl perl program was created after the log_html_gen.pl tool. Many of the log_html_gen.pl program routines were extracted and placed in globe.pm so that they could be used by both programs.

As with the LOG messages for the log_html_gen.pl tool, the requirements for Technical Publications relating to the INI files were:

• Document the individual INI sections and items.

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

The INI file syntax is well defined. In general, a section begins with [some_name] and ends with an empty []. Inside each section are items, possibly comments, and possibly nested sections. Items have the general syntax:

item = value // comment.

To aid in readability, items within a section are indented. Nested sections require further levels of indentation.

Because this ini_html_gen.pl perl program is based on the log_html_gen.pl perl program, it supports:

• XML tags defined as a comment after an INI item.

• XML tags can reference destination XML tags within the same file or from external files.

A valid argument could be made that self-documented configuration files are useful to the customer. Likewise, a valid argument could be made that self-documented configuration files provide the customer with too much information with which to shoot themselves in the foot. The two camps are still arguing.

The developers have the upper-hand and have tools which auto-generate configuration files without comments.

Hence, because the documentation for an INI file item will most likely reside external from the INI file itself and in order to simplify the XML syntax, the ini_html_gen.pl perl program takes additional input files that can contain the documentation.

So, descriptions to INI file items can be:

• in-line with the INI item definition itself in the comment section.

• within the INI 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). Even if a default fully-commented INI file doesn’t exist that the engineers maintain, an HTML file checked in near their source code could be maintained. Even failing that, the ini_html_gen.pl perl program does checks for all exposed INI items to see if documentation exists.

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

Input

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

src_ini_file is the input source file that has the INI items. This file has a pre-defined format and structure.

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.

org_title [optional] title for the example file. This is plain text that gets exposed in several places in the output.

ext_doc [optional] additional documentation file with XML tag destinations and HTML formatted information. This is useful when the src_ini_file does not have any XML tags or documentation, or when programs are based on the same source and have overlaps in the INI configuration.

The ext_doc can have documentation for more INI items than are present in the src_ini_file.

An example of where this would be useful is when working configuration files expose only those INI items needed for their specific modes of operation or their specific applications. In which case, the input src_ini_file could be an application-specific INI file without comments, while ext_doc could be a fully-commented and documented master default INI file.

Another example is when you desire documentation for customer-specific INI files that expose their default values.

Output

The goal of the ini_html_gen.pl perl program is a series of HTML files that fully document all configuration items exposed in the input INI file.

On the way to that goal, the ini_html_gen.pl perl program generates several intermediate files which can be used depending upon the input state of the source INI file.

INI file with XML tags: Sometimes the INI file to be documented has no XML tags in the comment area of the configuration item. Hence, you can run this tool to generate an output file with those tags. The output file then becomes an input in a subsequent run of the tool.

Note: Yes, this is convoluted, but it is intended only as a stop-gap measure until engineering is fully on board about how to document INI files. It is hoped that either their fully-documented master default INI file or their tool generated INI files will contain the appropriate XML tags. If they decide not to do that, then this tool can make assumptions about XML tag names, which it does for this temporary output file.

Text file with documentation and XML destination tags: If there is a fully-documented master default INI file, this temporary file holds just the XML destination tags and the associated HTML documentation. Later, this file can be used as an additional input file when creating documentation for an application-specific or customer-specific INI file.

Note: It can sometimes be trouble-some to use a valid fully-documented and XML tagged INI file as an additional source for the documentation, because the target XML tags cause unending loops in the tracing process. By extracting the documentation into a separate file, it contains only the destination XML tags. This tool can then be run once to get the documentation from the master and then a second time to create the HTML suite for the specific INI file.

INI file tagged and documented: If the source INI file had its documentation initially stored in another file, this creates a self-documented and XML tagged INI file.

Note: This file was used mostly as a test of the tools and proof of concept. This file should be a working INI file that might be cleaner and neater than the original INI file. If Technical Publications was given free reign to help create a self-documenting default master INI file, this particular version could be the one that is handed back after the initial effort and is subsequently maintained.

The various text files that are output were intended to give me a quick leg up in documenting new INI files when the files had no target XML tags, much less destination XML tags with HTML descriptions for the INI items. Hence, during the initial documentation phase, the ini_html_gen.pl program is sometimes run several times and various aspects of its output are fed back into the tool for yet other runs.

Eventually, though, a documentation file with destination XML tags and its HTML descriptions should be made available for use with subsequent versions of the INI file. As of this point in time until agreement is reached, it might remain a two-pass process or the tool might be modified into a one-pass process depending on our company decisions.

In any event, the final product is a series of HTML files. Each HTML file has a standard template format which is defined inside of the ini_html_gen.pl perl program. It leaves the order of the items as they were found in the original INI file. It adds an appropriate overview topic 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 ini_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 INI documentation 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