767 lines
37 KiB
Plaintext
767 lines
37 KiB
Plaintext
<!-- $XConsortium: ch03.sgm /main/11 1996/09/08 19:39:54 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.WrTop.div.1">
|
|
<title id="HRDC.WrTop.mkr.1">Writing a Help Topic</title>
|
|
<para>This chapter describes elements that you can use to structure your text.
|
|
It also explains how to include graphics and how to create hyperlinks to other
|
|
help topics.</para>
|
|
<informaltable id="HRDC.WrTop.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Creating Structure within a Topic52'--><xref
|
|
role="JumpText" linkend="HRDC.WrTop.mkr.2"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Entering Inline Elements62'--><xref
|
|
role="JumpText" linkend="HRDC.WrTop.mkr.9"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Creating Hyperlinks64'--><xref role="JumpText"
|
|
linkend="HRDC.WrTop.mkr.14"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Displaying Graphics76'--><xref role="JumpText"
|
|
linkend="HRDC.WrTop.mkr.23"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Including Special Characters80'--><xref
|
|
role="JumpText" linkend="HRDC.WrTop.mkr.27"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Including Comments and Writer's Memos81'--><xref
|
|
role="JumpText" linkend="HRDC.WrTop.mkr.29"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Creating an Index82'--><xref role="JumpText"
|
|
linkend="HRDC.WrTop.mkr.32"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Creating a Glossary83'--><xref role="JumpText"
|
|
linkend="HRDC.WrTop.mkr.34"></para></entry></row></tbody></tgroup></informaltable>
|
|
<sect1 id="HRDC.WrTop.div.2">
|
|
<title>Creating Help Topics</title>
|
|
<para>A help topic is a unit of information identified with a unique ID. Help
|
|
topics are grouped into a logical framework that best describes the product
|
|
for which you are writing online help.</para>
|
|
<para>The hierarchy of elements provided by DocBook gives you the framework
|
|
for organizing the help topics you write. The hierarchy of elements is as
|
|
follows: Chapter, Sect1, Sect2, Sect3, Sect4, and Sect5.</para>
|
|
<para>A topic's position within the hierarchy is determined by the element
|
|
which contains it, and how that element is embedded in higher level elements.
|
|
For example, if a topic that is tagged as Sect2 follows a topic tagged as
|
|
Sect1, that makes it a subtopic of the Sect1 topic.</para>
|
|
<para>An ID is required if the topic is to be accessed either from the application
|
|
(if you are writing application help) or from a hyperlink. Typically both
|
|
the element that contains the topic and its title will be marked with IDs.
|
|
ID is one of the attributes of the elements Chapter, Sect1, Sect2, Sect3,
|
|
Sect4, Sect5, and Title.</para>
|
|
<sect2 id="HRDC.WrTop.div.3">
|
|
<title>Example</title>
|
|
<para>The following line marks the start of a topic using the <Sect1> tag:
|
|
</para>
|
|
<programlisting><sect1 id="HRDC.WrTop.div.2"></programlisting>
|
|
<para>A Title is required for the elements Chapter, Sect1, Sect2, Sect3, Sect4,
|
|
Sect5, and immediately follows the start tag of the element. The markup would
|
|
look like this:</para>
|
|
<programlisting><sect1 id="HRDC.WrTop.div.2">
|
|
<title>Help Topics</title></programlisting>
|
|
<sect3 id="HRDC.WrTop.div.4">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><!--Original XRef content: 'Chapter 2,
|
|
“Organizing and Writing a Help Volume'--><xref role="ChapNumAndTitle"
|
|
linkend="HRDC.OrgH.mkr.1">, describes the general structure of a help volume,
|
|
including how to create a topic hierarchy.</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.5">
|
|
<title id="HRDC.WrTop.mkr.2">Creating Structure within a Topic</title>
|
|
<para>Within the body of a help topic, you have the following elements to
|
|
choose from to organize and present your information:</para>
|
|
<itemizedlist><listitem><para><emphasis>Paragraphs</emphasis> are used for
|
|
bodies of text.</para>
|
|
</listitem><listitem><para><emphasis>Lists</emphasis> are used for listed
|
|
information. There are several types of lists: ItemizedLists (bulleted), OrderedLists
|
|
(numbered), VariableLists (for defining lists of terms), and SegmentedLists
|
|
(for comparably labelled sets of information).</para>
|
|
</listitem><listitem><para><emphasis>Tables</emphasis> are for structured
|
|
arrays of information. There are InformalTables (untitled) and Tables (which
|
|
require a Title).</para>
|
|
</listitem><listitem><para><emphasis>Graphics</emphasis> can be included within
|
|
your text as <emphasis>inline elements</emphasis> or displayed between paragraphs
|
|
as standalone <emphasis>block-oriented elements</emphasis>. A Graphic points
|
|
to exterior files that contain the graphical data</para>
|
|
</listitem><listitem><para><emphasis>Hyperlinks</emphasis> provide references
|
|
to related topics. A hyperlink may lead to a subtopic, deeper in the hierarchy,
|
|
or branch to a topic in a completely different part of the hierarchy, or even
|
|
in another help volume.</para>
|
|
</listitem><listitem><para><emphasis>Computer literals</emphasis> are computer-recognized
|
|
text, such as file names and variable names, that can be displayed as either
|
|
separate example listings or inline elements.</para>
|
|
</listitem><listitem><para><emphasis>Notes, cautions, and warnings</emphasis>
|
|
call the reader's attention to important information.</para>
|
|
</listitem><listitem><para><emphasis>Emphasis</emphasis> is used to highlight
|
|
important words and phrases within paragraph text.</para>
|
|
</listitem></itemizedlist>
|
|
<sect2 id="HRDC.WrTop.div.6" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.3">To Start a Paragraph</title>
|
|
<para>Generally you use the <Para> tag to mark the start of a new paragraph.
|
|
The DocBook DTD offers three kinds of paragraphs. Para may contain block-oriented
|
|
elements (such as Lists and Figures). SimPara may contain only plain text
|
|
and in-line elements. FormalPara requires a Title.</para>
|
|
<para>If you want the paragraph to maintain the line breaks that you enter
|
|
in your source file, use the <LiteralLayout> tag.</para>
|
|
<sect3 id="HRDC.WrTop.div.7">
|
|
<title>Examples</title>
|
|
<para>Here is an example of a plain vanilla paragraph:</para>
|
|
<programlisting><para>The Application Builder provides an interactive, graphical environment that facilitates the development of desktop applications. </para>
|
|
</programlisting>
|
|
<para>The following LiteralLayout overrides the automatic word wrap in help
|
|
windows and maintains the line breaks exactly as entered in the source file.
|
|
The LiteralLayout element is especially useful for entering addresses.</para>
|
|
<programlisting><LiteralLayout>
|
|
Brown and Reed Financial Investors
|
|
100 Baltic Place Suite 40
|
|
New York, New York
|
|
</LiteralLayout></programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.8" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.4">To Enter an ItemizedList</title>
|
|
<para>An ItemizedList is a list in which every item is marked with a bullet,
|
|
dash, or other dingbat, or no mark at all. An ItemizedList contains one or
|
|
more ListItems.</para>
|
|
<para>A ListItem in an ItemizedList can contain paragraphs and other block-oriented
|
|
elements, including other lists.</para>
|
|
<para>You can use the Mark attribute to specify the mark you want used in
|
|
the ItemizedList. There is no fixed list of values for the Mark attribute,
|
|
but you can used the ISO text entity that designates the dingbat you want
|
|
used. Your application might supply the mark that will be used for an ItemizedList.
|
|
</para>
|
|
<para>Here is the syntax you use for the ItemizedList element:</para>
|
|
<programlisting><ItemizedList Mark="Bullet">
|
|
<ListItem>
|
|
<para> ... </para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para> ... </para>
|
|
</ListItem>
|
|
...
|
|
</ItemizedList></programlisting>
|
|
<sect3 id="HRDC.WrTop.div.9">
|
|
<title>Examples</title>
|
|
<para>Here is the markup for a simple ItemizedList:</para>
|
|
<programlisting><itemizedlist>
|
|
<listitem><para>Creating a Mail Message</para></listitem>
|
|
<listitem><para>Sending a Message</para></listitem>
|
|
<listitem><para>Reading Your Mail</para></listitem>
|
|
</itemizedlist></programlisting>
|
|
<para>The preceding markup would produce an ItemizedList that might appear
|
|
as follows:</para>
|
|
<itemizedlist><listitem><para>Creating a Mail Message</para>
|
|
</listitem><listitem><para>Sending a Message</para>
|
|
</listitem><listitem><para>Reading Your Mail</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.8a" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.4a">To Enter an OrderedList</title>
|
|
<para>An OrderedList contains ListItems marked with numbers or letters. A
|
|
ListItem within an OrderedList can contain paragraphs and other block-oriented
|
|
elements, including ItemizedLists and OrderedLists.</para>
|
|
<para>OrderedList has the Common attributes, and also Numeration, InheritNum,
|
|
and Continuation attributes.</para>
|
|
<para>The Numeration attribute specifies how the ListItems in the OrderedList
|
|
will be numbered or lettered. It may take the values Arabic, Upperalpha, Loweralpha,
|
|
Upperromman, or Lowerroman. If no value is specified, the expectation should
|
|
be that Arabic numbering is to be used.</para>
|
|
<para>The InheritNum attribute takes on the values Inherit or Ignore. If the
|
|
value is Inherit, it specifies that the numbering of ListItems in a nested
|
|
list should include the number of the ListItem within which it is nested.
|
|
That is, if another Orderedlist is nested in the second ListItem, the ListItems
|
|
of the nested list will be numbered 2a, 2b, 2c, etc., rather than simply a,
|
|
b, c, etc.</para>
|
|
<para>The Continuation attribute takes on the values Continues or Restarts.
|
|
If the value is Continues, the numbering of the OrderedList continues that
|
|
of the immediately preceding OrderedList. If the value is Restarts (the default),
|
|
the numbering of the OrderedList begins afresh. You need to supply the Continuation
|
|
attribute only if this OrderedList continues the numbering of the preceding
|
|
one.</para>
|
|
<sect3 id="HRDC.Ref.div.8b">
|
|
<title>Syntax Example</title>
|
|
<para>The following markup:</para>
|
|
<programlisting><OrderedList>
|
|
<ListItem>
|
|
<para>Creating a Mail Message</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>Sending a Message</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>Reading Your Mail</para>
|
|
</ListItem>
|
|
</OrderedList></programlisting>
|
|
<para>Produces the following list:</para>
|
|
<orderedlist><listitem><para>Creating a Mail Message</para>
|
|
</listitem><listitem><para>Sending a Message</para>
|
|
</listitem><listitem><para>Reading Your Mail</para>
|
|
</listitem></orderedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.8c" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.4c">To Enter a SegmentedList</title>
|
|
<para>SegmentedList marks a list segmented into labelled parallel sets of
|
|
information.</para>
|
|
<para>A SegmentedList may have an optional Title and TitleAbbrev, followed
|
|
by any number of SegTitles, and one or more SegListItems. Each SegListItem
|
|
has the same number of Segs as there are SegTitles in the SegmentedList to
|
|
which it belongs.</para>
|
|
<sect3 id="HRDC.Ref.div.8d">
|
|
<title>Syntax Example</title>
|
|
<para>The following is a markup for a SegmentedList:</para>
|
|
<programlisting><SegmentedList>
|
|
<SegTitle>Nation</SegTitle>
|
|
<SegTitle>Ethnic Groups</SegTitle>
|
|
<SegTitle>Languages</SegTitle>
|
|
<SegListItem>
|
|
<Seg>Japan</Seg>
|
|
<Seg>Japanese, Koreans, Ainu</Seg>
|
|
<Seg>Japanese</Seg>
|
|
</SegListItem>
|
|
<SegListItem>
|
|
<Seg>Spain</Seg>
|
|
<Seg>Spanish, Basques</Seg>
|
|
<Seg>Castillian, Catalan, Basque</Seg>
|
|
</SegListItem>
|
|
<SegListItem>
|
|
<Seg>Belgium</Seg>
|
|
<Seg>Flemish, Walloons<</Seg>
|
|
<Seg>Dutch, French</Seg>
|
|
</SegListItem>
|
|
</SegmentedList></programlisting>
|
|
<para>Would produce a list which might appear like this:</para>
|
|
<segmentedlist>
|
|
<segtitle>Nation</segtitle>
|
|
<segtitle>Ethnic Groups</segtitle>
|
|
<segtitle>Languages</segtitle>
|
|
<seglistitem>
|
|
<seg>Japan</seg>
|
|
<seg>Japanese, Koreans, Ainu</seg>
|
|
<seg>Japanese</seg></seglistitem>
|
|
<seglistitem>
|
|
<seg>Spain</seg>
|
|
<seg>Spanish, Basques</seg>
|
|
<seg>Castillian, Catalan, Basque</seg></seglistitem>
|
|
<seglistitem>
|
|
<seg>Belgium</seg>
|
|
<seg>Flemish, Walloons</seg>
|
|
<seg>Dutch, French</seg></seglistitem>
|
|
</segmentedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.8e" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.4e">To Enter a VariableList</title>
|
|
<para>The VariableList element is used to create a list of terms and their
|
|
definitions.</para>
|
|
<para>VariableList may have an optional Title and TitleAbbrev, followed by
|
|
one or more required VarListEntries.</para>
|
|
<para>VarListEntry is a required component of a VariableList. VarListEntry
|
|
contains a Term element, which marks the term being defined, and a ListItem
|
|
element, which holds the definition of the term.</para>
|
|
<sect3 id="HRDC.WrTop.div.8f">
|
|
<title>Example</title>
|
|
<para>Here is the syntx of the markup for a VariableList:</para>
|
|
<programlisting><VariableList>
|
|
<varlistentry>
|
|
<term>first term</term>
|
|
<listitem><para>definition of first term </para><listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>second term</term>
|
|
<listitem><para>definition of second term </para><listitem>
|
|
</varlistentry>
|
|
...
|
|
</VariableList></programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.17" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.6">To Show a Computer Listing</title>
|
|
<para>To show sections of program source code without changing the spacing
|
|
or line breaks, use the ProgramListing element. Line breaks and leading white
|
|
space are considered significant in a ProgramListing and preserved as-is.
|
|
</para>
|
|
<para>ProgramListing may contain inline elements, including LineAnnotations.
|
|
(LineAnnotations are comments on the code by the document author, not the
|
|
comments written into the code itself by the author of the code.</para>
|
|
<para>A ProgramListing may be embedded within the Example element. Example
|
|
typically contains a required Title and a ProgramListing.</para>
|
|
<para>ProgramListing has a Width attribute, which takes on numerical values
|
|
representing the maximum width of the contents.</para>
|
|
<para>Line breaks appear where you enter them in your source file. If the
|
|
example is too wide for the help window, a horizontal scroll bar appears so
|
|
the user can scroll to see all the example text.</para>
|
|
<warning>
|
|
<para>Do not include character sequences within a ProgramListing
|
|
that could be interpreted as DocBook markup tags. To avoid this problem, use
|
|
"&lt;" (the entity reference for the opening angle bracket) rather than
|
|
"<" to begin the names of markup tags.</para>
|
|
</warning>
|
|
<sect3 id="HRDC.WrTop.div.18">
|
|
<title>Example</title>
|
|
<para>In the following markup the ProgramListing element is used to represent
|
|
a directory listing in a terminal window.</para>
|
|
<programlisting><programlisting>In this tutorial, you will edit these graphics files:
|
|
H_ActionIcons.xwd H_HelpWindows.xwd
|
|
H_AppHelp.xwd H_Hyperlinks.xwd
|
|
H_Canonical.xwd H_Icons.xwd
|
|
H_FrontPanel.xwd H_InlineGraphic.xwd
|
|
</programlisting></programlisting>
|
|
<para>The markup produces this output:</para>
|
|
<programlisting>In this tutorial, you will edit these graphics files:
|
|
H_ActionIcons.xwd H_HelpWindows.xwd
|
|
H_AppHelp.xwd H_Hyperlinks.xwd
|
|
H_Canonical.xwd H_Icons.xwd
|
|
H_FrontPanel.xwd H_InlineGraphic.xwd</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.20" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.7">To Add a Note, Caution, or Warning</title>
|
|
<para>Use the Note, Caution, and Warning elements as follows:</para>
|
|
<programlisting><note>
|
|
<symbol>Body of note here.</symbol>
|
|
</note>
|
|
|
|
<caution>
|
|
<symbol role="Variable">Body of caution here</symbol>
|
|
</caution>
|
|
|
|
<warning>
|
|
<symbol role="Variable">Body of warning here.</symbol>
|
|
</warning></programlisting>
|
|
<para>The icons associated with the Note, Caution, and Warning elements are
|
|
obtained from the following graphics files, relative to your <filename>.sdl</filename> file:</para>
|
|
<para><filename>graphics/noteicon.pm</filename></para>
|
|
<para><filename>graphics/cauticon.pm</filename></para>
|
|
<para><filename>graphics/warnicon.pm</filename></para>
|
|
<para>The default icons are in<filename>/usr/dt/appconfig/help/C/graphics</filename>. If you create your own icons, be sure to keep them small, so
|
|
they will fit into the area allotted.</para>
|
|
<sect3 id="HRDC.WrTop.div.21">
|
|
<title>Example</title>
|
|
<para>The following markup for a note, warning, and caution produces the output
|
|
shown in <!--Original XRef content: 'Figure 3‐1'--><xref role="CodeOrFigureOrTable"
|
|
linkend="HRDC.WrTop.mkr.8">.</para>
|
|
<programlisting><note>
|
|
Before installing your application, complete the options checklist to determine the amount of disk space required.
|
|
</note>
|
|
|
|
<warning>
|
|
This product is highly acidic and can cause skin irritation. Wearing protective gloves is mandatory when applying this product.
|
|
</warning>
|
|
|
|
<caution>
|
|
Do not place your fingers near the parrot cage!
|
|
</caution>
|
|
|
|
</programlisting>
|
|
<figure>
|
|
<title id="HRDC.WrTop.mkr.8">Note, warning, and caution help icons</title>
|
|
<graphic id="HRDC.WrTop.grph.1" entityref="HRDC.WrTop.fig.7"></graphic>
|
|
</figure>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.23">
|
|
<title id="HRDC.WrTop.mkr.9">Entering Inline Elements</title>
|
|
<para>Inline elements are used to mark words or phrases within a paragraph
|
|
of text. These elements affect the font used to format particular items.</para>
|
|
<sect2 id="HRDC.WrTop.div.24" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.10">To Emphasize a Word or Phrase</title>
|
|
<para>Use the Emphasis element as shown:</para>
|
|
<programlisting><emphasis><symbol role="Variable">text</symbol> </emphasis>
|
|
</programlisting>
|
|
<sect3 id="HRDC.WrTop.div.25">
|
|
<title>Example</title>
|
|
<para>Here's how you might emphasize an important word:</para>
|
|
<programlisting>A thousand times <emphasis>no</emphasis></programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.26" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.11">To Cite a Title</title>
|
|
<para>Use the CiteTitle element as shown:</para>
|
|
<programlisting><CiteTitle> <symbol>title of a Book</symbol></CiteTitle>
|
|
</programlisting>
|
|
<sect3 id="HRDC.WrTop.div.27">
|
|
<title>Example</title>
|
|
<para>Here's how you would cite the title of this guide:</para>
|
|
<programlisting><CiteTitle>The Help System Author's and Programmer's Guide<CiteTitle>
|
|
</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.26a" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.11a">To Mark the Title of a Book, Chapter, or Section</title>
|
|
<para>Use the Title element as shown:</para>
|
|
<programlisting><Title> <symbol>title of the Book, Chapter, or Section</symbol></Title></programlisting>
|
|
<sect3 id="HRDC.WrTop.div.27a">
|
|
<title>Example</title>
|
|
<para>Here's how you would cite the title of this section:</para>
|
|
<programlisting><Title>To Mark the Title of a Book, Chapter, or Section</Title>
|
|
</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.29" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.12">To Display a Computer Literal</title>
|
|
<para>To display data presented to the user by a computer use the ComputerOutput
|
|
element as follows:</para>
|
|
<programlisting><computeroutput> <symbol>text</symbol></computeroutput>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.29a" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.12a">To Display a Filename</title>
|
|
<para>To display the name of a computer file, use the Filename element as
|
|
follows:</para>
|
|
<programlisting><filename><symbol>some filename</symbol></filename>
|
|
</programlisting>
|
|
<sect3 id="HRDC.WrTop.div.30a">
|
|
<title>Example</title>
|
|
<para>This markup:</para>
|
|
<programlisting>Add the entity to your <filename>Volume.sgm</filename> file.
|
|
</programlisting>
|
|
<para>produces this output:</para>
|
|
<para>Add the entityto your <filename>Volume.sgm</filename> file.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.31" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.13">To Display a Variable</title>
|
|
<para>To dispaly a variable, use the Symbol element as shown:</para>
|
|
<programlisting><symbol Role="Variable"> <symbol>text</symbol></symbol>
|
|
</programlisting>
|
|
<sect3 id="HRDC.WrTop.div.32">
|
|
<title>Example</title>
|
|
<para>This command-line syntax uses a variable to show that the user supplies
|
|
a file name.</para>
|
|
<programlisting>dtpad <symbol Role="Variable">filename</symbol></programlisting>
|
|
<para>It produces this output:</para>
|
|
<programlisting>dtpad <symbol>filename</symbol></programlisting>
|
|
<para>Symbol can appear within ComputerOutputs or ProgramListings.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.33">
|
|
<title id="HRDC.WrTop.mkr.14">Creating Hyperlinks</title>
|
|
<para>A hyperlink references a specific topic or location in a help volume.
|
|
This requires that the element you want to reference is given a unique ID.
|
|
</para>
|
|
<para>All the DocBook elements with the common attributes can be assigned
|
|
IDs, including Chapters, Sects, Titles, Lists, Graphics, and Tables.</para>
|
|
<para>Four DocBook elements are used in creating hyperlinks: Link, Anchor,
|
|
OLink, and XRef.</para>
|
|
<itemizedlist><listitem><para>Link marks a hypertext link. Link may contain
|
|
in-line elements, and it has Linkend and Type attributes.</para>
|
|
<para>The Linkend attribute is required. It specifies the target of the link
|
|
by giving the ID of the element the Link is linked to.</para>
|
|
<para>Link uses the SGML mechanism of IDREF in pointing to an element by its
|
|
ID. An SGML application may report an IDREF error when the ID specified in
|
|
a Linkend attribute does not occur in the document set being processed.</para>
|
|
<para>Link has a Type attribute which may take the following values: Jump,
|
|
JumpNewView, AppDefined, and Man.</para>
|
|
<para>A Jump link is the most common type of hyperlink. When the user chooses
|
|
a Jump link, the related topic is displayed.</para>
|
|
<para>JumpNewView links are intended for cross-volume links. When the user
|
|
chooses a JumpNewView link, a new dialog box containing information is displayed.
|
|
</para>
|
|
<para>An AppDefined link is for invoking some application behavior. To invoke
|
|
this behavior, the help must be displayed in dialogs created by the application.
|
|
</para>
|
|
<para>A Man link, when activated, displays a “man page” which
|
|
gives a brief online explanation of a system command. The information on man
|
|
pages is not supplied through the DocBook system.</para>
|
|
</listitem><listitem><para>Anchor marks a target for a Link. Anchor is an
|
|
inline element that may appear almost anywhere. Anchor is an empty element,
|
|
with no content. (Of course any element with an ID can serve as the target
|
|
of a Link.)</para>
|
|
<para>Anchor has a required ID attribute. At the minimum, only the Anchor
|
|
start tag is present, with an ID.</para>
|
|
</listitem><listitem><para>OLink marks a link that may perform some operation
|
|
to find its target.</para>
|
|
<para>OLink has a TargetDocEnt attribute, the value of which is the name of
|
|
a text or data entity already specified by the user.</para>
|
|
<para>OLink has a LinkMode attribute which points by an ID to a ModeSpec (located
|
|
for convenience in the BookInfo or DocInfo), which contains instructions for
|
|
operating on the entity named by the TargetDocEnt attribute. For example,
|
|
the TargetDocEnt may be another book, and the LinkMode attribute may specifiy
|
|
a ModeSpec that calls for all second-level headings to be searched for a particular
|
|
phrase.</para>
|
|
</listitem><listitem><para>XRef marks a cross reference link to another part
|
|
of the document.</para>
|
|
<para>Like Link, XRef has Linkend attribute, but like Anchor, it may have
|
|
no content.</para>
|
|
<para>The Title of the element specified by the Linkend attribute is used
|
|
as they text of the cross reference.</para>
|
|
</listitem></itemizedlist>
|
|
<sect2>
|
|
<title>Examples</title>
|
|
<para>This Link gives the label of a hot spot explicitly:</para>
|
|
<programlisting>To go there,<Link Linkend="H1-122-ch10-1> click here.</Link>
|
|
</programlisting>
|
|
<para>This Link points to a section and displays its title as the hot spot:
|
|
</para>
|
|
<programlisting>Click to go to <Link Linkend="S1-123-ch12-1" Endterm="T1-123-ch12-1"></Link>
|
|
</programlisting>
|
|
<para>The following example references the section of the document that has
|
|
the ID "ch05-s1" and supplies the text of its Title.</para>
|
|
<programlisting>See <Xref Linkend="ch05-s1"> for more information.</programlisting>
|
|
<para>It might be displayed like this: "See <citetitle>Terminal Emulation
|
|
and Terminal Type</citetitle> for more information."</para>
|
|
<para>There is an Anchor <symbol><anchor id=“077-ch02-AN-7”></symbol> in this sentence.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.44" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.16">To Create a Definition Link</title>
|
|
<para>If you are linking to a term in the Glossary, use the GlossTerm element
|
|
as shown:</para>
|
|
<programlisting><GlossTerm><symbol>text</symbol></GlossTerm></programlisting>
|
|
<para>Whenever you use the GlossTerm element in the text, be sure you include
|
|
a corresponding GlossEntry in the Glossary that gives the definition of the
|
|
term.</para>
|
|
</sect2>
|
|
</sect1><?Pub Caret>
|
|
<sect1 id="HRDC.WrTop.div.64">
|
|
<title id="HRDC.WrTop.mkr.23">Displaying Graphics</title>
|
|
<para>Help supports four graphics formats:</para>
|
|
<itemizedlist><listitem><para><emphasis>Tagged Image File Format (TIFF)</emphasis>—Color,
|
|
grayscale, and black-and-white images created by many standard drawing and
|
|
scanning applications (<symbol role="Variable">filename</symbol><filename>.tif</filename>).</para>
|
|
</listitem><listitem><para><emphasis>X Window dump</emphasis>—Screen
|
|
dumps from the X Window System™ created with the <command>xwd</command>
|
|
utility ( <symbol role="Variable">filename</symbol><filename>.xwd</filename>)
|
|
</para>
|
|
</listitem><listitem><para><emphasis>X pixmap</emphasis>—Color icon
|
|
images (<symbol role="Variable">filename</symbol><filename>.pm</filename>).
|
|
</para>
|
|
</listitem><listitem><para><emphasis>X bitmap</emphasis>—Two-color icon
|
|
images (<symbol role="Variable">filename</symbol><filename>.bm</filename>).
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
<para>Each graphic is maintained as a separate file. The file format is determined
|
|
using the file name extensions listed.</para>
|
|
<para>The Graphic element points via its attributes to an external file containing
|
|
graphical data.</para>
|
|
<para>A Graphic may be contained within a Figure. Figure must have a Title,
|
|
and may also contain a Link.</para>
|
|
<para>A Graphic is to be rendered as an object, not in-line. For in-line objects,
|
|
use the InlineGraphic element.</para>
|
|
<para>Graphic has the following attributes: Fileref, Entityref, and ID.</para>
|
|
<para>The value of the Fileref attribute should be a filename, qualified by
|
|
a pathname if desired.</para>
|
|
<para>The value of the Entityref attribute should be that of an external data
|
|
entity.</para>
|
|
<sect2 id="HRDC.Ref.div.">
|
|
<title>Syntax</title>
|
|
<para>Here are some examples of the syntax of Graphic:</para>
|
|
<programlisting><graphic id="ABUG.edprp.igrph.1" entityref="ABUG.edprp.fig.1"></graphic>
|
|
<graphic id="ABUG.crobj.igrph.2" entityref="ABUG.crobj.fig.2"></graphic>
|
|
<graphic id="ABUG.crobj.igrph.1" entityref="ABUG.crobj.fig.1"></graphic>
|
|
</programlisting>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.65" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.24">To Create a Figure</title>
|
|
<orderedlist><listitem><para>Declare a file entity to identify the image
|
|
file to be included in the Graphic that will be contained inside the Figure.
|
|
</para>
|
|
<programlisting><!entity <symbol role="Variable">graphic-entity</symbol> SYSTEM “<symbol role="Variable">filename.ext</symbol>”></programlisting>
|
|
</listitem><listitem><para>Use the Graphic element as shown:</para>
|
|
<programlisting><Graphic id="<symbol>id</symbol>"> entityref=" <symbol>graphic-entity</symbol>"<Graphic></programlisting>
|
|
<para>Where <symbol role="Variable">graphic-entity</symbol> is the entity
|
|
name for the graphic file you want to display.</para>
|
|
</listitem></orderedlist>
|
|
<para>If you want the Figure to be a hyperlink, use InlineGraphic instead
|
|
of Graphic, and put it inside a Link element.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.73">
|
|
<title id="HRDC.WrTop.mkr.27">Including Special Characters</title>
|
|
<para>Many special characters and symbols are available within DocBook. You
|
|
display a particular character by entering the appropriate entity reference.
|
|
</para>
|
|
<para>Refer to <!--Original XRef content: 'Chapter 6, “Summary
|
|
of Special Character
|
|
Entities'--><xref role="ChapNumAndTitle" linkend="HRDC.ChEnt.mkr.1">, for
|
|
a complete list of the available characters.</para>
|
|
<sect2 id="HRDC.WrTop.div.74" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.28">To Include a Special Character</title>
|
|
<orderedlist><listitem><para>Refer to <!--Original XRef content: 'Chapter 6,
|
|
“Summary of Special Character
|
|
Entities'--><xref role="ChapNumAndTitle" linkend="HRDC.ChEnt.mkr.1">, to determine
|
|
the entity name for the character you want to display.</para>
|
|
</listitem><listitem><para>Determine which ISO entity file contains the special
|
|
character, and add the following two lines among your other entity declarations
|
|
(where <symbol>entity-name</symbol> is a meaningful name to you):</para>
|
|
<programlisting><!entity & <symbol role="Variable">ISOset</symbol> PUBLIC "<symbol role="Variable">ISOsetpublicID</symbol>">
|
|
% ISOset;
|
|
|
|
</programlisting>
|
|
</listitem><listitem><para>Wherever you want to display the special character,
|
|
enter its entity reference:</para>
|
|
<programlisting>&<symbol role="Variable">entity-name</symbol>;</programlisting>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.WrTop.div.75">
|
|
<title>Examples</title>
|
|
<para>To entity for the copyright symbol (©) is included in the ISO numeric
|
|
set, so you must first include the ISO numeric entities (at the top of your
|
|
help volume with your other entity declarations) as shown here:</para>
|
|
<programlisting><!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN">
|
|
%ISOnumeric;</programlisting>
|
|
<para>Then you can place the following entity reference where the copyright
|
|
symbol is to appear:</para>
|
|
<programlisting>&copy;</programlisting>
|
|
<para>To display the uppercase Greek letter sigma (∑), you must first
|
|
include the ISO Greek entities (at the top of your help volume with your other
|
|
entity declarations) as shown here:</para>
|
|
<programlisting><!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN">
|
|
%ISOgreek;</programlisting>
|
|
<para>Then you can place the following entity reference where the sigma character
|
|
is to appear:</para>
|
|
<programlisting>&Sigma;</programlisting>
|
|
<para>As with any entity, case is not significant in the entity names for
|
|
special characters.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.77">
|
|
<title id="HRDC.WrTop.mkr.29">Including Writer's Comments</title>
|
|
<para>Frequently it is useful to include within your source files comments
|
|
that are not intended to be part of the help text. Text marked with the Comment
|
|
element is always ignored by the DocBook software. Comments can be used to
|
|
make notes to yourself or to another author, or to exclude some markup without
|
|
taking it out of the file.</para>
|
|
<para>A Comment may appear almost anywhere in the document, and may contain
|
|
paragraphs and other block-oriented elements, but a Comment cannot be nested
|
|
within another Comment.</para>
|
|
<sect2 id="HRDC.Ref.div.3">
|
|
<title>Syntax</title>
|
|
<programlisting><comment>
|
|
<symbol role="Variable">comment text here</symbol>
|
|
</comment></programlisting>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.78" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.30">To Insert a Comment</title>
|
|
<para>Use the comment begin marker <Comment> and end marker </Comment>
|
|
as shown:</para>
|
|
<programlisting><comment>
|
|
<symbol role="Variable">comment text here</symbol>
|
|
</comment></programlisting>
|
|
<sect3 id="HRDC.WrTop.div.79">
|
|
<title>Example</title>
|
|
<para>Here's an example that has two comments, a line before the paragraph,
|
|
and a single word within the paragraph.</para>
|
|
<programlisting><Comment>Here is my rough draft of the introduction: </Comment>
|
|
|
|
Welcome to my application. This software
|
|
is <Comment>perhaps</Comment>the fastest and most
|
|
efficient software you'll ever own.
|
|
|
|
</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.82">
|
|
<title id="HRDC.WrTop.mkr.32">Creating an Index</title>
|
|
<para>The index for a help volume is similar to the index for a book. As an
|
|
author, it is important to create index entries for your topics that will
|
|
allow users to search for keywords or concepts. Creating a thorough index
|
|
ensures that users will be able to find topics quickly and accurately.</para>
|
|
<para>In the DocBook markup, an IndexTerm is the tag for a word or phrase
|
|
in the help volume text that you want to be included in the index. An IndexEntry
|
|
is the element in the Index that holds the references to the IndexTerm. Thus
|
|
IndexEntries might be constructed by extracting and processing the IndexTerms.
|
|
</para>
|
|
<para>IndexTerms are words or phrases to be indexed. IndexTerms may occur
|
|
almost anywhere in the text flow, but are not part of the text itself. That
|
|
is, the contents of IndexTerm do not appear in the text itself.</para>
|
|
<para>An IndexTerm must contain a Primary, and may contain a See and one or
|
|
more SeeAlsos, as well as a Secondary. Secondary, in turn, may contain a See
|
|
and one or more SeeAlsos, as well as a Tertiary.</para>
|
|
<para>IndexTerm has the Common attributes, and also SpanEnd and Significance
|
|
attributes.</para>
|
|
<para>An empty IndexEntry with the SpanEnd attribute is used to mark the end
|
|
of a span of text that begins earlier at an IndexTerm that does have content.
|
|
The value of the SpanEnd attribute must be the ID of that earlier IndexTerm.
|
|
</para>
|
|
<para>The Significance attribute may have the value Preferred, indicating
|
|
that the IndexTerm is the most pertinent of the series, or the value Normal
|
|
(the default).</para>
|
|
<sect2 id="HRDC.WrTop.div.83" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.33">To Mark an Index Entry</title>
|
|
<para>Within the topic you want to index, use the IndexTerm element as shown:
|
|
</para>
|
|
<programlisting><para>This text deals with two subjects that should be listed in the index: how to rotate your terminal and how to adjust its height.</para>
|
|
<IndexTerm>
|
|
<Primary>rotating your terminal</Primary>
|
|
</IndexTerm>
|
|
<IndexTerm>
|
|
<Primary>terminal
|
|
<Secondary>rotation of</Secondary>
|
|
</Primary>
|
|
</IndexTerm>
|
|
<IndexTerm>
|
|
<Primary>terminal
|
|
<Secondary>adjustment of</Secondary>
|
|
<SeeAlso>troubleshooting</SeeAlso>
|
|
</Primary>
|
|
</IndexTerm></programlisting>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.WrTop.div.85">
|
|
<title id="HRDC.WrTop.mkr.34">Creating a Glossary</title>
|
|
<para>Like a glossary in a book, your help volume can contain a glossary that
|
|
defines important terms. The glossary, which is marked using the Glossary
|
|
element, is the last topic in your help volume. The glossary contains the
|
|
definitions for all the terms that are marked with the <GlossTerm> tag.
|
|
</para>
|
|
<para>Glossary contains the following components in the following order:</para>
|
|
<itemizedlist><listitem><para>Title (optional)</para>
|
|
</listitem><listitem><para>TitleAbbrev (optional)</para>
|
|
</listitem><listitem><para>one or more GlossEntries</para>
|
|
</listitem></itemizedlist>
|
|
<sect2 id="HRDC.WrTop.div.87" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.35">To Mark a Glossary Term</title>
|
|
<para>The GlossTerm tag is used to mark a term in the document text that is
|
|
glossed in the Glossary. Note that the GlossTerm element is also used to contain
|
|
those terms as they occur in GlossEntries in the Glossary.</para>
|
|
<para>Each key word or phrase that you enter with the GlossTerm element automatically
|
|
becomes a link to the term's definition in the Glossary.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.WrTop.div.89" role="Procedure">
|
|
<title id="HRDC.WrTop.mkr.36">To Define a Term in the Glossary</title>
|
|
<para>Terms are defined in the Glossay by using the GlossEntry element. A
|
|
GlossEntry contains, in order, a required GlossTerm, an optional Acronym,
|
|
and an optional Abbrev, followed by any number of GlossSees and GlossDefs,
|
|
in any order.</para>
|
|
<para>GlossDef is the definition of a GlossTerm in a GlossEntry. It may contain,
|
|
in any order, Comments, GlossSeeAlsos, paragraphs, and other block-oriented
|
|
elements.</para>
|
|
<para>GlossDef has the Common attributes and also the Subject attribute. The
|
|
Subject attribute may hold a list of subject areas as keywords, separated
|
|
only by spaces.</para>
|
|
<sect3 id="HRDC.WrTop.div.90">
|
|
<title>Syntax</title>
|
|
<programlisting><Glossary>
|
|
...
|
|
<GlossEntry>
|
|
<GlossTerm>
|
|
<symbol>term</symbol>
|
|
</GlossTerm>
|
|
<GlossDef>
|
|
<symbol>text of definition</symbol>
|
|
</GlossDef>
|
|
</GlossEntry>
|
|
...
|
|
</Glossary></programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|
|
<?Pub *0000043237>
|