Customizing the documentation HOWTO
Author: Matthew Maxwell
Date: June 23, 2004
Introduction
| |
The official OpenBasin documentation stie is http://openbasin.org/documentation/documentation.php; however, as you customize, change, and create OpenBasin scripts to fit your needs you may wish to change the provided documentation to fit your needs as well. The structure of the OpenBasin documentation allows you to create a localized version of the documentation on your computer for such changes, and the makers of OpenBasin have even provided a number of tools to aid you in this process. This HOWTO will review two scripts that can be useful in viewing, editing, and keeping your documentation up-to-date. The first is the OpenBasin documentation script that allows a person easy access to both view and change the OpenBasin documentation with a web-based interface. The second is a Perl script that can be configured to automatically check your OpenBasin scripts and add automatically and any new changes into your documentation.
|
Navigating the OpenBasin Documentation
| |
Before we explain how to use the OpenBasin Interactive Documentation script to edit the documentation, we'll briefly introduce how to navigate and use this script. Upon initially loading and all throughout the viewing process the documentation script is set up in a vertically split frame design.
On the left side a list of available OpenBasin objects are shown in both categorized and alphabetized formats. After initially loading the script, the right pane is empty; however, this pane will be used to show additional information about selected objects. You can select an object by clicking on it's name in the left pane. Once you do so that object's detailed information will appear in the right pane.
The detailed information view provides a variety of information. At the top it shows the name of the object and the actual path to the file in brackets. Below that a short description of the object is given. To the right are two links named 'Show Inherited' and 'Show Private' which we will discuss later. Further down you can see an inheritance tree for the object. This can be extremely useful if the object inherits information from other objects. Following that is a longer description of the object, and then a dividing line.
Listed below are any constructors, variables, or functions which the object has and a short description of each. Clicking on one of these will take you to a different part of the document that contains more detailed descriptions. Following this list is another dividing line followed by the detailed descriptions for each function and variable each separated by a dividing line. You will note on the right hand of these dividing lines that there is a arrow pointing upwards. Clicking on this arrow will take you to the top of the document.
Now, to discuss the 'Show Inherited' and 'Show Private' links which we skimmed over earlier. The 'Show Inherited' link changes the view so that it displays all of the functions and variables from not only from this object, but also from any parent objects that this object may have. The 'Show Private' link also changes the view. It allows private functions and variables to be shown on the screen too. Functions and variables are considered to be private if they start with an underscore character ('_').
|
Editing the OpenBasin Documentation
| |
If the OpenBasin Interactive Documentation script is already configured to allow customizations to the documentation. If you access the documentation through the URL listed in the ob_config.php file, you should see 'Edit Description' links throughout the detailed object view. Clicking on these will allow you to edit the descriptions for the object, function, or variable which they are next to. If these links do not appear, you must access the documentation through the URL specified in the ob_config.php file as $DOCUMENTATION_EDIT_URL. More information can be found in the Editing ob_config.php HOWTO.
When you edit the documentation you will be able to change both the short and the long descriptions for each element you edit. Also, if you edit the object itself you will be asked if the object is a station object, a sensor object, or a utility. Although picking more than one option is allowed it is not recommended. Changing these values will affect which categories the object is placed into (for instance the categories in the left pane of the script).
|
Advanced Tips
| |
To link to another script's detail page within a long or short description try the following code:
<a href="object.php?objectName=xxxxx">xxxxx</a>
Where 'xxxxx' represents the name of the object you wish to link to.
|
Automating the Documentation Process
| |
The openbasin-doc.pl script will aid you in keeping your documentation current. This script goes through each OpenBasin object listed in the 'objects' table of the database. It then adds new entries to the documentation for every new function or variable which it finds. It is also important to note that a new function is any function that has a different name or that has different parameters than all the previously known functions in the object. So just changing one of the parameters in a function will cause the openbasin-doc.pl script to interpret it as a new function.
The openbasin-doc.pl script will not automatically remove any old functions, variables, or objects that no longer exist; however, it will alert you when functions or variables no longer exist. Also it will not add any descriptions to the documentation listings. Although these actions must be performed by hand the openbasin-doc.pl script is invaluable in identifying what elements of the OpenBasin objects still need to be documented.
|
technical contact: Matthew Maxwell
general contact: 
|
