 |
    
Common Desktop Environment: Help System Author's and Programmer's Guide
2 Organizing and Writing
a Help Volume
Contents of Chapter:
- Help Volume Components
-
- Home Topic
-
- Topics and Subtopics
-
- Entities
-
- Meta Information
-
- Glossary
-
- General Markup Guidelines
-
- Markup in Your Source Files
-
- Displaying HelpTag Symbols
-
- A Help Volume at a Glance
-
- Help Source Files
-
- Creating Your volume.htg File
-
- Help Files in File Manager
-
- Writing Your First Help Volume: A Step-by-Step Example
-
- Create the Source Directory
-
- Create the Build Directory
-
- Create the Master HelpTag File
-
- Create the helptag.opt File
-
- Create the Run-Time Help Files
-
- Display the Help Volume
-
- Creating a Topic Hierarchy
-
 To Create a Home Topic-
- To Add a Topic to the Hierarchy
-
- Creating Meta Information Topics
-
- To Create a Meta Information Section
-
- Adding a Nonhierarchical Topic
-
- To Add a Nonhierarchical Topic
-
- Accessing Topics
-
- Rules for ID Names
-
- To Add an ID to a Topic
-
- Built-in IDs
-
- To Add an ID to an Element within a Topic
-
- Examples
-
- Using Entities
-
- Rules for Entity Declarations
-
- To Create a Text Entity
-
- To Create a File Entity
-
This chapter describes the organization and components of a help source file. It also provides a step-by-step example that shows how to process a help source file to create an online help volume.
A help volume has six major types of components: the home topic, topics, subtopics, entity declarations, meta information, and the glossary.
Home Topic
The home topic is the top-level topic in the topic hierarchy. It is the first topic, or beginning of the help volume. All other topics are subtopics. Your topic hierarchy may be several levels deep. However, to help prevent users from getting lost, you should keep your hierarchy as shallow as possible.
Topics and Subtopics
Topics and subtopics form a hierarchy below the home topic. Typically, the first level of topics following the hometopic are divided into chapters, using the <chapter> element. Within a chapter, topics are organized into sections. Subtopics of an <s1> section are entered with <s2>, subtopics of <s2> entered as <s3>, and so on.
Either element, chapter or section, can follow the home topic. There is no visible difference to the user if you start your hierarchy with <chapter> or <s1>. Figure 2-1 shows a simple hierarchy that includes three chapters. Each chapter contains several first-level sections. The third chapter adds two second-level sections.
Figure 2-1 Help volume topic organization
Entities
An author-defined entity can represent a string of characters or a file name. An entity declaration defines the entity name and the string or file it represents.
Entities are useful for:
- Referencing a common string of text. This is useful if there is some likelihood that the text may change or you simply don't want to type it repeatedly. Each place you want the text inserted, you reference the entity name.
- Referencing an external file. Entities are required for accessing graphics files. The <figure> and <graphic> elements have a required parameter that specifies an entity name, which refers to a graphic image file.
All entity declarations must be entered before any other markup in your help volume. To include an entity that you have defined, you use an entity reference. Entity references can be used anywhere within your help volume. When you process your help volume with the HelpTag software, each entity reference is replaced with the text or file that the entity represents. "Using Entities" describes how to define and use entities.
Meta Information
Meta information is information about your information. It includes information such as the volume's title, copyright notice, and abstract. The abstract is a brief description of the volume's contents.
The Help System uses the meta information to display the title of a help volume and its copyright information. The abstract description is displayed by the desktop Help Viewer in the Front Panel. Other applications capable of displaying help volumes could also make use of this information.
Meta information can also include help topics that are not part of the normal topic hierarchy. Nonhierarchical topics placed in the meta information section are accessed with links.
"Creating Meta Information Topics" shows you how to create a meta information section.
Glossary
The glossary includes definitions for terms that you've used throughout your help volume. If a term is entered using the <term> element, then it automatically becomes a definition link that, when selected, displays the glossary entry for that term.
Online help is written in ordinary text files. You use special codes, or tags, to markup elements within the information. The tags form a markup language called HelpTag. If a standard text editor is used, HelpTag markup is typed. Or, if the editor provides a macro package, tags can be stored and inserted using command keys. HelpTag markup can also be generated using a structured editor (see "Formal Markup").
The HelpTag markup language defines a hierarchy of elements that define high-level elements, such as chapters, sections, and subsections, and low-level elements, such as paragraphs, lists, and emphasized words.
The markup for most elements consists of a start tag and an end tag. Start tags are entered with the element name between angle brackets (< and >). End tags are similar, but the element name is preceded by a \ (backslash).
<element> ... text ... <\element>
For example, to mark the start and end of a book title you use markup like this:
<book>Geographical Survey of Northern Wisconsin<\book>
Where <book> is the start tag, and <\book> is the end tag.
Shorthand Markup
Shorthand markup is a streamlined tag set designed for authors who are using
a standard text editor to "hand-tag" information. Shorthand markup
provides several shortcuts. First, it minimizes the use of end tags.
For example, you do not need to enter end tags for chapters, sections, or
paragraphs. In addition, when possible, intermediate tags are automatically
assumed. For instance, the chapter and section elements allow you to omit a
<head> tag; you just type your headline.
Shorthand markup also simplifies the markup for many inline elements as well as stylistic changes. Rather than entering a begin and end tag, vertical bars are used to delimit the text like this:
<element| ... text ... |
For example, here's the short form of the <book> element shown previously:
<book| Geographical Survey of Northern Wisconsin|
If the element has parameters, they're entered before the first vertical bar like this:
<element parameters| ... text ... |
Some elements support an even shorter form where the start and end tags are replaced with a special two-character shortcut. For example, the <emph> (emphasis) element, whose normal syntax looks like this:
<emph> ... text ... <\emph>
can be entered using this shorthand form:
!! ... text ... !!
Chapter 3, "Writing a Help Topic," introduces shorthand markup and gives examples of the most frequently used elements. Chapter 5, "HelpTag Markup Reference," provides an alphabetical list of elements and describes each element in detail.
Formal Markup
If you intend to use formal markup, you still need to become familiar with the information covered in Part 2 of this book. Then refer to Chapter 8, "Reading the HelpTag Document Type Definition," for a description of formal markup.
At times, you may need to use the < (left angle bracket), the \ (backslash), or the & (ampersand) as text characters. To do so, precede each with an ampersand (&<, &\, or &&).
The following markup illustrates important elements of a help volume and the tags used to enter them. This example uses shorthand markup, which omits intermediate SGML structural tags and minimizes the number of required end tags. Indentation is used to highlight the hierarchical relationship of the elements; you don't need to indent the help files that you write.
All entity declarations go here (before any other markup).
<helpvolume>
<metainfo>
<title> Volume Title
<copyright>
Copyright topic goes here ...
<abstract>
The abstract describing your help volume goes here.
There may be other meta information topics.
.
.
.
<\metainfo>
<hometopic> Home Topic Title
Help volume introduction goes here ...
<s1> Title of First Topic Goes Here
Body of the first topic goes here ...
<s1> Title of Second Topic
Body of the second topic goes here ...
<s2> Title of Suptopic
Body of the subtopic goes here ...
.
.
.
<glossary>
The body of the glossary, which contains term definitions, goes here ...
<\helpvolume>
Online help is written in ordinary text files. You process, or compile, these files with the HelpTag software to create run-time help files that can be read by the Help System.
Creating Your volume.htg File
HelpTag expects a primary control file named volume.htg or volume.ctg, where volume is a name you choose. File extensions are used to distinguish whether the control file references shorthand (.htg) or formal (.ctg) markup.
Be sure your volume name is unique and meaningful. If your volume name is too general, it may conflict with another volume that someone else has created. If you are writing application help, one recommended practice is to use the application's class name. For example, the class name for the Icon Editor is Dticon, so its help volume is named Dticon.htg.
Multiple Source Files
The volume.htg file contains entity declarations and entity references to files that make up the help volume. Although HelpTag expects a single volume.htg file as input, you can separate your work into multiple source files. Additional files are sourced into the volume.htg file using file entities. A file entity is like a pointer to another file. That file, in effect, is inserted wherever the entity's name appears in the volume.htg file. The referenced files can also contain entity references to yet other files. (Entities can also be used to reference text strings.)
Example
Suppose a help volume has six chapters and each chapter is a separate file. The files are: HomeTopic, Metainfo, TOC, Tasks, Reference, and Glossary. The volume.htg file for the help volume includes file entities for each of the six files and a list of entity references that instruct the HelpTag software to process the files.
<!entity HomeTopic FILE "HomeTopic">
<!entity MetaInformation FILE "Metainfo">
<!entity TableOfContents FILE "TOC">
<!entity Tasks FILE "Tasks">
<!entity Reference FILE "Reference">
<!entity Glossary FILE "Glossary">
&HomeTopic;
&MetaInformation;
&TableOfContents;
&Tasks;
&Reference;
&Glossary;
The details of running HelpTag are covered in "To Create a Run-Time Help Volume."
File Manager represents help files as file icons with a question mark. In Figure 2-2, there are two source files (.ctg and.htg extensions) and one run-time file (.sdl extension). If you double-click a markup file, your standard editor opens the file for editing. Double-clicking a .sdl file displays the run-time file using the Help Viewer.
Figure 2-2 File Manager view of help files
To create a run-time help volume, first select the .htg or .ctg file icon in File Manager. Then, choose Compile from the File Manager Selected menu.
See Also
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 build directory.
- Create the master HelpTag file.
- Create the
helptag.opt 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. HelpTag markup is described more fully in Chapter 3, "Writing a Help Topic," and Chapter 5, "HelpTag Markup Reference."
Create the Source Directory
- Create a directory named
helpfiles where you will create and process your help files.
- Create a text file named
Commands 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 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 file.
<hometopic> Command Summary
<idx|commands|
Your &product; is capable of the following operations:
<list bullet>
* <xref ChannelChange>
* <xref VolumeUp>
* <xref VolumeDown>
* <xref VolumeMute>
<\list>
Choose one of the hyperlinks (underlined phrases)
to find out how to perform that operation.
<s1 id=ChannelChange> Changing the Channel
<idx|channel, changing|
Speak the command:
<ex> channel<\ex>
followed by a number from one to ninety nine.
<s1 id=VolumeUp> Turning Up the Volume
<idx|volume, changing|
Speak the command:
<ex> volume up<\ex>
For additional volume, speak the command:
<ex> more<\ex>
(See also <xref VolumeDown> )
<s1 id=VolumeDown> Turning Down the Volume
<idx|volume, changing|
Speak the command:
<ex> volume down<\ex>
To further reduce the volume, speak the command:
<ex> more<\ex>
(See also <xref VolumeUp> and <xref VolumeMute> )
<s1 id=VolumeMute> Turning Off the Sound
<idx|volume, changing|
<idx|sound, on/off|
Speak the command:
<ex> sound off<\ex>
To restore the sound, speak the command:
<ex> sound on<\ex>
(See also <xref VolumeDown> and <xref VolumeUp> )
- 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 in the same directory as the Commands file.
<metainfo>
<title> Using the &product;
<copyright>
© 1995 Voice Activation Company. All rights reserved.
<abstract> Help for Using the &product;.
<\metainfo>
Create the Build Directory
Create a subdirectory named build in the helpfiles directory.
Create the Master HelpTag File
- In the build subdirectory, create a text file whose name is of the form volume.htg. In this example, the file is named voiceact.htg.
- In the .htg file, define entities that associate the names of the Commands and Metainfo files with entity names. Also, define any entities that are used (either directly or indirectly) in the Commands and Metainfo files. Finally, refer to the Commands and Metainfo files by their entity names.
In this example, the contents of the voiceact.htg 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. -->
&MetaInformation;
&Commands;
Create the helptag.opt File
- In the build subdirectory, create a file named helptag.opt and put the following text into it. This information selects HelpTag options and indicates where to search for any files defined in FILE entity declarations.
onerror=go
memo
search=./
search=../
The onerror=go option instructs the HelpTag software to continue processing input files even if an error occurred. See "Parser Options" for an explanation of parser options. For a complete list and description of parser options, refer to the dthelptag(1) man page.
- 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.
Create the Run-Time Help Files
- Open File Manager and change to the
build subdirectory. Select the voiceact.htg file icon and choose Compile from the Selected menu in File Manager.
This executes the HelpTag 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.err.
- Open the voiceact.err 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 HelpTag manually in a terminal window.
To do so, execute the following command:
dthelptag -verbose voiceact.htg
The -verbose option tells HelpTag to display its progress on your screen.
Display the Help Volume
From the build subdirectory, double-click the voiceact.sdl file icon.
This displays the help volume using the desktop Help Viewer. You can now scroll 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. It displays the new help volume.
dthelpview -h voiceact.sdl
See Also
The topic hierarchy within your help volume begins with the home topic. Each help volume must have one home topic. The first level of subtopics below the home topic may be entered with <chapter> or <s1>.
Additional levels of subtopics are entered with <s2>, <s3>, and so on. The HelpTag markup language supports nine topic levels, <s1> to <s9>. However, information more than three or four levels deep often leads many readers to feel lost.
When a help volume is displayed, the help window displays a list of topics in its topic tree. Any topic entered with a <chapter> or <s1...s9> tag automatically appears in the topic tree. This provides an easy way to browse and view topics.
To enable users to display other related information from within a topic, you create hyperlinks. To do so, you assign a unique ID to each destination topic. Hyperlinks make it possible to reference a specific ID anywhere in your help information.
Example
Suppose you want to create a hierarchy to match this simple outline:
Tutorial for New Users
Module 1: Getting Started
Module 2: Creating Your First Report
Module 3: Printing the Report
Module 4: Saving Your Work and Quitting
Task Reference
Starting and Stopping
To Start the Program
To Quit the Program
Creating Reports
To Create a Detailed Report
To Create a Summary Report
Concepts for Advanced Users
Using Report Hot Links
Sharing Reports within a Workgroup
Reference
Command Summary
Report Attributes Summary
Then the general outline of your help volume would look like this. (The body of each topic and IDs for the topics are not shown.)
<hometopic> Welcome to Report Master
<chapter> Tutorial for New Users
<s1> Module 1: Getting Started
<s1> Module 2: Creating Your First Report
<s1> Module 3: Printing the Report
<s1> Module 4: Saving Your Work and Quitting
<chapter> Task Reference
<s1> Starting and Stopping
<s2> To Start the Program
<s2> To Quit the Program
<s1> Creating Reports
<s2> To Create a Detailed report
<s2> To Create a Summary report
<chapter> Concepts for Advanced Users
<s1> Using Report Hot Links
<s1> Sharing Reports within a Workgroup
<chapter> Reference
<s1> Command Summary
<s1> Report Attributes Summary
Indentation is used here to make it easier to see the structure of the help volume. You do not have to indent your files.
See Also
 Use the <hometopic> element as follows:
