debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: move C to en_US.UTF-8.

Browse Source
This commit is contained in:
Liang Chang
2022-01-20 02:27:30 +08:00
parent a1a43180ac
commit 53e4feeb32
2137 changed files with 43 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
cde/doc/en_US.UTF-8/guides/helpGuide/BEntity.sgm Normal file
View File

@@ -0,0 +1,105 @@
<!-- $XConsortium: BEntity.sgm /main/5 1996/06/19 16:03:41 drk $ -->
<!ENTITY HRDC.Intro.fig.1 SYSTEM "./helpGuide/graphics/HelpMenu.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.2 SYSTEM "./helpGuide/graphics/GenHelp.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.3 SYSTEM "./helpGuide/graphics/HyperFmt.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.4 SYSTEM "./helpGuide/graphics/Topics.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.5 SYSTEM "./helpGuide/graphics/IndxSrch.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.6 SYSTEM "./helpGuide/graphics/IndexNum.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.7 SYSTEM "./helpGuide/graphics/PrintDlg.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.8 SYSTEM "./helpGuide/graphics/HelpOrg.tif" NDATA TIFF>
<!ENTITY HRDC.Intro.fig.9 SYSTEM "./helpGuide/graphics/HelpMgr.tif" NDATA TIFF>
<!ENTITY HRDC.OrgH.fig.1 SYSTEM "./helpGuide/graphics/HelpVol.tif" NDATA TIFF>
<!ENTITY HRDC.OrgH.fig.2 SYSTEM "./helpGuide/graphics/FMhelpfs.tif" NDATA TIFF>
<!ENTITY HRDC.OrgH.fig.3 SYSTEM "./helpGuide/graphics/BuildDir.tif" NDATA TIFF>
<!ENTITY HRDC.OrgH.fig.4 SYSTEM "./helpGuide/graphics/ExHTopic.tif" NDATA TIFF>
<!ENTITY HRDC.OrgH.fig.5 SYSTEM "./helpGuide/graphics/GrEntity.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.1 SYSTEM "./helpGuide/graphics/ExBuList.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.2 SYSTEM "./helpGuide/graphics/ExNuList.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.3 SYSTEM "./helpGuide/graphics/ExLalst1.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.4 SYSTEM "./helpGuide/graphics/ExLaLstH.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.5 SYSTEM "./helpGuide/graphics/ExProced.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.6 SYSTEM "./helpGuide/graphics/ExComput.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.7 SYSTEM "./helpGuide/graphics/Icons.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.8 SYSTEM "./helpGuide/graphics/ExTHyper.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.9 SYSTEM "./helpGuide/graphics/ExInliGr.tif" NDATA TIFF>
<!ENTITY HRDC.WrTop.fig.10 SYSTEM "./helpGuide/graphics/ExWrapGr.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.1 SYSTEM "./helpGuide/graphics/Process.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.2 SYSTEM "./helpGuide/graphics/ViewVol.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.3 SYSTEM "./helpGuide/graphics/FMCompil.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.4 SYSTEM "./helpGuide/graphics/HelpMgr.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.5 SYSTEM "./helpGuide/graphics/FPanel.tif" NDATA TIFF>
<!ENTITY HRDC.CrHV.fig.6 SYSTEM "./helpGuide/graphics/PrintDlg.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.1 SYSTEM "./helpGuide/graphics/ExAnnot.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.2 SYSTEM "./helpGuide/graphics/ExCautio.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.3 SYSTEM "./helpGuide/graphics/ExEx.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.4 SYSTEM "./helpGuide/graphics/ExListHd.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.5 SYSTEM "./helpGuide/graphics/ExNoteHd.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.6 SYSTEM "./helpGuide/graphics/ExKeycap.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.7 SYSTEM "./helpGuide/graphics/ExLalstW.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.8 SYSTEM "./helpGuide/graphics/ExLaNowr.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.9 SYSTEM "./helpGuide/graphics/ExInliGr.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.10 SYSTEM "./helpGuide/graphics/ExLists.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.11 SYSTEM "./helpGuide/graphics/ExOthrHd.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.12 SYSTEM "./helpGuide/graphics/ExPHead.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.13 SYSTEM "./helpGuide/graphics/ExProc2.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.14 SYSTEM "./helpGuide/graphics/ExVex.tif" NDATA TIFF>
<!ENTITY HRDC.Ref.fig.15 SYSTEM "./helpGuide/graphics/ExXref.tif" NDATA TIFF>
<!ENTITY HRDC.ChEnt.fig.1 SYSTEM "./helpGuide/graphics/CharEntV.tif" NDATA TIFF>
<!ENTITY HRDC.ChEnt.fig.2 SYSTEM "./helpGuide/graphics/CharEntU.tif" NDATA TIFF>
<!ENTITY HRDC.CrDia.fig.1 SYSTEM "./helpGuide/graphics/GHelpLB.tif" NDATA TIFF>
<!ENTITY HRDC.CrDia.fig.2 SYSTEM "./helpGuide/graphics/QuickHlp.tif" NDATA TIFF>
<!ENTITY HRDC.Inst.fig.1 SYSTEM "./helpGuide/graphics/Approot.tif" NDATA TIFF>
<!ENTITY HRDC.Inst.fig.2 SYSTEM "./helpGuide/graphics/BldInst.tif" NDATA TIFF>
<!ENTITY HRDC.Lang.fig.1 SYSTEM "./helpGuide/graphics/FmtTable.tif" NDATA TIFF>

3
cde/doc/en_US.UTF-8/guides/helpGuide/Title.am Normal file
View File

@@ -0,0 +1,3 @@
# $XConsortium: Title.tmpl /main/2 1996/06/19 16:03:46 drk $
# TOC title, only what's between quotes should be modified.
HELPGUIDE_TITLE = "Help System Author's and Programmer's Guide"

3
cde/doc/en_US.UTF-8/guides/helpGuide/Title.tmpl Normal file
View File

@@ -0,0 +1,3 @@
/* $XConsortium: Title.tmpl /main/2 1996/06/19 16:03:46 drk $ */
/* TOC title, only what's between quotes should be modified. */
title = "Help System Author's and Programmer's Guide"

189
cde/doc/en_US.UTF-8/guides/helpGuide/adbook.sgm Normal file
View File

@@ -0,0 +1,189 @@
<!-- $XConsortium: adbook.sgm /main/10 1996/10/29 17:42:02 drk $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY HRDC.Intro.fig.1 SYSTEM "./helpGuide/graphics/H_HelpMenu.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.2 SYSTEM "./helpGuide/graphics/H_GeneralHelp.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.3 SYSTEM "./helpGuide/graphics/H_HyperFormats.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.4 SYSTEM "./helpGuide/graphics/H_Topics.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.5 SYSTEM "./helpGuide/graphics/H_IndexSearch.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.6 SYSTEM "./helpGuide/graphics/H_IndexNum.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.7 SYSTEM "./helpGuide/graphics/H_PrintDialog.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.8 SYSTEM "./helpGuide/graphics/H_HelpOrg.eps" NDATA eps>
<!ENTITY HRDC.Intro.fig.9 SYSTEM "./helpGuide/graphics/H_HelpManager.eps" NDATA eps>
<!ENTITY HRDC.OrgH.fig.1 SYSTEM "./helpGuide/graphics/H_HelpVolume.eps" NDATA eps>
<!ENTITY HRDC.OrgH.fig.2 SYSTEM "./helpGuide/graphics/H_FMhelpfiles.eps" NDATA eps>
<!ENTITY HRDC.OrgH.fig.3 SYSTEM "./helpGuide/graphics/H_BuildDir.eps" NDATA eps>
<!ENTITY HRDC.OrgH.fig.4 SYSTEM "./helpGuide/graphics/H_ExHomeTopic.eps" NDATA eps>
<!ENTITY HRDC.OrgH.fig.5 SYSTEM "./helpGuide/graphics/H_GraphicEntity.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.1 SYSTEM "./helpGuide/graphics/H_ExBulletList.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.2 SYSTEM "./helpGuide/graphics/H_ExNumList.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.3 SYSTEM "./helpGuide/graphics/H_ExLablist1.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.4 SYSTEM "./helpGuide/graphics/H_ExLabListHd.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.5 SYSTEM "./helpGuide/graphics/H_ExProcedure.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.6 SYSTEM "./helpGuide/graphics/H_ExComputer.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.7 SYSTEM "./helpGuide/graphics/H_Icons.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.8 SYSTEM "./helpGuide/graphics/H_ExTextHyperlink.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.9 SYSTEM "./helpGuide/graphics/H_ExInlineGraphic.eps" NDATA eps>
<!ENTITY HRDC.WrTop.fig.10 SYSTEM "./helpGuide/graphics/H_ExWrapGraphic.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.1 SYSTEM "./helpGuide/graphics/H_Process.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.2 SYSTEM "./helpGuide/graphics/H_ViewVolume.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.3 SYSTEM "./helpGuide/graphics/H_FMCompile.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.4 SYSTEM "./helpGuide/graphics/H_HelpManager.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.5 SYSTEM "./helpGuide/graphics/H_FrontPanel.eps" NDATA eps>
<!ENTITY HRDC.CrHV.fig.6 SYSTEM "./helpGuide/graphics/H_PrintDialog.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.1 SYSTEM "./helpGuide/graphics/H_ExAnnot.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.2 SYSTEM "./helpGuide/graphics/H_ExCaution.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.3 SYSTEM "./helpGuide/graphics/H_ExEx.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.4 SYSTEM "./helpGuide/graphics/H_ExListHd.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.5 SYSTEM "./helpGuide/graphics/H_ExNoteHd.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.6 SYSTEM "./helpGuide/graphics/H_ExKeycap.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.7 SYSTEM "./helpGuide/graphics/H_ExLablistWrap.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.8 SYSTEM "./helpGuide/graphics/H_ExLabNowrap.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.9 SYSTEM "./helpGuide/graphics/H_ExInlineGraphic.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.10 SYSTEM "./helpGuide/graphics/H_ExLists.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.11 SYSTEM "./helpGuide/graphics/H_ExOtherHead.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.12 SYSTEM "./helpGuide/graphics/H_ExPHead.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.13 SYSTEM "./helpGuide/graphics/H_ExProced2.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.14 SYSTEM "./helpGuide/graphics/H_ExVex.eps" NDATA eps>
<!ENTITY HRDC.Ref.fig.15 SYSTEM "./helpGuide/graphics/H_ExXref.eps" NDATA eps>
<!ENTITY HRDC.ChEnt.fig.1 SYSTEM "./helpGuide/graphics/H_CharEntVEllip.eps" NDATA eps>
<!ENTITY HRDC.ChEnt.fig.2 SYSTEM "./helpGuide/graphics/H_CharEntU.eps" NDATA eps>
<!ENTITY HRDC.CrDia.fig.1 SYSTEM "./helpGuide/graphics/H_GenHelpLB.eps" NDATA eps>
<!ENTITY HRDC.CrDia.fig.2 SYSTEM "./helpGuide/graphics/H_QuickHelp.eps" NDATA eps>
<!ENTITY HRDC.Inst.fig.1 SYSTEM "./helpGuide/graphics/H_Approot.eps" NDATA eps>
<!ENTITY HRDC.Inst.fig.2 SYSTEM "./helpGuide/graphics/H_BuildInstall.eps" NDATA eps>
<!ENTITY HRDC.Lang.fig.1 SYSTEM "./helpGuide/graphics/H_FormatTable.eps" NDATA eps>
<!ENTITY Pref SYSTEM "./helpGuide/preface.sgm">
<!ENTITY part1 SYSTEM "./helpGuide/part1.sgm">
<!ENTITY Intro SYSTEM "./helpGuide/ch01.sgm">
<!ENTITY part2 SYSTEM "./helpGuide/part2.sgm">
<!ENTITY OrgH SYSTEM "./helpGuide/ch02.sgm">
<!ENTITY WrTop SYSTEM "./helpGuide/ch03.sgm">
<!ENTITY CrHV SYSTEM "./helpGuide/ch04.sgm">
<!ENTITY ChEnt SYSTEM "./helpGuide/ch05.sgm">
<!ENTITY CmdS SYSTEM "./helpGuide/ch06.sgm">
<!ENTITY Sgml SYSTEM "./helpGuide/ch07.sgm">
<!ENTITY part3 SYSTEM "./helpGuide/part3.sgm">
<!ENTITY CrDia SYSTEM "./helpGuide/ch08.sgm">
<!ENTITY HReq SYSTEM "./helpGuide/ch09.sgm">
<!ENTITY DiaEv SYSTEM "./helpGuide/ch10.sgm">
<!ENTITY H4Hlp SYSTEM "./helpGuide/ch11.sgm">
<!ENTITY Inst SYSTEM "./helpGuide/ch12.sgm">
<!ENTITY part4 SYSTEM "./helpGuide/part4.sgm">
<!ENTITY Lang SYSTEM "./helpGuide/ch13.sgm">
<!ENTITY Gloss SYSTEM "./helpGuide/glossary.sgm">
<!ENTITY existential "[existential]" >
<!ENTITY florin "[florin]" >
<!ENTITY guillemetleft "[guillemetleft]" >
<!ENTITY guillemetright "[guillemetright]" >
<!ENTITY Rfraktur "[Rfraktur]" >
<!ENTITY lfraktur "[lfraktur]" >
]>
<!-- ____________________________________________________________________________ -->
<!-- <DocBook> -->
<Book>
<Title>Common Desktop Environment: Help System Author's and Programmer's Guide</Title>
&Pref;
<Part Id="HRDC.part1.div.1">
&part1;
&Intro;
</Part>
<Part Id="HRDC.part2.div.1">
&part2;
&OrgH;
&WrTop;
&CrHV;
&ChEnt
&CmdS;
&Sgml;
</Part>
<Part Id="HRDC.part3.div.1">
&part3;
&CrDia;
&HReq;
&DiaEv;
&H4Hlp;
&Inst;
</Part>
<Part Id="HRDC.part4.div.1">
&part4;
&Lang;
</Part>
&Gloss;
</Book>
<!-- </DocBook> -->

129
cde/doc/en_US.UTF-8/guides/helpGuide/book.sgm Normal file
View File

@@ -0,0 +1,129 @@
<!-- $XConsortium: book.sgm /main/8 1996/10/29 17:42:36 drk $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook//EN" [
<!ENTITY % ISOpublishing PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN">
%ISOpublishing;
<!ENTITY % ISOnumeric PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN">
%ISOnumeric;
<!ENTITY % ISOAMSAR PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN">
%ISOAMSAR;
<!ENTITY % ISOAMSBO PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN">
%ISOAMSBO;
<!ENTITY % ISOAMSO PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN">
%ISOAMSO;
<!ENTITY % ISOAMSR PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN">
%ISOAMSR;
<!ENTITY % ISOdiacritical PUBLIC "ISO 8879:1986//ENTITIES Diacritical Marks//EN">
%ISOdiacritical;
<!ENTITY % ISOgeneraltech PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN">
%ISOgeneraltech;
<!ENTITY % ISOalatin1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN">
%ISOalatin1;
<!ENTITY % ISOalatin2 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN">
%ISOalatin2;
<!ENTITY % ISOgreek PUBLIC "ISO 8879:1986//ENTITIES Greek Symbols//EN">
%ISOgreek;
<!ENTITY % ISOgreekletters PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN">
%ISOgreekletters;
<!ENTITY % ISOboxandline PUBLIC "ISO 8879:1986//ENTITIES Box and Line Drawing//EN">
%ISOboxandline;
<!ENTITY % BEntities SYSTEM "./helpGuide/BEntity.sgm">
%BEntities;
<!ENTITY Pref SYSTEM "./helpGuide/preface.sgm">
<!ENTITY part1 SYSTEM "./helpGuide/part1.sgm">
<!ENTITY Intro SYSTEM "./helpGuide/ch01.sgm">
<!ENTITY part2 SYSTEM "./helpGuide/part2.sgm">
<!ENTITY OrgH SYSTEM "./helpGuide/ch02.sgm">
<!ENTITY WrTop SYSTEM "./helpGuide/ch03.sgm">
<!ENTITY CrHV SYSTEM "./helpGuide/ch04.sgm">
<!ENTITY ChEnt SYSTEM "./helpGuide/ch05.sgm">
<!ENTITY CmdS SYSTEM "./helpGuide/ch06.sgm">
<!ENTITY Sgml SYSTEM "./helpGuide/ch07.sgm">
<!ENTITY part3 SYSTEM "./helpGuide/part3.sgm">
<!ENTITY CrDia SYSTEM "./helpGuide/ch08.sgm">
<!ENTITY HReq SYSTEM "./helpGuide/ch09.sgm">
<!ENTITY DiaEv SYSTEM "./helpGuide/ch10.sgm">
<!ENTITY H4Hlp SYSTEM "./helpGuide/ch11.sgm">
<!ENTITY Inst SYSTEM "./helpGuide/ch12.sgm">
<!ENTITY part4 SYSTEM "./helpGuide/part4.sgm">
<!ENTITY Lang SYSTEM "./helpGuide/ch13.sgm">
<!ENTITY Gloss SYSTEM "./helpGuide/glossary.sgm">
<!ENTITY existential "[existential]" >
<!ENTITY florin "[florin]" >
<!ENTITY guillemetleft "[guillemetleft]" >
<!ENTITY guillemetright "[guillemetright]" >
<!ENTITY Rfraktur "[Rfraktur]" >
<!ENTITY lfraktur "[lfraktur]" >
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment: Help System Author's and Programmer's Guide</Title>
&Pref;
<Part Id="HRDC.part1.div.1">
&part1;
&Intro;
</Part>
<Part Id="HRDC.part2.div.1">
&part2;
&OrgH;
&WrTop;
&CrHV;
&ChEnt;
&CmdS;
&Sgml;
</Part>
<Part Id="HRDC.part3.div.1">
&part3;
&CrDia;
&HReq;
&DiaEv;
&H4Hlp;
&Inst;
</Part>
<Part Id="HRDC.part4.div.1">
&part4;
&Lang;
</Part>
&Gloss;
</Book>

712
cde/doc/en_US.UTF-8/guides/helpGuide/ch01.sgm Normal file
View File

