BP Documentation

Table of Contents Documentation Interface Process for Self Documentation Script Documentation Script Categories perldoc Style Comments INI Parameter Documentation INI Parameter Categories

Documentation Interface

The primary user interface in the web front end for script documentation is in the Common and User Code Activation screens. These screens list all of the registered scripts and the documentation for each. In these screens the user can enable a script, view the script documentation, view the script source code, view the list of INI parameters that control the script, and get a short description of each relevant INI parameter. Both the scripts and INI parameters are grouped into common functional categories to make it easier to locate an item. There is also a separate INI editor that uses the documentation techniques listed here to group and describe the INI parameters.

Process for Self Documentation

Misterhouse has a startup process that scans all of the Perl scripts in the configured code directories (both common code and user code). This process pulls documentation from the code that is then presented to the user in the Code Activation screens. Misterhouse also parses the bin/mh.ini file for comments describing the INI parameters. These comments are presented to the user when the user clicks on a parameter in the Code Activation screen.

Script Documentation

The Code Activation screen displays script documentation found during the startup code scan. All Perl comments that begin with an @ sign ("#@") will be combined and displayed. The documentation comments can be anywhere in the file and are concatenated together removing any line breaks. Comments can be formatted using HTML markup in the comments. The most useful markup is the
to create a new line. More examples include

for formatted lists and for external links. The HTML appears to be passed, untouched, to the browser so any valid HTML will likely work.

Script Categories

The Code Activation screen categorizes the scripts according to a Perl comment at the very top of the file. This comment should have the form: code

1. Category=Category Name

code Category names are invented by simply including the a category name in a script. For example adding #Category=Foo will create the Foo category in the user interface.

perldoc Style Comments

Some of the scripts have perldoc style comments using =begin comment and =cut perldoc directives. These appear to only be useful when viewing the source code. There doesn't appear to be any other coordinated effort to document Misterhouse using PODs.

INI Parameter Documentation

There are two ways to view and edit INI parameters through the Misterhouse user interface. There is an INI editor whose sole purpose is to edit the INI parameter values. In addition INI parameters may be edited while using the Code Activation screens. The Code Activation screens display the INI variables that are referenced in the script. This list is created during the code scan at startup by looking for references to the %config_parms hash. An example is: code if( $::config_parms{rabitDetector_action} == "sterilize") ... code The INI parameters are documented in the bin/mh.ini file using just @ symbols. Again the list of possible INI parameters is built dynamically by scanning the bin/mh.ini file at startup. **The INI documentation has a different format than the Script documentation.** Unlike the Script documentation function, INI documentation //ignores// comments that begin with a # even if they include #@. In addition INI documentation //maintains// line breaks. The difference between script and INI documentation formats can be confusing so study it carefully. I'm not sure but the algorithm used to create the INI definitions //appears// to be 1) associate any comment that is on the end of the line containing the INI parameter definition and 2) failing that associate the previous, contiguous lines of comments just above the parameter definition. Using this second method, multiple parameters can end up with the same definition. When a new Common Code Script is added, any new INI parameters should be added to the bin/mh.ini file and given appropriate descriptions.

INI Parameter Categories

Just like Script categories, INI parameters are presented in categories when using the INI editor. The categories are defined in the bin/mh.ini file using the same syntax as with Scripts. For the INI categories, the category tags can be located anywhere in the file. All INI parameters following a category tag are grouped under that tag's value. The following syntax is used: code

1. Category=Category Name

code New categories are created by simply referencing a previously undefined category. The reserved category "Other" should not be use. Any parameters defined in the users private INI file (e.g. mh.private.ini) that are not first found in the mh.ini file will be listed under the "Other" category.