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:

Similarly, editing can be done directly from the RPL object using one of the following methods:

Hovering over the External Documentation icon provides tooltips on the use of this button, as follows:

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) is a common format used by web pages. There are numerous tools to develop and view these types of files.

HTML can be viewed using any common browser.

HTML can be edited using web development tools such as Adobe (MacroMedia) Dreamweaver. MS Word can also be used edit 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:

and a function named Set Outputs is given the default anchor SetOutputs. RiverWare will then provide the following to the access program:

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.

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.

Traditionally, .doc files could only be opened using Microsoft Word. Now, these can be viewed with certain browsers including Internet Explorer.

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.

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 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.

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 can be viewed (and edited) by any text editor and many web browsers. No further information is provided.