@@ -0,0 +1,712 @@
<!-- $XConsortium: ch01.sgm /main/12 1996/10/22 12:20:04 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.Intro.div.1">
<title id="HRDC.Intro.mkr.1">Introducing the Help System</title>
<para>This chapter introduces the Help System and briefly describes the user
interface. It shows how help information is organized, outlines how to create
and process help modules, and discusses the collaborative role of authors
and developers in the design and creation of application help.</para>
<informaltable id="HRDC.Intro.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Developer's Toolkit2'--><xref role="JumpText"
linkend="HRDC.Intro.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Overview of Online Help2'--><xref
role="JumpText" linkend="HRDC.Intro.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help Information Model3'--><xref
role="JumpText" linkend="HRDC.Intro.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help User Interface5'--><xref role="JumpText"
linkend="HRDC.Intro.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help Topic Organization11'--><xref
role="JumpText" linkend="HRDC.Intro.mkr.14"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'The Author's Job14'--><xref role="JumpText"
linkend="HRDC.Intro.mkr.18"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Programmer's Job19'--><xref role="JumpText"
linkend="HRDC.Intro.mkr.27"></para></entry></row></tbody></tgroup></informaltable>
<para><indexterm><primary>introduction to Help System</primary></indexterm><indexterm>
<primary>CDE Help System, introduction to</primary></indexterm></para>
<sect1 id="HRDC.Intro.div.2">
<title id="HRDC.Intro.mkr.2">Introduction to the Help System</title>
<para>The Help System provides a complete set of tools to develop online help
for application software. It enables authors to write online help that includes
graphics and text formatting, hyperlinks, and communication with the application.
</para>
<para>The Help System also provides a programmer's toolkit for integrating
online help into an application. The Help System application program interface
supplies two specialized help dialogs and supporting routines that are used
to display, navigate, search, and print online help modules.</para>
<sect2 id="HRDC.Intro.div.3">
<title id="HRDC.Intro.mkr.3">Developer's Toolkit</title>
<para>The Help System Developer's Toolkit contains tools to write, process,
and view online help and contains an application programming library.</para>
<sect3 id="HRDC.Intro.div.4">
<title>For Authors</title>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>DocBook markup language</emphasis> &mdash;a set of tags used in text files to mark organization and
content of your online help.</para>
</listitem><listitem><para><emphasis>DocBook software</emphasis>&mdash;a set
of software tools for converting the DocBook files you write into run-time
help files.</para>
</listitem><listitem><para><emphasis>Helpview application</emphasis>&mdash;a
viewer program for displaying your online help so you can read and interact
with it just as your audience will.</para>
</listitem></itemizedlist>
<para>Refer to <!--Original XRef content: 'Chapter&numsp;2, &ldquo;Organizing
and Writing a Help Volume'--><xref role="ChapNumAndTitle" linkend="HRDC.OrgH.mkr.1">,
to learn more about creating and processing online help.</para>
<sect4 id="HRDC.Intro.div.5">
<title>For Application Developers</title>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>DtHelp programming
library</emphasis>&mdash;an application program interface (API) for integrating
help windows into your application.</para>
</listitem><listitem><para><emphasis>A sample program</emphasis>&mdash;a simple
example that shows how to integrate the Help System into a Motif application
(see <!--Original XRef content: 'page&numsp;19'--><xref role="PageNum" linkend="HRDC.Intro.mkr.28">).
</para>
</listitem></itemizedlist>
<para>Chapters 9 through 13 discuss the application programming library.</para>
</sect4>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.6">
<title id="HRDC.Intro.mkr.4">Overview of Online Help</title>
<para>It's virtually impossible&mdash;and certainly impractical&mdash;for
anyone to learn and remember <emphasis>everything</emphasis> there is to
know about the computer hardware and software they use to do their job. Nearly
every computer user needs help at one time or another.</para>
<para>Online help, unlike a printed manual, has the power of the computer
at its disposal. Most importantly, this power makes it possible to adapt
the information to the user's current context. <emphasis>Context-sensitive</emphasis> help provides just enough help to get the user back on task. In
developing your online help, remember that users need different types of help
at different times. By anticipating users' questions, you can design your
application help to respond in a logical and intuitive manner.</para>
</sect1>
<sect1 id="HRDC.Intro.div.7">
<title id="HRDC.Intro.mkr.5">Help Information Model<indexterm><primary>information model, help</primary></indexterm><indexterm><primary>model, help
information</primary></indexterm></title>
<para>There are two general styles of online help:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Application help</emphasis>,
whose primary role is to be an integrated part of a Motif application.<indexterm>
<primary>Motif</primary></indexterm><indexterm><primary>Motif</primary>
</indexterm></para>
</listitem><listitem><para><emphasis>Standalone help</emphasis>, whose primary
role is to provide online access to task, reference, or tutorial information,
independent of any application software.<indexterm><primary>standalone help</primary></indexterm></para>
</listitem></itemizedlist>
<para>If you are developing online help for an application, you may choose
to organize the information exclusively for access within the application.
Or, you may design the information such that it can be browsed without the
application present, as in standalone help.</para>
<sect2 id="HRDC.Intro.div.8">
<title>Part of the Application</title>
<para>Help promotes a high degree of integration between the application and
its online help. From the user's perspective, the help is part of the application.
This approach minimizes the perceived &ldquo;distance&rdquo; away from the
application that the user must travel to get help.</para>
<para>Staying close to the application makes users more comfortable with online
help and gets them back on task as quickly as possible.</para>
</sect2>
<sect2 id="HRDC.Intro.div.9">
<title id="HRDC.Intro.mkr.6">Types of Help<indexterm><primary>getting help</primary></indexterm><indexterm><primary>help, how users get</primary></indexterm></title>
<para>Online help can be divided into three general categories:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Automatic help</emphasis>&mdash;The
application determines when help is needed and what to present. This is sometimes
called system-initiated help.</para>
</listitem><listitem><para><emphasis>Semiautomatic help</emphasis>&mdash;The
user decides when help is needed, but the system determines what to present.
Semiautomatic help is initiated by a user's gesture or request for help,
such as pressing F1. The system's response is called context-sensitive help
because it considers the user's current context in deciding what information
to display.</para>
</listitem><listitem><para><emphasis>Manual help</emphasis>&mdash;The user
requests specific information, such as from a Help menu.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.Intro.div.10">
<title>How Users Get Help</title>
<para>A user can request help in several ways. Most applications provide a
Help menu and Help key as well as Help buttons in dialog boxes.</para>
<sect3 id="HRDC.Intro.div.11">
<title>Help Key</title>
<para>Within most applications, the primary way for a user to request help
is by pressing the <emphasis>help key</emphasis>. In recent years, the F1
function key has become a defacto standard help key for many workstation
and personal computer products.</para>
<para>The Style Guide and Certification Checklist recommends the use of F1
as the help key, and the Motif programmer's toolkit even provides some
built-in behavior to make it easier to implement the help key in Motif
applications.</para>
<para>Some computers provide a Help key on the keyboard.</para>
</sect3>
<sect3 id="HRDC.Intro.div.12">
<title>Help Menu</title>
<para>The Help menu is a common way to provide access to help information.
Motif applications provide a Help menu, which is right-justified in the
menu bar. The <citetitle>Style Guide and Certification Checklist</citetitle>
makes recommendations regarding the commands contained in a Help menu.</para>
<figure>
<title>Application Help menu</title>
<graphic id="HRDC.Intro.grph.1" entityref="HRDC.Intro.fig.1"></graphic>
</figure>
</sect3>
<sect3 id="HRDC.Intro.div.13">
<title>Help Buttons</title>
<para>Many dialog boxes also provide a Help button to get help on the dialog.
The <citetitle>Style Guide and Certification Checklist</citetitle> recommends
that choosing the Help button in a dialog box be equivalent to pressing the
Help key while using that dialog. Exceptions should be made for complex dialogs,
where help on individual controls within the dialog box is appropriate.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.14">
<title id="HRDC.Intro.mkr.7">Help User Interface<indexterm><primary>overview</primary><secondary>Help graphical user interface</secondary></indexterm></title>
<para>This section is an overview of the graphical interface provided by the
Help System. For a detailed description of Help features and capabilities,
refer to the <citetitle>User's Guide</citetitle>; or, to view the corresponding
online help, you can open the desktop Front Panel Help Viewer (see <!--Original
XRef content:
'&ldquo;To Display the Help Index Volume&rdquo--><!--r; on
page&numsp;97'--><xref role="SecTitleAndPageNum" linkend="hrdc.crhv.mkr.12">).
Then choose, Common Desktop Environment and Desktop Help System.</para>
<para>While using an application, a user can request help by pressing the
Help key or by selecting the application's Help menu. In addition, applications
integrating the Help System can be installed so that their respective help
modules are accessible from the desktop Help Viewer. This enables a user
to browse help information supplied by different applications without having
to run each application.</para>
<sect2 id="HRDC.Intro.div.15">
<title>Help Windows</title>
<para>When a user requests help, the Help System displays a help window. There
are two types of help windows: general help and quick help. A general help
window has a menu bar, topic tree, and a topic display area. The topic tree
lists help topics that a user can choose. The lower portion of the window&mdash;the
topic display area&mdash;displays the selected topic.</para>
<para>A quick help window is a streamlined help window. It has only a topic
display area and one or more dialog buttons. Quick help windows are often
used for short, self-contained information such as a definition.</para>
<figure>
<title>General help and quick help window</title>
<graphic id="HRDC.Intro.grph.2" entityref="HRDC.Intro.fig.2"></graphic>
</figure>
</sect2>
<sect2 id="HRDC.Intro.div.16">
<title>Hyperlinks</title>
<para>Help topics often contain hyperlinks that &ldquo;jump&rdquo; to related
help information. Both text and graphics can be used as hyperlinks. <!--Original
XRef content: 'Figure&numsp;1&hyphen;3 on page&numsp;7'--><xref role="CodeOrFigOrTabAndPNum"
linkend="HRDC.Intro.mkr.8"> shows formatting styles used to identify hyperlinks.
</para>
<para><indexterm><primary>hyperlink</primary><secondary>display formats</secondary>
</indexterm>Solid or dashed underscores identify words or phrases that are
hyperlinks. The solid underscore, or standard hyperlink, is most common.
When the hyperlink is selected, the related topic is displayed. An author
designates whether the hyperlink topic is displayed in the current help window
or a new window. The dashed underscore represents a definition link. When
selected, the related topic is displayed in a quick help window. A gray, open-corner
box (dashed or solid line) designates a graphic hyperlink.</para>
<figure>
<title id="HRDC.Intro.mkr.8">Formats for graphic and text hyperlinks</title>
<graphic id="HRDC.Intro.grph.3" entityref="HRDC.Intro.fig.3"></graphic>
</figure>
</sect2>
<sect2 id="HRDC.Intro.div.17">
<title>Help Navigation<indexterm><primary>topic tree</primary><secondary>selecting topic</secondary></indexterm></title>
<para>The topic tree<indexterm><primary>topic tree</primary><secondary>in
general help dialog</secondary></indexterm> shown in <!--Original XRef content:
'Figure&numsp;1&hyphen;4'--><xref role="CodeOrFigureOrTable" linkend="HRDC.Intro.mkr.9">
is an outline of topics in the current help volume. The first topic at the
top of the list is the <emphasis>home topic,</emphasis> or beginning of the
help volume. An arrow (&filig;) points to the current topic and shows the
user's location in the help volume.</para>
<figure>
<title id="HRDC.Intro.mkr.9">Topic tree in a general help dialog box</title>
<graphic id="HRDC.Intro.grph.4" entityref="HRDC.Intro.fig.4"></graphic>
</figure>
<para>To display a help topic, a user selects a title in the topic tree or
a hyperlink within the topic display area. The user can browse the outline
of topics by scrolling the list and then select any topic. Navigation commands
enable the user to return to previous topics or to the beginning of the help
volume.</para>
<sect3 id="HRDC.Intro.div.18">
<title>Help Navigation Buttons<indexterm><primary>navigation, help buttons</primary></indexterm></title>
<para><indexterm><primary>buttons, navigation</primary></indexterm>The general
help dialog includes three dialog buttons: Backtrack, History, and Index.
These features are also available as menu selections.</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Backtrack</emphasis>
&mdash; returns to the previous topic. To retrace topics visited, press Backtrack
repeatedly until the desired topic is displayed.</para>
</listitem><listitem><para><emphasis>History</emphasis> &mdash; displays the <emphasis>History</emphasis> dialog box. This dialog box lists the help volumes and
topics that have been visited. To return to any topic in the list, select
its title.</para>
</listitem><listitem><para><emphasis>Index</emphasis> &mdash; displays the <emphasis>Index Search</emphasis> dialog box. This dialog lists
all the words and phrases that the author has marked as index entries. Selecting
an index entry, then one of the topics where the entry occurs, displays that
topic in the general help dialog. <!--Original XRef content: ''--><xref role="CodeOrFigureOrTable"
linkend="HRDC.Intro.mkr.10"></para>
</listitem></itemizedlist>
<para>When using the Help Viewer from the desktop Front Panel, the general
help dialog includes an additional dialog button called Top Level. After
exploring different help volumes, a user can select this button to return
to the top-level of the desktop index help volume.</para>
</sect3>
</sect2>
<sect2 id="HRDC.Intro.div.19">
<title>Help Menus</title>
<para><indexterm><primary>home topic</primary><secondary>menu command</secondary>
</indexterm>A general help dialog menu bar has five menus: File, Edit, Search,
Navigate, and Help. The Search and Navigate menus contain commands for the
index and navigation buttons described previously. In addition, the Navigate
menu has a Home Topic command that returns to the beginning of the help volume.
The remaining menus provide these features:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>File menu</emphasis> &mdash;
duplicates a help window, prints a help topic or the current help volume,
or closes the help window.</para>
<indexterm><primary>menu</primary><secondary>File</secondary></indexterm>
<indexterm><primary>menu</primary><secondary>Edit</secondary></indexterm>
<indexterm><primary>menu</primary><secondary>Help</secondary></indexterm>
<indexterm><primary>menu</primary><secondary>Navigate</secondary></indexterm>
</listitem><listitem><para><emphasis>Edit menu</emphasis> &mdash; copies text
from the help window to another application.</para>
</listitem><listitem><para><emphasis>Help menu &mdash;</emphasis> provides
help information that describes features of the help dialogs and how to use
them.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.Intro.div.20">
<title id="HRDC.Intro.mkr.10">Help Index</title>
<para><indexterm><primary>index</primary><secondary>Index search dialog index</secondary></indexterm>A help volume has an index of important words and
phrases that the user can search to find help topics on a subject. A user
can browse or search the index of the current volume, selected volumes, or
all help volumes available on the system. Regular expressions such as * (asterisk)
and ? (question mark) can be used to search for topics. To view the corresponding
help topic, the user selects the index entry.</para>
<figure>
<title id="HRDC.Intro.mkr.11">Index search dialog box</title>
<graphic id="HRDC.Intro.grph.5" entityref="HRDC.Intro.fig.5"></graphic>
</figure>
<para>Because the help index can be large even for a single volume, index
entries can be expanded or contracted. A prefix notation, either a + (plus)
or - (minus) sign, is used to show whether an index entry is expanded or
contracted. A minus sign indicates that all of the entries are displayed,
whereas a plus sign indicates that the entry can be expanded to show additional
index entries.</para>
<para>In <!--Original XRef content: 'Figure&numsp;1&hyphen;6 on page&numsp;10'--><xref
role="CodeOrFigOrTabAndPNum" linkend="HRDC.Intro.mkr.12">, the -36 prefix
means there are 36 index entries displayed. The +3 notation identifies contracted
entries. Selecting a contracted entry causes the list to expand, and the
+ sign changes to a - sign. The last index entry shown in the figure has
been expanded in this manner.</para>
<figure>
<title id="HRDC.Intro.mkr.12">Index entry prefix notation</title>
<graphic id="HRDC.Intro.grph.6" entityref="HRDC.Intro.fig.6"></graphic>
</figure>
</sect2>
<sect2 id="HRDC.Intro.div.21">
<title>Printing from Help<indexterm><primary>printing</primary><secondary>help information</secondary></indexterm></title>
<figure>
<title id="HRDC.Intro.mkr.13">Print dialog box</title>
<graphic id="HRDC.Intro.grph.7" entityref="HRDC.Intro.fig.7"></graphic>
</figure>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.22">
<title id="HRDC.Intro.mkr.14">Help Topic Organization<indexterm><primary>help</primary><secondary>topic organization</secondary></indexterm></title>
<para>An author organizes help information into a logical framework. Most
times, but not always, this results in an outline, or a hierarchy of topics.
The topic hierarchy in <!--Original XRef content: 'Figure&numsp;1&hyphen;8'--><xref
role="CodeOrFigureOrTable" linkend="HRDC.Intro.mkr.15"> consists of a main
level, three sections, and subordinate topics. Although Help has been optimized
for information that is organized in a hierarchy, you are free to create
any kind of organization you want.</para>
<figure>
<title id="HRDC.Intro.mkr.15">Hierarchy of topics</title>
<graphic id="HRDC.Intro.grph.8" entityref="HRDC.Intro.fig.8"></graphic>
</figure>
<sect2 id="HRDC.Intro.div.23">
<title>Help Topic<indexterm><primary>topic</primary><secondary>defined</secondary>
</indexterm><indexterm><primary>help topic</primary><secondary>defined</secondary></indexterm></title>
<para id="HRDC.Intro.mkr.16">A <emphasis>help topic</emphasis> is a unit of
information identified with a unique ID. A set of tags provided by the Help
System is used to mark help topics and create a structural framework. The
Help Viewer, which is part of the Help System, is able to directly access
and display a help topic.</para>
</sect2>
<sect2 id="HRDC.Intro.div.24">
<title><indexterm><primary>help volume</primary><secondary>defined</secondary>
</indexterm><indexterm><primary>volume</primary><secondary>defined</secondary>
</indexterm>Help Volume<indexterm><primary>volume</primary><secondary>as
collection of topics</secondary></indexterm><indexterm><primary>topic</primary>
<secondary>volume as collection of</secondary></indexterm></title>
<para>A <emphasis>help volume</emphasis> is a collection of topics that describe
an application or a particular subject. If you are developing application
help, typically there's one help volume per application. However, for complex
applications, or a collection of related applications, you might develop
several help volumes.</para>
</sect2>
<sect2 id="HRDC.Intro.div.25">
<title><indexterm><primary>help family</primary><secondary>defined</secondary>
</indexterm>Help Family<indexterm><primary>family</primary><secondary>definition
of</secondary></indexterm><indexterm><primary>group of related volumes, family
as</primary></indexterm><indexterm><primary>related volumes, family as group
of</primary></indexterm><indexterm><primary>volume</primary><secondary>family
of volumes</secondary></indexterm></title>
<para>Often, software is available as a set of related applications known
as a <emphasis>product family</emphasis>. For example, a set of office productivity
applications may include a word processor, a spreadsheet application, and
a drawing program. Because each application may have its own help volume,
it may be desirable to group the related help volumes in a <emphasis>help
family.</emphasis> A help family can include a single help volume or several
volumes.</para>
<para>Assembling your help volumes into a help family is optional. It is required
only if you want your help available for browsing within a <emphasis>help
browser</emphasis> such as the Help Viewer in the Front Panel.</para>
<para>Refer to <!--Original XRef content: '&ldquo;To Create a Help Family&rdquo;
on page&numsp;95'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.11">
for a description of help family files and how they are used.</para>
</sect2>
<sect2 id="HRDC.Intro.div.26">
<title>Help Index Volume<indexterm><primary>volume</primary><secondary>desktop
index volume</secondary></indexterm><indexterm><primary>help index</primary>
</indexterm><indexterm><primary>help index volume</primary><secondary>defined</secondary></indexterm></title>
<para>The desktop provides a special help volume called the <emphasis>index</emphasis> volume that lists help installed on your system. Clicking the
Help Viewer control in the Front Panel displays the index volume shown in
<!--Original XRef content: 'Figure&numsp;1&hyphen;9'--><xref role="CodeOrFigureOrTable"
linkend="HRDC.Intro.mkr.17"> on <!--Original XRef content: 'page&numsp;13'--><xref
role="PageNum" linkend="HRDC.Intro.mkr.17">.</para>
<para>It lists help families (underlined titles) and any volumes that are
members of the help family.</para>
<figure>
<title id="HRDC.Intro.mkr.17">Index help volume</title>
<graphic id="HRDC.Intro.grph.9" entityref="HRDC.Intro.fig.9"></graphic>
</figure>
<para>The index volume allows access to application-specific help without
using the application. Or, if you are writing standalone help, this is the
only way for users to get to your help. Even if you have only a single help
volume, it must belong to a help family to be browsable using the Help Viewer.
</para>
<para><!--Original XRef content: '&ldquo;Adding Your Help to the Browser
Volume&rdquo; on page&numsp;94'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.8">
describes how to create a family file and what you need to do to make your
help volume accessible from the index volume.</para>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.27">
<title id="HRDC.Intro.mkr.18">The Author's Job<indexterm><primary>author</primary><secondary>responsibilities</secondary></indexterm><indexterm>
<primary>job of author</primary></indexterm><indexterm><primary>responsibility</primary><secondary>author</secondary></indexterm></title>
<para>Writing online help differs from writing printed manuals, so it is important
to understand who you are writing for, how the information is accessed, and
how the information fits into an application.</para>
<sect2 id="HRDC.Intro.div.28">
<title>Objectives for Online Help<indexterm><primary>goals for online help</primary></indexterm><indexterm><primary>online help</primary><secondary>objectives</secondary></indexterm></title>
<para>The two most important objectives for designing quality online help
are:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Get the user back
on task as quickly and successfully as possible.</emphasis></para>
</listitem><listitem><para><emphasis>Educate the user to prevent future need
for assistance</emphasis>.</para>
</listitem></itemizedlist>
<para>Applying these objectives will help you make decisions regarding what
type of help is best and what amount of detail is needed.</para>
</sect2>
<sect2 id="HRDC.Intro.div.29">
<title id="HRDC.Intro.mkr.19">Know Your Audience<indexterm><primary>audience</primary><secondary>knowing</secondary></indexterm></title>
<para>Just as with any writing, to do a good job, you must know your audience
and understand what they require from the information you are writing. Most
importantly, with online help, you need to know the tasks they are attempting
and the problems they may encounter.</para>
</sect2>
<sect2 id="HRDC.Intro.div.30">
<title id="HRDC.Intro.mkr.20">Consider How Your Help Is Accessed<indexterm>
<primary>help</primary><secondary>types of access</secondary></indexterm><indexterm>
<primary>application help</primary></indexterm></title>
<para>It is just as important to understand how users will access your help
as it is to identify your audience correctly.</para>
<sect3 id="HRDC.Intro.div.31">
<title>Application Help</title>
<para>If you are writing help for an application, you need to decide which
topics are browsable and which topics are available from the application
as <emphasis>context-sensitive help</emphasis>. A topic is browsable if you
can navigate to it using the topic tree or hyperlinks. Topics designed exclusively
for context-sensitive help might not be browsable because the only way to
display the topic may be from within a particular context in the application.
</para>
<para>You must also decide if you want your application's help volume to be <emphasis>registered</emphasis>. Registered help volumes can be displayed by other applications
(such as the Help Viewer), making the information more widely accessible.
If another help volume contains hyperlinks to topics in your help volume,
your help volume must be registered.</para>
<para>See <!--Original XRef content: '&ldquo;Registering Your Application
and Its Help&rdquo; on page&numsp;247'--><xref role="SecTitleAndPageNum"
linkend="HRDC.Inst.mkr.9"> for information about installing and registering
your application.</para>
</sect3>
<sect3 id="HRDC.Intro.div.32">
<title>Standalone Help Volumes<indexterm><primary>standalone help</primary>
</indexterm><indexterm><primary>volume</primary><secondary>standalone help</secondary></indexterm></title>
<para>If you are writing a standalone help volume (a help volume not associated
with an application), you may choose to do things differently.</para>
<para>First, you must provide a path for users to get to all the topics you've
written. That is, every topic must be browsable through at least one hyperlink.
Also, because there's no application associated with your help, you must
rely on a help viewer (such as Help Viewer) to display your help volume.</para>
</sect3>
</sect2>
<sect2 id="HRDC.Intro.div.33">
<title>Evaluate How to Present Help</title>
<para>An application can incorporate different types of help. It is important
to evaluate what kind of help is best suited for your application. For example,
the same help information may be presented in a variety of ways. Some choices
include key features, a tutorial, examples, task instructions, shortcuts,
troubleshooting, reference information, glossary of terms, or referral to
hard copy or other online documentation. A help volume often combines different
presentations.</para>
</sect2>
<sect2 id="HRDC.Intro.div.34">
<title id="HRDC.Intro.mkr.21">Collaborate with the Application Programmer<indexterm>
<primary>author</primary><secondary>collaboration with application programmer</secondary></indexterm><indexterm><primary>application programmer, collaborating
with</primary></indexterm><indexterm><primary>programmer, application</primary>
<secondary>collaborating with</secondary></indexterm></title>
<para>If you are writing application help, you should work closely with the
application programmer. The degree to which the Help System is integrated
into an application is a design decision that you make collectively.</para>
<para>If an application and its help have very loose ties, there may be only
a handful of topics that the application is able to display directly. This
is easier to implement.</para>
<para>In contrast, the application could provide specific help for nearly
every situation in the application. This requires more work, but benefits
the user if done well.</para>
<para>It's up to you and your project team to determine the right level of
help integration for your project.</para>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.35">
<title id="HRDC.Intro.mkr.22">Author's Workflow<indexterm><primary>author</primary><secondary>workflow</secondary></indexterm></title>
<para>After designing your help, you create and process help topics to produce
a help volume. Your focus as an author is on these key tasks:</para>
<itemizedlist remap="Bullet1"><listitem><para>Write help topics</para>
</listitem><listitem><para>Create run-time help files</para>
</listitem><listitem><para>View the help volume</para>
</listitem></itemizedlist>
<sect2 id="HRDC.Intro.div.36">
<title id="HRDC.Intro.mkr.23">Write Help Topics with DocBook</title>
<para>Online help is written in ordinary text files. You use special codes,
or <symbol role="Variable">tags</symbol>, to markup <symbol role="Variable">elements</symbol> within the information. The tags form a markup language
called DocBook.</para>
<para>The DocBook markup language defines a hierarchy of <symbol role="Variable">elements</symbol> that define high-level elements, such as chapters, sections,
and subsections, and low-level elements such as paragraphs, lists, and emphasized
words.</para>
<para><!--Original XRef content: '&ldquo;General Markup Guidelines&rdquo;
on page&numsp;28'--><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.4">
gives a brief description of using markup.</para>
<sect3 id="HRDC.Intro.div.38">
<title id="HRDC.Intro.mkr.24">Formal Markup<indexterm><primary>formal markup</primary><secondary>defined</secondary></indexterm><indexterm><primary>markup</primary><secondary>formal (SGML)</secondary></indexterm><indexterm>
<primary>structured editor</primary></indexterm><indexterm><primary>editor,
structured</primary></indexterm></title>
<para><emphasis><indexterm><primary>markup language</primary><secondary>formal
markup, SGML-compliant</secondary></indexterm>Formal markup</emphasis> is
a Standard Generalized Markup Language (SGML) that an author can use to create
fully compliant SGML help topics. It requires start and end tags for <emphasis>all</emphasis> elements. Additionally, the structure of each element must
be explicitly tagged. Therefore, the number of tags increases significantly
using formal markup. Although an author can enter formal markup using a standard
editor, a structured editor is recommended.</para>
<sect4 id="HRDC.Intro.div.39">
<title>Structured Editors</title>
<para>New tools, called structured editors, are becoming available in response
to the need to create SGML markup efficiently. Typically, a structured editor
provides a context-sensitive menu. That is, the elements that appear in the
menu dynamically change based on the location of the cursor in the document.
</para>
<para>For example, if you are entering a list, then the menu contains only
elements that are valid within the context of a list element. This built-in
&ldquo;intelligence&rdquo; allows an author to create markup easily.</para>
<para>When an author chooses an element, such as section, title, or list,
the editor generates the corresponding start, end, and any intermediate structural
tags. For example, when an author selects a chapter element, the editor automatically
inserts the intermediate tags required by this element. The author simply
types the chapter title. Viewing the generated tags is optional; authors can
suppress the tags.</para>
</sect4>
<sect4 id="HRDC.Intro.div.40">
<title>Using Formal Markup</title>
<para>Before you use formal markup, first read the chapters in <citetitle>P<?Pub Caret1>art 2 - The Author's Job</citetitle> to become familiar with
the set of DocBook elements.</para>
<para><!--Original XRef content: ''--><xref role="Blank" linkend="HRDC.Sgml.mkr.1"> <!--Original
XRef content: 'Chapter&numsp;8, &ldquo;Reading the DocBook Document Type
Definition'--><xref role="ChapNumAndTitle" linkend="HRDC.Sgml.mkr.1"> explains
key components of the Document Type Definition (DTD) and shows you how to
create formal markup. The complete DocBook Document Type Definition appears
in the <citetitle>Guide to the DocBook DTD</citetitle>.</para>
<note>
<para>The Developer's Kit includes the DocBook Document Type Definition. The
file is located in the <filename>/usr/dt/dthelp/dtdocbook/SGML/docbook.dtd</filename> directory and is named <filename>DocBook.dtd</filename>.</para>
</note>
</sect4>
</sect3>
<sect3 id="HRDC.Intro.div.41">
<title>See Also</title>
<itemizedlist><listitem><para>The <citetitle>Guide to the DocBook DTD</citetitle>
gives a detailed description of each major tag listed in alphabetical order.
</para>
</listitem><listitem><para><!--Original XRef content: 'Chapter&numsp;8, &ldquo;Reading
the DocBook Document Type Definition'--><xref role="ChapNumAndTitle" linkend="HRDC.Sgml.mkr.1">
describes formal markup.</para>
</listitem><listitem><para><filename moreinfo="RefEntry">docbook.dtd(4)</filename> man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.Intro.div.42">
<title>Think Structure, Not Format</title>
<para>If you are familiar with other publishing systems, you may be accustomed
to formatting information as you like to see it. Authoring with DocBook requires
you to think about structure and content, not format.</para>
<para>As you write, you use tags to mark certain types of information. When
you do so, you are identifying <emphasis>what</emphasis> the information is,
but not how it should be formatted.</para>
<para>For instance, to refer to a book title, include markup like this:</para>
<programlisting>&lt;CiteTitle>System Administrator's Reference Guide&lt;/CiteTitle>
</programlisting>
<para>This abstraction separates structure and content from format, which
allows the same information to be used by other systems and perhaps formatted
differently. For instance, Help displays book titles using an italic font.
However, on another system an italic font may not be available, so the formatter
could decide that book titles are underlined.</para>
</sect2>
<sect2 id="HRDC.Intro.div.43">
<title id="HRDC.Intro.mkr.25">Create Run-Time Help Files<indexterm><primary>creating</primary><secondary>run-time help files</secondary></indexterm><indexterm>
<primary>run-time files</primary><secondary>creating</secondary></indexterm><indexterm>
<primary>files, run-time help</primary><secondary>creating</secondary></indexterm></title>
<para>The text files you write must be &ldquo;compiled&rdquo; using the DocBook
software to create <emphasis>run-time help files</emphasis>. It's the run-time
help files that are accessed when the user requests help. Run-time files
use the Semantic Delivery Language (SDL) format. This delivery language is
based on an SGML document type definition designed expressly for online information
delivery.<indexterm><primary>Semantic Delivery Language (SDL)</primary></indexterm><indexterm>
<primary>SDL (Semantic Delivery Language)</primary></indexterm></para>
<para>The Help System defines desktop actions and data types for help-specific
files. This lets you easily create a run-time file from your desktop by selecting
the icon of a help source file and choosing a menu command that processes
the file.<indexterm><primary>help</primary><secondary>actions</secondary>
</indexterm><indexterm><primary>actions, help</primary></indexterm><indexterm>
<primary>help</primary><secondary>data types</secondary></indexterm><indexterm>
<primary>data types, help</primary></indexterm> A <filename>.sdl</filename>
extension is used to identify run-time help files. If any errors occurred
during processing, they are reported in an error file ( <symbol role="Variable">volume</symbol><filename>.log</filename>).</para>
<para>Refer to <!--Original XRef content: '&ldquo;Creating Run-Time Help
Files&rdquo; on page&numsp;89'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.2">
for complete instructions to create a run-time help file. For general information
about desktop actions and data types, refer to the <citetitle>Advanced User's
and System Administrator's Guide</citetitle>.</para>
</sect2>
<sect2 id="HRDC.Intro.div.44">
<title id="HRDC.Intro.mkr.26">Review Help as the User Will See It<indexterm>
<primary>reviewing</primary><secondary>help as user will see it</secondary>
</indexterm><indexterm><primary>user'</primary></indexterm><indexterm><primary>s perspective, seeing help from</primary></indexterm><indexterm><primary>perspective, seeing help from user'</primary></indexterm><indexterm><primary>&sigma;</primary></indexterm></title>
<para>During the authoring process, you will need to display your help so
you can interact with it just as your audience will. To display a help volume
from the desktop, double-click the file icon of the run-time help volume (<symbol role="variable">volume</symbol>.<filename>sdl</filename>). Or, you can also
display any help topic using the <command>dthelpview</command> command. <!--Original
XRef content: 'Chapter&numsp;4, &ldquo;Processing and Displaying
a Help Volume'--><xref role="ChapNumAndTitle" linkend="HRDC.CrHV.mkr.1">,
describes both methods.</para>
<para>If you are writing application help, and the Help System has been integrated
into your application, you can view your help by running the application
and making help requests just as the user will.</para>
</sect2>
</sect1>
<sect1 id="HRDC.Intro.div.45">
<title id="HRDC.Intro.mkr.27">Programmer's Job<indexterm><primary>programmer,
application</primary><secondary>responsibility</secondary></indexterm><indexterm>
<primary>responsibility</primary><secondary>programmer</secondary></indexterm></title>
<para>As a programmer, you add code into your application so that when a user
requests context-sensitive help, the application displays help information
that is relevant to what the application is doing at that time.</para>
<note>
<para id="HRDC.Intro.mkr.28">The<filename>/usr/dt/share/examples/dthelp</filename>
directory contains source code for a sample program called <command>dthelpdemo</command>. It demonstrates how to add help dialogs to a Motif application.<indexterm>
<primary>sample application, integrated help</primary></indexterm></para>
</note>
<sect2 id="HRDC.Intro.div.46">
<title id="HRDC.Intro.mkr.29">Consider How Your Help Is Accessed</title>
<para>Providing useful information to the user requires considering the following:
</para>
<itemizedlist remap="Bullet1"><listitem><para>What confusing situation commonly
arise? Specific help in these situations can save users lots of time.</para>
</listitem><listitem><para>Why is the user asking for help now instead of
earlier or later? If there are several steps in a process and the user is
not at the first step, branch to information that is specific to the step
being done. This is more helpful than displaying the same information at each
step. If the user is at the first step, make available both detailed information
about the first step and an overview of all the steps.</para>
</listitem><listitem><para>Is the user requesting context-specific help or
just browsing the help information? If it is context-specific, supply information
that's relevant to the task now being done.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.Intro.div.47">
<title id="HRDC.Intro.mkr.30">Collaborate with the Help Author</title>
<para>Close collaboration with the online help author is needed because the
author needs to know how each context-specific topic is reached and the programmer
needs to know what is explained in each context-specific topic. Without such
coordination, the user may see irrelevant, ambiguous, or misleading information.
</para>
<para>Collaboration makes the best use of the programmer's understanding of
the application and the author's understanding of how to best communicate
relevant information to the user.</para>
</sect2>
<sect2 id="HRDC.Intro.div.48">
<title>Identify Help Entry Points</title>
<para>An application provides online help by establishing help <emphasis>entry points</emphasis>. Entry points are defined in the application and associated
with specific help topics. Each of the ways that a user can request help&mdash;the
Help key, button, or menu&mdash;represent entry points. For example, consider
an application with a Print dialog box that has a Help button. The author
writes a help topic that describes the contents of the dialog box and supplies
you with the ID of the topic. You can then associate the ID of the help topic
with the Help button using a callback routine.</para>
</sect2>
<sect2 id="HRDC.Intro.div.49">
<title id="HRDC.Intro.mkr.31">Create and Manage Help Dialogs</title>
<para>The Help System application program interface is designed especially
for use with Motif applications. Specifically, Help extends the Motif
widget set by providing two new widget classes (plus convenience functions
to manipulate them):</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>General help dialog</emphasis>, which provides a help window that includes a menu bar and a topic
tree, in addition to a help topic display area.</para>
</listitem><listitem><para><emphasis>Quick help dialog</emphasis>, which provides
a simple help window with a topic display area and a few dialog buttons.</para>
</listitem></itemizedlist>
<para>You can use either or both of these types of help windows within your
application. Once the application is compiled (with the Help library), the
help windows become part of the application.</para>
<para><!--Original XRef content: 'Chapter&numsp;9, &ldquo;Creating and Managing
Help Dialog Boxes'--><xref role="ChapNumAndTitle" linkend="HRDC.CrDia.mkr.1">,
describes the general help and quick help dialog boxes.</para>
</sect2>
<sect2 id="HRDC.Intro.div.50">
<title>Package and Distribute Help</title>
<para>Your product package includes both the run-time help file ( <symbol role="variable">volume</symbol>.<filename>sdl</filename>) and its graphics files. Additionally,
you can provide a help family file that enables your volume to be viewed using
the Front Panel Help Viewer.</para>
<para>If the help volume uses execution links, you should collaborate with
the author to include the appropriate execution link resources in your application's
application defaults file. <!--Original XRef content: 'Chapter&numsp;13, &ldquo;Preparing
an Installation Package'--><xref role="ChapNumAndTitle" linkend="HRDC.Inst.mkr.1">,
discusses which help files are delivered with your application.</para>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub *0000050603>

1083
cde/doc/en_US.UTF-8/guides/helpGuide/ch02.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

766
cde/doc/en_US.UTF-8/guides/helpGuide/ch03.sgm Normal file
View File

@@ -0,0 +1,766 @@
<!-- $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 &lt;Sect1> tag:
</para>
<programlisting>&lt;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>&lt;sect1 id="HRDC.WrTop.div.2">
&lt;title>Help Topics&lt;/title></programlisting>
<sect3 id="HRDC.WrTop.div.4">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><!--Original XRef content: 'Chapter&numsp;2,
&ldquo;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 &lt;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 &lt;LiteralLayout> tag.</para>
<sect3 id="HRDC.WrTop.div.7">
<title>Examples</title>
<para>Here is an example of a plain vanilla paragraph:</para>
<programlisting>&lt;para>The Application Builder provides an interactive, graphical environment that facilitates the development of desktop applications. &lt;/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>&lt;LiteralLayout>
Brown and Reed Financial Investors
100 Baltic Place Suite 40
New York, New York
&lt;/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>&lt;ItemizedList Mark="Bullet">
&lt;ListItem>
&lt;para> ... &lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para> ... &lt;/para>
&lt;/ListItem>
...
&lt;/ItemizedList></programlisting>
<sect3 id="HRDC.WrTop.div.9">
<title>Examples</title>
<para>Here is the markup for a simple ItemizedList:</para>
<programlisting>&lt;itemizedlist>
&lt;listitem>&lt;para>Creating a Mail Message&lt;/para>&lt;/listitem>
&lt;listitem>&lt;para>Sending a Message&lt;/para>&lt;/listitem>
&lt;listitem>&lt;para>Reading Your Mail&lt;/para>&lt;/listitem>
&lt;/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>&lt;OrderedList>
&lt;ListItem>
&lt;para>Creating a Mail Message&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>Sending a Message&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>Reading Your Mail&lt;/para>
&lt;/ListItem>
&lt;/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>&lt;SegmentedList>
&lt;SegTitle>Nation&lt;/SegTitle>
&lt;SegTitle>Ethnic Groups&lt;/SegTitle>
&lt;SegTitle>Languages&lt;/SegTitle>
&lt;SegListItem>
&lt;Seg>Japan&lt;/Seg>
&lt;Seg>Japanese, Koreans, Ainu&lt;/Seg>
&lt;Seg>Japanese&lt;/Seg>
&lt;/SegListItem>
&lt;SegListItem>
&lt;Seg>Spain&lt;/Seg>
&lt;Seg>Spanish, Basques&lt;/Seg>
&lt;Seg>Castillian, Catalan, Basque&lt;/Seg>
&lt;/SegListItem>
&lt;SegListItem>
&lt;Seg>Belgium&lt;/Seg>
&lt;Seg>Flemish, Walloons&lt;&lt;/Seg>
&lt;Seg>Dutch, French&lt;/Seg>
&lt;/SegListItem>
&lt;/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>&lt;VariableList>
&lt;varlistentry>
&lt;term>first term&lt;/term>
&lt;listitem>&lt;para>definition of first term &lt;/para>&lt;listitem>
&lt;/varlistentry>
&lt;varlistentry>
&lt;term>second term&lt;/term>
&lt;listitem>&lt;para>definition of second term &lt;/para>&lt;listitem>
&lt;/varlistentry>
...
&lt;/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
"&amp;lt;" (the entity reference for the opening angle bracket) rather than
"&lt;" 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>&lt;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
&lt;/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>&lt;note>
<symbol>Body of note here.</symbol>
&lt;/note>
&lt;caution>
<symbol role="Variable">Body of caution here</symbol>
&lt;/caution>
&lt;warning>
<symbol role="Variable">Body of warning here.</symbol>
&lt;/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&numsp;3&hyphen;1'--><xref role="CodeOrFigureOrTable"
linkend="HRDC.WrTop.mkr.8">.</para>
<programlisting>&lt;note>
Before installing your application, complete the options checklist to determine the amount of disk space required.
&lt;/note>
&lt;warning>
This product is highly acidic and can cause skin irritation. Wearing protective gloves is mandatory when applying this product.
&lt;/warning>
&lt;caution>
Do not place your fingers near the parrot cage!
&lt;/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>&lt;emphasis><symbol role="Variable">text</symbol> &lt;/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 &lt;emphasis>no&lt;/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>&lt;CiteTitle> <symbol>title of a Book</symbol>&lt;/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>&lt;CiteTitle>The Help System Author's and Programmer's Guide&lt;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>&lt;Title> <symbol>title of the Book, Chapter, or Section</symbol>&lt;/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>&lt;Title>To Mark the Title of a Book, Chapter, or Section&lt;/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>&lt;computeroutput> <symbol>text</symbol>&lt;/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>&lt;filename><symbol>some filename</symbol>&lt;/filename>
</programlisting>
<sect3 id="HRDC.WrTop.div.30a">
<title>Example</title>
<para>This markup:</para>
<programlisting>Add the entity to your &lt;filename>Volume.sgm&lt;/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>&lt;symbol Role="Variable"> <symbol>text</symbol>&lt;/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 &lt;symbol Role="Variable">filename&lt;/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 &ldquo;man page&rdquo; 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,&lt;Link Linkend="H1-122-ch10-1> click here.&lt;/Link>
</programlisting>
<para>This Link points to a section and displays its title as the hot spot:
</para>
<programlisting>Click to go to &lt;Link Linkend="S1-123-ch12-1" Endterm="T1-123-ch12-1">&lt;/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 &lt;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>&lt;anchor id=&ldquo;077-ch02-AN-7&rdquo;></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>&lt;GlossTerm><symbol>text</symbol>&lt;/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>&mdash;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>&mdash;Screen
dumps from the X Window System&trade; created with the <command>xwd</command>
utility ( <symbol role="Variable">filename</symbol><filename>.xwd</filename>)
</para>
</listitem><listitem><para><emphasis>X pixmap</emphasis>&mdash;Color icon
images (<symbol role="Variable">filename</symbol><filename>.pm</filename>).
</para>
</listitem><listitem><para><emphasis>X bitmap</emphasis>&mdash;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>&lt;graphic id="ABUG.edprp.igrph.1" entityref="ABUG.edprp.fig.1">&lt;/graphic>
&lt;graphic id="ABUG.crobj.igrph.2" entityref="ABUG.crobj.fig.2">&lt;/graphic>
&lt;graphic id="ABUG.crobj.igrph.1" entityref="ABUG.crobj.fig.1">&lt;/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>&lt;!entity <symbol role="Variable">graphic-entity</symbol> SYSTEM &ldquo;<symbol role="Variable">filename.ext</symbol>&rdquo;></programlisting>
</listitem><listitem><para>Use the Graphic element as shown:</para>
<programlisting>&lt;Graphic id="<symbol>id</symbol>"> entityref=" <symbol>graphic-entity</symbol>"&lt;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&numsp;6, &ldquo;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&numsp;6,
&ldquo;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>&lt;!entity &amp; <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>&amp;<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 (&copy;) 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>&lt;!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>&amp;copy;</programlisting>
<para>To display the uppercase Greek letter sigma (&sum;), 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>&lt;!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>&amp;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>&lt;comment>
<symbol role="Variable">comment text here</symbol>
&lt;/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 &lt;Comment> and end marker &lt;/Comment>
as shown:</para>
<programlisting>&lt;comment>
<symbol role="Variable">comment text here</symbol>
&lt;/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>&lt;Comment>Here is my rough draft of the introduction: &lt;/Comment>
Welcome to my application. This software
is &lt;Comment>perhaps&lt;/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>&lt;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.&lt;/para>
&lt;IndexTerm>
&lt;Primary>rotating your terminal&lt;/Primary>
&lt;/IndexTerm>
&lt;IndexTerm>
&lt;Primary>terminal
&lt;Secondary>rotation of&lt;/Secondary>
&lt;/Primary>
&lt;/IndexTerm>
&lt;IndexTerm>
&lt;Primary>terminal
&lt;Secondary>adjustment of&lt;/Secondary>
&lt;SeeAlso>troubleshooting&lt;/SeeAlso>
&lt;/Primary>
&lt;/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 &lt;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>&lt;Glossary>
...
&lt;GlossEntry>
&lt;GlossTerm>
<symbol>term</symbol>
&lt;/GlossTerm>
&lt;GlossDef>
<symbol>text of definition</symbol>
&lt;/GlossDef>
&lt;/GlossEntry>
...
&lt;/Glossary></programlisting>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub *0000043237>

508
cde/doc/en_US.UTF-8/guides/helpGuide/ch04.sgm Normal file
View File

@@ -0,0 +1,508 @@
<!-- $XConsortium: ch04.sgm /main/15 1996/10/22 14:42:40 cdedoc $ -->
<!-- (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.CrHV.div.1">
<title id="HRDC.CrHV.mkr.1">Processing and Displaying a Help Volume</title>
<para>This chapter shows you how to process your marked-up help files to create
an online format that you view using the Help System. It also describes how
to make your help volume accessible from the desktop Front Panel Help Viewer.
</para>
<informaltable id="HRDC.CrHV.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating Run-Time Help Files89'--><xref
role="JumpText" linkend="HRDC.CrHV.mkr.2"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Create a Run-Time Help Volume89'--><xref
role="JumpText" linkend="HRDC.CrHV.mkr.3"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Viewing a Help Volume92'--><xref
role="JumpText" linkend="HRDC.CrHV.mkr.6"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a Help Volume92'--><xref
role="JumpText" linkend="HRDC.CrHV.mkr.7"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Adding Your Help to the Index Volume94'--><xref
role="JumpText" linkend="HRDC.CrHV.mkr.8"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Printing Help Topics98'--><xref role="JumpText"
linkend="HRDC.CrHV.mkr.13"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Testing Your Help99'--><xref role="JumpText"
linkend="HRDC.CrHV.mkr.15"></para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect1 id="HRDC.CrHV.div.2">
<title>Overview</title>
<para>Before a help volume can be displayed, you must create a run-time help
file by processing your files with the DocBook software. Run-time files use
an online presentation format called <emphasis>Semantic Delivery Language</emphasis> (SDL). An<filename>.sdl</filename> file extension identifies a
run-time help file.</para>
<para>The utility <command>dtdocbook</command> takes documents conforming
to the DocBook 2.2.1 DTD subelement Part and produces documents conforming
to the SDL 1.2 DTD, which can serve as input to the DtHelp viewer.</para>
<para>During translation, several items are precomputed to speed run-time
display of the document. These items include: the table of contents, the keyword
index, resolution of cross-references, and labeling of ordered lists. The
SDL conforming document produced by the translation is compressed by default.
</para>
<graphic id="HRDC.CrHV.igrph.1" entityref="HRDC.CrHV.fig.1"></graphic>
<para>The Help System defines desktop actions and data types for help-specific
files. This lets you easily process and view a run-time help file from the
desktop.</para>
<sect2 id="HRDC.CrHV.div.3">
<title>DocBook Software</title>
<para>The DocBook software can be invoked automatically by double-clicking
a help source file in File Manager or by running the <command>dtdocbook</command>
command manually in a terminal window.</para>
<para><command>dtdocbook</command> does two significant tasks:</para>
<orderedlist><listitem><para>The DocBook <emphasis>parser</emphasis> converts
your marked-up files into an internal format (Semantic Delivery Language)
understood by the Help System. If you've made any markup errors, the errors
are reported in a file named <symbol role="Variable">volume</symbol><filename>.log</filename>.</para>
</listitem><listitem><para>If there are no parser errors, the master help
volume file (<symbol role="Variable">volume</symbol><filename>.sdl</filename>)
is created.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="HRDC.CrHV.div.4">
<title>Viewing Your Volume</title>
<para>After processing your source files with DocBook, your help volume is
ready to be displayed. You can display it by double-clicking the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file icon in File
Manager, or use the <command>dthelpview</command> command in a terminal window.
</para>
<graphic id="HRDC.CrHV.igrph.2" entityref="HRDC.CrHV.fig.2"></graphic>
<para>If you have written help for an application and the application is ready
to use, you can display your help by running the application and asking for
help.</para>
</sect2>
</sect1>
<sect1 id="HRDC.CrHV.div.5">
<title id="HRDC.CrHV.mkr.2">Creating Run-Time Help Files</title>
<para>When you run <command>dtdocbook</command>, it reads your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file and any additional source files
that are included using entities. It also validates graphics file names.</para>
<para>Be sure the <command>/usr/dt/bin/dtdocbook</command> command is in your
search path. (If you're not sure how to do this, ask your system administrator.)
</para>
<sect2 id="hrdc.crhv.div.6" role="Procedure">
<title id="hrdc.crhv.mkr.3">To Create a Run-Time Help Volume</title>
<orderedlist><listitem><para>Open File Manager and change to the directory
where your <symbol role="Variable">volume</symbol><filename>.sgm</filename>
file is located.</para>
<graphic id="hrdc.crhv.igrph.3" entityref="HRDC.CrHV.fig.3"></graphic>
</listitem><listitem><para>Select the file icon.</para>
</listitem><listitem><para>Choose Compile from the File Manager Selected menu.
</para>
<para>The <symbol role="Variable">volume</symbol><filename>.sgm</filename>
file is processed and creates a <symbol role="Variable">volume</symbol><filename>.sdl</filename> file and a <symbol role="Variable">volume</symbol><filename>.log</filename> file.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="HRDC.CrHV.div.7">
<title>DocBook Output</title>
<para>DocBook takes the file <symbol role="Variable">volume</symbol><filename>.sgm</filename> as its input and outputs several files:</para>
<itemizedlist><listitem><para>Most importantly, the final output file, a
run-time help volume, named <symbol role="Variable">volume</symbol><filename>.sdl</filename>.</para>
</listitem><listitem><para>If any errors occurred during processing, they
are reported in an error file named <symbol role="Variable">volume</symbol><filename>.log</filename>, typically removed after use.</para>
</listitem></itemizedlist>
<para>The <symbol role="Variable">volume</symbol><filename>.sdl</filename>
file is not created until the source file is without errors.</para>
<para>The <symbol role="Variable">volume</symbol><filename>.sdl</filename>,
file, plus your graphics files, are read by the Help System to display help
topics.</para>
<para>The run-time help file has the same base name as your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file. For example, if your source
file is named <filename>Librarian.sgm</filename>, then the help volume name
is <filename>Librarian.sdl</filename>.</para>
<para>The <command>dtdocbook</command> utility accepts a single file as an
argument. If the file name ends in the characters &ldquo;<filename>.sgm</filename>&rdquo;,
those characters are assumed to be the file name extension and are removed
to create the file base names for all intermediate files and for the final
output file.</para>
<para>When the <command>dtdocbook -c</command> or the <command>dtdocbook -d</command> option is specified to request compression or decompression of
an existing SDL file, the input file name will end in the characters &ldquo;<filename>.sdl</filename>&rdquo;. Again, those characters are assumed to be the file
name extension and are removed to create the file base names for all intermediate
files and for the final output file.</para>
<para>If the <command>-c</command> option is specified and the file is already
compressed, the file will be decompressed and recompressed. This action is
useful as a means to verify the integrity of a compressed SDL file.</para>
<para>If the <command>-d</command> is specified and the file is already decompressed,
the file will be re-parsed, all precomputations will be performed, and the
file will be re-written. This action is useful as a means to verify the integrity
of an SDL file. It is also useful for forcing a recomputation of the table
of contents, including byte offsets to individual help topics, when such recomputation
is made necessary, for example, by editing the SDL file directly.</para>
<para>The final output file name extension will always be &ldquo;<filename>.sdl</filename>&rdquo;, unless the <command>dtdocbook -o</command> option
is specified, in which case the <symbol role="Variable">filename</symbol>
argument to <command>dtdocbook -o</command> will be used as given as the output
file name.</para>
<caution>
<para>Never rename a run-time help file or graphics file after running <command>dtdocbook</command>. The information stored in the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file depends on the original names.
If you rename your <symbol role="Variable">volume</symbol><filename>.sgm</filename>
file or any of your graphic files, be sure to rerun <command>dtdocbook</command>.
</para>
</caution>
</sect2>
<sect2 id="HRDC.CrHV.div.8" role="Procedure">
<title>To Run the dtdocbook Command Manually</title>
<itemizedlist><listitem><para>Run the <command>dtdocbook</command> command
as follows:</para>
<para><command>dtdocbook</command> <symbol>options</symbol> <symbol>volume</symbol></para>
<para>Observe that <symbol>options</symbol> are entered before the <symbol>volume</symbol> name. <xref role="SecTitleAndPageNum" linkend="HRDC.CmdS.mkr.2">
lists all available options.</para>
</listitem></itemizedlist>
<sect3 id="HRDC.CrHV.div.9">
<title>Examples of Command Options.sgm</title>
<para>The following command processes a help volume named <filename>MyVolume</filename>:</para>
<programlisting>dtdocbook MyVolume</programlisting>
<para>Using the <command>-r</command> option removes all files previously
generated by processing a source file of <filename>MyVolume.sgm</filename>:
</para>
<programlisting>dtdocbook -r MyVolume.sgm</programlisting>
<para>The following command processes the source file named <filename>MyVolume.sgm</filename> and leaves the result in the file named <filename>Other_File.sdl</filename>::</para>
<programlisting>dtdocbook -o Other_File.sdl MyVolume.sgm</programlisting>
<para>Using the <command>-v</command> option causes the progress of the processing
to be displayed on your screen:</para>
<programlisting>dtdocbook -v MyVolume</programlisting>
</sect3>
<sect3 id="HRDC.CrHV.div.11">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="ChapNumAndTitle"
linkend="HRDC.Inst.mkr.1"> explains which help files are included in your
application installation package.</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.CrHV.div.12" role="Procedure">
<title id="HRDC.CrHV.mkr.5">To Review and Correct Parser Errors</title>
<para>The primary source of error messages will be the SGML parser. Most of
them will be SGML syntax error messages, and a few will be of the "file not
found" variety.</para>
<para>The two passes of the translation process that takes the source file
from SGML to SDL will also generate syntax error messages and "file not found"
messages, but to a lesser degree. The second of the two passes will issue
error messages rarely, since all the syntax and context will have been checked
by then.</para>
<para>After running <command>dtdocbook</command>, look at the contents of
the <symbol role="Variable">volume</symbol><filename>.log</filename> file
(where <symbol role="Variable">volume</symbol> is the base name of your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file).</para>
<para>It is quite possible for a single, simple error to produce several error
messages, because the error may cause the parser to lose track of the intended
context, making it impossible to interpret subsequent markup properly.</para>
<sect3 id="HRDC.CrHV.div.13">
<title>Common Errors</title>
<para>Most processing errors result from these common mistakes:</para>
<itemizedlist><listitem><para>Omitting an end tag</para>
</listitem><listitem><para>Using an incorrect entity name</para>
</listitem><listitem><para>Referring to an invalid element ID</para>
</listitem></itemizedlist>
<para>Omitting an end tag for an element is a common mistake. <emphasis>Virtually
all DocBook elements require end tags.</emphasis> Check your markup when you
have nested one structurally complex element within another, such as a figure
within a list.</para>
<para>Errors can also be introduced by using an incorrect entity name. In
most instances, it is simply a misspelled word. In other cases, an entity
name may have been changed, but cross-references to the original name were
overlooked. When you change an entity name, remember to search your source
file (or files) for all instances of the entity name.</para>
<para>Errors can also be introduced by changing the ID assigned to an element,
since this affects any cross-reference or link to that topic. When you change
an ID, remember to search your source file (or files) for all instances of
that ID.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrHV.div.14">
<title id="HRDC.CrHV.mkr.6">Viewing a Help Volume</title>
<para>The Help Viewer can be used to display any help volume. It supports
all DocBook hyperlinks but not application-defined links (because it cannot
know how your links are to be interpreted).</para>
<para>If you are writing application help and your application is ready to
use, you can also view your help by running your application, then requesting
help just as a user would.</para>
<sect2 id="HRDC.CrHV.div.15" role="Procedure">
<title id="HRDC.CrHV.mkr.7">To Display a Help Volume</title>
<orderedlist><listitem><para>Open File Manager and change to the directory
where the <symbol role="Variable">volume</symbol><filename>.sdl</filename>
file is located.</para>
</listitem><listitem><para>Double-click its icon.</para>
<para>The default action displays the file using the Help Viewer.</para>
</listitem></orderedlist>
<sect3 id="HRDC.CrHV.div.16" role="Procedure">
<title>To Run the dthelpview Command Manually</title>
<itemizedlist><listitem><para>If the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file for the volume you want to display is either in the current
directory or has been registered, execute this command:</para>
<para><command>dthelpview -helpVolume <symbol role="Variable">volume</symbol><filename>.sdl</filename></command></para>
<para><emphasis>Or,</emphasis> if the <symbol role="Variable">volume</symbol><filename>.sdl</filename> is in another directory (and hasn't been registered), execute
this command:</para>
<para><command>dthelpview -helpVolume /<symbol>full-path</symbol>/ <symbol>volume</symbol>.sdl</command></para>
</listitem></itemizedlist>
<para>The <command>-helpVolume</command> parameter can be shortened to <command>-h</command> in any of these commands.</para>
</sect3>
<sect3 id="HRDC.CrHV.div.17">
<title>Example</title>
<para>Suppose you have just edited your help volume. First, process it with
the DocBook software:</para>
<programlisting>dtdocbook MyVolume.sgm</programlisting>
<para>If no errors occurred, you could then display it with this command:
</para>
<programlisting>dthelpview -h MyVolume.sdl</programlisting>
</sect3>
<sect3 id="HRDC.CrHV.div.18">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9"></para>
</listitem></itemizedlist>
</sect3>
<sect3 id="HRDC.CrHV.div.19">
<title>Example: A Personal Help Directory</title>
<para>During a project, you may want to access the help volume you are developing,
but not expose it to all users on your system. For example, suppose your
working directory is <filename>/projects/help</filename> and your help volume
is named <filename>Myvolume</filename>.</para>
<para>First, create the personal help directory in your home directory where
you can register the volume:</para>
<programlisting>mkdir -p $HOME/.dt/help/C</programlisting>
<para>Now create a symbolic link to the <filename>Myvolume.sdl</filename>
file (which is created by the DocBook software):</para>
<programlisting>ln -s /projects/help/Myvolume.sdl $HOME/.dt/help/C/Myvolume.sdl
</programlisting>
<para>You can now display the volume with the following command (regardless
of your current directory) because the<filename>.dt/help/C</filename> directory
within your home directory is one of the first places the Help System looks
for help volumes.</para>
<programlisting>dthelpview -helpVolume Myvolume.sdl</programlisting>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrHV.div.20">
<title id="HRDC.CrHV.mkr.8">Adding Your Help to the Index Volume</title>
<para>The desktop provides a special help volume called the index volume that
lists help volumes available on your system. The index volume is displayed
by clicking the Help Viewer control in the Front Panel.</para>
<para>You can view assorted help volumes directly from the index volume. This
allows access to application-specific help without starting the application.
If you are writing standalone help, this is the only way for users to get
to your help.</para>
<figure>
<title id="HRDC.CrHV.mkr.9">Index help volume displaying help families</title>
<graphic id="HRDC.CrHV.grph.1" entityref="HRDC.CrHV.fig.4"></graphic>
</figure>
<para>To make your help volume available in the index volume, you create a
help family file. When your application is registered on the desktop, the
presence of a family file causes the help volume to be included in the index
volume.</para>
<sect2 id="HRDC.CrHV.div.21">
<title id="HRDC.CrHV.mkr.10">Index Volume</title>
<para>A desktop utility creates and updates the index volume. When a user
clicks on the Front Panel Help Viewer for the first time, the utility is automatically
run. It identifies help volumes and help family files that are located in
the help search path directories. It creates a file called <filename>index.hv</filename> in the user's <filename>HomeDirectory/.dt/help/$DTUSERSESSION</filename> directory. After its initial creation, the volume is updated only
if changes have occurred.</para>
<para>To manually update the index volume, refer to <xref role="SecTitleAndPageNum"
linkend="HRDC.CmdS.mkr.5">.</para>
<para>Any help volume listed in the index volume can be viewed by selecting
the volume title. Because you can display and navigate through different volumes,
the index help window includes an additional button, called Top Level.You
can use this button to return to the index list after displaying one or more
volumes.</para>
</sect2>
<sect2 id="HRDC.CrHV.div.22">
<title>Help Family File</title>
<para>The desktop utility examines help family files to identify which help
volumes are gathered into the index volume. <xref role="CodeOrFigureOrTable"
linkend="HRDC.CrHV.mkr.9"> on <xref role="PageNum" linkend="HRDC.CrHV.mkr.9">
shows two help families, Common Desktop Environment and Overview and Basic
Desktop Skills, listed in the index volume. Each family file consists of
one or more related help volumes. For example, the Common Desktop Environment
family includes different volumes that describe the desktop.</para>
<para>Refer to the Advanced User's and System Administrator's Guide for a
detailed explanation of how an application and its help files are installed
on the desktop.</para>
</sect2>
<sect2 id="HRDC.CrHV.div.23" role="Procedure">
<title id="HRDC.CrHV.mkr.11">To Create a Help Family</title>
<orderedlist><listitem><para>Pick a file name that is unique to your product.
Use the<filename>.hf</filename> extension to identify the file as a <emphasis>help family</emphasis>.</para>
<para><filename><symbol>family</symbol>.hf</filename></para>
</listitem><listitem><para>Enter the following lines into the file:</para>
<programlisting>*.charSet: <symbol>character-set</symbol>
*.title: <symbol>family title</symbol>
*.bitmap: <symbol>icon file</symbol>
*.abstract: <symbol>family abstract</symbol>
*.volumes: <symbol>volume volume volume ...</symbol></programlisting>
<para>Where <symbol>character-set</symbol> specifies the character set used
by the <symbol>family title</symbol> and <symbol>family abstract</symbol>
strings. <xref role="SecTitleAndPageNum" linkend="HRDC.Lang.mkr.11"> for a
list of supported character sets. The <symbol>family title</symbol> and <symbol>family abstract</symbol> should not contain any DocBook markup; this file
is <emphasis>not</emphasis> processed with the DocBook software.</para>
<para>The <symbol>icon file</symbol> is optional. If you provide one, the
path you use to specify the location of the file should be a complete path
name. If you do not provide an icon, do not include the <filename>*.bitmap</filename> resource in your family file.</para>
<para>The list of <symbol>volume</symbol> names identifies which volumes belong
to the family. The volumes will be listed in the order they appear on this
line. A volume may be listed in more than one family.</para>
<para>If any of the values occupy more than one line, end each line &mdash;
except the last &mdash; with a backslash (<filename>\</filename>).</para>
<para>Any line in the file that begins with an <filename>!</filename> (exclamation
mark) is a comment line and is ignored.</para>
</listitem><listitem><para>When you prepare your final product, you should
install your <symbol>family</symbol><filename>.hf</filename> file with the
rest of your help files. When the desktop integration script, (<command>dtappintegrate</command>) is run, it creates the symbolic links to your family file.</para>
<para>The <citetitle>Advanced User's and System Administrator's Guide</citetitle>
describes how to run the <command>dtappintegrate</command> script.</para>
</listitem></orderedlist>
<sect3 id="HRDC.CrHV.div.24">
<title>Example</title>
<para>Here's an example of a family file for the desktop's online help.</para>
<programlisting>*.charSet: ISO-8859-1
*.title: Common Desktop Environment
*.bitmap: /usr/dt/appconfig/help/C/graphics/cdelogo.pm
*.abstract: Overview and Basic Desktop Skills \
* File Manager and the Desktop \
* Front Panel \
* Application Manager \
* Style Manager \
* Text Editor \
* Mailer
*.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
Appmanager.sdl Stylemgr.sdl
Textedit.sdl Mailer.sdl
</programlisting>
<para>The help family file actually included with the desktop software may
not exactly match this example.</para>
</sect3>
<sect3 id="HRDC.CrHV.div.25">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
linkend="HRDC.Lang.mkr.5"> for a list of supported character set names</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="hrdc.crhv.div.26" role="Procedure">
<title id="hrdc.crhv.mkr.12">To Display the Index Volume</title>
<orderedlist><listitem><para>Choose the Help Viewer control from the desktop's
Front Panel.</para>
<graphic id="hrdc.crhv.igrph.4" entityref="HRDC.CrHV.fig.5"></graphic>
</listitem><listitem><para>Scroll the help window to view the help families
available on your system.</para>
</listitem><listitem><para>If desired, display a volume by selecting the help
family title.</para>
</listitem></orderedlist>
<note>
<para>To view help information about the Help System, choose the title Common
Desktop Environment and then Desktop Help System.</para>
</note>
<sect3 id="hrdc.crhv.div.27" role="Procedure">
<title>To Display the Index Volume Manually</title>
<itemizedlist><listitem><para>Run the <command>dthelpview</command> command
as follows:</para>
<programlisting>dthelpview -helpVolume index</programlisting>
</listitem></itemizedlist>
</sect3>
<sect3 id="hrdc.crhv.div.28">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="hrdc.cmds.mkr.4">
lists <command>dthelpview</command> command line.</para>
</listitem><listitem><para><command>dthelpgen</command>(1) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrHV.div.29">
<title id="HRDC.CrHV.mkr.13">Printing Help Topics<indexterm><primary>printing</primary><secondary>help topics</secondary></indexterm></title>
<para>After displaying your help volume, you can print help topics. Using
the Print dialog box shown in <!--Original XRef content: 'Figure&numsp;4&hyphen;2'--><xref
role="CodeOrFigureOrTable" linkend="HRDC.CrHV.mkr.14"> you can print an individual
topic, a table of contents and index information, or the entire help volume.
Printed output omits graphics.</para>
<figure>
<title id="HRDC.CrHV.mkr.14">Help print dialog box</title>
<graphic id="HRDC.CrHV.grph.2" entityref="HRDC.CrHV.fig.6"></graphic>
</figure>
</sect1>
<sect1 id="HRDC.CrHV.div.30">
<title id="HRDC.CrHV.mkr.15">Testing Your Help</title> <indexterm><primary>testing</primary><secondary>help</secondary></indexterm><indexterm><primary>validating hyperlinks</primary></indexterm><indexterm><primary>hyperlink</primary><secondary>validating hyperlinks</secondary></indexterm><indexterm>
<primary>verifying application entry points</primary></indexterm><indexterm>
<primary>application entry points, verifying</primary></indexterm><indexterm>
<primary>entry points in application, verifying</primary></indexterm><indexterm>
<primary>points, entry, verifying in application</primary></indexterm><indexterm>
<primary>testing</primary><secondary>graphics on various displays</secondary>
</indexterm><indexterm><primary>graphics, testing on various displays</primary>
</indexterm><indexterm><primary>displays, testing graphics on various</primary>
</indexterm>
<para>Testing your help volume is as important as testing any software product.
Here are some tips to help you plan your testing.</para>
<sect2 id="HRDC.CrHV.div.31">
<title>Validating Hyperlinks</title>
<itemizedlist remap="Bullet1"><listitem><para>Display your help volume and
try every hyperlink. Any underlined text (solid or dashed underlines) is a
hyperlink. Also, test any graphics that are hyperlinks. Graphic hyperlinks
use an open-cornered border (dashed or solid) around the image as a hyperlink
cue.</para>
</listitem><listitem><para>If you are writing application-specific help and
you have included any <command>JumpNewView</command>, <command>Man</command>,
or <command>AppDefined</command> links, you must test these links from your
application. Testing such links using <command>dthelpview</command> does not
ensure that the links will operate correctly from within your application.
</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.CrHV.div.32">
<title>Verifying Entry Points</title>
<para>If you are writing application-specific help that uses IDs to access
particular help topics, there are two ways to verify that the IDs have been
properly established within the help volume:</para>
<itemizedlist remap="Bullet1"><listitem><para>Run your application and request
help just as a user will, trying each of the entry points. This also verifies
that the application is using the correct IDs.</para>
</listitem><listitem><para>If your application is not ready to use (still
under development), you can test each ID by running <command>dthelpview</command>
for each ID:</para>
<programlisting>dthelpview -helpVolume <symbol role="Variable">volume.sdl</symbol> -locationId <symbol role="Variable">id</symbol></programlisting>
<para>Where <symbol role="Variable">id</symbol> is the location ID that you
want to test. If <command>dthelpview</command> displays the correct topic,
then the ID is okay.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.CrHV.div.33">
<title>Checking Index Entries</title>
<para>Users search or browse a help volume index to find help topics. Examine
your index entries carefully to eliminate any vague terms or duplicate entries.
Also select each index entry to verify that the topic displayed is the most
appropriate information.</para>
</sect2>
<sect2 id="HRDC.CrHV.div.34">
<title>Testing Graphics</title>
<itemizedlist remap="Bullet1"><listitem><para>Physically run your application
on various displays to verify that the graphics are acceptable on color,
grayscale, and monochrome displays.</para>
</listitem><listitem><para>You can also simulate other displays by changing
the number of colors used by the desktop. To do so, open Style Manager, choose
Number Of Colors, and select a different color option.</para>
</listitem></itemizedlist>
<sect3 id="HRDC.CrHV.div.36">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><!--Original XRef content: '&ldquo;Generating
a Index Help Volume (dthelpgen)&rdquo; on page&numsp;193'--><xref role="SecTitleAndPageNum"
linkend="HRDC.CmdS.mkr.5"></para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1><?Pub Caret1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

914
cde/doc/en_US.UTF-8/guides/helpGuide/ch05.sgm Normal file
View File

@@ -0,0 +1,914 @@
<!-- $XConsortium: ch05.sgm /main/11 1996/08/25 15:10:20 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.ChEnt.div.1">
<title id="HRDC.ChEnt.mkr.1">Summary of Special Character Entities</title>
<para>This chapter provides a list of special characters that can be used
when writing a help topic.<indexterm><primary>special characters</primary>
<secondary>list of</secondary></indexterm><indexterm><primary>character,
inserting special</primary></indexterm><indexterm><primary>predefined entities</primary></indexterm><indexterm><primary>entities</primary><secondary>special
character</secondary></indexterm><indexterm><primary>symbol</primary></indexterm>
The following special characters can be inserted into text by typing the associated
entity name in the position where the special character is to appear.</para>
<table id="HRDC.ChEnt.tbl.1" frame="Topbot">
<title>Numeric and Special Graphic Symbols</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="0.90in">
<colspec colwidth="1.75in">
<colspec colname="col3" colwidth="2.35in">
<spanspec nameend="col3" namest="col1" spanname="1to3">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Symbol</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Entity Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Description</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>&amp;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;amp;</literal></para></entry>
<entry align="left" valign="top"><para>ampersand</para></entry></row>
<row>
<entry align="left" valign="top"><para>'</para></entry>
<entry align="left" valign="top"><para><literal>&amp;apos;</literal></para></entry>
<entry align="left" valign="top"><para>apostrophe</para></entry></row>
<row>
<entry align="left" valign="top"><para>*</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ast;</literal></para></entry>
<entry align="left" valign="top"><para>asterisk</para></entry></row>
<row>
<entry align="left" valign="top"><para>\</para></entry>
<entry align="left" valign="top"><para><literal>&amp;bsol;</literal></para></entry>
<entry align="left" valign="top"><para>backslash, reversed solidus</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&cent;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;cent;</literal></para></entry>
<entry align="left" valign="top"><para>cent sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>:</para></entry>
<entry align="left" valign="top"><para><literal>&amp;colon;</literal></para></entry>
<entry align="left" valign="top"><para>colon</para></entry></row>
<row>
<entry align="left" valign="top"><para>,</para></entry>
<entry align="left" valign="top"><para><literal>&amp;comma;</literal></para></entry>
<entry align="left" valign="top"><para>comma</para></entry></row>
<row>
<entry align="left" valign="top"><para>@</para></entry>
<entry align="left" valign="top"><para><literal>&amp;commat;</literal></para></entry>
<entry align="left" valign="top"><para>commercial at</para></entry></row>
<row>
<entry align="left" valign="top"><para>&copy;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;copy;</literal></para></entry>
<entry align="left" valign="top"><para>copyright symbol</para></entry></row>
<row>
<entry align="left" valign="top"><para>&curren;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;curren;</literal></para></entry>
<entry align="left" valign="top"><para>general currency sign</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&darr;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;darr;</literal></para></entry>
<entry align="left" valign="top"><para>downward arrow</para></entry></row>
<row>
<entry align="left" valign="top"><para>&deg;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;deg;</literal></para></entry>
<entry align="left" valign="top"><para>degree sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&divide;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;divide;</literal></para></entry>
<entry align="left" valign="top"><para>divide sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>$</para></entry>
<entry align="left" valign="top"><para><literal>&amp;dollar;</literal></para></entry>
<entry align="left" valign="top"><para>dollar sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>=</para></entry>
<entry align="left" valign="top"><para><literal>&amp;equals;</literal></para></entry>
<entry align="left" valign="top"><para>equal sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>!</para></entry>
<entry align="left" valign="top"><para><literal>&amp;excl;</literal></para></entry>
<entry align="left" valign="top"><para>exclamation mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&frac12;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac12</literal></para></entry>
<entry align="left" valign="top"><para>fraction one-half</para></entry></row>
<row>
<entry align="left" valign="top"><para>&frac14;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac14</literal></para></entry>
<entry align="left" valign="top"><para>fraction one-quarter</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&frac18;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac18</literal></para></entry>
<entry align="left" valign="top"><para>fraction one-eighth</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&frac34;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac34</literal></para></entry>
<entry align="left" valign="top"><para>fraction three-quarters</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&frac38;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac38</literal></para></entry>
<entry align="left" valign="top"><para>fraction three-eighths</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&frac58;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac58;</literal></para></entry>
<entry align="left" valign="top"><para>fraction five-eighths</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&frac78;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;frac78;</literal></para></entry>
<entry align="left" valign="top"><para>fraction seven-eighths</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>></para></entry>
<entry align="left" valign="top"><para><literal>&amp;gt;</literal></para></entry>
<entry align="left" valign="top"><para>greater-than sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&half;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;half;</literal></para></entry>
<entry align="left" valign="top"><para>fraction one-half</para></entry></row>
<row>
<entry align="left" valign="top"><para>-</para></entry>
<entry align="left" valign="top"><para><literal>&amp;hyphen;</literal></para></entry>
<entry align="left" valign="top"><para>hyphen</para></entry></row>
<row>
<entry align="left" valign="top"><para>&iexcl;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;iexcl;</literal></para></entry>
<entry align="left" valign="top"><para>inverted exclamation mark</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&iquest;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;iquest;</literal></para></entry>
<entry align="left" valign="top"><para>inverted question mark</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&larr;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;larr;</literal></para></entry>
<entry align="left" valign="top"><para>leftward arrow</para></entry></row>
<row>
<entry align="left" valign="top"><para>{</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lcub;</literal></para></entry>
<entry align="left" valign="top"><para>left curly brace</para></entry></row>
<row>
<entry align="left" valign="top"><para>_</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lowbar;</literal></para></entry>
<entry align="left" valign="top"><para>low line</para></entry></row>
<row>
<entry align="left" valign="top"><para>(</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lpar;</literal></para></entry>
<entry align="left" valign="top"><para>left parenthesis</para></entry></row>
<row>
<entry align="left" valign="top"><para>[</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lsqb;</literal></para></entry>
<entry align="left" valign="top"><para>left square bracket</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>`</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lsquo;</literal></para></entry>
<entry align="left" valign="top"><para>left single quote</para></entry></row>
<row>
<entry align="left" valign="top"><para>&lt;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lt;</literal></para></entry>
<entry align="left" valign="top"><para>less-than sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&nbsp;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;nbsp;</literal></para></entry>
<entry align="left" valign="top"><para>no break space</para></entry></row>
<row>
<entry align="left" valign="top"><para>&not;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;not;</literal></para></entry>
<entry align="left" valign="top"><para>not</para></entry></row>
<row>
<entry align="left" valign="top"><para>#</para></entry>
<entry align="left" valign="top"><para><literal>&amp;num;</literal></para></entry>
<entry align="left" valign="top"><para>number sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&para;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;para;</literal></para></entry>
<entry align="left" valign="top"><para>paragraph sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>%</para></entry>
<entry align="left" valign="top"><para><literal>&amp;percnt;</literal></para></entry>
<entry align="left" valign="top"><para>percent sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>.</para></entry>
<entry align="left" valign="top"><para><literal>&amp;period;</literal></para></entry>
<entry align="left" valign="top"><para>full stop, period</para></entry></row>
<row>
<entry align="left" valign="top"><para>+</para></entry>
<entry align="left" valign="top"><para><literal>&amp;plus;</literal></para></entry>
<entry align="left" valign="top"><para>plus sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&plusmn;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;plusmn;</literal></para></entry>
<entry align="left" valign="top"><para>plus-or-minus sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&pound;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;pound;</literal></para></entry>
<entry align="left" valign="top"><para>pound sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>?</para></entry>
<entry align="left" valign="top"><para><literal>&amp;quest;</literal></para></entry>
<entry align="left" valign="top"><para>question mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&rarr;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rarr;</literal></para></entry>
<entry align="left" valign="top"><para>rightward arrow</para></entry></row>
<row>
<entry align="left" valign="top"><para>}</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rcub;</literal></para></entry>
<entry align="left" valign="top"><para>right curly brace</para></entry></row>
<row>
<entry align="left" valign="top"><para>&rdquo;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rdquo;</literal></para></entry>
<entry align="left" valign="top"><para>right double quote</para></entry></row>
<row>
<entry align="left" valign="top"><para>&reg;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;reg;</literal></para></entry>
<entry align="left" valign="top"><para>registered sign, a circled R</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>)</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rpar;</literal></para></entry>
<entry align="left" valign="top"><para>right parenthesis</para></entry></row>
<row>
<entry align="left" valign="top"><para>]</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rsqb;</literal></para></entry>
<entry align="left" valign="top"><para>right square bracket</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>'</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rsquo;</literal></para></entry>
<entry align="left" valign="top"><para>right single quote</para></entry></row>
<row>
<entry align="left" valign="top"><para>&sect;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sect;</literal></para></entry>
<entry align="left" valign="top"><para>section sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;semi;</literal></para></entry>
<entry align="left" valign="top"><para>semicolon</para></entry></row>
<row>
<entry align="left" valign="top"><para>/</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sol;</literal></para></entry>
<entry align="left" valign="top"><para>solidus</para></entry></row>
<row>
<entry align="left" valign="top"><para>&times;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;times;</literal></para></entry>
<entry align="left" valign="top"><para>multiply sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&trade;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;trade;</literal></para></entry>
<entry align="left" valign="top"><para>trademark sign</para></entry></row>
<row>
<entry align="left" valign="top"><para>&uarr;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;uarr;</literal></para></entry>
<entry align="left" valign="top"><para>upward arrow</para></entry></row>
<row>
<entry align="left" valign="top"><para>&yen;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;yen;</literal></para></entry>
<entry align="left" valign="top"><para>yen sign</para></entry></row></tbody>
</tgroup></table>
<table id="HRDC.ChEnt.tbl.2" frame="Topbot">
<title>Greek Characters</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="1.11in">
<colspec colname="col2" colwidth="1.53in">
<colspec colname="col3" colwidth="2.35in">
<spanspec nameend="col2" namest="col1" spanname="1to2">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Symbol</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Entity Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Description</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" spanname="1to2" valign="top"><para>Lowercase Greek Letters
</para></entry></row>
<row>
<entry align="left" valign="top"><para>&alpha;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;alpha;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek alpha</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&beta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;beta;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek beta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&chi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;chi;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek chi</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&delta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;delta;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek delta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&epsiv;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;epsiv;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek epsilon, variant</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&eta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;eta;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek eta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&gamma;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;gamma;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek gamma</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&iota;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;iota;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek iota</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&kappa;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;kappa;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek kappa</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&lambda;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;lambda;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek lambda</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&mu;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;mu;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek mu</para></entry></row>
<row>
<entry align="left" valign="top"><para>&nu;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;nu;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek nu</para></entry></row>
<row>
<entry align="left" valign="top"><para>&omega;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;omega;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek omega</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&phis;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;phis;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek phi</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&pi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;pi;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek pi</para></entry></row>
<row>
<entry align="left" valign="top"><para>&piv;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;piv;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek pi, variant</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&psi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;psi;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek psi</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&rho;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rho;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek rho</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&sigma;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sigma;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek sigma</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&tau;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;tau;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek tau</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&thetas;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;thetas;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek theta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&thetav;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;thetav;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek theta, variant</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&upsi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;upsi;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek upsilon</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&xi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;xi;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek xi</para></entry></row>
<row>
<entry align="left" valign="top"><para>&zeta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;zeta;</literal></para></entry>
<entry align="left" valign="top"><para>lowercase Greek zeta</para></entry>
</row>
<row>
<entry align="left" spanname="1to2" valign="top"><para>Uppercase Greek Letters
</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Delta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Delta;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek delta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Gamma;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Gamma;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek gamma</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Lambda;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Lambda</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek lambda</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Omega;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Omega;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek omega</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Pi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Pi;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek pi</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Phi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Phi;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek phi</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Psi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Psi;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek psi</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Sigma;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Sigma;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek sigma</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Theta;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Theta;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek theta</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Upsi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Upsi;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek upsilon</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&Xi;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Xi;</literal></para></entry>
<entry align="left" valign="top"><para>uppercase Greek xi</para></entry></row>
</tbody></tgroup></table>
<table id="HRDC.ChEnt.tbl.3" frame="Topbot">
<title>General Technical Symbols</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="0.90in">
<colspec colname="col2" colwidth="1.75in">
<colspec colname="col3" colwidth="2.35in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Symbol</literal>
</para></entry><entry align="left" valign="bottom"><para><literal>Entity Name</literal></para></entry><entry align="left" valign="bottom"><para><literal>Description</literal></para></entry></row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>&aleph;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;aleph;</literal></para></entry>
<entry align="left" valign="top"><para>Hebrew letter aleph</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&and;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;and;</literal></para></entry>
<entry align="left" valign="top"><para>wedge, logical AND</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ap;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ap;</literal></para></entry>
<entry align="left" valign="top"><para>approximately equal</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&cap;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;cap;</literal></para></entry>
<entry align="left" valign="top"><para>intersection</para></entry></row>
<row>
<entry align="left" valign="top"><para>&cong;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;cong;</literal></para></entry>
<entry align="left" valign="top"><para>congruent with</para></entry></row>
<row>
<entry align="left" valign="top"><para>&cup;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;cup;</literal></para></entry>
<entry align="left" valign="top"><para>union or logical sum</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&equiv;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;equiv;</literal></para></entry>
<entry align="left" valign="top"><para>identical with</para></entry></row>
<row>
<entry align="left" valign="top"><para>&exist;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;exist;</literal></para></entry>
<entry align="left" valign="top"><para>at least one exists</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&forall;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;forall;</literal></para></entry>
<entry align="left" valign="top"><para>for all</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ge;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ge;</literal></para></entry>
<entry align="left" valign="top"><para>greater than or equal</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&infin;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;infin;</literal></para></entry>
<entry align="left" valign="top"><para>infinity</para></entry></row>
<row>
<entry align="left" valign="top"><para>&isin;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;isin;</literal></para></entry>
<entry align="left" valign="top"><para>set membership</para></entry></row>
<row>
<entry align="left" valign="top"><para>&le;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;le;</literal></para></entry>
<entry align="left" valign="top"><para>less than or equal</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ne;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ne;</literal></para></entry>
<entry align="left" valign="top"><para>not equal</para></entry></row>
<row>
<entry align="left" valign="top"><para>&notin;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;notin;</literal></para></entry>
<entry align="left" valign="top"><para>negated set membership</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&or;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;or;</literal></para></entry>
<entry align="left" valign="top"><para>Vee, logical OR</para></entry></row>
<row>
<entry align="left" valign="top"><para>&part;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;part;</literal></para></entry>
<entry align="left" valign="top"><para>partial differential</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&perp;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;perp;</literal></para></entry>
<entry align="left" valign="top"><para>perpendicular</para></entry></row>
<row>
<entry align="left" valign="top"><para>&prime;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;prime;</literal></para></entry>
<entry align="left" valign="top"><para>prime, or minute of arc</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&prop;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;prop;</literal></para></entry>
<entry align="left" valign="top"><para>proportional to</para></entry></row>
<row>
<entry align="left" valign="top"><para>&rArr;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;rArr;</literal></para></entry>
<entry align="left" valign="top"><para>right double arrow</para></entry></row>
<row>
<entry align="left" valign="top"><para>&sub;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sub;</literal></para></entry>
<entry align="left" valign="top"><para>subset; is implied by</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&sube;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sube;</literal></para></entry>
<entry align="left" valign="top"><para>subset, equals</para></entry></row>
<row>
<entry align="left" valign="top"><para>&sup;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;sup;</literal></para></entry>
<entry align="left" valign="top"><para>superset; implies</para></entry></row>
<row>
<entry align="left" valign="top"><para>&there4;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;there4;</literal></para></entry>
<entry align="left" valign="top"><para>therefore</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Prime;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Prime;</literal></para></entry>
<entry align="left" valign="top"><para>double prime, or second of an arc</para></entry>
</row></tbody></tgroup></table>
<table id="HRDC.ChEnt.tbl.4" frame="Topbot">
<title>Publishing Symbols</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="0.90in">
<colspec colname="col2" colwidth="1.75in">
<colspec colname="col3" colwidth="2.35in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Symbol</literal>
</para></entry><entry align="left" valign="bottom"><para><literal>Entity Name</literal></para></entry><entry align="left" valign="bottom"><para><literal>Description</literal></para></entry></row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>&bull;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;bull;</literal></para></entry>
<entry align="left" valign="top"><para>round bullet, filled</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&clubs;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;clubs;</literal></para></entry>
<entry align="left" valign="top"><para>clubs suit symbol</para></entry></row>
<row>
<entry align="left" valign="top"><para>&diams;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;diams;</literal></para></entry>
<entry align="left" valign="top"><para>diamonds suit symbol</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&hearts;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;hearts;</literal></para></entry>
<entry align="left" valign="top"><para>hearts suit symbol</para></entry></row>
<row>
<entry align="left" valign="top"><para>&hellip;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;hellip;</literal></para></entry>
<entry align="left" valign="top"><para>horizontal ellipsis</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&mdash;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;mdash;</literal></para></entry>
<entry align="left" valign="top"><para>em dash (long dash)</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&ndash;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ndash;</literal></para></entry>
<entry align="left" valign="top"><para>en dash (short dash)</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>&spades;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;spades;</literal></para></entry>
<entry align="left" valign="top"><para>spades suit symbol</para></entry></row>
<row>
<entry align="left" valign="top"><para>&vellip;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;vellip;</literal></para></entry>
<entry align="left" valign="top"><para>vertical ellipsis</para></entry></row>
</tbody></tgroup></table>
<table id="HRDC.ChEnt.tbl.5" frame="Topbot">
<title>Latin 1 Characters</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colname="col1" colwidth="0.90in">
<colspec colwidth="1.75in">
<colspec colname="col3" colwidth="2.35in">
<spanspec nameend="col3" namest="col1" spanname="1to3">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Symbol</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Entity Name</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Description</literal></para></entry>
</row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para>&aacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;aacute;</literal></para></entry>
<entry align="left" valign="top"><para>small a, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&acirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;acirc;</literal></para></entry>
<entry align="left" valign="top"><para>small a, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&aelig;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;aelig;</literal></para></entry>
<entry align="left" valign="top"><para>small ae diphthong</para></entry></row>
<row>
<entry align="left" valign="top"><para>&agrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;agrave;</literal></para></entry>
<entry align="left" valign="top"><para>small a, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&aring;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;aring;</literal></para></entry>
<entry align="left" valign="top"><para>small a, ring</para></entry></row>
<row>
<entry align="left" valign="top"><para>&atilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;atilde;</literal></para></entry>
<entry align="left" valign="top"><para>small a, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&auml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;auml;</literal></para></entry>
<entry align="left" valign="top"><para>small a, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ccedil;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ccedil;</literal></para></entry>
<entry align="left" valign="top"><para>small c, cedilla</para></entry></row>
<row>
<entry align="left" valign="top"><para>&eacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;eacute;</literal></para></entry>
<entry align="left" valign="top"><para>small e, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ecirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ecirc;</literal></para></entry>
<entry align="left" valign="top"><para>small e, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&egrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;egrave;</literal></para></entry>
<entry align="left" valign="top"><para>small e, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&eth;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;eth;</literal></para></entry>
<entry align="left" valign="top"><para>small eth, Icelandic</para></entry></row>
<row>
<entry align="left" valign="top"><para>&euml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;euml;</literal></para></entry>
<entry align="left" valign="top"><para>small e, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&iacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;iacute;</literal></para></entry>
<entry align="left" valign="top"><para>small i, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&icirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;icirc;</literal></para></entry>
<entry align="left" valign="top"><para>small i, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&igrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;igrave;</literal></para></entry>
<entry align="left" valign="top"><para>small i, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&iuml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;iuml;</literal></para></entry>
<entry align="left" valign="top"><para>small i, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ntilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ntilde;</literal></para></entry>
<entry align="left" valign="top"><para>small N, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&oacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;oacute;</literal></para></entry>
<entry align="left" valign="top"><para>small o, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ocirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ocirc;</literal></para></entry>
<entry align="left" valign="top"><para>small o, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ograve;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ograve;</literal></para></entry>
<entry align="left" valign="top"><para>small o, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&oslash;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;oslash;</literal></para></entry>
<entry align="left" valign="top"><para>small o, slash</para></entry></row>
<row>
<entry align="left" valign="top"><para>&otilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;otilde;</literal></para></entry>
<entry align="left" valign="top"><para>small o, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ouml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ouml;</literal></para></entry>
<entry align="left" valign="top"><para>small o, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&szlig;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;szlig;</literal></para></entry>
<entry align="left" valign="top"><para>small sharp s, German</para></entry></row>
<row>
<entry align="left" valign="top"><para>&thorn;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;thorn;</literal></para></entry>
<entry align="left" valign="top"><para>small thorn, Icelandic</para></entry></row>
<row>
<entry align="left" valign="top"><para>&uacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;uacute;</literal></para></entry>
<entry align="left" valign="top"><para>small u, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ucirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ucirc;</literal></para></entry>
<entry align="left" valign="top"><para>small u, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ugrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ugrave;</literal></para></entry>
<entry align="left" valign="top"><para>small u, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&uuml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;uuml;</literal></para></entry>
<entry align="left" valign="top"><para>small u, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&yacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;yacute;</literal></para></entry>
<entry align="left" valign="top"><para>small y, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&yuml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;yuml;</literal></para></entry>
<entry align="left" valign="top"><para>small y, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Aacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Aacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Acirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Acirc;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&AElig;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;AElig;</literal></para></entry>
<entry align="left" valign="top"><para>capital ae diphthong</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Agrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Agrave;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Aring;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Aring;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, ring</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Atilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Atilde;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Auml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Auml;</literal></para></entry>
<entry align="left" valign="top"><para>capital a, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ccedil;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ccedil;</literal></para></entry>
<entry align="left" valign="top"><para>capital c, cedilla</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Eacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Eacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital E, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ecirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ecirc;</literal></para></entry>
<entry align="left" valign="top"><para>capital E, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Egrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Egrave;</literal></para></entry>
<entry align="left" valign="top"><para>capital E, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&ETH;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;ETH;</literal></para></entry>
<entry align="left" valign="top"><para>capital Eth, Icelandic</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Euml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Euml;</literal></para></entry>
<entry align="left" valign="top"><para>capital E, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Iacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Iacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital I, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Icirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Icirc;</literal></para></entry>
<entry align="left" valign="top"><para>capital I, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Igrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Igrave;</literal></para></entry>
<entry align="left" valign="top"><para>capital I, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Iuml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Iuml;</literal></para></entry>
<entry align="left" valign="top"><para>capital I, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ntilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ntilde;</literal></para></entry>
<entry align="left" valign="top"><para>capital N, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Oacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Oacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ocirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ocirc;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ograve;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ograve;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Oslash;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Oslash;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, slash</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Otilde;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Otilde;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, tilde</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ouml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ouml;</literal></para></entry>
<entry align="left" valign="top"><para>capital O, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&THORN;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;THORN;</literal></para></entry>
<entry align="left" valign="top"><para>capital THORN, Icelandic</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Uacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Uacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital U, acute accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ucirc;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ucirc;</literal></para></entry>
<entry align="left" valign="top"><para>capital U, circumflex</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Ugrave;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Ugrave;</literal></para></entry>
<entry align="left" valign="top"><para>capital U, grave accent</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Uuml;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Uuml;</literal></para></entry>
<entry align="left" valign="top"><para>capital U, umlaut mark</para></entry></row>
<row>
<entry align="left" valign="top"><para>&Yacute;</para></entry>
<entry align="left" valign="top"><para><literal>&amp;Yacute;</literal></para></entry>
<entry align="left" valign="top"><para>capital Y, acute accent</para></entry></row>
</tbody></tgroup></table>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

246
cde/doc/en_US.UTF-8/guides/helpGuide/ch06.sgm Normal file
View File

@@ -0,0 +1,246 @@
<!-- $XConsortium: ch06.sgm /main/9 1996/08/26 10:45:30 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.CmdS.div.1">
<title id="HRDC.CmdS.mkr.1">Command Summary</title>
<para>This chapter summarizes the command-line options available when the
help commands are run manually in a terminal window.</para>
<sect1 id="HRDC.CmdS.div.2">
<title>Help System Commands</title>
<para>Desktop actions and data types provided by the Help System enable you
to compile and view run-time help files by clicking a help file icon or choosing
a menu item. However, if you want to select particular command options, you
must enter the command manually in a terminal window or create new actions.
</para>
<para>Help actions and data types are defined in two files, <filename>dthelp.dt</filename> and <filename>dtdocbook.dt</filename>, located in the
<filename>/usr/dt/appconfig/types/</filename><symbol role="Variable">lang</symbol> directory.
</para>
<para>The commands summarized here are:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="145*">
<colspec align="left" colwidth="383*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>dtDocBook</command></para></entry>
<entry align="left" valign="top"><para>Compiles DocBook source files into
a run-time file.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>dthelpview</command></para></entry>
<entry align="left" valign="top"><para>Displays a help volume, help topic,
text file, or man page.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>dthelpgen</command></para></entry>
<entry align="left" valign="top"><para>Collects help family files into a new
help volume, <filename>index.hv</filename>, which contains an entry for each
family file.</para></entry></row></tbody></tgroup></informaltable>
</sect1>
<sect1 id="HRDC.CmdS.div.3">
<title id="HRDC.CmdS.mkr.2">Processing DocBook Files (dtdocbook)</title>
<para>The DocBook software, invoked with the <command>dtdocbook</command>command,
compiles your DocBook source files into a run-time help file. You run <command>dtdocbook</command> in the directory where your <symbol role="Variable">volume</symbol><filename>.sgm</filename> source file is located.</para>
<sect2 id="HRDC.CmdS.div.4">
<title>Command Syntax</title>
<programlisting>dtdocbook [command-options] volume</programlisting>
<para>Where <symbol role="Variable">command-options</symbol> are options entered
before the <symbol role="Variable">volume</symbol> name.</para>
</sect2>
<sect2 id="HRDC.CmdS.div.5">
<title>Command Options</title>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="116*">
<colspec align="left" colwidth="412*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-c</command></para></entry>
<entry align="left" valign="top"><para>Compress an existing SDL file; assume
an input file name extension of &ldquo;<filename>.sdl</filename>&rdquo;</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>-d</command></para></entry>
<entry align="left" valign="top"><para>Decompress an existing SDL file; assume
an input file name extension of &ldquo;<filename>.sdl</filename>&rdquo;
</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-h</command></para></entry>
<entry align="left" valign="top"><para>(Help) Emit a synopsis of the <command>dtdocbook</command> command and a list of option to the standard output</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>-l</command></para></entry>
<entry align="left" valign="top"><para>Leave a log file in <filename>basename.log</filename></para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-m</command></para></entry>
<entry align="left" valign="top"><para>(Map) Add additional SDATA and/or character
mapping files</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-o</command> <filename>file</filename></para></entry>
<entry align="left" valign="top"><para>Use <filename>file</filename> as the
output file name; do not add any file name extension</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-r</command></para></entry>
<entry align="left" valign="top"><para>Remove any intermediate files and the
output file; do not complain if none exist</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-u</command></para></entry>
<entry align="left" valign="top"><para>(Uncompressed) Do not compress the
output file during translation</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-v</command></para></entry>
<entry align="left" valign="top"><para>(Verbose) Cause <command>dtdocbook</command> to generate and display parser messages during processing</para></entry>
</row></tbody></tgroup></informaltable>
<para>If the <command>-c</command> option is specified and the file is already
compressed, the file will be decompressed and recompressed. This action is
useful as a means to verify the integrity of a compressed SDL file.</para>
<para>If the <command>-d</command> is specified and the file is already decompressed,
the file will be re-parsed, all precomputations will be performed, and the
file will be re-written. This action is useful as a means to verify the integrity
of an SDL file. It is also useful for forcing a recomputation of the table
of contents, including byte offsets to individual help topics, when such recomputation
is made necessary, for example, by editing the SDL file directly.</para>
<sect3 id="HRDC.CmdS.div.7">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="HeadingAndPage"
linkend="HRDC.CrHV.mkr.2"></para>
</listitem><listitem><para><xref role="HeadingAndPage" linkend="HRDC.Inst.mkr.5">
</para>
</listitem><listitem><para><xref role="HeadingAndPage" linkend="HRDC.CrHV.mkr.6"></para>
</listitem><listitem><para><filename moreinfo="RefEntry">dtdocbook</filename>(1)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CmdS.div.8">
<title id="HRDC.CmdS.mkr.4">Displaying Help Topics (dthelpview)</title>
<para>The <command>dthelpview</command> command can be used to display a help
volume, individual help topic, text file, or man page.</para>
<sect2 id="HRDC.CmdS.div.9">
<title>Command Syntax</title>
<para>The various ways to invoke Helpview are:</para>
<itemizedlist><listitem><para><command>dthelpview -helpVolume <symbol role="Variable">volume</symbol> [ -locationId <symbol role="Variable">id</symbol> ]</command>
</para>
</listitem><listitem><para><command>dthelpview -man</command></para>
</listitem><listitem><para><command>dthelpview -manPage</command> <symbol role="Variable">man</symbol></para>
</listitem><listitem><para><command>dthelpview -file</command> <symbol role="Variable">filename</symbol></para>
</listitem></itemizedlist>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="188*">
<colspec align="left" colwidth="340*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-helpVolume</command> <symbol role="Variable">volume</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the name of the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file you want to view. A path name
is not required unless the volume is not in the current directory <emphasis>and</emphasis> the volume has not been registered.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-locationId</command> <symbol role="Variable">id</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies an ID. <command>dthelpview</command> displays the topic that contains <symbol role="Variable">id</symbol>.
If you do not specify an ID, Helpview uses <filename>_hometopic</filename>
by default.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-man</command></para></entry>
<entry align="left" valign="top"><para>Displays a dialog that prompts for
a man page to view, then displays the requested man page.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-manPage</command> <symbol role="Variable">man</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies that a particular man page
be displayed.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-file</command> <symbol role="Variable">filename</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies that a particular text file
be displayed.</para></entry></row></tbody></tgroup></informaltable>
<para>The default <symbol role="Variable">volume</symbol> and <symbol role="Variable">id</symbol> can be set in <command>dthelpview</command>'s app-defaults file,
<filename>/usr/dt/app-defaults/C/Dthelpview</filename>.</para>
<sect3 id="HRDC.CmdS.div.10">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9">
</para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.6"></para>
</listitem><listitem><para><command>dthelpview</command>(1) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CmdS.div.11">
<title id="HRDC.CmdS.mkr.5">Generating an Index Help Volume (dthelpgen)</title>
<para>The <command>dthelpgen</command> utility creates a special help volume
that enables users to display help volumes registered on their system using
the Front Panel Help Viewer. When a user initially clicks the Help Viewer
control in the Front Panel, <command>dthelpgen</command> is run automatically.
It locates help family files by searching the help search path directories
(local or networked), and then creates an index volume (<filename>index.hv</filename>) in the user's <filename>HomeDirectory/.dt/help/$DTUSERSESSION</filename>directory. Once built, the volume is updated in response to any
of these actions:</para>
<itemizedlist><listitem><para>Add, remove, or modify family files or help
volumes</para>
</listitem><listitem><para>Change the <systemitem class="environvar">LANG</systemitem> environment variable</para>
</listitem><listitem><para>Invoke the <literal>ReloadApps</literal> action
</para>
</listitem><listitem><para>Run <command>dthelpgen</command> manually in a
terminal window</para>
</listitem></itemizedlist>
<para>The index volume is displayed by clicking the Help Viewer control in
the Front Panel. Or, you can manually run <command>dthelpview</command> and
supply the index volume name as shown in this command line:</para>
<programlisting>dthelpview -h index.hv</programlisting>
<sect2 id="HRDC.CmdS.div.12">
<title>Command Syntax</title>
<programlisting>dthelpgen -dir [<symbol role="Variable">options</symbol>]
</programlisting>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="356*">
<tbody>
<row>
<entry><para><command>-dir</command></para></entry>
<entry><para>Specifies the directory in which to place the index volume and
intermediate files. This is a required parameter.</para></entry></row></tbody>
</tgroup></informaltable>
</sect2>
<sect2 id="HRDC.CmdS.div.13">
<title>Options</title>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="167*">
<colspec align="left" colwidth="361*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>-generate</command></para></entry>
<entry align="left" valign="top"><para>Specifies that a new index help volume
should be created even if the family files and help volumes on the system
have not been modified.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-file</command> <symbol role="Variable">basename</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the name of the help volume
and any intermediate files generated by <command>dthelpgen</command>. The
default name is <filename>index.hv</filename>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><command>-lang</command></para></entry>
<entry align="left" valign="top"><para>Specifies which language directories
to search for help families and help volumes. If the <command>-lang</command>
option is set, it takes precedence over the current value of the <systemitem class="environvar">LANG</systemitem> environment variable.</para></entry>
</row></tbody></tgroup><?Pub Caret></informaltable>
<note>
<para>If you run <command>dthelpgen</command> while the index volume is displayed
in a help window, you should close the window, then reopen the index volume.
</para>
</note>
<sect3 id="HRDC.CmdS.div.14">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.9"></para>
</listitem><listitem><para><command moreinfo="RefEntry">dthelpgen</command>(1)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

488
cde/doc/en_US.UTF-8/guides/helpGuide/ch07.sgm Normal file
View File

@@ -0,0 +1,488 @@
<!-- $XConsortium: ch07.sgm /main/13 1996/09/08 19:40:15 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.Sgml.div.1">
<title id="HRDC.Sgml.mkr.1">Reading the DocBook Document Type Definition</title>
<para>This chapter explains how to read the DocBook 2.2.1 Document Type Definition
(DTD) and how to use it to create fully compliant Standard Generalized Markup
Language (SGML) help files.</para>
<informaltable id="HRDC.Sgml.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'DocBook 1.3 DTD196'--><xref role="JumpText"
linkend="HRDC.Sgml.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'DTD Components196'--><xref role="JumpText"
linkend="HRDC.Sgml.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Element Declarations196'--><xref
role="JumpText" linkend="HRDC.Sgml.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Element Declaration Keywords198'--><xref
role="JumpText" linkend="HRDC.Sgml.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Attribute List Declarations199'--><xref
role="JumpText" linkend="HRDC.Sgml.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Formal Markup199'--><xref role="JumpText"
linkend="HRDC.Sgml.mkr.7"></para></entry></row></tbody></tgroup></informaltable>
<sect1 id="HRDC.Sgml.div.2">
<title>Document Type Definition</title>
<para>A <emphasis>Document Type Definition</emphasis> (DTD) defines a set
of elements used to create a structured (or hierarchical) document. The DTD
specifies the syntax for each element and governs how and where elements can
be used in a document.</para>
<sect2 id="HRDC.Sgml.div.3">
<title id="HRDC.Sgml.mkr.2">DocBook 2.1 DTD</title>
<para>The DocBook 2.2.1 DTD tag set and its associated rules are referred
to as formal markup. The DTD conforms to the Standard Generalized Markup Language
(SGML) ISO specification 8879:1986. This means that you can use formal markup
to create help files that are SGML compliant.</para>
<para>Appendix A contains the complete DTD specification. The DTD is also
available in the Developer's Toolkit. It is located in the <filename>/usr/dt/dthelp/dtdocbook/SGML</filename> directory and is named <filename>DocBook.dtd</filename>.</para>
<sect3 id="HRDC.Sgml.div.4">
<title>See Also</title>
<itemizedlist><listitem><para><filename>dtdocbookdtd(4)</filename> man page.
</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Sgml.div.5">
<title id="HRDC.Sgml.mkr.3">DTD Components</title>
<para>The DTD defines each of the DocBook elements described in previous chapters
in a technical notation. This section introduces some key terms and explains
how to read the syntax of the element notations. It does not attempt to fully
describe each section of the DTD.</para>
<sect2 id="HRDC.Sgml.div.6">
<title id="HRDC.Sgml.mkr.4">Element Declarations</title>
<para>The DocBook DTD defines each DocBook element in an <emphasis>element
declaration</emphasis>. The declaration uses a precise notation to describe
an element, its required components, and any elements it can or cannot contain.
Each element also has its attributes and the values they can take defined
in an <emphasis>attribute declaration</emphasis>, which is discussed in the
next section <xref role="SecTitleAndPageNum" linkend="HRDC.Sgml.mkr.6">.</para>
<para>Both in its element declarations, and its attribute declarations, the
DocBook DTD makes extensive use of entity references, which stand for entities
that represent groupings of elements or attributes. (In the DTD, these entity
declarations precede the element declarations and the attribute declarations.)
</para>
<para>For example, the DTD declares an entity with the reference "%commmonatts;"
to stand for the group of common attributes that so many of the DocBook elements
have: ID, Lang (language), Remap, Role, and XRefLabel. As another example,
the DTD declares an entity with the reference "%list.gp;" that stands for
ItemizedList, OrderedList, SegmentedList, VariableList, etc.</para>
<para>The syntax of an element declaration is as follows:</para>
<programlisting>&lt;!ELEMENT <symbol>element_type minimization (content model)</symbol>></programlisting>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="116*">
<colspec align="left" colwidth="412*">
<tbody>
<row>
<entry align="left" valign="top"><para><symbol>element_type</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the element name, which is
also used as the tag name. For example, the tag for the element type Title
is &lt;Title>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><symbol>minimization</symbol></para></entry>
<entry align="left" valign="top"><para>A two-character entry that indicates
whether a start or an end tag is required. The first character represents
the start tag; the second character represents the end tag. A space separates
the two characters. The letter <Literal>O</Literal> means that the tag is
optional. A <literal>-</literal> (minus sign) indicates the tag is required.
</para><para>For example, an entry like this, <literal>- -</literal>, indicates
that the element requires both start and end tags. The DTD for DocBook 2.2.1
requires both start and end tags for the great majority of its elements.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol>content model</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies a list of the required and
optional elements that the element type can contain. It defines the sequence
of elements and, if applicable, the number of occurrences that may occur.
It also may specify the elements that cannot be contained within the element
in question.</para></entry></row></tbody></tgroup></informaltable>
<para>The content model uses these notations:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="106*">
<colspec align="left" colwidth="422*">
<tbody>
<row>
<entry align="left" valign="top"><para><literal>|</literal></para></entry>
<entry align="left" valign="top"><para>A vertical bar represents &ldquo;or&rdquo;.
</para></entry></row>
<row>
<entry align="left" valign="top"><para><literal>+</literal></para></entry>
<entry align="left" valign="top"><para>A plus sign after the name of the element
means the element must appear at least once, and that it can be repeated.
</para></entry></row>
<row>
<entry align="left" valign="top"><para><literal>*</literal></para></entry>
<entry align="left" valign="top"><para>An asterisk after the name of the element
means the element can appear zero or more times.</para></entry></row>
<row>
<entry align="left" valign="top"><para><literal>?</literal></para></entry>
<entry align="left" valign="top"><para>A question mark after the name of the
element means the element can appear zero or one time.</para></entry></row>
<row>
<entry align="left" valign="top"><para>,</para></entry>
<entry align="left" valign="top"><para>A comma describes sequence, that is,
the element type before the comma must be followed by the element specified
after the comma.</para></entry></row>
<row>
<entry align="left" valign="top"><para><literal>+</literal> (<symbol>element_
type(s)</symbol>)</para></entry>
<entry align="left" valign="top"><para>The <literal>+</literal> (plus sign)
indicates that the listed element or elements enclosed within the parentheses
can be used within the element type or within any of the elements it contains.
This is called an inclusion.</para></entry></row>
<row>
<entry align="left" valign="top"><para><literal>-</literal> (<symbol>element_
type(s)</symbol>)</para></entry>
<entry align="left" valign="top"><para>A <literal>-</literal> (minus sign)
indicates that the listed element or elements enclosed within the parentheses
cannot be used within this element, or within any of the elements it contains.
This is called an exclusion.</para></entry></row></tbody></tgroup></informaltable>
<sect3 id="HRDC.Sgml.div.7">
<title>Examples</title>
<para>Each of the following examples shows an element declaration and explains
what it means.</para>
<itemizedlist><listitem><para>This declares that the Appendix element requires
both starting and ending tags. It further declares that Appendix may contain
an optional DocInfo element, followed by a required Title, and an optional
TitleAbbrev, followed by one or more of the elements referred to by the entity
reference "%sect.gp;" (namely, Sect1 and its permitted subcomponents). It
also declares that the elements referred to by the entity reference "%ubiq.gp;"
(namely, IndexTerms) can be included within an Appendix or within any of its
subcomponents.</para>
<programlisting>&lt;:!ELEMENT Appendix - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;)) +(%ubiq.gp;) >
</programlisting>
</listitem><listitem><para>This declares that the OrderedList element requires
both starting and ending tags, and that it must contain at least one ListItem
</para>
<programlisting>&lt;!ELEMENT OrderedList - - (ListItem+) ></programlisting>
</listitem><listitem><para>This declares that the ListItem element requires
both starting and ending tags, and that it must contain at least one of the
group of elements referred to by the entity reference "%component.gp;", which
includes among other things Paragraphs, Lists, and Tables.</para>
<programlisting>&lt;!ELEMENT ListItem - - ((%component.gp;)+) ></programlisting>
</listitem><listitem><para>This declares that the Sect1 element requires both
starting and ending tags. It further declares that Sect1 has a required Title
and an optional TitleAbbrev. It next declares that Sect1 can have zero or
more ToCs, LoTs, Indexes, Glossaries, and Bibliographies (which are the elements
referred to by the entity reference "%nav.gp;"). It then declares that the
Sect1 element must contain at least one of the group of elements referred
to by the entity reference "%component.gp;", which includes among other things
Paragraphs, Lists,and Tables, and that these will optionally be followed by
zero or more Sect2s or RefEntries.</para>
<programlisting>&lt;!ELEMENT Sect1 - - (Title, TitleAbbrev?, (%nav.gp;)*, (((%component.gp;)+, (RefEntry* | Sect2*)) | RefEntry+ | Sect2+), (%nav.gp;)*) +(%ubiq.gp;) >
</programlisting>
</listitem><listitem><para>This declares that the InformalTable element requires
both starting and ending tags. It further declares that InformalTable must
contain one or more Graphics or one or more TGroups (this is the meaning of
the string referred to by the entity reference "%tblcontent.gp;"). It also
declares that the InformalTable element cannot contain a Table or another
InformalTable.</para>
<programlisting>&lt;!ELEMENT InformalTable - - ((%tblcontent.gp;)) -(Table|InformalTable)>
</programlisting>
</listitem><listitem><para>This declares that the TGroup element requires
a start tag but not an end tag, and may contain the following elements in
the following order: zero or more ColSpecs, zero or more SpanSpecs, zero or
one THead, zero or one TFoot, and a required TBody.</para>
<programlisting>&lt;!ELEMENT TGroup - O (ColSpec*, SpanSpec*, THead?, TFoot?, TBody) >
</programlisting>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.Sgml.div.8">
<title id="HRDC.Sgml.mkr.5">Element Declaration Keywords</title>
<para>Some elements include a keyword in the element declaration that describes
the data content of the element. Three keywords appear in the DTD: <computeroutput>EMPTY</computeroutput>, <computeroutput>CDATA</computeroutput>, and <computeroutput>#PCDATA</computeroutput>.</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="110*">
<colspec align="left" colwidth="418*">
<tbody>
<row>
<entry align="left" valign="top"><para><computeroutput>EMPTY</computeroutput></para></entry>
<entry align="left" valign="top"><para>Specifies that the element has no data
content.</para></entry></row>
<row>
<entry align="left" valign="top"><para><computeroutput>CDATA</computeroutput></para></entry>
<entry align="left" valign="top"><para>Represents &ldquo;character data.&rdquo;
That is, the data content of the element is not recognized as markup.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><computeroutput>#PCDATA</computeroutput></para></entry>
<entry align="left" valign="top"><para>Represents &ldquo;parsed character
data.&rdquo; That is, the data content may include both text and markup characters
that the DocBook parser interprets accordingly.</para></entry></row></tbody>
</tgroup></informaltable>
</sect2>
<sect2 id="HRDC.Sgml.div.9">
<title id="HRDC.Sgml.mkr.6">Attribute List Declarations</title>
<para>An attribute list declares additional properties that further describe
an element. An attribute list declaration has the syntax:</para>
<programlisting>&lt;!ATTLIST <symbol>element_type attribute_values default_value</symbol>></programlisting>
<sect3 id="HRDC.Sgml.div.7a">
<title>Examples</title>
<para>Each of the following examples shows an aatribute list declaration and
explains what it means.</para>
<itemizedlist><listitem><para>This attribute list declaration means that the
element Para has the common attributes, and there are no default values for
them.</para>
<programlisting>&lt;!ATTLIST Para %commonatts; ></programlisting>
</listitem><listitem><para>This attribute list declaration means that the
element Sect1 has the common attributes, and also a Label attribute and a
Renderas attribute. The Label attribute take "character data" for its values,
and the default value is implied. The Renderas attribute (which can determine
how the Sect1 is displayed) can take the values Sect2, Sect3, Sect4, or Sect5.
For example, if Renderas="Sect2", the Sect1 will be displayed with the same
formatting as a Sect2.</para>
<programlisting>&lt;!ATTLIST Sect1
%commonatts;
Label CDATA #IMPLIED
Renderas (Sect2 | Sect3 | Sect4 | Sect5) #IMPLIED ></programlisting>
</listitem><listitem><para>This attribute list declaration means that the
element TFoot has the common attributes, with no default values, and also
VAlign attribute which can take the values "Top", "Middle", and "Bottom",
with "Top" as the default value.</para>
<programlisting>&lt;!ATTLIST TFoot
%commonatts;
VAlign (Top | Middle | Bottom) "Top" ></programlisting>
</listitem><listitem><para>This attribute list declaration means that the
element OrderedList has the common attributes, with no default values, and
also several other attributes.</para>
<para>The Numeration attribute determines how the ListItems in the OrderedList
will be numbered: it takes the values "Arabic" (arabic numbers), "Upperalpha"
(capital letters), "Loweralpha" (lower case letters), "Upperroman" (upper
case Roman numerals) and "Lowerroman" (lower case Roman numerals).</para>
<para>The InheritNum attribute determines whether the numeration of an OrderedList
embedded in another OrderedList will be embedded in the numeration of the
containing list (so that the items in a list embedded in item 2 of another
list might be numbered 2a, 2b, 2c,etc.) InheritNum takes the values "Inherit"
and "Ignore", with "Ignore" as the default.</para>
<para>The Continuation attributes determines whether the numeration of an
OrderedList will continue from the numeration of the preceding OrderedList,
or start anew. It takes the values "Continues" and "Restarts", with "Restarts"
as the default.</para>
<programlisting>&lt;!ATTLIST OrderedList
%commonatts;
Numeration (Arabic|Uperalpha|Loweralpha|Uperroman|Lowerroman)
#IMPLIED
InheritNum (Inherit|Ignore) Ignore
Continuation (Continues|Restarts) Restarts
></programlisting>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Sgml.div.10">
<title id="HRDC.Sgml.mkr.7">Formal Markup</title>
<para>After you have learned the basic set of elements, using a structured
editor is the best approach for creating formal markup. With a structured
editor, the author creates formal markup by choosing elements from a menu.
In response, the structured editor generates all of the tags required for
each element. In addition, it verifies that the structural framework being
created conforms to the Document Type Definition.</para>
<sect2 id="HRDC.Sgml.div.11">
<title id="HRDC.Sgml.mkr.8">Formal Markup Caveats</title>
<para>DocBook is a formal markup language. Nearly every element requires
a start and an end tag. If the start tag is <symbol>&lt;ElementName></symbol>,
the end tag will take the form <symbol>&lt;/ElementName></symbol>,with the
/(forward slash) marking it as the end tag.</para>
<para>In formal markup, each element, its component parts, and elements it
contains must be explicitly tagged. For example, here is a schematic formal
markup for a Row in a Table containing two Entries. (For ease of reading in
this and other markup examples, tags are indented. Indentation is not required
in actual markup.)</para>
<programlisting>&lt;row>
&lt;entry align="left" valign="top">
&lt;para><symbol>contents of first entry</symbol>&lt;/para>
&lt;/entry>
&lt;entry align="left"valign="top">
&lt;para><symbol>contents of second entry</symbol>&lt;/para>
&lt;/entry>
&lt;row>
</programlisting>
<para>Notice that Entry and Para, the subcomponents of the Row, each have
their own start and end tags.</para>
</sect2>
<sect2 id="HRDC.Sgml.div.13">
<title id="HRDC.Sgml.mkr.9">Explicit Hierarchy of Elements</title>
<para>Each element declaration in the DTD contributes to a set of rules that
governs how and where elements can be used. Because elements contain other
elements, which may contain other elements, a document is a hierarchy of
elements. At the top level, the Part element is the container for every other
element in the help volume.</para>
<para>To decide what markup is necessary to create a help topic, you need
to become familiar with the rules that govern the DocBook markup laguage.
</para>
<para>One way to learn the markup language would be to study the element declarations
for the components you need to use. For example, suppose you want to create
a chapter. First, look at the declaration for the Chapter element listed below.
</para>
<programlisting>&lt;!ELEMENT Chapter - - (DocInfo?, Title, TitleAbbrev?, (%sect1.gp;), (Index |
Glossary | Bibliography)*) +(%ubiq.gp;) ></programlisting>
<para>This tells you a Chapter may have a DocInfo component. So next you look
at the declaration for DocInfo, to see how it is constructed.</para>
<programlisting>&lt;!ELEMENT DocInfo - - (Title, TitleAbbrev?, Subtitle?, AuthorGroup+, Abstract*, RevHistory?, LegalNotice*) -(%ubiq.gp;) >
</programlisting>
<para>This tells you that a DocInfo requires at least a Title and one or more
AuthorGroups, and may optionally contain various other elements. So next
you would have check into the declarations for the Title element and the AuthorGroup
element, to see how they are constructed.</para>
<programlisting>&lt;!ELEMENT Title - - ((%inlinechar.gp;)+) >
&lt;!ELEMENT AuthorGroup - - ((Author | Editor | Collab | CorpAuthor |
OtherCredit)+) >
</programlisting>
<para>By continuing along in this fashion until you have investigated all
the subcomponents of a Chapter, and all the subcomponents of the subcomponents,
down to the innermost nested element, and mastered how they work, you could
learn how to construct a Chapter.</para>
<para>Fortunately, however, using a structured editor minimizes what an author
needs to know about the DTD and the syntx of the markup tags. The structured
editor application &ldquo;reads&rdquo; the DTD and creates each element's
required tags, many of which are intermediate structural tags.</para>
<sect3 id="HRDC.Sgml.div.14">
<title>Example</title>
<para>This formal markup sample is an excerpt from the desktop Text Editor
help volume. To view the corresponding online information, choose the Help
Viewer in the Front Panel. Select Common Desktop Environment and then choose
Text Editor Help from the listed volumes. In the Text Editor volume, choose
Text Editor Tasks and then To Open an Existing Document.</para>
<para>Indentation and extra white space is used in this example to make it
easier to read the text and corresponding element tags. Remember that using
indentation and extra white space is not necessary in actual markup.</para>
<programlisting>&lt;sect2 id=&ldquo;TOOPENANEXISTINGDOCUMENT&rdquo;>
&lt;title>To Open an Existing Document&lt;/title>
&lt;para>You can use Text Editor or File Manager to open an existing document.&lt;/para>
&lt;IndexTerm>&lt;primary>document &lt;secondary>opening&lt;/secondary>
&lt;/primary>&lt;/IndexTerm>
&lt;IndexTerm>&lt;primary>opening
&lt;secondary>existing document&lt;/secondary>
&lt;/primary>&lt;/IndexTerm>
&lt;para>To open an existing document from the Text Editor:&lt;/para>
&lt;OrderedList>
&lt;ListItem>
&lt;para> Choose Open from the File menu.&lt;/para>
&lt;para> The Open a File dialog box lists files and folders on your system. You can browse the documents listed, or change to a new folder to locate other files on your system.&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para> Select the document you want to open in the Files list or type the file name in the Open a File field. &lt;/para>
&lt;para>&lt;emphasis>Or,&lt;/emphasis> if the document is not in the current folder, first change to the folder that contains your document. Then choose a name in the Folders list or type the path name of the folder you wish to change to in the Enter path or folder name field.&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para> Press Return or click OK.&lt;/para>
&lt;/ListItem>
&lt;/OrderedList>
&lt;graphic id="some-graphic-id" entityref="some-graphic-entity">&lt;/graphic>
&lt;para>To open an existing document from the File Manager:&lt;/para>
&lt;IndexTerm>&lt;primary>opening
&lt;secondary>document from File Manager&lt;/secondary>
&lt;/primary>&lt;/IndexTerm>
&lt;IndexTerm>&lt;primary>document
&lt;secondary>opening from File Manager&lt;/secondary>
&lt;/primary>&lt;/IndexTerm>
&lt;IndexTerm>&lt;primary>File Manager
&lt;secondary>opening documents&lt;/secondary>
&lt;/primary>&lt;/IndexTerm>
&lt;OrderedList>
&lt;ListItem>
&lt;para>Display the document's file icon in a File Manager Window.&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para> Do <emphasis>one</emphasis> of the following: &lt;/para>
&lt;InformalList>
&lt;ListItem>
&lt;para>Double-click the document's file icon.&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>Select the document, then choose Open from the Selected menu.&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>Drag the document to the Text Editor's control in the Front Panel.&lt;/para>
&lt;/ListItem>
&lt;/InformalList>
&lt;/ListItem>
&lt;/OrderedList>
&lt;sect3>
&lt;title>See Also&lt;/title>
&lt;InformalList>
&lt;ListItem>
&lt;para>&lt;xref linkend="some-sect-id" endterm="some-sects-title-id">&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>&lt;xref linkend="another-sect-id" endterm="another-sects-title-id">&lt;/para>
&lt;/ListItem>
&lt;ListItem>
&lt;para>&lt;xref linkend="some-other-sect-id" endterm="some-other-sects-title-id">&lt;/para>
&lt;/ListItem>
&lt;/InformalList>
&lt;sect3>
&lt;sect2>
</programlisting>
</sect3>
</sect2>
<sect2 id="HRDC.Sgml.div.15">
<title id="HRDC.Sgml.mkr.10">File Entity Declarations</title>
<para>To declare a file entity in formal markup, use this syntax:</para>
<programlisting>&lt;!entity <symbol>entityname</symbol> SYSTEM " <symbol>filename</symbol>"></programlisting>
<para>Where <symbol>entityname</symbol>is the name of the entity and <symbol>filename</symbol> is the name of the file. The keyword <computeroutput>SYSTEM</computeroutput> is required.</para>
<sect3 id="HRDC.Sgml.div.16">
<title>Example</title>
<para>Here are the entity declarations for a help volume that consists of
three text files and contains a graphic image.</para>
<programlisting>
&lt;!entity <symbol>MetaInformation</symbol> SYSTEM "<symbol>metainfo</symbol>">
&lt;!entity <symbol>BasicTasks</symbol> SYSTEM "<symbol>basics</symbol>">
&lt;!entity <symbol>AdvancedFeatures</symbol> SYSTEM "<symbol>advanced</symbol>">
&lt;!entity <symbol>process_diagram</symbol> SYSTEM "<symbol>process.tif</symbol>">
</programlisting>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

293
cde/doc/en_US.UTF-8/guides/helpGuide/ch08.sgm Normal file
View File

@@ -0,0 +1,293 @@
<!-- $XConsortium: ch08.sgm /main/12 1996/09/08 19:40:25 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.CrDia.div.1">
<title id="HRDC.CrDia.mkr.1">Creating and Managing Help Dialog Boxes</title>
<para>This chapter describes the Help dialog widgets and how to create them.
</para>
<informaltable id="HRDC.CrDia.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help Dialog Boxes207'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'General Help Dialog208'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Create a General Help Dialog209'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Quick Help Dialog211'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Create a Quick Help Dialog211'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Summary of Application Program Interface214'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.8"></para></entry></row></tbody></tgroup>
</informaltable>
<sect1 id="HRDC.CrDia.div.2">
<title id="HRDC.CrDia.mkr.2">Help Dialog Boxes</title>
<indexterm><primary>creating</primary><secondary>help dialog boxes</secondary>
</indexterm><indexterm><primary>managing help dialog boxes</primary></indexterm><indexterm><primary>dialog boxes</primary><secondary>creating and managing</secondary></indexterm><indexterm><primary>dialog boxes</primary><secondary>quick help</secondary></indexterm><indexterm><primary>dialog boxes</primary>
<secondary>general help</secondary></indexterm><indexterm><primary>general
help dialog box</primary><secondary>features</secondary></indexterm>
<para>For application programmers, the Help System provides a programming
library that adds help dialog boxes to any Motif application. The library
provides two types of help dialog boxes:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>General help dialogs</emphasis> have a menu bar, a topic tree, and a help topic display area.
The topic tree lists the help volume's topics and subtopics. Users use the
topic tree to select topics to view, to browse available topics, and to locate
where they are in the help volume.</para>
</listitem><listitem><para><emphasis>Quick help dialogs</emphasis> contain
a topic display area and one or more dialog buttons at the bottom.</para>
</listitem></itemizedlist>
<sect2 id="HRDC.CrDia.div.3">
<title>Standard Xt Paradigm<indexterm><primary>widget classes</primary>
</indexterm><indexterm><primary>class, dialog widgets</primary></indexterm></title>
<para><indexterm><primary>widget resources</primary></indexterm><indexterm>
<primary>resources</primary><secondary>help dialog boxes</secondary></indexterm>In
terms of programming, you interact with the help dialogs the same as you
do with any other Motif widgets in your applications. The two types of
help dialog boxes are defined as two new widget classes: <classname>DtHelpDialog</classname> and <classname>DtHelpQuickDialog</classname>.</para>
<para>Nearly every attribute of the help windows&mdash;including the volume
name and topic ID&mdash;are manipulated as widget resources. For instance,
to display a new topic, you just execute an <function>XtSetValues()</function>
call to set the <systemitem class="resource">DtNhelpVolume</systemitem>, <systemitem class="resource">DtNlocationId</systemitem>, and <systemitem class="resource">DtNhelpType</systemitem> resources. For more information, refer to <!--Original
XRef content: '&ldquo;Displaying Help Topics&rdquo;
on page&numsp;216'--><xref role="SecTitleAndPageNum" linkend="HRDC.HReq.mkr.3">.
</para>
<note>
<para>Integrating the Help System into an application requires a working
knowledge of the C programming language, the Motif programmer's toolkit,
and the Xt Intrinsics toolkit.</para>
</note>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.4">
<title id="HRDC.CrDia.mkr.3">General Help Dialog</title>
<para>A general help dialog has two display areas: the topic tree and topic
display area. The topic tree provides a scrollable list of help topics. The
home topic title is always the first item. When a user chooses a title, an
arrow (&rarr;) marks the title and its help information is displayed in the topic
display area. <!--Original XRef content:
'Figure&numsp;9&hyphen;1
on page&numsp;209'--><xref role="CodeOrFigOrTabAndPNum" linkend="hrdc.crdia.mkr.4">
shows the topic tree and topic display area of a general help window. The
current topic, &ldquo;To select a palette&rdquo;, is displayed.</para>
<para>The general help dialog includes three dialog buttons: Backtrack, History,
and Index. These commands are also available in the Help menus. For an overview
of the Help dialogs and the graphical user interface, refer to the section,
<!--Original XRef content: '&ldquo;Help
User Interface&rdquo; on page&numsp;5'--><xref role="SecTitleAndPageNum"
linkend="HRDC.Intro.mkr.7">.</para>
<para><indexterm><primary>general help dialog box</primary><secondary>features</secondary></indexterm><indexterm><primary>general help dialog box</primary>
<secondary>dialog buttons</secondary></indexterm><indexterm><primary>dialog
boxes</primary><secondary>general help</secondary></indexterm></para>
<figure>
<title id="HRDC.CrDia.mkr.4">General help dialog</title>
<graphic id="HRDC.CrDia.grph.1" entityref="HRDC.CrDia.fig.1"></graphic>
</figure>
<sect2 id="HRDC.CrDia.div.5" role="Procedure">
<title id="HRDC.CrDia.mkr.5">To Create a General Help Dialog<indexterm><primary>creating</primary><secondary>general help dialog box</secondary></indexterm><indexterm>
<primary>general help dialog box</primary><secondary>creating</secondary>
</indexterm><indexterm><primary>dialog boxes</primary><secondary>creating
general help</secondary></indexterm></title>
<orderedlist><listitem><para>Include the appropriate header files:</para>
<programlisting>#include &lt;Help.h>
#include &lt;HelpDialog.h></programlisting>
</listitem><listitem><para>Create an instance of the general help dialog widget:
</para>
<para>Use the <function moreinfo="RefEntry">DtCreateHelpDialog()</function>
convenience function.</para>
<para><emphasis>Or,</emphasis> use the <function moreinfo="RefEntry">XtCreateManagedWidget()</function> function.</para>
</listitem><listitem><para>Add a callback for handling hyperlink events that
occur within the dialog. (For more information, see <xref role="SecTitleAndPageNum"
linkend="HRDC.DiaEv.mkr.3">.)</para>
</listitem><listitem><para>Add a <emphasis>close callback</emphasis> for handling
the Close command.</para>
</listitem></orderedlist>
<sect3 id="HRDC.CrDia.div.6">
<title>Example</title>
<para>The following code segment creates a general help dialog (as a child
of <symbol role="Variable">parent</symbol>) using the convenience function.
The dialog is left unmanaged&mdash;presumably it is managed elsewhere in the
application when a help request is made.</para>
<programlisting>Widget mainHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP_TYPE_TOPIC"); ac++;
mainHelpDialog =
DtCreateHelpDialog (parent, "mainHelpDialog", al, ac);</programlisting>
<para>The following two calls add the hyperlink and close callbacks to the
dialog. Presumably, the functions <function>HyperlinkCB()</function> and <function>CloseHelpCB()</function> are declared elsewhere in the application.</para>
<programlisting>XtAddCallback (mainHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (mainHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);</programlisting>
</sect3>
<sect3 id="HRDC.CrDia.div.7">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.H4Hlp.mkr.1"></para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.DiaEv.mkr.7">
</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtCreateHelpDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpDialog</filename>(3)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.8">
<title id="HRDC.CrDia.mkr.6">Quick Help Dialog</title>
<para><indexterm><primary>quick help dialog box</primary><secondary>buttons</secondary></indexterm>The quick help dialog box is designed to help you
meet the primary objective of online help: <emphasis>Get the user back on
task as quickly and successfully as possible.</emphasis> This simple user
interface helps keep the user focused on the information. The information
should be useful enough that the user dismisses the dialog after reading it
and continues working.</para>
<figure>
<title>Quick help dialog with four standard buttons</title>
<graphic id="HRDC.CrDia.grph.2" entityref="HRDC.CrDia.fig.2"></graphic>
</figure>
<para>The quick help dialog has five buttons, four of which are managed. The
remaining dialog button is configurable, so this button can be used for anything.
However, its intended purpose is to provide a path to more help in one of
these two ways:</para>
<itemizedlist><listitem><para>Let the user ask for more detailed information.
In this case, the default button label (More) is appropriate. This is called <emphasis>progressive disclosure</emphasis>.</para>
</listitem><listitem><para>Let the user open a general help dialog for general
browsing of the application's help volume. In this case, <literal>Browse&hellip;</literal> is the most appropriate button label.</para>
</listitem></itemizedlist>
<para>The Developer's toolkit includes a convenience function, <function>DtHelpQuickDialogGetChild()</function>, for determining the widget ID for
any of the quick help dialog buttons.</para>
<sect2 id="HRDC.CrDia.div.9" role="Procedure">
<title id="HRDC.CrDia.mkr.7">To Create a Quick Help Dialog</title>
<orderedlist><listitem><para>Include the appropriate header files:</para>
<programlisting>#include &lt;Help.h>
#include &lt;HelpQuickD.h></programlisting>
</listitem><listitem><para>Create an instance of the quick help dialog widget:
</para>
<itemizedlist><listitem><para>Use the <function moreinfo="refentry">DtCreateHelpQuickDialog()</function> convenience function.</para>
</listitem><listitem><para><emphasis>Or,</emphasis> use the <function moreinfo="refentry">
XtCreateManagedWidget()</function> function.</para>
</listitem></itemizedlist>
</listitem><listitem><para>Add a callback for handling hyperlink events that
occur within the dialog. (For more information, see <xref role="SecTitleAndPageNum"
linkend="HRDC.DiaEv.mkr.3">.)</para>
</listitem><listitem><para>Add a <emphasis>close callback</emphasis> for handling
the OK button.</para>
</listitem><listitem><para>Configure the dialog buttons that you want to use:
</para>
<itemizedlist><listitem><para>If you intend to use the application-configured
button, manage it and add an activate callback.</para>
</listitem><listitem><para>If you want to disallow printing, unmanage the
Print button.</para>
</listitem><listitem><para>Manage the Help button and add a <emphasis>help
callback</emphasis> to the dialog to allow the user to get &ldquo;help on
help.&rdquo;</para>
</listitem></itemizedlist>
</listitem></orderedlist>
<sect3 id="HRDC.CrDia.div.10">
<title>Example</title>
<para>The following code segment creates a quick help dialog (as a child of <symbol>parent</symbol>) using the convenience function. The dialog is left unmanaged;
presumably, it is managed elsewhere in the application when a help request
is made. In this example, the application-configured button is enabled and
used to request more help.</para>
<programlisting>Widget quickHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP;_TYPE_TOPIC"); ac++;
quickHelpDialog =
DtCreateHelpQuickDialog (<symbol>parent</symbol>, "quickHelpDialog", al, ac);
</programlisting>
<para>The following two calls add the hyperlink and close callbacks to the
dialog. Presumably, the functions <function>HyperlinkCB()</function> and <function>CloseHelpCB()</function> are declared elsewhere in the application.</para>
<programlisting>XtAddCallback (quickHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (quickHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);
</programlisting>
<para>Here, the application-configured button is managed and assigned an activate
callback that invokes the application's <function>MoreHelpCB()</function>
function.</para>
<programlisting>moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_MORE_BUTTON);
XtManageChild (moreButton);
XtAddCallback (moreButton, XmNactivateCallback,
MoreHelpCB, (XtPointer)NULL);
</programlisting>
<para>To provide &ldquo;help on help,&rdquo; the dialog's Help button is managed
and a help callback is added to the dialog.</para>
<programlisting>helpButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_HELP_BUTTON);
XtManageChild (helpButton);
XtAddCallback (quickHelpDialog,DtNhelpCallback,
HelpRequestCB, USING_HELP);
</programlisting>
<para>Like other Motif dialogs, when you add a help callback to a quick
help dialog, it is used by both the F1 key and the Help button.</para>
</sect3>
<sect3 id="HRDC.CrDia.div.11">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.DiaEv.mkr.7"></para>
</listitem><listitem><para><xref role="ChapNumAndTitle" linkend="HRDC.H4Hlp.mkr.1"></para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtCreateHelpQuickDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpQuickDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpQuickDialogGetChild</filename>(3) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.12">
<title id="HRDC.CrDia.mkr.8">Summary of Application Program Interface</title>
<para>Related man pages for the Help System are:</para>
<itemizedlist><listitem><para>Functions for creating and working with dialogs:
</para>
<itemizedlist><listitem><para><filename>DtHelp(5)</filename></para>
</listitem><listitem><para><filename>DtHelpDialog(5)</filename></para>
</listitem><listitem><para><filename>DtHelpQuickD(5)</filename></para>
</listitem><listitem><para><function>DtCreateHelpDialog()</function></para>
</listitem><listitem><para><function>DtCreateHelpQUickDialog()</function></para>
</listitem><listitem><para><function>DtHelpQuickDialogGetChild()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Function for implementing item help mode:</para>
<itemizedlist><listitem><para><function>DtHelpReturnSelectedWidgetId()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Function for specifying the message catalog for
the Help library:</para>
<itemizedlist><listitem><para><function>DtHelpSetCatalogName()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Applications and actions for creating and viewing
a help volume:</para>
<itemizedlist><listitem><para><filename>dtdocbook</filename>(1)</para>
</listitem><listitem><para><filename>dthelpview</filename>(1)</para>
</listitem><listitem><para><filename>dthelpgen</filename>(1)</para>
</listitem><listitem><para><filename>dthelpaction(5)</filename></para>
</listitem><listitem><para><filename>dtmanaction(5)</filename></para>
</listitem></itemizedlist>
</listitem><listitem><para>Document Type Definitions:</para>
<itemizedlist><listitem><para><filename>dtdocbookdtd(4)</filename></para>
</listitem><listitem><para><filename>dtsdldtd(4)</filename></para>
</listitem></itemizedlist>
</listitem><?Pub Caret1></itemizedlist>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

579
cde/doc/en_US.UTF-8/guides/helpGuide/ch09.sgm Normal file
View File

@@ -0,0 +1,579 @@
<!-- $XConsortium: ch09.sgm /main/10 1996/09/08 19:40:34 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.HReq.div.1">
<title id="HRDC.HReq.mkr.1">Responding to Help Requests</title>
<para>This chapter explains how to display different types of help information
by setting Help Dialog widget resources.</para>
<informaltable id="HRDC.HReq.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Requesting Help215'--><xref role="JumpText"
linkend="HRDC.HReq.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Displaying Help Topics216'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a Help Topic217'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a String of Text218'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a Text File219'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display a Man Page220'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.8"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Enabling the Help Key (F1)220'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.9"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Providing a Help Menu224'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.11"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Supporting Item Help Mode225'--><xref
role="JumpText" linkend="HRDC.HReq.mkr.12"></para></entry></row></tbody></tgroup>
</informaltable>
<sect1 id="HRDC.HReq.div.2">
<title id="HRDC.HReq.mkr.2">Requesting Help</title>
<indexterm><primary>responding to</primary><secondary>help requests</secondary>
</indexterm><indexterm><primary>requests, responding to help</primary></indexterm>
<para>When a user requests help while using your application, it is the application's
responsibility to determine what help topic should be displayed.</para>
<sect2 id="HRDC.HReq.div.3">
<title>Context Sensitivity</title>
<para>Some help requests amount to an explicit request for specific information,
such as help on &ldquo;version&rdquo; (which usually displays the copyright
topic). Other help requests, however, may require some degree of context sensitivity.
That is, some processing might be needed to determine the appropriate help
topic based on the user's current context within the application.</para>
<para>For instance, your application might test the status of certain modes
or settings to determine the appropriate help topic. Or, it might test the
value of an input field and provide detailed help if the value is not valid,
and general help if the value is valid.</para>
</sect2>
<sect2 id="HRDC.HReq.div.4">
<title>Entry Points</title>
<para>An <emphasis>entry point</emphasis> is a specific location within a
help volume&mdash;usually the beginning of a topic&mdash;that can be directly
accessed by requesting help within the application.</para>
<para>From the author's point of view, entry points are established by assigning
IDs at the appropriate places within the help volume. From the programmer's
point of view, entry points are created by enabling the user to request help
and using the appropriate ID when a particular request is made.</para>
<para>There are four general ways for users to request help:</para>
<itemizedlist remap="Bullet1"><listitem><para>Pressing the <emphasis>help
key</emphasis> (which is F1 on most keyboards)</para>
</listitem><listitem><para>Clicking the Help button in a dialog box</para>
</listitem><listitem><para>Choosing a command from the application's Help
menu</para>
</listitem><listitem><para>Choosing On Item help</para>
</listitem></itemizedlist>
</sect2>
</sect1>
<sect1 id="HRDC.HReq.div.5">
<title id="HRDC.HReq.mkr.3">Displaying Help Topics</title>
<para>When a help request is made, the application determines what help topic
to display. It then creates (if necessary) and manages a help dialog, and
sets the appropriate resources to display a help topic.</para>
<para>Most requests display help topics that are part of the application's
help volume, but the Help System's help dialogs are also capable of displaying
man pages, text files, and simple text strings.</para>
<para id="HRDC.HReq.mkr.4">The Help System's help dialogs are based exclusively
on Xt Intrinsics and Motif programming, so you change the values within
a help dialog just like any other widget: by setting resources.</para>
<para>The <systemitem class="resource">DtNhelpType</systemitem> resource determines
what type of information is displayed. It can be set to any of these values:
</para>
<itemizedlist remap="Bullet1"><listitem><para><systemitem class="constant">DtHELP_TYPE_TOPIC</systemitem> for displaying normal help topics that are
part of a help volume. The volume is specified by setting the <systemitem class="resource">DtNhelpVolume</systemitem> resource; the topic is specified
by setting <systemitem class="resource">DtNLocationId</systemitem> resource.
</para>
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_STRING</systemitem> for displaying a string supplied by the application. Automatic
word wrap is disabled, so line breaks are observed as specified in the string.
The string is specified by setting the <systemitem class="resource">DtNstringData</systemitem> resource.</para>
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_DYNAMIC_STRING</systemitem> for displaying a string supplied by the application, using word
wrap to format the text. Line breaks within the string are used to separate
paragraphs. The string is specified by setting the <systemitem class="resource">DtNstringData</systemitem> resource.</para>
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_FILE</systemitem>
for displaying a text file. The name of the file to be displayed is specified
by setting the <systemitem class="resource">DtNhelpFile</systemitem> resource.
</para>
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_MAN_PAGE</systemitem> for displaying a manual reference page (man page) in a help
dialog. The man page to be displayed is specified by setting the <systemitem class="resource">DtNmanPage</systemitem> resource.</para>
</listitem></itemizedlist>
<para>These values are defined in the <filename>Help.h</filename> file.</para>
<sect2 id="HRDC.HReq.div.6">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
linkend="HRDC.CrDia.mkr.1"></para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.HReq.div.7" role="Procedure">
<title id="HRDC.HReq.mkr.5">To Display a Help Topic</title>
<orderedlist><listitem><para>Create a help dialog.</para>
</listitem><listitem><para>Set the following resources for the help dialog:
</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="164*">
<colspec align="left" colwidth="364*">
<tbody>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_TOPIC</systemitem>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpVolume</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to the volume name for your application.
</para></entry></row>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNlocationId</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to the topic ID that you want to
display.</para></entry></row></tbody></tgroup></informaltable>
<para>You can also set other values for the dialog, such as its size and title.
</para>
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
</listitem></orderedlist>
<sect3 id="HRDC.HReq.div.8">
<title>Example</title>
<para>This program segment displays a topic with the ID <symbol>getting-started</symbol> in the volume <filename>MyVolume</filename>.</para>
<programlisting>ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++;
XtSetArg (al[ac], DtNhelpVolume, &ldquo;MyVolume&rdquo;); ac++;
XtSetArg (al[ac], DtNlocationId, &ldquo;getting-started&rdquo;); ac++;
XtSetArg (al[ac], DtNcolumns, 40); ac++;
XtSetArg (al[ac], DtNrows, 12); ac++;
XtSetValues (helpDialog, al, ac);
XtManageChild (helpDialog);</programlisting>
<para>If the help volume <filename>MyVolume</filename> is not registered,
then a complete path to the <filename>MyVolume.sdl</filename> file is required
for the value of <systemitem class="resource">DtNhelpVolume</systemitem>.
</para>
</sect3>
</sect2>
<sect2 id="HRDC.HReq.div.9" role="Procedure">
<title id="HRDC.HReq.mkr.6">To Display a String of Text</title>
<orderedlist><listitem><para>Create a quick help dialog.</para>
<para>You can use a general help dialog to display string data, but this isn't
recommended because most of its features do not apply to string data.</para>
</listitem><listitem><para>Set the following resources for the help dialog:
</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="177*">
<colspec align="left" colwidth="351*">
<tbody>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_DYNAMIC_STRING</systemitem> (if you want word wrap enabled) or <systemitem class="constant">DtHELP_TYPE_STRING</systemitem> (if you want the line breaks
within the string to be maintained)</para></entry></row>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNstringData</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to the string you want to display.
A copy of the string is kept internally, so you need not maintain your copy
of it.</para></entry></row></tbody></tgroup></informaltable>
<para>You can also set other values for the dialog, such as its size and title.
</para>
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
</listitem></orderedlist>
<sect3 id="HRDC.HReq.div.10">
<title>Example</title>
<para>This program segment displays a string stored in the variable <symbol role="Variable">descriptionString</symbol>.</para>
<programlisting>ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_DYNAMIC_STRING); ac++;
XtSetArg (al[ac], DtNstringData, (char *)descriptionString); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog);</programlisting>
<para>If the string is no longer needed within the application, the memory
can be freed, because the help dialog makes its own copy of the data.</para>
<programlisting>XtFree (descriptionString);</programlisting>
</sect3>
</sect2>
<sect2 id="HRDC.HReq.div.11" role="Procedure">
<title id="HRDC.HReq.mkr.7">To Display a Text File</title>
<orderedlist><listitem><para>Create a quick help dialog or retrieve one from
your dialog cache.</para>
<para>You can use a general help dialog to display a text file, but this isn't
recommended because most of its features are useful only for standard help
topics.</para>
</listitem><listitem><para>Set the following resources for the help dialog:
</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="159*">
<colspec align="left" colwidth="369*">
<tbody>
<row>
<entry align="left" valign="top"><para><systemitem class="prompt">DtNhelpType</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_FILE</systemitem>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><systemitem class="prompt">DtNhelpFile</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to the file name you want to display.
If the file is not in the application's current directory, provide a path
to the file.</para></entry></row></tbody></tgroup></informaltable>
<para>You can also set other values for the dialog, such as its size and title.
In particular, you might want to set the width to 80 columns, which is the
standard width for text files.</para>
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
</listitem></orderedlist>
<sect3 id="HRDC.HReq.div.12">
<title>Example</title>
<para>The following program segment displays a file named <filename>/tmp/printer.list</filename>. It also sets the size of the dialog to better suit a text file.
</para>
<programlisting>ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_FILE); ac++;
XtSetArg (al[ac], DtNhelpFile, &ldquo;/tmp/printer.list&rdquo;); ac++;
XtSetArg (al[ac], DtNcolumns, 80); ac++;
XtSetArg (al[ac], DtNrows, 20); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog);</programlisting>
</sect3>
</sect2>
<sect2 id="HRDC.HReq.div.13" role="Procedure">
<title id="HRDC.HReq.mkr.8">To Display a Man Page</title>
<indexterm><primary>displaying</primary><secondary>man page</secondary></indexterm>
<indexterm><primary>man page</primary><secondary>displaying</secondary></indexterm>
<indexterm><primary>&lt;Filename | Command>DtHELP_TYPE_MAN_PAGE &lt;Default Para Font></primary></indexterm>
<orderedlist><listitem><para>Create a quick help dialog.</para>
<para>You can use a general help dialog to display a man page, but this isn't
recommended because most of its features are useful only with standard help
topics.</para>
</listitem><listitem><para>Set the following resources for the help dialog:
</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="159*">
<colspec align="left" colwidth="369*">
<tbody>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_MAN_PAGE</systemitem>.</para></entry></row>
<row>
<entry align="left" valign="top"><para><systemitem class="resource">DtNmanPage</systemitem></para></entry>
<entry align="left" valign="top"><para>Set to the name of the man page. The
value of this resource is passed directly to the system <command>man</command>
command. So, to specify a particular section of a man page, precede the man
page name by a section number, just as you would if you were typing the <command>man</command> command conventionally.</para></entry></row></tbody></tgroup>
</informaltable>
<para>You can also set other values for the dialog, such as its size and title.
</para>
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
</listitem></orderedlist>
<sect3 id="HRDC.HReq.div.14">
<title>Example</title>
<para>The following program segment displays the man page for the <command>grep</command> command. It also sets the size of the dialog to better suit
a man page.</para>
<programlisting>ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_MAN_PAGE); ac++;
XtSetArg (al[ac], DtNmanPage, &ldquo;grep&rdquo;); ac++;
XtSetArg (al[ac], DtNcolumns, 80); ac++;
XtSetArg (al[ac], DtNrows, 20); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog);</programlisting>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.HReq.div.15">
<title id="HRDC.HReq.mkr.9">Enabling the Help Key (F1)</title>
<indexterm><primary>F1 (help key)</primary></indexterm><indexterm><primary>key, enabling help (F1)</primary></indexterm><indexterm><primary>help key</primary></indexterm>
<para>The <emphasis>help key</emphasis> mechanism is a feature built into
all Motif manager widgets and primitive widgets. The help key is enabled
by adding a <emphasis>help callback</emphasis> to the widget where you want
the help key active.</para>
<para>Within your application, you should add a help callback to each widget
where you want a unique entry point into help. The help callback mechanism
automatically &ldquo;walks&rdquo; up the widget hierarchy (up to the shell
widget) until it finds a widget with a help callback, then invokes that callback.
</para>
<para>If you add a help callback to a manager widget, when the help key is
pressed for any of its children, the manager's help callback is invoked (unless
the child widget has a help callback of its own).</para>
<sect2 id="HRDC.HReq.div.16" role="Procedure">
<title id="HRDC.HReq.mkr.10">To Add a Help Callback</title>
<para>Use the <function>XtAddCallback()</function> function as follows:</para>
<programlisting>XtAddCallback (
Widget widget,
String DtNhelpCallback,
XtCallbackProc HelpRequestCB,
XtPointer clientData );
</programlisting>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="170*">
<colspec align="left" colwidth="358*">
<tbody>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">widget</symbol></para></entry>
<entry align="left" valign="top"><para>The widget where you want to activate
the help key.</para></entry></row>
<row>
<entry align="left" valign="top"><para><function role="Variable">HelpRequestCB()</function></para></entry>
<entry align="left" valign="top"><para>The function in your application that
handles the help request when the user presses the help key.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">clientData</symbol></para></entry>
<entry align="left" valign="top"><para>The data you want passed to the <function>HelpRequestCB()</function>function. Typically, this data identifies the topic
to be displayed.</para></entry></row></tbody></tgroup></informaltable>
<para>When the user presses the help key, the help callback is invoked for
the widget with the current keyboard focus. If that widget does not have a
help callback, the help callback for its nearest ancestor that does have a
help callback is invoked.</para>
<para>If no help callbacks are found, nothing happens. Therefore, it is recommended
that you add a help callback to each shell in your application. This ensures
that no user requests for help are lost.</para>
<para>Adding a help callback to a dialog shell automatically enables the Help
button on the dialog to invoke the help callback.</para>
</sect2>
<sect2 id="HRDC.HReq.div.17">
<title>Importance of Client Data</title>
<para>Specifying a unique value for <symbol role="Variable">clientData</symbol>
in each help callback you add saves you the trouble of writing a separate
function to process each help callback. Your application can have a single
callback procedure to process all help requests (see <xref role="SecTitleAndPageNum"
linkend="HRDC.HReq.mkr.10">). Within the callback procedure, use the <symbol role="Variable">clientData</symbol> to identify where the user requested help.
That is, each time you add a help callback, you should provide a unique value
for <symbol role="Variable">clientData</symbol>.</para>
<sect3 id="HRDC.HReq.div.18">
<title>Example</title>
<para>The following example demonstrates one way to associate IDs with entry
points. A <filename>HelpEntryIds.h</filename> file is used to define a unique
integer for each <symbol role="Variable">clientData</symbol> value for each
help callback. Also defined are two ID strings for each widget: one for normal
F1 help, the other for item help mode (where the user picks a widget to get
a description).</para>
<para>For this example, assume that the application's user interface is just
a main window with three input fields: Name, Address, and Telephone Number.
Here's what the <filename>HelpEntryIds.h</filename> file would contain:</para>
<programlisting>#define HELP_volumeName "MyVolume"
#define HELP_MainWindow 100
#define HELP_MainWindow_ID "basic-tasks"
#define HELP_MainWindow_ITEM_ID "main-window-desc"
#define HELP_NameField 101
#define HELP_NameField_ID "specifying-a-name"
#define HELP_NameField_ITEM_ID "name-field-desc"
#define HELP_AddressField 102
#define HELP_AddressField_ID "specifying-an-address"
#define HELP_AddressField_ITEM_ID "address-field-desc"
#define HELP_PhoneField 103
#define HELP_PhoneField_ID "specifying-a-phone-no"
#define HELP_PhoneField_ITEM_ID "phone-field-desc"</programlisting>
<para>Within the part of the application that initially creates the widgets,
a help callback is added to each widget as follows:</para>
<programlisting>XtAddCallback (mainWindow, DtNhelpCallback,
HelpRequestCB, HELP_MainWindow);
XtAddCallback (nameField, DtNhelpCallback,
HelpRequestCB, HELP_NameField);
XtAddCallback (addressField, DtNhelpCallback,
HelpRequestCB, HELP_AddressField);
XtAddCallback (phoneField, DtNhelpCallback,
HelpRequestCB, HELP_PhoneField);</programlisting>
<para>Within the <function>HelpRequestCB()</function> function, the <symbol role="Variable">clientData</symbol> parameter is used to dispatch the help
requests (through a <command>switch()</command> statement). Within each case,
the value of a global flag <systemitem class="environvar">itemHelp</systemitem>
is tested to see if the help callback was invoked by the F1 key (the flag
is &ldquo;false&rdquo;) or by the user picking the widget in item help mode
(the flag is &ldquo;true&rdquo;).</para>
<programlisting>XtCallbackProc HelpRequestCB (
Widget w,
XtPointer clientData,
XtPointer callData)
{
char *topicToDisplay;
Boolean useQuickHelpDialog;
/* <emphasis>Determine the topic ID for the given `clientData.'</emphasis> */
switch ((int)clientData)
{
case HELP_MainWindow:
useQuickHelpDialog = False;
if (itemHelpFlag)
topicToDisplay = HELP_MainWindow_ITEM_ID;
else
topicToDisplay = HELP_MainWindow_ID;
break; case HELP_NameField:
useQuickHelpDialog = True;
if (itemHelpFlag)
topicToDisplay = HELP_NameField_ITEM_ID;
else
topicToDisplay = HELP_NameField_ID;
break; case HELP_AddressField:
useQuickHelpDialog = True;
if (itemHelpFlag)
topicToDisplay = HELP_AddressField_ITEM_ID;
else
topicToDisplay = HELP_AddressField_ID;
break; case HELP_PhoneField:
useQuickHelpDialog = True;
if (itemHelpFlag)
topicToDisplay = HELP_PhoneField_ITEM_ID;
else
topicToDisplay = HELP_PhoneField_ID;
break; default:
/* <emphasis>An unknown clientData was received.</emphasis> */
/* <emphasis>Put your error handling code here.</emphasis> */
return;
break;
}
/* <emphasis>Display the topic.</emphasis> */
ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++;
XtSetArg (al[ac], DtNhelpVolume, HELP_volumeName); ac++;
XtSetArg (al[ac], DtNhelpType, topicToDisplay); ac++;
if (useQuickHelpDialog)
{
XtSetValues (mainQuickHelpDialog, al, ac);
XtManageChild (mainQuickHelpDialog);
}
else
{
XtSetValues (mainHelpDialog, al, ac);
XtManageChild (mainHelpDialog);
}
/* <emphasis>Clear the `item help' flag.</emphasis> */
itemHelpFlag = False;
}
</programlisting>
<para>The preceding function assumes that the application uses two help dialogs
for all help requests (<command>mainHelpDialog</command> and <command>mainQuickHelpDialog</command>), and that those dialogs have already been created. It also assumes
that <command>al</command> and <command>ac</command> (used in assembling
Xt argument lists) are declared elsewhere.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.HReq.div.19">
<title id="HRDC.HReq.mkr.11">Providing a Help Menu<indexterm><primary>help
menu, providing</primary></indexterm><indexterm><primary>menu</primary><secondary>providing help menu</secondary></indexterm></title>
<para>The <citetitle>Style Guide and Certification Checklist</citetitle> recommends
that each menu bar include a Help menu. The Help menu may contain a variety
of commands that lets the user access different types of online help for your
application.</para>
<para>The most important commands include:</para>
<itemizedlist><listitem><para><command>Introduction</command> displays the
home topic of your application's help, allowing the user to use hyperlinks
to navigate to any desired information.</para>
</listitem><listitem><para><command>Using Help</command> displays &ldquo;help&rdquo;
on help. This is information that tells the user how to use the Help System.
</para>
</listitem><listitem><para><command>Version</command> displays your application's
version and copyright information.</para>
</listitem></itemizedlist>
<para>Additional commands may display help on special keyboard usage, application
tasks, reference, or tutorials. You should design your Help menu to best suit
your application, while staying within the guidelines and recommendations
of the <citetitle>Style Guide and Certification Checklist.</citetitle></para>
<sect2 id="HRDC.HReq.div.20">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
linkend="HRDC.OrgH.mkr.13"> describes how authors create the<?Pub Caret> home
topic for a help volume.</para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.16">
describes how authors create a copyright topic.</para>
</listitem><listitem><para><xref role="ChapNumAndTitle" linkend="HRDC.H4Hlp.mkr.1">describes
how help on help is found and how to add it to your application.</para>
</listitem></itemizedlist>
</sect2>
</sect1>
<sect1 id="HRDC.HReq.div.21">
<title id="HRDC.HReq.mkr.12">Supporting Item Help Mode</title>
<para>Some applications provide an On Item or Help Mode command in their Help
menu. This command temporarily redefines the mouse pointer as a <literal>?</literal> (question mark) to prompt the user to select an item on the screen.
When an item is selected, the application is expected to display a description
of the item.</para>
<para>The convenience function, <function>DtHelpReturnSelectedWidgetId()</function>,
changes the pointer to a question mark and waits for the user to pick a widget.
The ID of the selected widget is returned. This function is similar to the <function>XmTrackingLocate()</function> function except that <function>DtHelpReturnSelectedWidgetId()</function> returns NULL if the user presses Escape to cancel the operation.
</para>
<para>To display help on the selected item, your application can simply invoke
the help callback for the returned widget. This is equivalent to the user
pressing <KeyCap>F1</KeyCap> while using that widget.</para>
<para>If you want the application to differentiate between item help and F1
help, you can set a flag before calling the widget's help callback. The help
callback procedure can then use that flag to determine that the callback was
invoked as a result of item help and alter its response accordingly.</para>
<sect2 id="HRDC.HReq.div.22" role="Procedure">
<title id="HRDC.HReq.mkr.13">To Add Support for Item Help</title>
<orderedlist><listitem><para>Write a function that uses the <function>DtHelpReturnSelectedWidgetId()</function> function. Within this function, invoke the help callback for the
selected widget. In the following steps, this function is called
<function>ProcessOnItemHelp()</function>, but you can name it whatever you want.</para>
</listitem><listitem><para>Add to your Help menu a command button labeled
<command>On Item</command>. Add an activate callback that invokes your
<function>ProcessOnItemHelp()</function> function.</para>
</listitem><listitem><para>Add a help callback to each widget in your application
where you want item help to be available.</para>
</listitem></orderedlist>
<para>If the selected widget does not have a help callback, the application
should try its parent widget. Similarly, if the parent does not have a help
callback, the application should continue to walk up the widget hierarchy
until it finds a help callback.</para>
<sect3 id="HRDC.HReq.div.23">
<title>Example</title>
<para>The following procedure is a sample <function>ProcessOnItemHelp()</function>
function that would be invoked by choosing <command>On Item</command> from
the Help menu.</para>
<programlisting>void ProcessOnItemHelp(
Widget widget)
{
/* <emphasis>Declare a variable for the selected widget.</emphasis> */
Widget selWidget=NULL;
int status=DtHELP_SELECT_ERROR;
/* <emphasis>Get an application shell widget from our widget hierarchy to
* pass into DtHelpReturnSelectedWidgetId().</emphasis> */
while (!XtIsSubclass(widget, applicationShellWidgetClass))
widget = XtParent(widget);
status = DtHelpReturnSelectedWidgetId(widget, NULL, &amp;selWidget);
switch ((int)status)
{
case DtHELP_SELECT_ERROR:
printf(&ldquo;Selection Error, cannot continue\n&rdquo;);
break;
case DtHELP_SELECT_VALID:
/* <emphasis>We have a valid widget selection, now let's look
for a registered help callback to invoke.</emphasis> */
while (selWidget != NULL)
{
if ((XtHasCallbacks(selWidget, XmNhelpCallback)
== XtCallbackHasSome))
{
/* <emphasis>Found a help callback, so just call it</emphasis> */
XtCallCallbacks((Widget)selWidget,
XmNhelpCallback,NULL);
break;
}
else
/* <emphasis>No help callback on current widget, so try
the widget's parent</emphasis> */
selWidget = XtParent(selWidget);
}
break;
case DtHELP_SELECT_ABORT:
printf("Selection Aborted by user.\n");
break;
case DtHELP_SELECT_INVALID:
printf("You must select a component within your app.\n");
break;
}
}
</programlisting>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub *0000036813>

275
cde/doc/en_US.UTF-8/guides/helpGuide/ch10.sgm Normal file
View File

@@ -0,0 +1,275 @@
<!-- $XConsortium: ch10.sgm /main/11 1996/09/08 19:40:44 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.DiaEv.div.1">
<title id="HRDC.DiaEv.mkr.1">Handling Events in Help Dialogs</title>
<para>This chapter describes several Help dialog events that an application
must be equipped to handle.</para>
<informaltable id="HRDC.DiaEv.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Supporting Help Dialog Events229'--><xref
role="JumpText" linkend="HRDC.DiaEv.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Responding to Hyperlink Events230'--><xref
role="JumpText" linkend="HRDC.DiaEv.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Detecting When Help Dialogs Are Dismissed232'--><xref
role="JumpText" linkend="HRDC.DiaEv.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Using the Application-Configured
Button233'--><xref role="JumpText" linkend="HRDC.DiaEv.mkr.6"></para></entry>
</row></tbody></tgroup></informaltable>
<sect1 id="HRDC.DiaEv.div.2">
<title id="HRDC.DiaEv.mkr.2">Supporting Help Dialog Events</title>
<indexterm><primary>help dialog</primary><secondary>handling events in</secondary></indexterm><indexterm><primary>event</primary>
<secondary>in help dialog, handling</secondary></indexterm><indexterm><primary>dialog</primary><secondary>handling event in</secondary></indexterm>
<para>Like other widgets within your application, help windows have some behavior
that must be supported by the application.</para>
<sect2 id="HRDC.DiaEv.div.3">
<title>Hyperlink Events</title>
<para>Most standard hyperlink events are handled internally by the Help System.
However, there are four types of hyperlinks that your application is responsible
for handling:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Jump-new-view hyperlinks</emphasis> &mdash;Your application must create a new help dialog to honor
the author's request for a topic to be displayed in a new help window.</para>
</listitem><listitem><para><emphasis>Man page links</emphasis>&mdash;Your
application must create a new quick help dialog (or get one from your cache)
to display a man page. Typically, the size of man page windows is different
from all other help windows.</para>
</listitem><listitem><para><emphasis>Application-defined links</emphasis>&mdash;Your
application must interpret the data associated with these links. Application-defined
links exist only if you and the author have collaborated to create them.
</para>
</listitem><listitem><para><emphasis>Text file links</emphasis>&mdash;Your
application must create a quick help dialog (or get one from you cache) to
display the text file.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.DiaEv.div.4">
<title>When Dialogs Are Dismissed</title>
<para>When the user closes a help dialog, your application needs to know so
it can store the dialog in its cache, or destroy it. The general help dialog
supports a help closed callback. To detect when a quick dialog is dismissed,
add a callback to its Close button.</para>
</sect2>
<sect2 id="HRDC.DiaEv.div.5">
<title>Quick Help Buttons</title>
<para>The behavior for some of the buttons in quick help dialogs must be handled
by your application. These buttons can be managed and unmanaged as needed.
You add behavior just like any other push button: using an activate callback.
</para>
<sect3 id="HRDC.DiaEv.div.6">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><link linkend="HRDC.WrTop.div.33" endterm="HRDC.WrTop.mkr.14"></link>describes the types of links supported by the Help System
and explains how to create them.</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.DiaEv.div.7">
<title id="HRDC.DiaEv.mkr.3">Responding to Hyperlink Events</title> <indexterm><primary>responding to</primary><secondary>hyperlink event</secondary></indexterm><indexterm>
<primary>hyperlink</primary><secondary>event, responding to</secondary></indexterm><indexterm>
<primary>event</primary><secondary>hyperlink, responding to</secondary></indexterm>
<para>Your application needs to provide support only for the types of hyperlinks
used within the help volume to be displayed. In general, it is recommended
that you provide support for all link types.</para>
<para>For your application to be notified when a hyperlink is chosen, it must
add a <emphasis>hyperlink callback</emphasis> to the help dialog. You must
write a callback function that handles the hyperlink appropriately.</para>
<sect2 id="HRDC.DiaEv.div.8" role="Procedure">
<title id="HRDC.DiaEv.mkr.4">To Provide a Hyperlink Callback<indexterm><primary>hyperlink</primary><secondary>callback, providing</secondary></indexterm><indexterm>
<primary>callback</primary><secondary>hyperlink, providing</secondary></indexterm><indexterm>
<primary>&lt;Filename | Command>XtAddCallback &lt;Default Para Font></primary></indexterm><indexterm>
<primary>function</primary><secondary>&lt;Filename | Command>XtAddCallback() &lt;Default Para Font></secondary></indexterm></title>
<orderedlist><listitem><para>Add a hyperlink callback to each help dialog
as shown:</para>
<programlisting>XtAddCallback ( <symbol role="Variable">helpDialog</symbol>, DtNhyperlLinkCallback,
<symbol role="Variable">HyperlinkCB</symbol>, (XtPointer)NULL);</programlisting>
<para>Where <symbol role="Variable">helpDialog</symbol> is the widget ID of
the help dialog and <symbol role="Variable">HyperlinkCB</symbol> is the name
of the callback function for handling hyperlinks.</para>
</listitem><listitem><para>Write the <symbol role="Variable">HyperlinkCB</symbol>
function to handle the hyperlink events that can occur within the dialog.
</para>
</listitem></orderedlist>
<para>Within the hyperlink callback, you have access to the following callback
structure (which is declared in <filename>&lt;Dt/Help.h></filename>):<indexterm>
<primary>&lt;Filename | Command>DtHelpDialogCallbackStruct &lt;Default Para Font></primary>
</indexterm><indexterm><primary>structure</primary><secondary>&lt;Filename | Command>DtHelpDialogCallbackStruct &lt;Default Para Font></secondary></indexterm></para>
<programlisting>typedef struct
{
int reason;
XEvent *event;
char *locationId;
char *helpVolume;
char *specification;
int hyperType;
int windowHint;
} DtHelpDialogCallbackStruct;</programlisting>
<para>The <command>hyperType</command> element indicates which type of link
was executed. Its possible values are: <filename>DtHELP_LINK_TOPIC</filename> <command>,</command> <filename>DtHELP_LINK_MAN_PAGE</filename><command>,</command> <filename>DtHELP_LINK_APP_DEFINE</filename><command>, or</command> <filename>DtHELP_LINK_TEXT_FILE</filename><command>. For a description of which structure elements are valid
for different types refer to the</command> <filename moreinfo="RefEntry">DtHelpDialog</filename>(3) man page.</para>
<para>The <computeroutput>windowHint</computeroutput> element indicates a
window type. Its possible values are: <systemitem>DtHELP_CURRENT_WINDOW</systemitem>, <systemitem>DtHELP_POPUP_WINDOW</systemitem>, or
<systemitem>DtHELP_NEW_WINDOW.</systemitem></para>
<sect3 id="HRDC.DiaEv.div.9">
<title>Example</title>
<para>The following function, <filename>HyperlinkCB()</filename>, illustrates
the general structure needed to handle hyperlink callbacks.</para>
<programlisting>XtCallbackProc
HyperlinkCB (widget, clientData, callData)
Widget widget;
XtPointer clientData;
XtPointer callData;
{
DtHelpDialogCallbackStruct *hyperData =
(DtHelpDialogCallbackStruct *) callData;
switch ((int)hyperData-> hyperType)
{
case DtHELP_LINK_TOPIC:
/* <symbol role="Variable">Handles &ldquo;jump new view&rdquo;hyperlinks.</symbol> */
break;
case DtHELP_LINK_MAN_PAGE:
/* <symbol role="Variable">Handles &ldquo;man page&rdquo; hyperlinks.</symbol> */
break;
case DtHELP_LINK_APP_DEFINE:
/* <symbol role="Variable">Handles &ldquo;application-defined&rdquo; hyperlinks.</symbol> */
break;
case DtHELP_LINK_TEXT_FILE:
/* <symbol role="Variable">Handles &ldquo;text file&rdquo; hyperlinks.</symbol> */
break;
default:
break;
}</programlisting>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.DiaEv.div.10">
<title id="HRDC.DiaEv.mkr.5">Detecting When Help Dialogs Are Dismissed<indexterm>
<primary>help dialog</primary><secondary>detecting when dismissed</secondary>
</indexterm><indexterm><primary>dialog</primary><secondary>detecting when
dismissed</secondary></indexterm></title>
<para>To detect when a general help dialog is closed, add the following callback
to the dialog:</para>
<programlisting>XtAddCallback (<symbol role="Variable">helpDialog</symbol>, DtNcloseCallback,
<symbol role="Variable">HelpCloseCB</symbol>, (XtPointer)NULL);
</programlisting>
<para><indexterm><primary>callback</primary><secondary>close callback example</secondary></indexterm>Where <symbol role="Variable">helpDialog</symbol>
is the widget ID for the help dialog and <symbol role="Variable">HelpCloseCB</symbol> is the name of the callback procedure you've written to handle
closing dialogs.</para>
<para>To detect when a quick help dialog is closed, add the following callback
to the dialog's OK button:</para>
<programlisting>XtAddCallback (DtHelpQuickDialogGetChild ( <symbol role="Variable">helpDialog</symbol>,
DtHELP_QUICK_OK_BUTTON), XmNactivateCallback, <symbol role="Variable">HelpCloseCB</symbol>,
(XtPointer)NULL);</programlisting>
<para>Where <symbol role="Variable">helpDialog</symbol> is the widget ID for
the help dialog and <symbol role="Variable">HelpCloseCB</symbol> is the name
of the callback procedure you've written to handle closing dialogs.</para>
</sect1>
<sect1 id="HRDC.DiaEv.div.11">
<title id="HRDC.DiaEv.mkr.6">Using the Application-Configured Button<indexterm>
<primary>button, application-configured</primary></indexterm></title>
<para>The quick help dialog's application-configured button lets you add custom
behavior to any quick help dialog. This button can be used for anything you
want, but its intended purpose is to provide a path to more help in one of
these two ways:</para>
<itemizedlist remap="Bullet1"><listitem><para>Lets the user progressively
ask for more information. This is sometimes called progressive disclosure.
In this case, the default button label (More) is appropriate.</para>
</listitem><listitem><para><emphasis>L</emphasis>ets the user open a general
help dialog for general browsing of the application's help volume. In this
case, Browse&hellip; is the most appropriate button label.</para>
</listitem></itemizedlist>
<sect2 id="HRDC.DiaEv.div.12" role="Procedure">
<title id="HRDC.DiaEv.mkr.7">To Enable the Application-Configured Button<indexterm>
<primary>application-configured, button enabling</primary></indexterm></title>
<orderedlist><listitem><para>Get the button's ID.</para>
</listitem><listitem><para>Add an activate callback to the button.</para>
</listitem><listitem><para>Manage the button.</para>
</listitem></orderedlist>
<sect3 id="HRDC.DiaEv.div.13">
<title>Example</title>
<para>The following code segment gets the button's ID, assigns a callback,
and manages the button. It assumes that <command>quickHelpDialog</command>
was just created.</para>
<programlisting>Widget moreButton;
moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DtHELP_QUICK_MORE_BUTTON);
XtAddCallback (moreButton, XmNactivateCallback,
MoreHelpCB, NULL);
XtManageChild (moreButton);</programlisting>
</sect3>
<sect3 id="HRDC.DiaEv.div.14">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><!--Original XRef content: '&ldquo;To
Create a Quick Help Dialog&rdquo; on page&numsp;211'--><xref role="SecTitleAndPageNum"
linkend="HRDC.CrDia.mkr.7"></para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpDialog</filename>(3)
man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpQuickDialog</filename>(3) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.DiaEv.div.12a" role="Procedure"><title id="HRDC.DiaEv.mkr.7a">To Access DtInfo by Using the "More" Button</title>
<para>As an extension to the desktop DtHelp facility, an application may add a local callback for the "More" button on the quick help dialog, which subsequently invokes dtinfo for additional information related to the quick help presentation, and/or directly invokes DtInfo for detailed help (such as for "On Application" or "On Window").</para>
<para>If you want your application to provide the user access to a local information corpus at a specific point of relevance, you use the built-in function <command>DtActionInvoke()</command>. The anchor point may be as broad as the top of a bookcase, or as fine as a specific section. Targets within sections are also possible, as long as they have been given externally unique link IDs during construction of the data.</para>
<sect3><title>Example</title>
<para>This section describes the use of the CDE desktop action API to invoke (or connect to) DtInfo.</para>
<para>Before <command>DtActionInvoke</command> is called, the application must first call <command>DtInitialize</command> to initialize the desktop services library, and <command>DtDbLoad</command> to load the actions and datatypes database. Since the DtInfo actions and datatype entries are part of the CDE desk top, there is no need to use the <command>DtDbReloadNotify</command> function for these alone.</para>
<programlisting>#include &lt;Dt/Action.h>
#include &lt;limits.h>
#include &lt;locale.h>
...
int info_bridge( char * infolib, char* uulocator)
{
char info_uuid[ MAXFQLOCATORBUFSIZE ];
char exec_host[ MAXHOSTNAMESIZE ];
DtActionArg* args = NULL;
Xegetshorthostname(localhost, MAXHOSTNAMESIZE);
args = (DtActionArg*) XtCalloc( 2, sizeof(DtActionArg) );
...
args[0].argclass = DtACTION_BUFFER;
args[0].u.buffer.bp = (void*) infolib;
args[0].u.buffer.size = strlen( infolib) + 1;
args[0].u.buffer.writable = False;
...
sprintf( info_uuid, "%s%s", "mmdb:LOCATOR=", uulocator );
args[1].argclass = DtACTION_BUFFER;
args[1].u.buffer.bp = (void*) info_uuid;
args[1].u.buffer.size = strlen( info_uuid) + 1;
args[1].u.buffer.writable = False;
actionId = DtActionInvoke(
w,
"DtShowInfoAtLOC",
args,
2,
NULL,
exec_host,
NULL,
True,
NULL,
NULL
);
...
XtFree( args );
}
</programlisting>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub Caret>
<?Pub *0000018925>

328
cde/doc/en_US.UTF-8/guides/helpGuide/ch11.sgm Normal file
View File

@@ -0,0 +1,328 @@
<!-- $XConsortium: ch11.sgm /main/10 1996/09/08 19:40:53 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.H4Hlp.div.1">
<title id="HRDC.H4Hlp.mkr.1">Providing Help on Help</title>
<para>This chapter explains how to incorporate a help volume into your application
that describes the features of the Help System and how to use them. This
help volume provides help on using the Help dialog boxes.</para>
<informaltable id="HRDC.H4Hlp.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Accessing Help on Help in an Application236'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.2"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Set the helpOnHelpVolume Resource237'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.3"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Provide a Using Help Command237'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.4"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Display Help on Help238'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.5"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Writing Your Own Help on Help Volume239'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.6"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Copy the Help4Help Source Files241'--><xref
role="JumpText" linkend="HRDC.H4Hlp.mkr.7"></para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect1 id="HRDC.H4Hlp.div.2">
<title>Providing Help on Help</title>
<para>Help on help tells users how to use the Help System. Specifically, it
describes such tasks as using hyperlinks, navigating topics, using the index,
and printing help topics. Normally, help on help is supplied as an individual
help volume named Help4Help.</para>
<para>The Help4Help volume and its source files are included in the Developer's
Toolkit. You can use the default volume &ldquo;as is,&rdquo; or modify it
for your application's design.</para>
<sect2 id="HRDC.H4Hlp.div.3">
<title>For Application Help</title>
<para>If you are writing application-specific help, there are two ways to
ensure that your application has help on help for its own help dialogs:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Rely on the desktop's
help on help volume.</emphasis> For example, on workstations running the
desktop, the standard Help4Help volume is installed.</para>
</listitem><listitem><para><emphasis>Supply your own help on help volume.</emphasis> The DocBook source files for the Help4Help volume are provided
in the <filename>/usr/dt/dthelp/help4help/C</filename> directory. You run
DocBook in this directory to create the run-time help file. Graphics files
used in the help on help volume are stored in the <filename>graphics</filename>
subdirectory.</para>
</listitem></itemizedlist>
</sect2>
<sect2 id="HRDC.H4Hlp.div.4">
<title>For Standalone Help</title>
<para>If you are writing standalone help, you are probably relying on the
Helpview program already being installed and ready to use. If this is the
case, you don't have to worry about help on help because Helpview accesses
the standard Help4Help volume by default.</para>
</sect2>
<sect2 id="HRDC.H4Hlp.div.5">
<title>How Help on Help Is Found</title>
<para>Each application that uses the Help System (including Helpview) has
a <systemitem class="resource">helpOnHelpVolume</systemitem> resource that
identifies a help volume to be accessed for help on help topics. For Helpview,
this resource is set as follows:</para>
<programlisting>DtHelpview*helpOnHelpVolume: Help4Help</programlisting>
<para>If you provide your own help on help volume, be sure to give it a unique
name so it doesn't conflict with another help on help volume that may be installed
on the system.</para>
</sect2>
</sect1>
<sect1 id="HRDC.H4Hlp.div.6">
<title id="HRDC.H4Hlp.mkr.2">Accessing Help on Help in an Application</title>
<para>Your application should do the following to support help on help:</para>
<itemizedlist remap="Bullet1"><listitem><para>Set the <systemitem class="resource">helpOnHelpVolume</systemitem> resource to identify the help volume you want
to access.</para>
</listitem><listitem><para>Add a <command>Using Help</command> command to
the application's Help menu.</para>
</listitem></itemizedlist>
<sect2 id="HRDC.H4Hlp.div.7" role="Procedure">
<title id="HRDC.H4Hlp.mkr.3">To Set the helpOnHelpVolume Resource</title>
<orderedlist><listitem><para>Add a line to your application's application-defaults
file like this:</para>
<para><symbol role="Variable">App-class</symbol>* <systemitem class="resource">helpOnHelpVolume</systemitem>: <symbol role="Variable">volume</symbol></para>
<para>Where <symbol role="Variable">App-class</symbol> is the application's
class name and <symbol role="Variable">volume</symbol> is the name of the
help on help volume you want to access.</para>
<para><emphasis>Or,</emphasis> within your application, set the <systemitem class="resource">helpOnHelpVolume</systemitem> resource for each help dialog
you create.</para>
</listitem></orderedlist>
<sect3 id="HRDC.H4Hlp.div.8">
<title>Examples</title>
<itemizedlist remap="Bullet1"><listitem><para>This line in <filename>dthelpview's</filename> application-defaults file (<command>DtHelpview</command>) specifies
the help on help volume:</para>
<programlisting>DtHelpview*helpOnHelpVolume: Help4Help</programlisting>
</listitem><listitem><para>To specify the help on help volume when creating
a help dialog, add it to the argument list passed to the create function
as shown here:</para>
<programlisting>ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpOnHelpVolume, "Help4Help"); ac++;
helpDialog = DtCreateHelpDialog (parent, "helpDialog", al, ac);</programlisting>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.H4Hlp.div.9" role="Procedure">
<title id="HRDC.H4Hlp.mkr.4">To Provide a Using Help Command</title>
<orderedlist><listitem><para>Add to your Help menu a button labeled <literal>Using Help</literal>. Also add the necessary activate callback to call your <function>HelpRequestCB()</function> function.</para>
</listitem><listitem><para>Add support to your <function>HelpRequestCB()</function>
function to display help on help. Specifically:</para>
<itemizedlist><listitem><para>Create a quick help dialog.</para>
</listitem><listitem><para>Set the dialog's title to Help On Help.</para>
</listitem><listitem><para>Display the home topic of the help on help volume.
</para>
</listitem><listitem><para>Manage the quick help dialog.</para>
</listitem></itemizedlist>
</listitem></orderedlist>
<sect3 id="HRDC.H4Hlp.div.10">
<title>Example</title>
<para>The following lines create a menu button labeled <literal>Using Help&hellip;</literal> that calls the <function>HelpRequestCB()</function> function.
</para>
<programlisting>/* <emphasis>Create the "Using Help ..." button.</emphasis> */
labelStr = XmStringCreateLtoR ("Using Help ...",
XmSTRING_DEFAULT_CHARSET);
ac = 0;
XtSetArg (al[ac], XmNlabelString, labelStr); ac++;
button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,
ac);
XtManageChild (button);
XmStringFree (labelStr);
/* <emphasis>Add a callback to the button.</emphasis> */
XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
USING_HELP);</programlisting>
<para><systemitem class="constant">USING_HELP</systemitem> is the client data
passed to the <function>HelpRequestCB()</function> function when the menu
button is chosen by the user. Presumably it has been defined somewhere in
the application (perhaps in a <filename>Help.h</filename> file) as a unique
integer:</para>
<programlisting>#define USING_HELP 47</programlisting>
<para>To see how the <function>HelpRequestCB()</function> function handles
the <systemitem class="constant">USING_HELP</systemitem> case, see the example
in the next section, &ldquo;To Display Help on Help.&rdquo;</para>
</sect3>
</sect2>
<sect2 id="HRDC.H4Hlp.div.11" role="Procedure">
<title id="HRDC.H4Hlp.mkr.5">To Display Help on Help</title>
<orderedlist><listitem><para>Create a quick help dialog (or retrieve one from
your cache).</para>
</listitem><listitem><para>Display in the dialog the home topic of your help
on help volume.</para>
</listitem></orderedlist>
<para>Help on help can be displayed in a general help window, but a quick
help dialog is recommended because its user interface is simpler and less
intimidating to the new users who commonly need help on help.</para>
<sect3 id="HRDC.H4Hlp.div.12">
<title>Example</title>
<para>The following program segment is part of a <function>HelpRequestCB()</function> function. Presumably, the <systemitem class="constant">USING_HELP</systemitem> constant is passed to the function because the user chose Using
Help from the application's Help menu or chose the Help button in a quick
help dialog.</para>
<para>This example assumes that the application never creates more than one
Help On Help dialog and maintains its widget ID in a variable called <symbol role="Variable">onHelpDialog</symbol>.</para>
<programlisting>case USING_HELP:
if (onHelpDialog == (Widget)NULL)
{
/* <emphasis>Get a quick help dialog for use as the "help on help" dialog.</emphasis> */
onHelpDialog = FetchHelpDialog (True);
if (onHelpDialog == (Widget)NULL)
/* <emphasis>We didn't get a dialog! Add your error handling code here.</emphasis> */
}
/* <emphasis>Set the proper volume and ID to display the home topic of the help on help volume. Also, set the dialog's title.</emphasis> */
ac = 0; XtSetArg (al[ac], XmNtitle, "Help On Help"); ac++;
XtSetArg (al[ac], XmNhelpType, DT_HELP_TYPE_TOPIC); ac++;
XtSetArg (al[ac], XmNhelpVolume, "Help4Help"); ac++;
XtSetArg (al[ac], XmNlocationId, "_hometopic"); ac++;
XtSetValues (onHelpDialog, al, ac);
/* <emphasis>If the "help on help" dialog is already managed, it might be in another workspace, so unmanage it.</emphasis> */
if (XtIsManaged (onHelpDialog))
XtUnmanageChild (onHelpDialog);
/* <emphasis>Manage the "help on help" dialog.</emphasis> */
XtManageChild (onHelpDialog);
break;
</programlisting>
<para>To see how the rest of the <function>HelpRequestCB()</function> function
might be structured, refer to the example in <xref role="SecTitleAndPageNum"
linkend="HRDC.HReq.mkr.10">.</para>
</sect3>
<sect3 id="HRDC.H4Hlp.div.13">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
linkend="HRDC.CrDia.mkr.7"></para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.HReq.mkr.5">
</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.H4Hlp.div.14">
<title id="HRDC.H4Hlp.mkr.6">Writing Your Own Help on Help Volume</title>
<para>If you need to provide your own help on help volume, you should start
with the existing Help4Help volume and then make the necessary changes. All
the source files used to write the Help4Help volume are provided in the
<filename>/usr/dt/dthelp/help4help/C</filename> directory.</para>
<para>To prevent installation conflicts, name your help on help volume something
other than Help4Help. Consider picking a name that is specific to your product.
For example, if your application's help volume is Newapp, your help for help
volume could be NewappH4H.</para>
<sect2 id="HRDC.H4Hlp.div.15">
<title>Required Entry Points</title>
<para>To ensure that context-sensitive help within a help dialog operates
correctly, you must provide the following entry points (IDs) within your help
on help volume. (These are already included in the Help4Help source files.)
</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="158*">
<colspec align="left" colwidth="370*">
<tbody>
<row>
<entry align="center" valign="top"><para>ID</para></entry>
<entry align="center" valign="top"><para>Topic Description</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>_hometopic</command></para></entry>
<entry align="left" valign="top"><para>Displays an introduction to using the
help system. This topic is displayed when you choose Using Help from the general
help dialog's Help menu, or when you press F1 in a quick help dialog. This
ID is generated automatically for PartIntro, so do not try to specify it explicitly.
</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>_copyright</command></para></entry>
<entry align="left" valign="top"><para>Displays the copyright and version
information for the help on help volume. This topic is displayed when you
choose Version from the general help dialog's Help menu. This ID is generated
automatically for LegalNotice, so do not try to specify it explicitly.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>history</command></para></entry>
<entry align="left" valign="top"><para>Displays a topic that describes how
to use the History dialog. This topic is displayed when you choose Help or
press F1 within the History dialog.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>printing</command></para></entry>
<entry align="left" valign="top"><para>Displays a topic describing how to
use the Print dialog. This topic is displayed when you choose Help or press
F1 within the Print dialog.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>index-search</command></para></entry>
<entry align="left" valign="top"><para>Displays a topic describing how to
use the Index Search dialog. This topic is displayed when you choose Help
or press F1 within the Index Search dialog.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>volume-select</command></para></entry>
<entry align="left" valign="top"><para>Displays a topic describing how to
use the Search Volume Selection Dialog. This topic is displayed when you choose
Help or press F1 within the Search Volume Selection Dialog.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="HRDC.H4Hlp.div.16" role="Procedure">
<title id="HRDC.H4Hlp.mkr.7">To Copy the Help4Help Source Files</title>
<orderedlist><listitem><para>Copy the entire <filename>/usr/dt/dthelp/help4help/C</filename> directory to a new working directory ( <symbol role="Variable">new-dir</symbol>) using a command like this:</para>
<para><command>cp -r /usr/dt/dthelp/help4help/C <symbol role="Variable">new-dir</symbol></command></para>
<para>This creates <symbol role="Variable">new-dir</symbol> and copies all
the files and directories into it.</para>
</listitem><listitem><para>To permit editing the files (which are copied as
read only), change the permissions using a command like this:</para>
<programlisting>chmod -R u+w <symbol role="Variable">new-dir</symbol></programlisting>
</listitem></orderedlist>
<para>The Help4Help volume uses these DocBook source files:</para>
<itemizedlist><listitem><para><filename>MetaInfo.sgm</filename></para>
</listitem><listitem><para><filename>Toc.sgm</filename></para>
</listitem><listitem><para><filename>Tasks.sgm</filename></para>
</listitem><listitem><para><filename>Home.sgm</filename></para>
</listitem><listitem><para><filename>Concepts.sgm</filename></para>
</listitem><listitem><para><filename>Ref.sgm</filename></para>
</listitem><listitem><para><filename>Appendix.sgm</filename></para>
</listitem></itemizedlist>
<para>Graphics are stored in the <filename>graphics</filename> subdirectory.
</para>
<para>Be sure to rename the <filename>Help4Help.sgm</filename> file before
running DocBook. Your help on help volume should have a unique name to prevent
conflicts with other help on help volumes.</para>
<sect3 id="HRDC.H4Hlp.div.17">
<title>Example</title>
<para>The following commands create a copy of the help on help volume and
make its files writable. (Presumably the <filename>projects</filename> subdirectory
already exists.)</para>
<programlisting>cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help
chmod -R u+w /users/dex/projects/NewHelp4Help</programlisting>
<para>To build a new version of the run-time help files, first ensure that
the directory <filename>/usr/dt/bin</filename> is in your search path. Then
change to the new directory, rename the <filename>Help4Help.sgm</filename>
file, and run DocBook:</para>
<programlisting>cd /users/dex/projects/NewHelp4Help
mv Help4Help.sgm NewH4H.sgm
dtDocBook NewH4H</programlisting>
<para>When the DocBook software is done, you can display the new help on help
volume using this command:</para>
<para><command>dthelpview -helpVolume NewH4H</command></para><?Pub Caret>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

274
cde/doc/en_US.UTF-8/guides/helpGuide/ch12.sgm Normal file
View File

@@ -0,0 +1,274 @@
<!-- $XConsortium: ch12.sgm /main/11 1996/09/08 19:41:02 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.Inst.div.1">
<title id="HRDC.Inst.mkr.1">Preparing an Installation Package</title>
<para id="HRDC.Inst.mkr.2">This chapter identifies the help files that are
included in an application installation package. It also describes how help
files are handled when your application is registered on the desktop.</para>
<informaltable id="HRDC.Inst.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Delivering Online Help244'--><xref
role="JumpText" linkend="HRDC.Inst.mkr.4"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating an Installation Package244'--><xref
role="JumpText" linkend="HRDC.Inst.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Registering Your Application and
Its Help247'--><xref role="JumpText" linkend="HRDC.Inst.mkr.9"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Product Preparation Checklists248'--><xref
role="JumpText" linkend="HRDC.Inst.mkr.12"></para></entry></row></tbody></tgroup>
</informaltable>
<sect1 id="HRDC.Inst.div.2">
<title id="HRDC.Inst.mkr.3">Overview</title>
<para>When it comes time to prepare your final product, you must be sure that
all your help files are created and installed properly. Your product package
includes both the run-time help file (<symbol>volume</symbol><filename>.sdl</filename>) and its graphic files. Additionally, you can provide a help
family file that enables your volume to be viewed using the Front Panel Help
Viewer.</para>
</sect1>
<sect1 id="HRDC.Inst.div.3">
<title id="HRDC.Inst.mkr.4">Delivering Online Help</title>
<para>Online help can be fully integrated into an application or provided
as a standalone help volume. Fully integrated help allows a user to directly
access help information from an application by using a Help menu or Help key.
A standalone volume on the other hand, can only be displayed using the desktop
Help Viewer.</para>
<para>A system administrator may choose to add a standalone help volume to
the desktop when an application does not provide integrated help or a customized
environment provides a supplemental help volume. See <xref role="SecTitleAndPageNum"
linkend="HRDC.Inst.mkr.10"> for instructions to install a standalone volume
on the desktop.</para>
</sect1>
<sect1 id="HRDC.Inst.div.4">
<title id="HRDC.Inst.mkr.5">Creating an Installation Package</title>
<para>Your installation package should include these help files:</para>
<itemizedlist><listitem><para>Run-time help files</para>
</listitem><listitem><para>Graphics files</para>
</listitem><listitem><para>Help family file (optional)</para>
</listitem><listitem><para>Application defaults file (optional)</para>
</listitem></itemizedlist>
<para>The run-time help file and any graphics used in the online help are
included in your installation package. A help family file is optional for
integrated application help. However, if you want your application help to
be browsable using the desktop Help Viewer, you must provide a family file.
If you are delivering a standalone help volume, you must provide a help family
file. See <xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.11">.</para>
<para>If your application's help volume includes execution links, it is recommended
that the author define execution aliases in an application defaults file.
This takes advantage of the Help System's default execution policy which will
automatically execute links with execution aliases. However, if the help volume
is viewed as an independent volume using a separate information viewer, such
as the Help Viewer, the Help System will display a confirmation dialog box
when an execution link is selected.</para>
<para><xref role="CodeOrFigureOrTable" linkend="HRDC.Inst.mkr.6"> on <xref
role="Page" linkend="HRDC.Inst.mkr.6"> shows a typical installation package
for an application and its help files. Help files are grouped in a separate <filename>help</filename> subdirectory which contains a default language directory
(C is the default). The run-time help file, family file, and graphics files
are located in this directory.</para>
<figure>
<title id="HRDC.Inst.mkr.6">Application installation package</title>
<graphic id="HRDC.Inst.grph.1" entityref="HRDC.Inst.fig.1"></graphic>
</figure>
<para>If your application provides online help in multiple languages, you
should create a <symbol role="Variable">language</symbol> subdirectory to
accommodate each language (where <symbol role="Variable">language</symbol>
matches the user's <systemitem class="resource">LANG</systemitem> environment
variable). For example, an application that provides both an English and German
user interface stores its corresponding online help in two subdirectories: <filename>C</filename> for English and <filename>german</filename> for German.</para>
<sect2 id="HRDC.Inst.div.5">
<title>Run-Time Help File</title>
<para>DocBook creates a single run-time help file, <symbol role="Variable">volume</symbol><filename>.sdl</filename>. The base name, <symbol role="Variable">volume</symbol>, is the same as the base name of your <symbol role="Variable">volume</symbol><filename>.sgm</filename> file. The Help Viewer uses information
stored in this master help file and also accesses any associated graphic files.
</para>
<para>You don't need to ship the <symbol role="Variable">volume</symbol><filename>.sgm</filename> or any additional files generated by the DocBook software.
</para>
</sect2>
<sect2 id="HRDC.Inst.div.6">
<title id="HRDC.Inst.mkr.7">Graphics Files</title>
<para>If your help volume uses graphics, the image files are typically stored
in a separate directory for convenience. However, you may choose to store
them in the same location as your <symbol role="Variable">volume</symbol> <command>.sgm</command> file.</para>
<para>A run-time help file does not include actual graphic images. Instead,
it contains a &ldquo;reference&rdquo; to the location of each graphic file.
When you run DocBook, the <command>dtdocbook</command> compiler incorporates
the relative path names of the graphics files into the help volume.</para>
<para>When the help files are installed, the graphics files must be in the
same relative position as when the run-time file was built. Otherwise, the
help volume will be unable to locate the graphics files. For example, if your
graphics files are in a subdirectory named <filename>graphics</filename> one
level below your <symbol role="Variable">volume</symbol><filename>.sgm</filename>
file, then your installation package must preserve that relative position.
The graphics files must be placed in a subdirectory named <filename>graphics</filename> one level below the <symbol role="Variable">volume</symbol><filename>.sdl</filename> file.</para>
<figure>
<title>Relationship of build directories and installation package</title>
<graphic id="HRDC.Inst.grph.2" entityref="HRDC.Inst.fig.2"></graphic>
</figure>
</sect2>
<sect2 id="HRDC.Inst.div.7">
<title>Help Family File</title>
<para>You can optionally provide a help family file (<symbol>volume</symbol><filename>.hf</filename>). A family file briefly describes your help volume and includes
copyright information. It can also be used to group one or more related volumes
into a single product category.</para>
<para id="HRDC.Inst.mkr.8">If you want your help volume to be accessible from
the desktop browser volume, then you must provide a family file in your installation
package. To create a family file, see <xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.11">.
</para>
</sect2>
</sect1>
<sect1 id="HRDC.Inst.div.8">
<title id="HRDC.Inst.mkr.9">Registering Your Application and Its Help</title>
<para>The desktop's integration utility, <command>dtappintegrate</command>,
registers your application and its help files by creating symbolic links between
the installed application files and specific desktop directories. Application
registration ensures that your help files are located in the directory search
paths used by the Help System.</para>
<para>Registration enables two important features of the Help System:</para>
<itemizedlist><listitem><para><emphasis>Cross-volume hyperlinks</emphasis>
&mdash; A hyperlink in one help volume can refer to another help volume using
just the volume name and an ID within the volume. If the destination volume
is registered, the link does not have to specify where the volume is stored
on the file system.</para>
</listitem><listitem><para><emphasis>Help family browsing</emphasis> &mdash;
If you also register a &ldquo;help family&rdquo;, then your help volumes will
be browsable using the Help Viewer.</para>
</listitem></itemizedlist>
<para>Registering your online help makes it easier to access the help you
provide. For authors and programmers, it's easier because references to your
volume can use just the volume name, without specifying the volume's actual
location.</para>
<para>If you register a help family with one or more help volumes, you make
your help available for general browsing from the Front Panel Help Viewer.
This allows access to application-specific help without using the application.
If you are writing standalone help, this is the only way for users to get
to your help.</para>
<sect2 id="HRDC.Inst.div.9">
<title id="HRDC.Inst.mkr.10">Standalone Help</title>
<para>A standalone help volume for an application or a customized environment
can be created using the Help System Developer's Kit. To make the help volume
accessible from in the desktop index volume, a system administrator installs
the run-time help file, associated graphics, and family file in the
<filename>/etc/dt/appconfig/help/</filename><symbol role="Variable">language</symbol>
directory.</para>
<para>Remember that the run-time help file and its graphics files must be
installed in the same relative position as when the help volume was built.
See <xref role="SecTitleAndPageNum" linkend="HRDC.Inst.mkr.7"> to review the
installation of graphics files.</para>
</sect2>
<sect2 id="HRDC.Inst.div.10">
<title>What Happens When the Application Is Registered</title>
<para>Application registration creates symbolic links from the run-time help
file and family located in <symbol>app_root</symbol>/<filename>dt/appconfig/help</filename> <symbol>language</symbol> to the <filename>/etc/dt/appconfig/help</filename>/<symbol>language</symbol> directory.</para>
<para>Refer to the <citetitle>Advanced User's and System Administrator's Guide</citetitle> for detailed instructions for application registration.</para>
</sect2>
<sect2 id="HRDC.Inst.div.11">
<title id="HRDC.Inst.mkr.11">How a Help Volume Is Found</title>
<para>The Help System uses desktop search paths to locate help volumes. When
help is requested within an application or a help volume is specified in a
command line, the help volume is found by checking a set of search path directories.
You can control the directory search path for help volumes by modifying several
environment variables. Refer to the <citetitle>Advanced User's and System
Administrator's Guide</citetitle> for detailed information about specifying
search paths.</para>
</sect2>
</sect1>
<sect1 id="HRDC.Inst.div.12">
<title id="HRDC.Inst.mkr.12">Product Preparation Checklists</title>
<para>The following checklists should help you verify that you've prepared
your product correctly. Of course, there's no substitute for testing your
product by using it as a user would.</para>
<sect2 id="HRDC.Inst.div.13">
<title>For Authors</title>
<orderedlist><listitem><para><emphasis>A final version of the run-time help
file was created.</emphasis></para>
<para>Here are the recommended commands for creating the run-time file:</para>
<para><command>dtdocbook -r</command> <symbol role="Variable">volume</symbol></para>
<para><command>dtdocbook</command> <symbol role="Variable">volume</symbol></para>
<para>The <command>-r</command> option removes files from any previous <command>dtdocbook</command> command. You should not distribute a help volume that
has any parser errors. If any parser errors have occurred, dtdocbook will
place them in the intermediate file <symbol role="Variable">volume</symbol><filename>.log</filename>.</para>
</listitem><listitem><para><emphasis>All hyperlinks have been tested</emphasis>.
</para>
<para>Verify that each hyperlink displays the proper topic or performs the
correct action.</para>
</listitem><listitem><para><emphasis>Execution aliases have been defined for
execution links.</emphasis></para>
<para>Execution aliases are defined as resources in the application's application
defaults file. An execution alias associates a name with a shell command to
be executed. If you have used execution links in your help volume, coordinate
with the application developer to add these resources to the application defaults
file.</para>
</listitem><listitem><para><emphasis>All graphics are acceptable.</emphasis></para>
<para>Make sure that the graphics have been tested on various color, grayscale,
and monochrome displays.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="HRDC.Inst.div.14">
<title>For Product Integrators</title>
<orderedlist><listitem><para><emphasis>The run-time file is installed.</emphasis></para>
</listitem><listitem><para><emphasis>All graphics are installed in the proper
locations.</emphasis></para>
<para>Each graphics file must be installed in the same relative position to
the <filename>.sdl</filename> file that it was in relative to the<filename>.sgm</filename> file when the DocBook software was run.</para>
</listitem><listitem><para><emphasis>The help volume is registered.</emphasis></para>
<para>The <command>dtappintegrate</command> script was run to create symbolic
links from the installation directory to the registration directory.</para>
</listitem><listitem><para><emphasis>A product family file is installed and
registered.</emphasis></para>
<para>The family file is installed with the other help files. When <command>dtappintegrate</command> is run, it creates a symbolic link for the family
file. Registering a family file for your help volume is optional, but if you
choose not to register a family file, your help volume will not be accessible
from the Front Panel Help Viewer.</para>
</listitem></orderedlist>
</sect2>
<sect2 id="HRDC.Inst.div.15">
<title>For Programmers</title>
<orderedlist><listitem><para><emphasis>The application sets the correct values
for these required resources:</emphasis></para>
<programlisting><symbol>App-class</symbol>*helpVolume: <symbol>volume</symbol>
<symbol>App-class</symbol>*helpOnHelpVolume: <symbol role="Variable">help-on-help-volume</symbol></programlisting>
<para>The <systemitem class="resource">helpVolume</systemitem> resource identifies
the help volume for your application. The <systemitem class="resource">helpOnHelpVolume</systemitem> resource identifies the help volume that contains the help on
using the help system.</para>
</listitem><listitem><para><emphasis>Execution aliases are included in the
application defaults file.</emphasis></para>
<para>An author defines execution aliases as application resources. An execution
alias associates a name with a shell command to be executed. If execution
links have been used in the help volume, check with the author to identify
the resources that need to be added.</para><?Pub Caret1>
</listitem><listitem><para><emphasis>The application sets the desired values
for the following optional resources:</emphasis></para>
<programlisting><symbol>App-class</symbol>*DtHelpDialogWidget*onHelpDialog*rows: <symbol>rows</symbol>
<symbol>App-class</symbol>*DtHelpDialogWidget*onHelpDialog*columns: <symbol role="Variable">columns</symbol>
<symbol>App-class</symbol>*DtHelpDialogWidget*definitionBox*rows: <symbol role="Variable">rows</symbol>
<symbol>App-class</symbol>*DtHelpDialogWidget*definitionBox*columns: <symbol role="Variable">columns</symbol>
</programlisting>
<para>The <systemitem class="resource">onHelpDialog</systemitem> resources
control the size of the quick help dialogs used to display Help on Help. The <systemitem class="resource">definitionBox</systemitem> resources control the size of
the quick help dialog used for definition links.</para>
</listitem><listitem><para><emphasis>The application uses either the default
font resources or defines font resources in the application's application-defaults
file.</emphasis></para>
<para>In most cases an application can rely on the default font resources.
However, when custom fonts are used, they must be defined in the application-
defaults file. Sample font schemes are provided in the <filename>/usr/dt/dthelp/fontschemes</filename> directory. See <xref role="ChapNumAndTitle" linkend="HRDC.Lang.mkr.1">,
for additional information about font schemes.</para>
</listitem></orderedlist>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub *0000023101>

560
cde/doc/en_US.UTF-8/guides/helpGuide/ch13.sgm Normal file
View File

@@ -0,0 +1,560 @@
<!-- $XConsortium: ch13.sgm /main/9 1996/08/26 10:45:59 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.Lang.div.1">
<title id="HRDC.Lang.mkr.1">Native Language Support</title>
<para id="HRDC.Lang.mkr.2">This chapter identifies files used by the Help
System that require modification when a help volume is provided in multiple
languages.</para>
<informaltable id="HRDC.Lang.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Internationalized Online Help253'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.3"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Character Sets and Multibyte Characters254'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.5"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'DtHelp Message Catalog258'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.8"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'LANG Environment Variable259'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.9"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Understanding Font Schemes260'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.11"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Creating a Formatting Table263'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.14"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Displaying a Localized Help Volume265'--><xref
role="JumpText" linkend="HRDC.Lang.mkr.17"></para></entry>
</row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Preparing Online Help for International
Audiences265'--><xref role="JumpText" linkend="HRDC.Lang.mkr.18"></para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect1 id="HRDC.Lang.div.2">
<title id="HRDC.Lang.mkr.3">Internationalized Online Help</title>
<para>If your product is intended for an international audience, then providing
online help in the user's native language is important. The Help System supports
the authoring and displaying of online help in virtually any language.</para>
<para>When you process a help volume to create run-time help files, the DocBook
software must be told what language and character set you used to author your
files. The language and character set information is also used to determine
the proper fonts for displaying the help volume.</para>
</sect1>
<sect1 id="HRDC.Lang.div.3">
<title id="HRDC.Lang.mkr.4">Internationalization Factors</title>
<para>Several factors, which are explained in the following section, contribute
to providing effective online help in the user's native language.</para>
<sect2 id="HRDC.Lang.div.4">
<title id="HRDC.Lang.mkr.5">Character Sets</title>
<para>A <emphasis>character set</emphasis> determines how a computer's internal
character codes (numbers) are mapped to recognizable characters. In most languages,
single-byte characters are sufficient for representing an entire character
set. However, there are some languages that use thousands of characters. These
languages require two, three, or four bytes to represent each character uniquely.
</para>
<para>Character sets supported by the Help System are listed in <xref role="CodeOrFigureOrTable"
linkend="HRDC.Lang.mkr.6">. However, some characters sets may not exist on
all platforms.</para>
<table id="HRDC.Lang.tbl.1">
<title id="HRDC.Lang.mkr.6">Common Desktop Environment Character Sets</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.17in">
<colspec colname="col2" colwidth="1.99in">
<colspec colwidth="2.07in">
<thead>
<row><entry align="left" valign="bottom"><para>Language</para></entry><entry
align="left" valign="bottom"><para>Character Set Name</para></entry><entry
align="left" valign="bottom"><para>Description</para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para>Western Europe and Americas</para></entry>
<entry align="left" valign="top"><para>ISO-8859-1</para></entry>
<entry align="left" valign="top"><para>ISO Latin 1</para></entry>
</row>
<row>
<entry align="left" colname="col2" valign="top">HP-ROMAN8</entry>
<entry align="left" valign="top">HP Roman</entry>
</row>
<row>
<entry align="left" colname="col2" valign="top">IBM-850</entry>
<entry align="left" valign="top">PC Multilingual</entry>
</row>
<row>
<entry align="left" valign="top"><para>Central Europe</para></entry>
<entry align="left" valign="top"><para>ISO-8859-2</para></entry>
<entry align="left" valign="top"><para>ISO Latin 2</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Cyrillic</para></entry>
<entry align="left" valign="top"><para>ISO-8859-5</para></entry>
<entry align="left" valign="top"><para>ISO Latin/Cyrillic</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Arabic</para></entry>
<entry align="left" valign="top"><para>ISO-8859-6</para></entry>
<entry align="left" valign="top"><para>ISO Latin/Arabic</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-ARABIC8</para></entry>
<entry align="left" valign="top"><para>HP Arabic8</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>IBM-1046</para></entry>
<entry align="left" valign="top"><para>PC Arabic</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Hebrew</para></entry>
<entry align="left" valign="top"><para>ISO-8859-8</para></entry>
<entry align="left" valign="top"><para>ISO Latin/Hebrew</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-HEBREW8</para></entry>
<entry align="left" valign="top"><para>HP Hebrew8</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>IBM-856</para></entry>
<entry align="left" valign="top"><para>PC Hebrew</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Greek</para></entry>
<entry align="left" valign="top"><para>ISO-8859-7</para></entry>
<entry align="left" valign="top"><para>ISO Latin/Greek</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP GREEK8</para></entry>
<entry align="left" valign="top"><para>HP Greek8</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Turkish</para></entry>
<entry align="left" valign="top"><para>ISO-8859-9</para></entry>
<entry align="left" valign="top"><para>ISO Latin 5</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-TURKISH8</para></entry>
<entry align="left" valign="top"><para>HP Turkish8</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Japanese</para></entry>
<entry align="left" valign="top"><para>EUC-JP</para></entry>
<entry align="left" valign="top"><para>Japanese EUC (JISX0201, JISX0208, JISX0212)
</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-SJIS</para></entry>
<entry align="left" valign="top"><para>HP Japanese Shift JIS</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-KANA8</para></entry>
<entry align="left" valign="top"><para>HP Japanese Katakana8 (JISX0201 1976)
</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>IBM-932</para></entry>
<entry align="left" valign="top"><para>PC Japanese Shift JIS</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Korean</para></entry>
<entry align="left" valign="top"><para>EUC-KR</para></entry>
<entry align="left" valign="top"><para>Korean EUC</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Chinese</para></entry>
<entry align="left" valign="top"><para>EUC-CN</para></entry>
<entry align="left" valign="top"><para>Simplified Chinese EUC (China) (GB2312)
</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>EUC-TW</para></entry>
<entry align="left" valign="top"><para>Traditional Chinese EUC (Taiwan) (CNS
11643.*)</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-BIG5</para></entry>
<entry align="left" valign="top"><para>HP Traditional Chinese Big5</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-CCDC</para></entry>
<entry align="left" valign="top"><para>HP Traditional Chinese CCDC</para></entry>
</row>
<row>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><para>HP-15CN</para></entry>
<entry align="left" valign="top"><para>HP Traditional Chinese EUC</para></entry>
</row>
<row>
<entry align="left" valign="top"><para>Thai</para></entry>
<entry align="left" valign="top"><para>TIS-620</para></entry>
<entry align="left" valign="top"><para>Thai</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>When writing DocBook files, you may use multibyte characters for any
help text, but the DocBook markup itself (tag names, entity names, IDs, and
so on) must be entered using eight-bit characters.</para>
</sect2>
<sect2 id="HRDC.Lang.div.8">
<title>DocBook Software</title>
<para>When you process a help volume to create run-time help files, the DocBook
software must be told what language and character set you used to author your
files. The language and character set information is used to determine the
proper fonts for displaying help topics. If you do not specify a language
and character set, DocBook assumes the default, which is English and ISO-8859-1.
</para>
<para>The language and character set can be defined in the <systemitem class="environvar">LANG</systemitem> environmental variable, or by using the Lang attribute of
Part.</para>
<note>
<para>When writing DocBook files, you may use multibyte characters for any
help text. However, the DocBook markup itself (tag names, entity names, IDs,
and so on) must be entered using eight-bit characters.</para>
</note>
</sect2>
<sect2 id="HRDC.Lang.div.9">
<title id="HRDC.Lang.mkr.8">DtHelp</title>
<para>The menus, buttons, and labels that appear in help dialogs should also
be displayed in the user's native language. To enable this, Help dialogs read
such strings from a <emphasis>message catalog</emphasis> named <filename>DtHelp.cat</filename>. The message catalog source file,
<filename>DtHelp.msg</filename>, contains strings for menus, buttons, and messages. If the language
you need is not supplied, you must translate the sample message catalog
(<filename>/usr/dt/dthelp/nls/C/DtHelp.msg</filename>) and then use the <command>gencat</command> command to create the run-time message catalog file. See <xref
role="SecTitleAndPageNum" linkend="HRDC.Lang.mkr.16"> for instructions.</para>
<para>Refer to your system documentation to determine the correct directory
where your new message catalog should be installed.</para>
</sect2>
<sect2 id="HRDC.Lang.div.10">
<title id="HRDC.Lang.mkr.9">LANG Environment Variable</title>
<para>The user's <systemitem class="environvar">LANG</systemitem> environment
variable is important for two reasons:</para>
<itemizedlist><listitem><para>The value of <systemitem class="environvar">LANG</systemitem> is used to locate the correct help volume.</para>
</listitem><listitem><para>When a help topic is displayed, the correct fonts
and formatting rules are chosen based on the user's <systemitem class="environvar">LANG</systemitem> variable. This is especially important for Asian languages
that have word-wrap rules that are more sophisticated than European and American
languages.</para>
</listitem></itemizedlist>
<sect3 id="HRDC.Lang.div.11">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><citetitle>Internationalization
Programmer's Guide</citetitle></para>
</listitem><listitem><para>NLS documentation for your computer's operating
system or programmer's kit</para>
</listitem></itemizedlist>
</sect3>
</sect2>
<sect2 id="HRDC.Lang.div.13">
<title>Formatting Tables</title>
<para>A multibyte language, such as Japanese or Chinese, requires a <emphasis>formatting table</emphasis>. This table specifies a list of characters that
cannot start a line and those characters that cannot end a line. When help
files are processed, the formatting table ensures that lines wrap correctly. <xref
role="SecTitleAndPageNum" linkend="HRDC.Lang.mkr.14"> explains how to create
a new table or edit the sample table provided in the Help Developer's Kit.
</para>
</sect2>
<sect2 id="HRDC.Lang.div.14">
<title>Font Schemes</title>
<para>One of the primary functions of the DocBook software is to convert your
marked-up files into a run-time format that the Help System understands. Text
is formatted by specifying particular attributes such as type family, size,
slant, and weight. A <emphasis>font scheme</emphasis> is simply a name, like
an alias, that the Help System uses to assign fonts to DocBook elements such
as heads, procedures, lists, and so forth. It provides a way to map a group
of text attributes used by the Help System with specific fonts.</para>
<para>Applications that use the standard Common Desktop Environment fonts
do not need to define additional font resources. If your application relies
on a different set of fonts, you must create and add a font scheme to your
application.</para>
<sect3 id="HRDC.Lang.div.15">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><filename moreinfo="RefEntry">DtStdInterfaceFontNames(5)</filename> man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtStdAppFontNames
(5)</filename> man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Lang.div.16">
<title id="HRDC.Lang.mkr.11">Understanding Font Schemes</title>
<para>When you write a help volume using the DocBook markup language, you
don't specify the fonts and sizes of the text. When you run the DocBook software,
the elements that you've entered are formatted into run-time help files that
include text attributes.</para>
<para>A <emphasis>font scheme</emphasis> maps text attributes to actual font
specifications. For example, if a help topic is formatted using a bold, sans
serif typeface, the font scheme identifies which Common Desktop Environment
standard font or X font is actually used to display the text.</para>
<para>One of the primary uses of font schemes is to provide a choice of font
sizes. The DocBook software formats the body of most topics as 10-point text.
However, because the actual display font is determined by the font scheme
being used, all 10-point text could be specified to use a 14-point font.</para>
<sect2 id="HRDC.Lang.div.17">
<title id="HRDC.Lang.mkr.12">Font Resources</title>
<para>Each font scheme is actually a set of X resources. These resources are
read by the application displaying the help. If you want to change the font
scheme, you can set font resources in your application's application defaults
file.</para>
<para>Each resource within a font scheme has this general form:</para>
<para>*<symbol role="Variable">pitch</symbol>.<symbol role="Variable">size</symbol>.<symbol role="Variable">slant</symbol>. <symbol role="Variable">weight</symbol>.<symbol role="Variable">style</symbol>. <symbol role="Variable">lang</symbol>.<symbol role="Variable">char-set</symbol>: <symbol role="Variable">font specification</symbol></para>
<para>Where:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="116*">
<colspec align="left" colwidth="412*">
<tbody>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">pitch</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the horizontal spacing of
characters. This field should be either <command>p</command> (proportional)
or <command>m</command> (monospace).</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">size</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the height of the desired
font. For help files formatted with DocBook, this value should be <symbol>6</symbol>, <symbol>8</symbol>, <symbol>10</symbol>, <symbol>12</symbol>,
or <symbol>14</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">slant</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the slant of the desired
font. Usually this field is either <command>roman</command> for upright letters
or <command>italic</command> for slanted letters</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">weight</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the weight of the desired
font. Usually this field is either <command>medium</command> or <command>bold</command>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">style</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the general style of the
desired font. For help files formatted with DocBook, this value should be
either <symbol>serif</symbol> or <symbol>sans_serif</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">lang</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies that volumes compiled using
this language should use these fonts. Usually the entry uses an * (asterisk)
so that all volumes using the specified <symbol role="Variable">char_set</symbol>
will use these fonts.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">char-set</symbol></para></entry>
<entry align="left" valign="top"><para>Specifies the character set used to
author the help text. This value must match the character set that was specified
when DocBook was run. The default is <symbol>ISO-8859-1</symbol>. Some special
characters are displayed using a <command>symbol</command> character set.
</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>An * (asterisk) can be used in a field to specify a font that has any
value of that particular attribute. For instance, the symbol set (for special
characters and special symbols) distinguishes a unique font based only on
size and character set.</para>
<para>Its font resources appear like this within a font scheme:</para>
<programlisting>*.6.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-60-*-*-
p-*-adobe-fontspecific
*.8.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-80-*-*-
p-*-adobe-fontspecific
*.10.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-100-*-
*-p-*-adobe-fontspecific
*.12.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-120-*-
*-p-*-adobe-fontspecific
*.14.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-140-*-
*-p-*-adobe-fontspecific</programlisting>
<para>The <symbol>char-set</symbol> field is the only field that cannot use
the * (asterisk).</para>
<para>To display multibyte languages, such as Japanese or Korean, font resources
must be specified using a font set. A font set is actually a group of fonts.
A resource entry for a font set is similar to a single font, except that a
, (comma) separates multiple font names and the specification ends with a
: (colon). Here is an example of a fully specified font resource for a Japanese
font set.</para>
<programlisting>bridge-gothic-medium-r-normal--18-180-75-75-c-80-jisx0201.1976-0,
bridge-gothic-medium-r-normal--18-180-75-75-c-160-jisx0208.1983-0,
bridge-gothic-medium-r-normal--18-180-75-75-c-160-jisx0212.1990-0:</programlisting>
<para>You can also specify fonts for a multibyte language by providing a minimal
XLFD font specification and allowing the system to supply the character set
value to produce a font set.</para>
<programlisting>*.12.roman.medium.*.ja_JP.EUC-JP: -*-*-*-*-*-*-*-120-*-*-*-*-*-*:
</programlisting>
<para>When specifying a font set, remember to end the specification with a
: (colon). This instructs the Help System to load a set of fonts to display
the information. Font sets are used to display multibyte languages. For volumes
containing single-byte information, use the standard font specification.</para>
<sect3 id="HRDC.Lang.div.18">
<title>Sample Font Schemes</title>
<para>The <filename>/usr/dt/dthelp/fontschemes</filename> directory contains
four font schemes:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="165*">
<colspec align="left" colwidth="363*">
<tbody>
<row>
<entry align="left" valign="top"><para><computeroutput>fontDef.fns</computeroutput></para></entry>
<entry align="left" valign="top"><para>Default fonts used by the Help System
</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><computeroutput>fontLarge.fns</computeroutput></para></entry>
<entry align="left" valign="top"><para>Example of a larger font</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><computeroutput>fontMulti.fns</computeroutput></para></entry>
<entry align="left" valign="top"><para>Example of a multi-byte font</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><computeroutput>fontX11.fns</computeroutput></para></entry>
<entry align="left" valign="top"><para>Example of standard X11 fonts</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect3>
</sect2>
<sect2 id="HRDC.Lang.div.19" role="Procedure">
<title id="HRDC.Lang.mkr.13">To Choose a Font Scheme</title>
<para>Edit the application-defaults file for the application that displays
the online help. Replace the current font resources (if any) with the new
scheme.</para>
<para>If you are making this change just for yourself, copy the application-defaults
file into your home directory before editing it.</para>
<sect3 id="HRDC.Lang.div.20">
<title>Example</title>
<para>To use a larger size font (in the help dialogs) of a personal application
named <filename>DtStopWatch</filename>, perform these steps:</para>
<para>Change to your home directory:</para>
<programlisting>cd</programlisting>
<para>Then copy the <filename>DtStopWatch</filename> application-defaults
file and make it writable:</para>
<programlisting>cp /usr/dt/app-defaults/C/DtStopWatch.
chmod u+w DtStopWatch</programlisting>
<para>Edit the <filename>DtStopWatch</filename>file to add the largest scheme
(<filename>fontLarge.fns</filename>. Go to the end of the file, and insert
the contents of this file:</para>
<para><filename>/usr/dt/dthelp/fontschemes/fontLarge.fns</filename></para><?Pub Caret>
<para>Save your new <filename>DtStopWatch</filename> file.</para>
<para>Start the <filename>DtStopWatch</filename> application, select Help,
and verify that help topics are displayed using the new font scheme.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Lang.div.21">
<title id="HRDC.Lang.mkr.14">Creating a Formatting Table</title>
<para>A multibyte language, such as Japanese or Chinese, requires a <emphasis>formatting table</emphasis>. This table contains three message sets. The first
set consists of characters that cannot start a line; the second set lists
any characters that cannot end a line; and the third set indicates how to
handle newline characters that occur between a single-byte and a multibyte
character.</para>
<para>A formatting table is an ASCII file whose file name must end with a
<filename>.msg</filename> extension. <xref role="CodeOrFigureOrTable" linkend="HRDC.Lang.mkr.15">
shows an excerpt from a formatting table for Simplified Chinese.</para>
<figure>
<title id="HRDC.Lang.mkr.15">Sample formatting table</title>
<graphic id="HRDC.Lang.grph.1" entityref="HRDC.Lang.fig.1"></graphic>
</figure>
<para>Any line that begins with a $ (dollar sign) followed by a space is a
comment.</para>
<sect2 id="HRDC.Lang.div.22">
<title>Sample Formatting Table</title>
<para>A sample formatting table for a multibyte character set is located in
the <filename>/usr/dt/dthelp/nls/zh_CN.dt-eucCN</filename>directory and is
named <filename>fmt_tbl.msg.</filename></para>
<para>The sample table can be modified by adding or removing characters. To
edit the formatting table, use an editor capable of composing characters in
the language you have chosen for the help information. If you intend to create
help information using a multibyte language, you need to create a formatting
table.</para>
</sect2>
<sect2 id="HRDC.Lang.div.23" role="Procedure">
<title id="HRDC.Lang.mkr.16">To Create a Message Catalog</title>
<para>If you translate the <filename>DtHelp.msg</filename> file, create a
new formatting table, or modify the sample table (<filename>fmt_tbl.msg</filename>),
you must update the message catalog used by the Help System.</para>
<para>Use this command syntax to generate the catalog file:</para>
<para><command>gencat</command> <symbol>file</symbol><filename>.cat</filename> <symbol>file</symbol><filename>.msg</filename></para>
<para>Message catalogs for the standard desktop applications are located in
the <filename>/usr/dt/lib/nls/msg/</filename><symbol>lang</symbol> directory.
To install a message catalog, refer to your operating system documentation
for guidelines.</para>
<sect3 id="HRDC.Lang.div.24">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><command>gencat</command>(1)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.Lang.div.25">
<title id="HRDC.Lang.mkr.17">Displaying a Localized Help Volume</title>
<para>To view a help volume created for a locale different from your current
system, you must set your <systemitem class="environvar">LANG</systemitem>
environment variable to match the help volume. The value of the <systemitem class="environvar">LANG</systemitem> environment variable is platform-specific.
If you are not familiar with this variable, check with your system administrator
for the correct value and procedure to set your environment.</para>
</sect1>
<sect1 id="HRDC.Lang.div.26">
<title id="HRDC.Lang.mkr.18">Preparing Online Help for International Audiences</title>
<para>The following checklist summarizes the questions you should answer when
providing online help for international audiences.</para>
<itemizedlist remap="Bullet1"><listitem><para>Are help topics written with
an international audience in mind?</para>
</listitem><listitem><para>Was the DocBook software run using the correct <systemitem class="environvar">LANG</systemitem> setting? If you author in another character
set, you may have to translate the <filename>DtHelp.msg</filename> message
catalog file and provide a font scheme that supports the new character set.
</para>
</listitem><listitem><para>Within your DocBook markup, are all tag names,
entity names, and IDs entered using an eight-bit character set, even if the
help text uses multibyte characters?</para>
</listitem><listitem><para>When the user's <systemitem class="environvar">LANG</systemitem> environment variable is set to the correct language, are
the help files installed so they are found and displayed appropriately?</para>
</listitem><listitem><para>If you have integrated the Help System into an
application, have you properly set the locale using the <function>XtSetLanguageProc()</function> function?</para>
</listitem></itemizedlist>
<sect2 id="HRDC.Lang.div.27">
<title>See Also</title>
<itemizedlist remap="Bullet1"><listitem><para><xref role="HeadingAndPage"
linkend="HRDC.Inst.mkr.11"></para>
</listitem><listitem><para><command>XtSetLanguageProc</command>(3) man page
</para>
</listitem><listitem><para><command>gencat</command>(1) man page</para>
</listitem><listitem><para>NLS documentation for your computer's operating
system or programmer's kit</para>
</listitem></itemizedlist>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

406
cde/doc/en_US.UTF-8/guides/helpGuide/glossary.sgm Normal file
View File

@@ -0,0 +1,406 @@
<!-- $XConsortium: glossary.sg
/main/1 1996/01/07 20:10:08 vobad
$ -->
<!-- (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. -->
<glossary id="HRDC.Gloss.div.1">
<title>Glossary</title>
<glossentry><glossterm>application help</glossterm>
<glossdef>
<para>Online help for a particular application (software).</para>
</glossdef>
</glossentry>
<glossentry><glossterm>application-defined link</glossterm>
<glossdef>
<para>A hyperlink designed especially for invoking some application behavior.
To invoke the behavior, the help must be displayed in dialogs created by the
application. (Application-defined hyperlinks are ignored by Helpview.)</para>
</glossdef>
</glossentry>
<glossentry><glossterm>automatic help</glossterm>
<glossdef>
<para>Help presented by the syste as the result of a particular condition
or error. Sometimes called &ldquo;syste initiated&ldquo; help. For example,
error dialogs are a for of &ldquo;automatic help.&rdquo; See also <emphasis>semi-automatic help</emphasis> and <emphasis>manual help</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>caution</glossterm>
<glossdef>
<para>A warning to the user about possible loss of data. See also <emphasis>note</emphasis> and <emphasis>warning</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>close callback</glossterm>
<glossdef>
<para>An application function called when a help dialog box is closed.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>context-sensitive help</glossterm>
<glossdef>
<para>Online information that is relevant to what the user is doing within
an application. Sometimes, pressing the F1 key is referred to as &ldquo;context-sensitive
help&rdquo; because the choice of help topic is based on the user's context.
</para>
</glossdef>
</glossentry>
<glossentry><glossterm>cross-volume hyperlink</glossterm>
<glossdef>
<para>A hyperlink that jumps to a topic in a different help volume. Cross-volume
hyperlinks are entered using the Link element, where the Linkend attribute
specifies the ID of the element that is being linked to:</para>
<programlisting>&lt;link lnkend="some-id">&lt;/link></programlisting>
</glossdef>
</glossentry>
<glossentry><glossterm>dialog cache</glossterm>
<glossdef>
<para>A list of help dialogs that has been created but may not be in use.
When the application needs a new help dialog, it first searches its dialog
cache for an unused dialog. If one is found, it is used. Otherwise, all dialogs
are in use, so a new one is created.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>Document Type Definition</glossterm>
<glossdef>
<para>A description of a set of elements used to create a structured (or hierarchical)
information. The Document Type Definition (DTD) specifies the syntax for
each element and governs how and where elements can be used in a document.
</para>
</glossdef>
</glossentry>
<glossentry><glossterm>element</glossterm>
<glossdef>
<para>A logical portion of information, such as a book title, a paragraph,
a list, or a topic. Normally, the extent of an element is marked by <emphasis>tags</emphasis>, although the tags for some elements are assumed by context.
</para>
</glossdef>
</glossentry>
<glossentry><glossterm>emphasis</glossterm>
<glossdef>
<para>An element of text that calls attention to the text (usually by being
formatted as <emphasis>italic</emphasis>).</para>
</glossdef>
</glossentry>
<glossentry><glossterm>entity</glossterm>
<glossdef>
<para>A text string or file with a name. Most entities are named by the author
(using the &lt;!Entity> element), but some entities are predefined. See also <emphasis>entity declaration</emphasis> and <emphasis>entity reference</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>entity declaration</glossterm>
<glossdef>
<para>Markup that establishes an entity name and its value. See also <emphasis>entity</emphasis> and <emphasis>entity reference</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>entity reference</glossterm>
<glossdef>
<para>Use of an entity name preceded by an &amp; (ampersand) and followed
by a; (semicolon) that indicates to DocBook that the entity is to be inserted
where the entity name appears. See also <emphasis>entity</emphasis> and <emphasis>entity declaration</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>entry point</glossterm>
<glossdef>
<para>A point within a help volume that may be displayed directly as the result
of a request for help. That is, a topic where the user may &ldquo;enter&rdquo;
or begin reading online help. Any topic, or location within a topic, that
has an ID can become an entry point.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>example listing</glossterm>
<glossdef>
<para>A body of text in which line breaks are left as they are and which is
displayed in a computer font. The text is typically an example of a portion
of a computer file.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>execution alias</glossterm>
<glossdef>
<para>A resource that assigns a name to a command string or script that an
execution link executes.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>execution link</glossterm>
<glossdef>
<para>A hyperlink that executes a shell command or script. In DocBook, the
OLink element is the mechanism for this.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>execution policy</glossterm>
<glossdef>
<para>The Help Syste provides a resource that can be set to control the behavior
of execution links. This enables a syste administrator or user to establish
an appropriate level of security for any given application.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>figure</glossterm>
<glossdef>
<para>A graphic or illustration that appears in the help information.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>formal markup</glossterm>
<glossdef>
<para>A tag set and accompanying usage rules that are specified in the DocBook
2.2.1 Document Type Defnition (DTD). By following the rules set forth in the
DTD, an author can produce Standard Generalized Markup Language (SGML) compliant
help source files.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>general help dialog box</glossterm>
<glossdef>
<para>A window in which help information is displayed. General help dialog
boxes have a menu bar, a topic tree (which provides a list of topics), and
a help topic display area. See also <emphasis>quick help dialogbox</emphasis>.
</para>
</glossdef>
</glossentry>
<glossentry><glossterm>help callback</glossterm>
<glossdef>
<para>An application function called when the user presses the F1 key.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>help family</glossterm>
<glossdef>
<para>A set of help volumes that are related to one another because the applications
they refer to are related.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>help key</glossterm>
<glossdef>
<para>A designated key, usually the F1 function key, used to request help
on the current context. Some keyboards have a dedicated Help key that may
take the place of F1. In Motif applications, the help key is enabled by
adding a help callback to a widget.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>help on help</glossterm>
<glossdef>
<para>Help information about how to use the help dialog boxes. The user gets
this information by pressing F1 while using a help window, or by choosing
Using Help fro the Help menu in a general help dialog box.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>help volume</glossterm>
<glossdef>
<para>A complete body of information about a subject. Also, this ter can refer
to either the set of source files that contain the marked-up text or the run-time
files generated by running DocBook.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>History dialog box</glossterm>
<glossdef>
<para>A dialog box that shows a list of the sequence of topics the user has
visited. The history sequence can be traversed in reverse order to make it
easy for the user to return to earlier topics.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>hyperlink</glossterm>
<glossdef>
<para>A segment of text (word or phrase) or graphic image that has some behavior
associated with it. The most common type of hyperlink is a &ldquo;jump&rdquo;
link, which connects to a related topic. When the user chooses a jump link,
the related topic is displayed. Hyperlinks can also be used to invoke other
kinds of behavior, such as executing a syste command or invoking specific
application behavior.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>hyperlink callback</glossterm>
<glossdef>
<para>An application function that is invoked when a user chooses a hyperlink.
This function is responsible for handling the types of hyperlinks not handled
automatically within the help dialog.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>index</glossterm>
<glossdef>
<para>A list of important words and phrases that appear throughout a help
volume. The index is an alphabetical list of the words or phrases that can
be searched to find help on a subject. The Help Syste displays the index when
the user chooses the Index button (in a general help dialog box). See also <emphasis>Index Search dialog box.</emphasis></para>
</glossdef>
</glossentry>
<glossentry><glossterm>Index Search dialog box</glossterm>
<glossdef>
<para>A dialog box that shows a list of index entries for a help volume. An
index can be displayed for the current volume, selected volumes, or all help
volumes. A user can search the index for a word or phrase and any corresponding
topics that contain the search string will be listed.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>index volume</glossterm>
<glossdef>
<para>The desktop uses the Helpview progra as a &ldquo;help browser&rdquo;
by displaying a special indexvolume that lists the help installed on the system.
A utility called <command>dthelpgen</command> creates this volume in the user's
home directory.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>inline graphic</glossterm>
<glossdef>
<para>A small graphic (illustration) that appears within a line of text.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>jump-new-view hyperlink</glossterm>
<glossdef>
<para>A hyperlink that, when chosen, displays its information in a new dialog
box. Jump-new-view links are intended for cross-volume links. The user senses
a &ldquo;new context&rdquo; by a new window being displayed.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>man page link</glossterm>
<glossdef>
<para>A hyperlink that, if activated, displays a &ldquo;man page,&rdquo; which
is a brief online explanation of a system command. The information in man
pages are not supplied through the DocBook system.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>manual help</glossterm>
<glossdef>
<para>A style of online help that requires the user to know what help is needed
and how to get it. For example, most commands in a Help menu are considered
&ldquo;manual&rdquo; help because the user chooses when and what to view.
See also <emphasis>automatic help</emphasis> and <emphasis>semi-automatic
help</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>note</glossterm>
<glossdef>
<para>A message to the user that draws attention to important information.
If the information is critically important, a caution or warning is used instead.
See also <emphasis>caution</emphasis> and <emphasis>warning</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>parser</glossterm>
<glossdef>
<para>The portion of the DocBook software that reads the source files (which
are created by the author) and converts the into run-time help files that
the Help Syste dialogs can read. If the author uses markup incorrectly (or
incompletely), the parser detects the problems and indicates that &ldquo;parser
errors&rdquo; have occurred.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>quick help dialog box</glossterm>
<glossdef>
<para>A streamlined help dialog box that has a help topic display area and
one or more push buttons. See also <emphasis>general help dialog box</emphasis>,
which offers additional capabilities.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>registration</glossterm>
<glossdef>
<para>The process of declaring a help volume to be accessible for browsing
or cross- volume linking.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>run-time help files</glossterm>
<glossdef>
<para>The files generated by the <command>dtdocbook</command> command. These
are the files distributed to users who will use the Help System.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>Search Volume Selection dialog box</glossterm>
<glossdef>
<para>A dialog box that lists the help volumes available on a user's system.
When a user chooses Selected fro the Index Search dialog box, this dialog
box lists help volumes that the user can select. One or more volume names
can be selected and the corresponding index information is reported in the
Index Search dialog box.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>semi-automatic help</glossterm>
<glossdef>
<para>A style of online help in which the user requests help and the system
decides, based on the current circumstances, which help information to display. &ldquo;Context-sensitive&rdquo;
help (pressing the F1 key) is an example of semi-automatic help. See also <emphasis>automatic help</emphasis> and <emphasis>manual help</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>standalone help</glossterm>
<glossdef>
<para>Help information intended to be used independently of application software.
For example, online help that explains the basics of computer programming
may not be associated with a particular application. A standalone help volume
can be displayed using the <command>dthelpview</command> command.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>Standard Generalized Markup Language (SGML)</glossterm>
<glossdef>
<para>An international standard [ISO 8879: 1986] that establishes a method
for information interchange. SGML prescribes constructs for marking the structure
of information separate fro its intended presentation or format. The DocBook
markup language conforms to this SGML standard.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>tag</glossterm>
<glossdef>
<para>A text string that marks the beginning or end of an element. A start
tag consists of a &lt; (left angle bracket) followed by a special character
string (consisting of only letters), optional attributes and values, and terminated
by a > (right angle bracket).</para>
<para>An end tag consists of a &lt; (left angle bracket), a / (forward slash),
the same special character string, and a > (right angle bracket).</para>
</glossdef>
</glossentry>
<glossentry><glossterm>Tagged Image File Format (TIFF)</glossterm>
<glossdef>
<para>A standard graphics file format. The Help Syste dialog boxes support
TIFF 5.0 images. TIFF images are identified by the <filename>.tif</filename>
file-name extension.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>topic</glossterm>
<glossdef>
<para>Information about a specific subject. Usually, this is approximately
one screenful of information. Online help topics are linked to one another
through hyperlinks.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>topic hierarchy</glossterm>
<glossdef>
<para>A help volume's branching structure in which the home topic branches
out (through hyperlinks) to progressively more detailed topics. See also <emphasis>home topic</emphasis>.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>topic tree</glossterm>
<glossdef>
<para>In a general help dialog box, a list of topics that can be selected
to display help information.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>warning</glossterm>
<glossdef>
<para>Information that warns the user about possible injury or unrecoverable
loss of data. See also <emphasis>caution</emphasis> and <emphasis>note</emphasis>.
</para>
</glossdef>
</glossentry>
<glossentry><glossterm>widget</glossterm>
<glossdef>
<para>The fundamental building block of graphical user interfaces. The Motif
widget set provides widgets of all sorts, suitable for constructing an application
user interface.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>X bitmap</glossterm>
<glossdef>
<para>A two-tone image that has one foreground color and one background color.
Bitmap image files are identified by the<filename>.bm</filename> file-name
extension.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>X pixmap</glossterm>
<glossdef>
<para>A multicolor image. Pixmap image files are identified by the <filename>.pm</filename> file-name extension.</para>
</glossdef>
</glossentry>
<glossentry><glossterm>X window dump</glossterm>
<glossdef>
<para>An image captured from an X Window System<?Pub Caret> display. The <command>xwd</command> utility is used to capture a window image. X window dump image
files are identified by the <filename>.xwd</filename> file-name extension.
</para>
</glossdef>
</glossentry>
</glossary>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/Approot.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/BldInst.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/BuildDir.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/CharEntU.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/CharEntV.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExAnnot.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExBuList.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExCautio.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExComput.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExEx.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExHTopic.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExInliGr.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExKeycap.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExLaLstH.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExLaNowr.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExLalst1.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExLalstW.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExListHd.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExLists.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExNoteHd.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExNuList.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExOthrHd.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExPHead.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExProc2.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExProced.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExTHyper.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExVex.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExWrapGr.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ExXref.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/FMCompil.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/FMhelpfs.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/FPanel.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/FmtTable.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/GHelpLB.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/GenHelp.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/GrEntity.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/HelpMenu.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/HelpMgr.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/HelpOrg.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/HelpVol.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/HyperFmt.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/Icons.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/IndexNum.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/IndxSrch.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/PrintDlg.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/Process.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/QuickHlp.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/Topics.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/en_US.UTF-8/guides/helpGuide/graphics/ViewVol.tif Normal file
View File

Binary file not shown.

10
cde/doc/en_US.UTF-8/guides/helpGuide/part1.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part1.sgm /main/1 1996/01/23 18:29:12 vobadm $ -->
<!-- (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. -->
<Title>Introduction</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

10
cde/doc/en_US.UTF-8/guides/helpGuide/part2.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part2.sgm /main/1 1996/01/23 18:29:40 vobadm $ -->
<!-- (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. -->
<Title>The Author's Job</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

10
cde/doc/en_US.UTF-8/guides/helpGuide/part3.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part3.sgm /main/1 1996/01/23 18:30:08 vobadm $ -->
<!-- (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. -->
<Title>The Programmer's Job</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

10
cde/doc/en_US.UTF-8/guides/helpGuide/part4.sgm Normal file
View File

@@ -0,0 +1,10 @@
<!-- $XConsortium: part4.sgm /main/1 1996/01/23 18:30:35 vobadm $ -->
<!-- (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. -->
<Title>Internationalization</Title>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->

150
cde/doc/en_US.UTF-8/guides/helpGuide/preface.sgm Normal file
View File

@@ -0,0 +1,150 @@
<!-- $XConsortium: preface.sgm /main/12 1996/09/08 19:41:20 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. -->
<preface id="HRDC.Pref.div.1">
<title>Preface</title>
<para>This manual describes how to develop online help for Common Desktop
Environment application software. It covers how to create help topics and
how to integrate online help into a Motif&trade; application.</para>
<sect1 id="HRDC.Pref.div.2">
<title>Who Should Use This Book</title>
<para>The audience for this book includes:</para>
<itemizedlist remap="Bullet1"><listitem><para>Authors who design, create,
and view online help information</para>
</listitem><listitem><para>Developers who want to create software applications
that provide a fully integrated help facility</para>
</listitem></itemizedlist>
</sect1>
<sect1 id="HRDC.Pref.div.3">
<title>How This Book Is Organized</title>
<para>This book has four parts. Part 1 describes the collaborative role that
authors and developers undertake to design application help. Part 2 provides
information for authors organizing and writing online help. Part 3 describes
the Help System application programmer's toolkit. Part 4 contains information
for both authors and programmers about preparing online help for different
language environments.</para>
<para>This book includes these chapters:</para>
<para>Part 1&mdash; Introduction</para>
<para><!--Original XRef content: 'Chapter&numsp;1, &ldquo;Introducing the
Help System'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.Intro.mkr.1"><emphasis
role="Lead-in">,</emphasis> provides an overview of authors' and developers'
collaborative role in producing online help.</para>
<para>Part 2&mdash; The Author's Job</para>
<para><literal><!--Literal closed to allow XRef:--></literal> <!--Original
XRef content: 'Chapter&numsp;2, &ldquo;Organizing and Writing a Help Volume'--><xref
role="ChapNumAndTitleLead-in" linkend="HRDC.OrgH.mkr.1"><emphasis role="Lead-in">
,</emphasis> describes the components that make up a help volume.</para>
<para><!--Original XRef content: 'Chapter&numsp;3, &ldquo;Writing a Help
Topic'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.WrTop.mkr.1"><emphasis
role="Lead-in">,</emphasis> introduces the Help System markup language and
gives examples of elements used to format different types of information.
It describes how to include graphics and create hyperlinks.</para>
<para><!--Original XRef content: 'Chapter&numsp;4, &ldquo;Processing and
Displaying a Help Volume'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.CrHV.mkr.1"><emphasis
role="Lead-in">,</emphasis> describes how to process a marked-up file (or
files) to generate a single run-time file for online viewing.</para>
<para>The <citetitle>Guide to the DocBook DTD</citetitle><?Pub Caret> lists
in alphabetical order the DocBook markup language elements, and describes
their use.</para>
<para><!--Original XRef content: 'Chapter&numsp;6, &ldquo;Summary of Special
Character Entities'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.ChEnt.mkr.1"><emphasis
role="Lead-in">,</emphasis> provides a list of characters and associated entity
names that can be used to insert special characters into help topic text.
</para>
<para><!--Original XRef content: 'Chapter&numsp;7, &ldquo;Command Summary'--><xref
role="ChapNumAndTitleLead-in" linkend="HRDC.CmdS.mkr.1"><emphasis role="Lead-in">
,</emphasis> summarizes how to process and view a help volume by entering
commands in a terminal emulator window.</para>
<para><!--Original XRef content: 'Chapter&numsp;8, &ldquo;Reading the DocBook
Document Type Definition'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.Sgml.mkr.1"><emphasis
role="Lead-in">,</emphasis> describes the DocBook DTD and how to use it to
create fully compliant Standard Generalized Markup Language (SGML) help files.
</para>
<para>Part 3&mdash; The Programmer's Job</para>
<para><!--Original XRef content: 'Chapter&numsp;9, &ldquo;Creating and Managing
Help Dialog Boxes'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.CrDia.mkr.1"><emphasis
role="Lead-in">,</emphasis> introduces the Help Dialog widgets and explains
how to use them.</para>
<para><!--Original XRef content: 'Chapter&numsp;10, &ldquo;Responding to
Help Requests'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.HReq.mkr.1"><emphasis
role="Lead-in"></emphasis>, explains how an application provides entry points
to access different types of help.</para>
<para><!--Original XRef content: 'Chapter&numsp;11, &ldquo;Handling Events
in Help Dialogs'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.DiaEv.mkr.1"><emphasis
role="Lead-in">,</emphasis>shows how an application can use a callback structure
to handle hyperlink events.</para>
<para><!--Original XRef content: 'Chapter&numsp;12, &ldquo;Providing Help
on Help'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.H4Hlp.mkr.1"><emphasis
role="Lead-in">,</emphasis> describes how an application can provide a help
module that tells users how to use the Help System.</para>
<para><literal><!--Literal closed to allow XRef:--></literal> <!--Original
XRef content: 'Chapter&numsp;13, &ldquo;Preparing an Installation Package'--><xref
role="ChapNumAndTitleLead-in" linkend="HRDC.Inst.mkr.1"><emphasis role="Lead-in">
,</emphasis> covers what to include in an installation package to supply
online help with an application.</para>
<para>Part 4&mdash; Internationalization</para>
<para><!--Original XRef content: 'Chapter&numsp;14, &ldquo;Native Language
Support'--><xref role="ChapNumAndTitleLead-in" linkend="HRDC.Lang.mkr.1"><emphasis
role="Lead-in">,</emphasis> identifies language-dependent files used by the
Help System.</para>
<para><emphasis role="Lead-in">Glossary</emphasis> is a list of words and
phrases found in this book and their definitions.</para>
</sect1>
<sect1 id="HRDC.Pref.div.4">
<title>Related Books</title>
<para>Related Common Desktop Environment books that you may find helpful are:
</para>
<itemizedlist remap="Bullet1"><listitem><para><citetitle>Advanced User's and
System Administrator's Guide</citetitle></para>
</listitem><listitem><para><citetitle>Internationalization Programmer's Guide</citetitle></para>
</listitem><listitem><para><citetitle>Style Guide and Certification Checklist</citetitle></para>
</listitem><listitem><para><citetitle>User's Guide</citetitle></para>
</listitem><listitem><para><citetitle>Guide to the DocBook DTD</citetitle></para>
</listitem></itemizedlist>
<para>For a technical description of Standard Generalized Markup Language
(SGML), refer to:</para>
<itemizedlist remap="Bullet1"><listitem><para><citetitle>The SGML Handbook</citetitle> by Charles F. Goldfarb, Oxford University Press (ISBN 0-19-853737-9).
</para>
</listitem></itemizedlist>
</sect1>
<sect1 id="HRDC.Pref.div.5">
<title>What Typographic Changes and Symbols Mean</title>
<para>The following table describes the type changes and symbols used in this
book.</para>
<table id="HRDC.Pref.tbl.1" frame="Topbot">
<title>Typographic Conventions</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.21in">
<colspec colwidth="1.77in">
<colspec colwidth="3.04in">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Typeface or Symbol</literal></para></entry><entry align="left" valign="bottom"><para><literal>Meaning</literal></para></entry><entry align="left" valign="bottom"><para><literal>Example</literal></para></entry></row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para><filename>AaBbCc123</filename></para></entry>
<entry align="left" valign="top"><para>The names of commands, files, and
directories; on-screen computer output</para></entry>
<entry align="left" valign="top"><para>Edit your <filename>.login</filename>
file.</para><para>Use <command>ls -a</command> to list all files.</para><para><command>system%</command> <filename moreinfo="RefEntry">You have mail.</filename></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Command-line placeholder:</para><para>replace with a real name or value</para></entry>
<entry align="left" valign="top"><para>To delete a file, type <command>rm</command> <userinput> </userinput><symbol role="Variable">filename.</symbol></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Book titles, new words or terms, or
words to be emphasized</para></entry>
<entry align="left" valign="top"><para>Read Chapter 6 in the <emphasis>User's
Guide</emphasis><userinput>. </userinput>These are called <symbol role="Variable">class</symbol> options.You <emphasis>must</emphasis> be root to do this.</para></entry>
</row></tbody></tgroup></table>
</sect1>
</preface>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
<?Pub *0000014819>