Writing Your First Help Volume: A Step-by-Step Example

Typically you organize your help files in a help directory. This step-by-step example demonstrates how to create and view a standalone help volume. (As a standalone volume, it does not involve interaction with an application.)

To create and process a help volume, you follow these steps:

Create the source directory for help files.
Create the master DocBook file.
Create the run-time help files.
Display the help volume.

Each task is described in the section that follows. The markup language used in the text files is introduced later in this chapter. DocBook markup is described more fully in Chapter 3 “Writing a Help Topic” and in the Guide to the DocBook DTD.

Create the Source Directory

Create a directory named helpfiles where you will create and process your help files.
Create a text file named Commands.sgm in the directory just created.
For this example, all the information is put into a single file. Typically, you will use multiple files to fully explain the system or application you are writing help for.
The Commands.sgm file contains text and element tags. The element tags within the < and > (angle brackets) indicate the structure of the information.

Type the following markup text in the Commands.sgm file.

<Chapter>
<Title id="CommandSummary-id>Command Summary</Title>
<Indexterm><Primary>commands<Primary></Indexterm>
<Para>Your&product; is capable of the following operations:</Para>
<ItemizedList>
<ListItem><Para><Link Linkend="ChannelChange-id">ChannelChange</Link></Para></ListItem>
<ListItem><Para><Link Linkend="VolumeUp-id"> VolumeUp </Link>       </Para></ListItem>
<ListItem><Para><Link Linkend="VolumeDown-id"> VolumeDown </Link></Para></ListItem>
<ListItem><Para><Link Linkend="VolumeMute-id"> VolumeMute </Link></Para></ListItem>
</ItemizedList>
<Para>Choose one of the hyperlinks (underlined phrases)
to find out how to perform that operation.</Para>
<Sect1 id="ChannelChange-s">
<Title id="ChannelChange-t">Changing the Channel</Title>
<Indexterm><Primary>channel<Secondary>changing</Secondary><Primary></Indexterm>
<Para>Speak the command:
<Programlisting> channel</Programlisting>
followed by a number from <Command>one</Command>to <Command>ninety-nine</Command>.</Para>
</Sect1>
<Sect1 id="VolumeUp-s">
<Title id="VolumeUp-t">Turning Up the Volume</Title>
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
<Para>Speak the command:
<Programlisting>volume up</Programlisting></Para>
<Para>For additional volume, speak the command:
<Programlisting>more</Programlisting></para>
<Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link>)</Para>
</Sect1>
<Sect1 id="VolumeDown-s">
<Title id="VolumeDown-t">Turning Down the Volume</Title>
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
<Para>Speak the command:
<Programlisting>volume down</Programlisting></Para>
<Para>To reduce the volume further, speak the command:
<Programlisting>more</Programlisting></Para>
<Para>(See also <Link Linkend="VolumeUp-id"> VolumeUp </Link> and <Link Linkend="VolumeMute-id">VolumeMute</Link>)</Para>
</Sect1>
<Sect1 id="VolumeMute-s">
<Title id="VolumeMute-t">Turning Off the Sound</Title>
<Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
<Indexterm><Primary>sound<Secondary>on/off</Secondary></Primary></Indexterm>
<Para>Speak the command:
<Programlisting>sound off</Programlisting></Para>
<Para>To restore the sound, speak the command:
<Programlisting>sound on</Programlisting></Para>
<Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link> and <Link Linkend="VolumeUp-id">VolumeUp</Link></Para>
</Sect1>
</Chapter>

Create a text file that gives the information a title, provides copyright information, and provides other information about the online help.

In this example, the following text is put into a file called Metainfo.sgm in the same directory as the Commands.sgmfile.

<DocInfo>
 <Title> Using the &product;</Title>
        <AuthorGroup><Author>Jim Jonas</Author>
                </AuthorGroup>
        <Abstract> Help for Using the &product;.
                </Abstract>
        <LegalNotice>
        <BlockQuote>
        <para>&copy; 1995 Voice Activation Company.
        All rights reserved.</para>
        </BlockQuote>
                </LegalNotice>
</DocInfo>

Create the Master DocBook File

Create a text file whose name is of the form volume.sgm. In this example, the file is named voiceact.sgm.
In the voiceact.sgm file, define entities that associate the names of the Commands.sgm and Metainfo.sgm files with entity names. Also, define any entities that are used (either directly or indirectly) in the Commands.sgm and Metainfo.sgm files. Finally, refer to the Commands.sgm and Metainfo.sgm files by their entity names.

In this example, the contents of the voiceact.sgm file look like this. The text within the <!...> elements are comments, which are ignored.

<! Declare an entity for each of the source text files. >
<!entity MetaInformation  FILE "Metainfo">
<!entity Commands   FILE "Commands">
 
<! Define an entity that names the product and includes
        the trademark symbol (&tm;). >
 
<!entity product "VoAc&tm; Voice-Activated Remote Control">
 
<! Include the text files. >
<Part>
&MetaInformation;
&Commands;
</Part>

Create the Run-Time Help Files

Verify that the /usr/dt/bin directory is in your search path by typing this command in a terminal window:
echo $PATH
If the directory is not in your path, add it to your PATH environment variable. If you're not sure how to do this, refer to your system documentation or ask your system administrator.
Open File Manager and change to the helpfiles directory. Select the voiceact.sgm file icon and choose Compile from the Selected menu in File Manager.
This executes the DocBook software which creates a run-time version of your online help volume (voiceact.sdl). Status and error messages are placed in a new file, whose name is of the form volume.log.
Open the voiceact.log file to check that your file processed without errors. If errors occurred, fix them by editing or renaming the text files as needed.




	NOTE: You can run DocBook manually in a terminal window. To do so, execute the following command: dtdocbook voiceact.sgm

Display the Help Volume

From the helpfiles directory, double-click the voiceact.sdl file icon.

This displays the help volume using the desktop Help Viewer. You can now scroll through the information and jump to related information by choosing hyperlinks.




	NOTE: You can run the Help Viewer manually in a terminal window. To do so, execute the following command, which displays the new help volume: dthelpview -h voiceact.sdl

Writing Your First Help Volume: A Step-by-Step Example

Technical documentation

» Table of Contents

» Glossary

» Index

Create the Source Directory

Create the Master DocBook File

Create the Run-Time Help Files

Display the Help Volume

See Also