179 lines
11 KiB
HTML
179 lines
11 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="reference" />
|
||
|
|
<meta name="DC.Title" content="Editing help documents generated by GUI Builder" />
|
||
|
|
<meta name="abstract" content="For each PDML project file, the GUI Builder generates a help skeleton and puts it into a single HTML document. Before use, this HTML file is broken up into single topic HTML files for each dialog of the PDML project. This provides the user with granular help for each topic and allows you to manage only a few large help files." />
|
||
|
|
<meta name="description" content="For each PDML project file, the GUI Builder generates a help skeleton and puts it into a single HTML document. Before use, this HTML file is broken up into single topic HTML files for each dialog of the PDML project. This provides the user with granular help for each topic and allows you to manage only a few large help files." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="pdmlpg1.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="helpinfo" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Editing help documents generated by GUI Builder</title>
|
||
|
|
</head>
|
||
|
|
<body id="helpinfo"><a name="helpinfo"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Editing help documents generated by GUI Builder</h1>
|
||
|
|
<div><p>For each PDML project file, the GUI Builder generates a help skeleton
|
||
|
|
and puts it into a single HTML document. Before use, this HTML file is broken
|
||
|
|
up into single topic HTML files for each dialog of the PDML project. This
|
||
|
|
provides the user with granular help for each topic and allows you to manage
|
||
|
|
only a few large help files.</p>
|
||
|
|
<div class="section"><p>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:</p>
|
||
|
|
<ul><li>Header</li>
|
||
|
|
<li>Topic section for each dialog</li>
|
||
|
|
<li>Topic section for each control that is help-enabled</li>
|
||
|
|
<li>Footer</li>
|
||
|
|
</ul>
|
||
|
|
<p>In addition, you can add additional topic sections before the footer
|
||
|
|
to provide additional information or common information. Topic sections have
|
||
|
|
only the html body until they are split, when a header and footer are created.
|
||
|
|
When the Help Document is split up, the processor adds a header and footer
|
||
|
|
to the topic section to make a complete HTML file. The header and footer from
|
||
|
|
the Help Document are used as default header and footer. However, you can
|
||
|
|
override the default header with your own.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Inside the Help Document</h4><p>The following sections
|
||
|
|
explain the parts of the Help Document: </p>
|
||
|
|
<dl><dt class="dlterm"><strong>Header</strong></dt>
|
||
|
|
<dd>The end of the header section is shown by the following tag:<pre><!-- HELPDOC:HEADEREND --></pre>
|
||
|
|
If
|
||
|
|
you want to override the default header for all of the individual topics when
|
||
|
|
they are split, use the <tt>HEADER</tt> keyword and provide the name of an
|
||
|
|
html fragment to include. For example:<pre><!-- HELPDOC:HEADEREND HEADER="defaultheader.html" --></pre>
|
||
|
|
</dd>
|
||
|
|
<dt class="dlterm"><strong>Topic segment</strong></dt>
|
||
|
|
<dd>Each topic is surrounded by the following tags: <pre><!-- HELPDOC:SEGMENTBEGIN --></pre>
|
||
|
|
and<pre><!-- HELPDOC:SEGMENTEND --></pre>
|
||
|
|
Immediately following the <tt>SEGMENTBEGIN</tt> tag is an anchor tag which
|
||
|
|
names the segment. It also provides the file name of the HTML document that
|
||
|
|
is created when the Help Document is split. The name of the segment combines
|
||
|
|
the panel identifier, control identifier, and future file extension (html).
|
||
|
|
For example: "MY_PANEL.MY_CONTROL.html" Segments for panels have only the
|
||
|
|
panel identifier and future file extension. <p>The help generator will place
|
||
|
|
text in the document indicating where you place your help information:</p>
|
||
|
|
<pre><!-- 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 --></pre>
|
||
|
|
<p> You can add additional
|
||
|
|
HTML 2.0 tags as needed after the anchor tag and before the <tt>SEGMENTEND</tt> tag. </p>
|
||
|
|
<p>The <tt>PDMLSYNCH</tt> tag
|
||
|
|
controls how closely a segment is tied to the controls defined in PDML. If <tt>PDMLSYCH</tt> is
|
||
|
|
"YES", the Help Document segment will be removed if the control of the same
|
||
|
|
name is removed in the PDML. <tt>PDMLSYNCH="NO"</tt> indicates the topic must
|
||
|
|
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.</p>
|
||
|
|
<p>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 want to have internal links within
|
||
|
|
a topic, the processor only removes any preceding "#" when the reference has
|
||
|
|
".html" embedded in it.</p>
|
||
|
|
<p>If you want to override the default header
|
||
|
|
for any particular topic, use the <tt>HEADER</tt> keyword and provide the
|
||
|
|
name of an html fragment to include. For example: </p>
|
||
|
|
<pre><!-- HELPDOC:SEGMENTBEGIN PDMLSYNCH="YES" HEADER="specialheader.html" --></pre>
|
||
|
|
</dd>
|
||
|
|
<dt class="dlterm"><strong>Footer</strong></dt>
|
||
|
|
<dd>The footer in the Help Document begins with the following tag: <pre><!-- HELPDOC:FOOTERBEGIN --></pre>
|
||
|
|
The
|
||
|
|
standard footer is </BODY></HTML>This footer is added to each HTML file.</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Adding links</h4><p>You can add links to any external or
|
||
|
|
internal URL as well as any other segment. However, you must follow some conventions: </p>
|
||
|
|
<ul><li>External URLs are used in the standard manner. This includes internal
|
||
|
|
links to external URLs</li>
|
||
|
|
<li>Internal links within the same topic are written in the standard way,
|
||
|
|
but must not have ".html" as part of the tag name. This is because the Help
|
||
|
|
Document processor assumes that any link with .html will need to be an external
|
||
|
|
link when the topics are separate. Therefore, it removes the preceding "#".</li>
|
||
|
|
<li>Links to other topic segments must be written with a preceding "#" as
|
||
|
|
though they are an internal anchor reference.</li>
|
||
|
|
<li>Internal links to other topic segments may also be created. Only the leading
|
||
|
|
"#" is removed during processing.</li>
|
||
|
|
</ul>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> <ul><li>At run-time, the PanelManager class looks for help files in a subdirectory
|
||
|
|
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. </li>
|
||
|
|
<li>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.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Editing using a visual editor</h4><p>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 want 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.</p>
|
||
|
|
<p><img src="rzahh059.gif" alt="Editing HELPDOC tags" /></p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Creating Additional Topics</h4><p>You can create additional
|
||
|
|
topic segments in the Help Document. It is often easiest to do this by copying
|
||
|
|
another segment. When you copy the segment, you must copy the horizontal rules
|
||
|
|
just before the SEGMENTBEGIN and after the SEGMENTEND tag. This will make
|
||
|
|
future visual editing much easier and help avoid mismatched tags. For best
|
||
|
|
results, use the following tips: </p>
|
||
|
|
<ul><li>The name of the anchor must be the name you want for the resulting single
|
||
|
|
file when the Help Document is split. It must end in ".html".</li>
|
||
|
|
<li>Use the PDMLSYNCH="NO" keyword on the SEGMENTBEGIN tag to prevent the
|
||
|
|
segment from being removed if the help skeleton is regenerated.</li>
|
||
|
|
<li>Any references to your new topic will be made as an internal link in the
|
||
|
|
Help Document with a preceding "#". This "#" will be removed in later processing
|
||
|
|
when the segments are split into single files.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Checking Your Links</h4><p>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.</p>
|
||
|
|
<p>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 <a href="helpex.htm#helpex__help2htm">Help
|
||
|
|
Document to HTML Processing</a>.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="pdmlpg1.htm" title="The Graphical Toolbox, a set of UI tools, makes it easy to create custom user interface panels in Java.">Graphical Toolbox and PDML</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|