skip to main content
RPL External Documentation
RiverWare Policy Language (RPL)
RPL External Documentation
This document describes the RiverWare capability to link a RPL set to documentation that resides in a separate file viewable by commonly used viewing and editing programs.
The RiverWare RPL editors support an optional multiple-line text description, displayed in a plain-text editor box and is stored in the RPL set file. Often this text description is not sufficient to adequately describe a complicated rule or policy set. The purpose of a link to external documentation is to allow the user to develop more detailed documentation that will reside in a separate application like MS Word, PDF, or an HTML file. From the RPL editors, the user can click to go to the documentation file.
Note:  The external documentation support described in this document is distinct from this description text value.
A RPL set consists of rules (or user-defined accounting methods) and functions organized into groups. In this document, the term RPL object refers generically to a RPL set component of any sort, i.e., to the Set, Policy or Utility Group, Function, Rule, or Method.
Overview
The following is an overview of the capabilities:
• From a RPL dialog, the user is able to easily access external documentation for the RPL object associated with that dialog.
• The four supported types of documents are as follows:
– HTML,
– MS Word,
– PDF, and
– plain Text
• The user is able to specify the applications for both viewing and editing each type of document
• The following modes of access are provided:
– Edit. The user can view, create, and change the contents of the document.
– View. The user can view but not change the contents of the document.
• The granularity of the documentation is flexible. Users can associate a separate document with each RPL object within a RPL set or they can document an entire RPL set with a single document.
• When using HTML, the application can open to the most relevant portion of the document. This applies in the following circumstances:
– There is more than one RPL object described in the associated document, e.g., the documentation is a single file describing the entire ruleset, and,
– The user is using standard named anchors within the documentation to describe the sections that pertain to each RPL objects.
• The user can create an HTML template of the RPL set that contains the description field for each object. The user can then expand the documentation using an HTML editor.
The following sections describe the external document link feature. Configuration of this feature is done with the following process:
1. The user must specify the application to be used to edit and/or view one or more types of files;
2. The user specifies how the document is structured by associating RPL objects with external files.
File Association
The RiverWare File Type Association Manager is used to specify the executable programs used for viewing and editing documents of the four supported Format Types (HTML, PDF, Word, or Text). The file paths are stored with the user's settings. It is accessible in the following ways:
• The RPL editor View, then External Documentation, then File Type Associations menu
• The workspace Utilities, then File Type Associations menu
• The Utilities, then File Type Associations Manager from the Configure External Document Reference dialog.
Each file format has a distinct Edit and View mode program association. This allows the user to edit with one program and view with another. Only the document formats that the user wishes to use need to be specified. The others can be left as the default or left blank.
Executable file paths can be edited (including pasting from the system clipboard) by double-clicking an item within the Executable column or can be picked with a File Selector by selecting the folder icon. All of the executable file paths can be set to the default executable associated with the user's account using the Settings, then Set Default Executables menu operation. Changes can either be saved (by selecting OK or Apply) or dropped (by selecting Restore or Cancel).
The PDF View item is set to the path associated with PDF files, is non-editable, and is shown with a gray background. This is the same path used to locate the pdf reader for RiverWare Help and other purposes. Do an internet search on “Windows file type association” for details on setting this association.
Currently, the Support anchors for Edit operations check box is not operable. When opening a RPL Object External Document for Editing, the anchor text (used to automatically scroll to a particular section within the document) is only supported for HTML. For all types, the name of the RPL Object name text is copied to the system clipboard and can be used to paste into the Search function within the editor or viewer program.
Document Structure
This section provides an overview of the possible document configurations including some advantages and disadvantages to both. Following are setup configurations that have been envisioned.
One Document that Describes the Entire Set
• Advantages. One document is typically easier to maintain and share. Also, the user only needs to configure the external link for the overall RPL set, not for each individual RPL object within the set.
• Disadvantages. Unless the viewing document is HTML, there is no way for the user to automatically open the document to the correct location. For example, if the user selects to view a rule document (say in PDF) they must still search for that rule within the PDF document. Also, multiple model users have to coordinate if they wish to develop documentation simultaneously.
One Document for Each RPL Object in the Set
• Advantages. One document for each RPL object allows the user to easily view the external document specific to that object. For example, the user selects the View button for a rule and the document specific to that rule opens. Multiple users can more easily develop documentation simultaneously.
• Disadvantage. It is more time consuming to configure and maintain. When sharing, there are many more documents to pass around. If there are a large number of RPL objects, there will be a large number of documents.
Multiple Documents With One for Each Policy and Utility Group
This structure is a hybrid of the two above and has some of the advantages and disadvantages of both. This structure is useful because exceptions to the overall scheme are natural. For example, most of the set could be described by one document, while special objects could be described in a document of their own.
Combinations of the above could be envisioned. The choice of the structure to use depends on the format and the end use.
Separate View and Edit Documents
External documentation for a single object might also be found in two different files, one for editing and one for viewing. For example, documentation might be created in MS Word, saved in Word format for the purposes of future edits, and also saved to a PDF file for the purpose of viewing. Thus the utility allows the user to specify two locations, one for the purposes of viewing and another for editing. Figure 4.1 shows an example as two separate documents, one for viewing, one for editing.
Figure 4.1   
When the documentation for an object is split across many files, then it will often be convenient to the users for all the files to be located in the same directory. This organization is supported without requiring the user to provide redundant information (i.e., repeat the full path to the documentation for each object in the ruleset). At the same time, there is enough flexibility so as not to impose a specific organization on the documentation, either that there be a one-to-one correspondence between ruleset objects and documents or that multiple documents appear in the same directory.
Configuration and User Interface
The document structure is specified in the RPL set by supplying path names to a directory and then specifying file names within that directory. Further, because RPL objects are organized in a hierarchical organization (RPL sets contain policy and utility groups, policy groups contain rules and functions, utility groups contain functions) the hierarchical organization enables RPL objects to share information between objects. When configuration information is provided for an object, the containing objects inherit the configuration from their parent as their default configuration. The user can change the containing objects’ configuration as necessary. Thus to specify a single directory in which all the documentation for a RPL set is contained, the user need only specify that value as the directory associated with the set; all groups, functions, and rules in that set will inherit this as their documentation directory.
In addition to providing flexibility with respect to the organization of the documentation, this approach has the advantage that when documentation is moved (say from the modeler’s file system to a stakeholder’s file system), the ruleset will typically only need to be updated in one place to reflect this change. Environment variables can be used to further simplify moving RPL set documentation between machines. With the use of environment variables, the base directory of all RPL set documents within a users configuration can be set without any changes to the document link configuration within RiverWare. The environment variable substitution mechanism uses UNIX-style syntax (even on Windows): any environment variable name (case sensitive with only alphanumeric characters and underscores) preceded with a dollar sign “$” is translated to the environment variable defined in the user session, outside of RiverWare. For example, an environment variable name ALLUVIAL_RPL_DOC is defined as C:\Projects\docs, then within the RPL external documentation link, $ALLUVIAL_RPL_DOC\forecastDraft\ will refer to C:\Projects\docs\forecastDraft. This is specifically designed for portability of external RPL documentation across machines and platforms. Slashes can be forward or back slashes and redundant slashes are condensed.
In this documentation and in the user interface, we refer to the two parts of the location specification as the Directory and the File name. There is nothing that requires that the two parts correspond to a directory and file name in the local file system. Another possibility is that the two parts together specify the location of a document as a URL. In this case, the first part to be something like http://www.WaterU.edu/Models, which is not strictly speak a directory.
Note:  The file name specification could be an absolute path specified relative to the directory specification, e.g., “MyFunctions/FunctionA.htm”.
The configuration dialog is available from the RPL editor View, then External Documentation, then Configure menu. Figure 4.2 shows the dialog for the RPL Set.
Figure 4.2   
In this dialog, the RPL object is listed at the top and there is a button to take you to the that RPL object. Then, there are two areas, one for the View Document and one for the Edit Document. If the Use View Document check box in the Edit Document area is checked, the remainder of the Edit Document area is hidden. This toggle specifies that the View and Edit documents are the same. The process of specifying a View and Edit document is the same, so it is only described for the View Document. Figure 4.3 shows the View Document dialog.
Figure 4.3   
For the Directory, File, and Anchor (when using HTML), the user can specify to use the listed Default or select to use a Custom configuration. When Custom is first selected, the Default value is copied down from the Default field. For the Custom configurations, the user can either type in a value or use the File Chooser button to specify. For the File, the user can also specify the file type or use the auto selection. Anchors are currently only supported for HTML files; see “HTML” for details.
The default Directory is the directory containing the RPL set itself. The default File is the name of the RPL set with a modified filename extension. It is typically “.doc” or “.docx”, but will instead be “.html” if a file with the resulting name at the path actually exists.
For RPL objects (e.g. a group or rule) within a set, the default directory and file names are inherited from the containing RPL object, and the default anchor (when HTML is used) is based on the RPL object name.
Note:  Spaces and most punctuation are removed.
Note:  The default anchors for all the objects within a RPL set are reported in a table in the generated HTML template file; see “HTML”) for details.
At the bottom of the View area is the resulting command that is generated and will be passed to the operating system to start the application. This is the result of the configuration that has been defined. It is the chosen application followed by the command used by that application to open the specified file. Selecting the View (or Edit) button will execute the command.
As noted above, the Edit Document area is similar to the View Document area. At the bottom of the window are OK (apply and close), Apply, Restore to previously applied values, and Cancel buttons.
Once applied, the configuration settings are propagated to the default value of contained RPL Objects. Thus, the user only needs to specify as much information as necessary to fully configure the document. If the user is using the layout One Document that Describes the Entire Set, he/she only needs to configure the RPL set and all rules, groups and methods will be configured correctly; see “One Document that Describes the Entire Set”. If the user is using the layout One Document for Each RPL Object in the Set, he/she needs to make sure that each RPL object is configured correctly but using a consistent naming convention can be used to simplify the configuration; see “One Document for Each RPL Object in the Set”. If there are exceptions to the naming convention, the user would need to configure the RPL objects that have the exception.
Viewing and Editing
This section first describes viewing and editing documents in general, then describes peculiarities and specifics for each type of supported document. Once configured, viewing can be done directly from the RPL Object Editor using one of the following methods:
• Select the External Documentation icon . It is on the top of the dialog by the object name.
Note:  This icon is only shown if a document actually exists at the configured file path (including the default path if that is a correct configuration).
Note:  If the path leads to a web address, i.e. http://, the icon is always shown. RiverWare does not attempt to verify the existence of such pages on the web.
• Use the View, then External Documentation, then View Document menu.
Similarly, editing can be done directly from the RPL object using one of the following methods:
• Shift-Click the External Documentation icon
• Use the View, then External Documentation, then Edit Document menu.
Hovering over the External Documentation icon provides tooltips on the use of this button, as follows:
• Select: View External Document
• Shift-Click: Edit External Document
• Control-Click: Configure Document
• Shift-Control-Click: Show Info
Although Anchors are only supported when viewing HTML documents, the actual name of the RPL Object is copied to the system clipboard; see “Anchors in HTML Files” for details. This can then be used to paste into the Search field in the editor or viewer program. For example, if viewing a PDF, the user can click the external documentation icon for a function, then press Ctrl+F to bring up the search field/dialog, then press Ctrl+V to paste the name of the function in the box.
The following sections describe the specific application recommended (and not recommended) to view and edit each type of document and then the mechanism to configure the application that is associated with a document type.
• Hyper Text Markup Language (.html)
• MS Word (.doc or .docx)
• Portable Document Format (.pdf)
• Text (.txt or other)
HTML
Hyper Text Markup Language (HTML) is a common format used by web pages. There are numerous tools to develop and view these types of files.
Viewing HTML Files
HTML can be viewed using any common browser.
Editing HTML Files
HTML can be edited using web development tools such as Adobe (MacroMedia) Dreamweaver. MS Word can also be used edit HTML files.
Anchors in HTML Files
When a document describes more than one object and the user requests to view the documentation for a particular object, the program, if configured correctly, can open to the most relevant location within the document. In order to accomplish this, there needs to be some sort of connection between locations within the document and objects in the set. In this document we will refer to these as anchors. In HTML, locations within a document are defined using named anchors.
RiverWare uses anchors to provide a mechanism for navigating to a particular location within a document. For a given object that inherits its document location from a parent object, by default RiverWare assumes the existences of an anchor for this object whose text is based on the object name. In particular, we assume that the anchor label is the object name, with illegal characters replaced with legal ones. The user may override the default value and edit it or specify that no anchor exists.
Typically, the user is responsible for inserting anchors into the external documentation; see “Generating a HTML Template File” for a tool to help create a document with anchors. RiverWare doesn’t attempt to inspect the documentation, so care will be required on the part of the user to maintain anchors correctly. As with other sorts of references from an external document to the details of a ruleset, the potential for inconsistencies is large. For example, if the user changes the name of a function in a ruleset, then the name of the anchor for that function in the documentation would need to be changed as well. In addition, access programs will often not normally make anchor text visible, making it more challenging for the user to verify that the anchor labels are correct. To support the management of anchors, RiverWare supports copy/paste between fields containing object names and external programs.
For example, if the external document points to the following HTML file:
http://www.WaterU.edu/Models/Functions.html
and a function named Set Outputs is given the default anchor SetOutputs. RiverWare will then provide the following to the access program:
http://www.WaterU.edu/Models/Functions.html#SetOutputs
Generating a HTML Template File
The External Documentation feature provides a utility to generate a template of the RPL objects in the set. This can be used as a starting point in which the user can fill in the missing pieces. It allows someone not too familiar with HTML to quickly generate a working document and all the associated anchors and formatting.
From the RPL set Configure External Document Reference, the user can select Utilities, then Generating HTML Template File to generate an HTML file that contains all of the RPL objects in the set. The file is created in the directory specified in the View Document configuration. It is given the name specified in the File field if it is an HTML file or the default name with a “-DocTemplate.html” appended if the File field contains a non-HTML file.
The HTML document also contains a table of contents that lists the type of RPL object, the name of that object (and a link to the referenced section) and the anchor that it uses. Shown in the body of the file is the RPL object name and any description (i.e. in the View, then Show Description in RPL editor) that existed in the RPL object at the time the template was created. Once the template is created, it can be viewed/edited using the view/edit button. The user can then fill in pieces as necessary and save the resulting file. Then there should be no need to re-generate this template again.
Figure 4.4 shows an example from a one group with one rule and one function. The text came from the description field in each object.
Figure 4.4   
Microsoft Word
Microsoft (MS) Word (.doc or .docx) files are commonly developed using Microsoft Word, but more recently can be viewed (and even edited) using many browsers.
Viewing Microsoft Word Files
Traditionally, .doc files could only be opened using Microsoft Word. Now, these can be viewed with certain browsers including Internet Explorer.
Note:  Choosing to view a .doc file with Microsoft Word and Explorer do not automatically make the document non-editable. The file system must be used if the user wishes to make the document read-only.
Editing Microsoft Word Files
Microsoft Word is typically used to edit .doc files. The latest versions of Internet Explorer also has capabilities to edit these types of files.
For both editing and viewing Word and HTML files, in MS Word has feature called the Document Map that is useful to navigate through documents. Similar to bookmarks in a PDF file, a pane is added to the document that allows the user to navigate to defined headings in the document.
To access this feature, use the View, then Document Map in MS Word. Figure 4.5 shows a sample for the HTML document; see “Generating a HTML Template File”.
Figure 4.5   
PDF
Adobe Portable Document Format (PDF) has become the standard document format when sharing read-only versions of documents. These documents can be viewed by the free Adobe Acrobat Reader and more recently by many browsers.
Viewing PDF Files
Viewing of PDF files is accomplished using a PDF Reader. This is the same format and program that the RiverWare Help file uses. This is not editable here, but you can change the default PDF reader in Windows by changing the file type association. Do an internet search on “Windows file type association” for details on setting this association.
Editing PDF Files
Although limited editing of PDF can be done using the full version of Adobe Acrobat, this is not a supported editing tool. Otherwise, PDFs are read-only and cannot be edited. They are typically created from some other document editing application like MS Word or Adobe FrameMaker. We will not discuss editing PDF further.
Text Files
Text files can be viewed (and edited) by any text editor and many web browsers. No further information is provided.
Use Example
Following is an imaginary use example to show the process. Perhaps, we are a water agency and have a complex ruleset. We wish to share this ruleset and documentation with stakeholders in the basin but we do not wish to let them have an easily editable copy of this document. Also, we already have some descriptions entered in the ruleset but no other documentation. In this example, we wish to use our favorite web browser to view the document and MS Word to edit the document. Once the document is complete, we will post it to a web page so that stakeholders can see it. As a result, we will use HTML as the type of document.
We set this up using the following procedure.
1. Define the file associations. We will use FireFox to view the document and MS Word to edit the document. Figure 4.6 shows how we set up the File Type Association Manager; see “File Association”.
Figure 4.6   
Because we are using HTML, we can use anchors to automatically open the HTML file to the right place.; see “Anchors in HTML Files”. As a result, we only need one document for the entire RPL set. Thus we are using the One Document that Describes the Entire Set structure; see “One Document that Describes the Entire Set”. We do want to have separate documents for viewing and editing. While making changes to the ruleset and hence the Edit document, we will still have an official View document that stakeholders can use. See “Separate View and Edit Documents” for a diagram of this structure. Hence, we will need to configure only the top level of the RPL set.
2. From the RPL set, we open the configuration menu using the View, then External Documentation, then Configure menu.
Because we already have some descriptions in our RPL set and we wish to use HTML, we will use the automatically generated template as a starting point. First lets specify a location to put the file, say C:\Temp\docs
3. In the View area, select the Custom toggle for the Directory and enter C:\Temp\docs
Now we will generate the template.
1. In the Configure dialog we choose Utilities, then Generating HTML Template File. It gives us a warning that a file named C:/Temp/docs/Basin-DocTemplate.html will be saved.
Note:  Our RPL set is named Basin.rls.gz.
2. We do not like the name of this file (and to avoid overwriting our completed external document with an inadvertently generated template file in the future), we change both the file name and the name in the configuration. We change the file to Basin-Doc.html using windows explorer. In the File area of the configuration, we change the name to Basin-Doc.html and select Apply when complete.
For now we will leave the View document in the C:\Temp\docs folder. Once we are complete we will move this to a web server. Figure 4.7 shows our configuration.
Figure 4.7   
3. Now we select the View button and see the template file in Firefox.
We see that we have a pseudo table of contents with links, then each object is listed with the text that came from the description.
4. We select the Edit button and see the file open in Word.
5. We edit the document in Word by adding text, pictures, graphs, flowcharts, etc. We make sure to save it as the same name. We can edit the formats of the headings and text. When editing the headings, we make sure to use the Format, then Styles and Formatting menu in Work to change all instances at once.
6. Anytime we wish to see how this document looks in the browser. We can save the file from Word and switch back to the RPL set and select the External Documentation icon . This takes us directly to that RPL Object section in the document.
7. When editing is complete, we copy the final HTML to a web server.
8. Then we go back to the configuration menu for the RPL Set and change the View document. First we want to indicate that the Edit document is now different, so we toggle off the Use View Document option. We make sure the Edit document area is now correct.
9. Now we want to change the View area to point the Custom Directory to a web server:
http://cadswes2.colorado.edu/docs/
Figure 4.8 shows the configuration for this setup.
If we select the external documentation icon for any RPL object, it will take us to this web page and automatically scroll to the section related to that object. We now share our model and ruleset with our stakeholders.
Figure 4.8   
 
Revised: 06/03/2019