- <hometopic> Title
Body of topic.
If you include a meta information section (<metainfo>), the home topic must follow it.
Examples
Here's a home topic with a title and a single sentence as its body:
<hometopic> Welcome to My Application
Congratulations, you've entered
the online help for My Application.
Here's a sample home topic that includes hyperlinks to its four subtopics:
<hometopic> Welcome to Report Master
Welcome to the online help for Report Master.
Choose one of the following hyperlinks:
<list bullet>
* <xref Tutorial>
* <xref Tasks>
* <xref Concepts>
* <xref Reference>
<\list>
If you need help, press F1.
The preceding markup produces this output:
To Add a Topic to the Hierarchy
To add another topic at the same level, repeat the same element.
- Or,
to add a subtopic (a topic one level deeper in the hierarchy), use the element that is one level deeper than the preceding topic.
Example
If the current topic is an <s1>, enter a subtopic using <s2>.
<s1 id=getting-started> Getting Started
<s2 id=starting-the-program> Starting the Program
Here's the body of the first subtopic.
<s2 id=stopping-the-program> Stopping the Program
Here's the body of the second subtopic.
The second <s2> is also a subtopic of the <s1>.
Note: Sometimes a parent-child-sibling metaphor is used to describe the relationships between topics in a hierarchy. In the preceding example, the <s1> topic is the "parent" of both <s2>s (the "children" topics). The two <s2>s are "siblings" of one another. All three topics are "descendents" of the home topic.
The meta information section is primarily intended for information about information. Similar to providing a copyright page in a book, this section includes information such as the volume title, copyright, trademark, and other notices.
A secondary use of the meta information section is to enter help topics that are not part of the normal topic hierarchy. These nonhierarchical topics are useful for creating custom definition links that pop-up a topic in a quick help dialog box.
- Enter the <metainfo> tag to start the section, and enter the required subelements <title> and <copyright> as shown:
<metainfo>
<title> Volume Title Here
<copyright>
Body of copyright topic here.
.
.
.
- Enter any of the optional elements as shown:
<abstract>
Body of the abstract topic here.
Do not use any HelpTag markup within the abstract!
- Enter the <\metainfo> end tag to end the section.
.
.
.
<\metainfo>
Note: Some elements in the meta information section require a <head> tag before the topic heading.
The <abstract> section is recommended. Applications that access help volumes can use this information to present a brief description of the volume. Because the abstract might be displayed in plain text windows (that do not support multiple fonts and graphic formatting), avoid including any HelpTag markup in the abstract.
Example
Here's a typical meta information section:
<metainfo>
<title> Report Master, Version 1.0
<copyright>
<otherhead> Report Master
<image>
Version 1.0
© Copyright Reports Incorporated 1995
All rights reserved.
<\image>
<abstract>
This is the online help for the mythical Report Master
application. This help includes a self-guided tutorial,
a summary of common tasks, general concepts, and quick
reference summaries.
<\metainfo>
The <image> element is used to preserve the author's line breaks. The © entity inserts the copyright symbol.
See Also
Adding a Nonhierarchical Topic
Topics entered with a <chapter> or <s1...s9> element tag automatically appear in the topic tree. When a title is selected in the topic tree, the corresponding help topic is displayed in a general help dialog box. However, sometimes you may want to create and display a topic independent of the topic hierarchy you have created. For example, you might want to display a topic in a separate, quick help window.
To Add a Nonhierarchical Topic
Add the topic just before the end of your meta information section using the <otherfront> element as follows:
- <otherfront id=id><head> Topic Title
Body of topic.
The ID parameter and <head> tag are required.
You can add as many <otherfront> topics as you want. They may be in any order, but they must be the last topics in the <metainfo> ... <\metainfo> section.
Example
This partial help volume shows how a general topic is added to the meta information section. The topic's title is "Pop-up!" and its ID is my-popup-topic.
<metainfo>
<title> My Help
<copyright>
This is My Help, Version 1.0. © 1995.
.
.
.
<otherfront id=my-popup-topic> <head> Pop-up!
This is a pop-up topic, displayed via a definition link
somewhere in my help volume.
<\metainfo>
<hometopic> Welcome to My Help
.
.
.
Presumably, within some other topic in the help volume, there's a definition link to display this topic.
The link might look like this:
Here's a sample of a pop-up <link my-popup-topic Definition>
definition link<\link>.
The words "definition link" become the active hyperlink and will be displayed with a dashed underline. Selecting the link displays the "Pop-up!" topic in a quick help dialog box.
See Also
Many elements in the HelpTag language support an ID attribute. An ID is a unique name used internally to identify topics and elements within topics. An ID is defined only once, but multiple hyperlinks and cross-references can refer to the same ID. IDs are not seen by the user.
If you are writing help for an application, IDs are also used by the application to identify particular topics to display when the user requests help. For example, you might write several topics that describe an application's menus. The IDs that you assign to the topics are used by the application developer. By defining identical IDs within the application code, the developer can integrate specific topics. This allows the application to access and display the correct topic when help is requested for a particular menu.
Rules for ID Names
- ID strings may contain letters (A - Z and a - z), digits (0 - 9), and the minus (-) sign, and must begin with a letter.
- Author-defined IDs may not use the _ (underscore character); it is reserved for IDs that are built into some HelpTag elements.
- Case is not significant, but is often used to increase readability.
- ID strings cannot be longer than 64 characters.
- Each ID within a single help volume must be unique.
To Add an ID to a Topic
Use the id parameter for the element as follows:
- <element id=id> ...
The elements that start a new topic and support an author-defined ID are:
- <chapter id=id>
- <otherfront id=id>
- <rsect id=id>
- <s1 id=id>
- <s2 id=id> . . .<s9 id=id>
A few elements have built-in IDs and, therefore, do not support an author-defined ID. Each of the following elements also starts a new topic, but these elements have predefined IDs (shown in parentheses):
- <abstract>
- (_abstract)
- <copyright>
- (_copyright)
- <glossary>
- (_glossary)
- <hometopic>
- (_hometopic)
- <title>
- (_title)
To Add an ID to an Element within a Topic
If the element supports an author-defined ID, use the id parameter for the element as follows:
- <element id=id> ...
The elements (within a topic) that support an ID attribute are:
- <figure id=id>
- <graphic id=id>
- <image id=id>
- <location id=id>
- <p id=id>
Or, use the <location> element to set an ID at an arbitrary point within the topic as follows:
<location id=id> text <\location>
Where text is any word or phrase where you want to add an ID. The <\location> end tag is required. When you activate a link to a location ID, the Help Viewer displays the topic containing the ID and scrolls the window to the ID position.
Examples
If you add an ID to a figure, you must have a caption. The caption is needed in case a cross reference is made to the figure's ID. In that case, the caption becomes a hyperlink to the figure.
Here's the markup for a figure with the ID my-big-picture.
<figure id=my-big-picture entity=big-picture-TIFF>
Here's My Figure
<\figure>
Here's a paragraph where the phrase "easier than ever" has been assigned the ID easy-spot:
Getting help is <location id=easy-spot> easier than ever<\location>.
An entity can represent a string of characters or the contents of a file. An entity declaration defines the entity by associating the entity name with a specific character string or file name. An entity reference is replaced by the string or file contents when you process the help volume with the dthelptag command.
Entities are useful for:
- Referencing a common string of text. This is useful if there is some likelihood that the text may change or you simply don't want to type it repeatedly. Each place you want the text inserted, you reference the entity name.
- Referencing an external file. Entities are required for accessing graphics files. The <figure> and <graphic> elements have a required parameter that you use to specify an entity name, which refers to a graphic image file.
File entities are also useful for splitting your HelpTag source into multiple files. Use entity references to include other files into your master HelpTag file for processing.
Rules for Entity Declarations
- Entity names may contain letters (A - Z and a - z), digits (0 - 9), and the minus (-) sign, and must begin with a letter.
- Case is not significant in entity names, but is often used to increase readability.
- Entity names cannot be longer than 64 characters.
- Each entity name must be unique within a single volume.
To Create a Text Entity
- Declare an entity as follows:
<!entity Entityname "text">
Where Entityname is the name of the entity and text is the string that you want substituted for every reference to the entity. Remember, all entity declarations must come before any other markup in your help volume.
- For each location where you want the text string to be inserted, enter the entity reference as follows:
&Entityname;
The & (ampersand) and ;(semicolon) characters are required for the HelpTag software to properly recognize the entity reference.
Example
The following line declares a text entity named Assoc that contains the string "Society of Agricultural Engineers":
<!entity Assoc "Society of Agricultural Engineers">
The following sentence includes a reference to the entity:
Welcome to the &Assoc;.
When the help volume is processed with the HelpTag software, the entity reference is replaced with the value of the entity. So, the sentence reads:
Welcome to the Society of Agricultural Engineers.
To Create a File Entity
- Declare an entity as follows:
<!entity Entityname FILE "filename">
Where Entityname is the name of the entity and filename is the name of the file. The keyword FILE is required.
- Reference the entity as follows:
- If the file is a text file, enter the following entity reference at each location where you want the contents of the file inserted.
&Entityname;
The & (ampersand) and ; (semicolon) characters are required for the HelpTag software to properly recognize the entity reference.
- If the file is a graphics file, include the name of the entity as a parameter in one of the following markup lines:
<figure entity=Entityname ... >
Or:
<graphic entity=Entityname ... >
Or:
<p gentity=Entityname ... >
Note: Do not include any path in the file name. If the file is not in the current directory when you run the HelpTag software, add the appropriate search path to the helptag.opt file. (See "To Create a Run-Time Help Volume.")
Example: Text File Entities
Suppose you wrote the text for your help volume in three files named file1, file2, and file3, plus a fourth file containing your <metainfo> ...</metainfo> section. You could include them in your volume.htg file like this:
<!entity MetaInformation FILE "metainfo">
<!entity MyFirstFile FILE "file1">
<!entity MySecondFile FILE "file2">
<!entity MyThirdFile FILE "file3">
&MetaInformation;
<hometopic> My Home Title
Welcome to my application's help volume.
&MyFirstFile;
&MySecondFile;
&MyThirdFile;
Example: A Graphic File Entity
Suppose a simple help volume has a figure in the home topic and the graphic image for the figure is stored in a file named picture.tif. The following example shows how that image would be used in a figure.
<!entity MetaInformation FILE "metainfo">
<!entity MyPicture FILE "picture.tif">
&MetaInformation;
<hometopic> A Sample Graphic
Welcome to my application's help volume
<figure nonumber entity=MyPicture>
A Picture
<\figure>
The text "A Picture" is the figure's caption.
The markup produces this output:
See Also
|
