The Help Document is a valid HTML file and can be viewed in any browser and edited using most HTML editors. Tags that define the sections in a Help Document are embedded within comments, so they do not show up in a browser. The comment tags are used to break the Help Document into several sections:
The help generator will place text in the document indicating where you should place your help information:
<!-- HELPDOC:SEGMENTBEGIN PDMLSYNCH="YES" --><A NAME="MY_PANEL.MY_CONTROL.html"></A> <H2>My favorite control</H2> Insert help for "My favorite control" here. <P><!-- HELPDOC:SEGMENTEND -->You can add additional HTML 2.0 tags as needed after the anchor tag and before the SEGMENTEND tag.
The PDMLSYNCH tag controls how closely a segment is tied to the controls defined in PDML. If PDMLSYCH is "YES", the Help Document segment will be removed if the control of the same name is removed in the PDML. PDMLSYNCH="NO" indicates the topic should be kept in the Help Document regardless of whether a corresponding control exists in the PDML. This is used, for example, when you create additional topics for depth or a common topic.
The help generated for a panel has links to each control enabled for help on the panel. These links are generated with a local anchor reference, so that you can test them as internal links in a standard browser. When the Help Document is split, the processor removes the "#" on these internal links making them external links in the resulting single topic HTML files. Because you may wish to have internal links within a topic, the processor only removes any preceding "#" when the reference has ".html" embedded in it.
If you want to override the default header for any particular
topic, use the HEADER keyword and provide the name of an
html fragment to include.. For example:
<!-- HELPDOC:SEGMENTBEGIN PDMLSYNCH="YES"
HEADER="specialheader.html" -->
NOTE: At run-time, the PanelManager class
looks for help files in a subdirecory with the same name as the
PDML file. When the processor splits the Help Document, it creates
this subdirectory by default and places the resulting HTML files in
it.
The processor does not make any adjustments for external URL references that are relative links. When you link from an individual topic file, any relative links will be searching from the new subdirectory. Therefore, you will need to place copies of resources such as images where they can be found or use "../" in the path in order to search from the panel directory. |
You can edit your help content in almost any visual HTML editor. Because the HELPDOC tags are comments they may not be obvious in some editors. For convenience, a horizontal rule is added to the help skeleton immediately before the SEGMENTBEGIN tag and immediately after the SEGMENTEND tag. These horizontal rules provide clear visual indication of the entire segment in a visual editor. If you select a segment because you wish to move, copy, or delete it, select the surrounding horizontal rules to be sure you have included the SEGMENTBEGIN and SEGMENTEND tags in your selection. These horizontal rules are not copied to the final individual HTML files.
For most writing, you can check your links by viewing your document in a web browser and selecting different links. In the single Help Document, the links are still in their internal form.
As you reach completion, or when you want to test with the application you are developing help for, you will need to break the Help Document into single files. You do this with Help Document to HTML Processing.
If you need to regenerate the Help Document after editing, your writing will be preserved. You may want to regenerate the Help Document if you add new controls after generating the original help skeleton. In this case, the help generator checks for an existing Help Document before it creates a new skeleton. If one is found, it preserves any existing segments and then adds the new controls.