Use Example
Following is an imaginary use example to show the process. Perhaps, we are a water agency and have a complex ruleset. We want to share this ruleset and documentation with stakeholders in the basin, but we do not want 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 want to view the document with our favorite web browser, and edit the document with our favorite HTML editor. Once the document is complete, we will post it to a web page so 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. Make sure your Windows file associations are defined. We will use a web browser to view the HTML document.
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 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 let’s 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.
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 file 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.5 shows our configuration.
Figure 4.5
3. Now select the View button and see the template file in a browser.
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 can then edit this HTML file in our favorite HTML editor or even Word to add 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 to change all instances at once.
5. When editing is complete, we copy the final HTML to a web server.
6. 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.
7. Now we want to change the View area to point the Custom Directory to a web server, such as:
http://SomeSampleWebServer.com/docs/
Figure 4.6 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.6
Revised: 01/05/2024