skip to main content
Viewing and Editing Documents
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, that is, 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.
Revised: 01/04/2021