-
Notifications
You must be signed in to change notification settings - Fork 130
INI File and Common Code Documentation
This page describes how the INI files and Common Code files use imbedded documentation for the Web UI. Developers and users creating new common code or user code files can use the methods below to provide help text in the Web UI.
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.
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.
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 <br> to create a new line. More examples include <ul><li><li></ul> for formatted lists and <a href=><a\> for external links. The HTML appears to be passed, untouched, to the browser so any valid HTML will likely work.
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:
#Category=Category Name
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.
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:
if( $::config_parms{rabitDetector_action} == "sterilize") ...
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 inadvertently end up with the same definition.
When adding a new Common Code Script, any new INI parameters should be added to the bin/mh.ini file and given appropriate descriptions.
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:
#Category=Category Name
New categories are created by simply referencing a previously undefined category. The reserved category "Other" should not be used. 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.