HP OpenVMS Systems Documentation |
Common Desktop Environment: Help System Author's and Programmer's Guide 3 Writing a Help TopicContents of Chapter: This chapter describes elements that you can use to format your text. It also explains how to include graphics and how to create hyperlinks to other help topics. Examples shown in this chapter use shorthand markup. Creating Help TopicsA 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 you are writing online help for.Each topic you write should have an element (or tag) that marks the start of the topic:
Where element is one of the following: chapter, s1, s2, ..., s9. The body of the topic may begin on any line after the title. The topic's position within the topic hierarchy is determined by the element used to start the topic and by the element used to start the immediately preceding topic. For example, a topic that starts with <s2> and immediately follows a topic that starts with <s1> makes the <s2> topic a subtopic of the <s1> topic. The id is required if the topic is to be accessed either from the application (if you are writing application help) or from a hyperlink. The help topic title can be any string. If the title string occupies more than one line in your source file, end all but the last line with an & (ampersand). To force a line break at a particular place within the title, use a \ (backslash) character. ExampleThe following line marks the start of a topic using the <s1> tag:
To force the title to be displayed on two lines, you use a \(backslash) like this:
See Also
Creating Structure within a TopicWithin the body of a help topic, you have the following elements to choose from to organize and present your information:
To Start a ParagraphInsert a blank line after the previous paragraph or other element.
ExamplesHere are two paragraphs, separated by a blank line. Because neither paragraph has any special parameters, the <p> tag does not have to be entered (it is assumed when you enter one or more blank lines):
If you want a paragraph indented from the left margin, include the optional indent parameter:
The following paragraph overrides the automatic word wrap in help windows and maintains the line breaks exactly as entered in the source file. The <image> element is especially useful for entering addresses.
To Enter a ListUse the <list> element as shown:
ExamplesHere's a simple list. Because the type isn't specified, it defaults to a bulleted list. Because spacing isn't specified, it defaults to loose, which leaves a blank line between each item.
The online format of the preceding markup is:
To format the same list with numbers and reduced spacing between items, use:
The output is:
To Enter a LablistA lablist is a two column list with optional column headings.To create a labeled list without headings, use the <lablist> element as shown:
ExampleHere's a list of labeled chapter descriptions. The optional label headings are not provided.
The output is:
To Enter a Lablist with HeadingsUse the <lablist> and <labheads> elements as shown:
ExampleThis markup:
produces this output:
See Also
To Provide Subheadings within a TopicFor medium headings (slightly smaller than the topic title), use the following markup:
ExampleHere, the <procedure> element is used to add a small heading before each list.
This markup creates this output:
To Show a Computer ListingFor computer listings that do not contain any special character sequences that will be interpreted as HelpTag markup, use the <ex> (example) element as shown:
For computer listings that contain special character sequences used by HelpTag, use the <vex> (verbatim example) element as shown:
The optional size attribute, which determines the size of the font used to display the example, can be specified as smaller or smallest. ExampleHere the<ex> element is used to represent a directory listing in a terminal window.
The markup produces this output:
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. See AlsoTo Add a Note, Caution, or WarningInclude the <note>, <caution>, or <warning> element as follows:
Names of the default icons used by the Help System for note, caution, and warning elements are specified in the following entities.
If you create your own icon images for notes, cautions, and warnings, be sure to keep them small so they will fit into the area allotted. Also, the graphic images must be in your HelpTag search path, which is specified in your ExampleThe following markup for a note, warning, and caution produces the output shown in Figure 3-1.
Figure 3-1 Note, warning, and caution help icons
See Also
Entering Inline ElementsInline elements are used to mark words or phrases within a paragraph of text. These elements affect the font used to format particular items.To Emphasize a Word or PhraseUse the <emph> element (emphasis) as shown:
Emphasized text is displayed using an italic font. ExampleHere's how you might emphasize an important word:
Or, using the shorthand form:
In both cases, the word "no" is displayed in italics. To Enter a Book TitleUse the <book> element as shown:
ExampleHere's how you would enter the title of this guide:
To Emphasize Using a Bold FontUse the<term> element as shown:
To Display a Computer LiteralUse the <computer> element as shown:
ExampleComputer text is useful for identifying a file name. Here the helptag.opt file name is tagged using shorthand markup. The file name will be displayed in computer text.This markup:
produces this output:
Add the search path to your To Display a VariableUse the <var> element (variable) as shown:
Variables are displayed using an italic font. ExampleThis command-line syntax uses a variable to show that the user supplies a file name.
It produces this output:
Variables can appear within computer text or computer example listings. This example specifies volume as a variable part of a file name:
It produces:
The HelpTag software takes your In both of these examples, the %% pairs could have been entered with the long form (<var>...<\var>) or the short form (<var|...|). Creating HyperlinksA 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. These HelpTag elements can be assigned IDs:<chapter> , <s1...s9> , <location> , <p> , <image> , <figure> , and <graphic> . Help supports five types of hyperlinks:
<xref> and <link> , that can be used to create hyperlinks to an ID. In addition, the <p> , <image> , and <figure> elements can be used to create hyperlinks using a graphic image.Using the <xref> ElementIf you are linking to an element with a title, such as a chapter or section, the simplest way to do so is with the<xref> element. When you use <xref> to create a link, you specify the ID of the topic that you want to link to. The title of the topic is inserted in place of the <xref> element and becomes the active hyperlink.
Hypertext links created with <xref> display the new topic in the same window. If you desire different behavior by using the other link types, then you must use the Also, you cannot use <xref> to jump to topics that have built-in IDs (such as <hometopic> or <glossary>). To create a hyperlink to any of those elements, you must use the <link> element. To Create a Link Using <xref>Use the <xref> element as shown:
The section title replaces the <xref> element. The title is a hyperlink, designated by an underline. This is how the sentence would appear in a help volume.
Using the Link ElementYou can use either the<xref> or <link> element to create standard hypertext links. However, to use the other types of links listed in the section"Creating Hyperlinks," you must use the <link> element.To Create a Link Using <link>To jump to a topic within the same volume, use the <link> element as shown:
ExampleHere is the previous example using the<link> element instead of the <xref> element.
To Create a Link to a Predefined IDTo jump to a topic (within the same volume) that has a predefined ID, use the <link> element as shown:
ExampleThis link jumps to the home topic of the current volume:
To Create a Link to a Topic in a Different VolumeTo jump to a topic in another help volume:
ExamplesThis link jumps to the home topic of a help volume calledGeoMap :
Here's the same link, but it displays the topic in a new window:
This link jumps to the topic, DesktopKeyboardNav , in the help volume named Intromgr .
If the help volume you are targeting is not registered on the desktop, then you must provide a complete path name to the volume or specify the appropriate search path in your helptag.opt file.See AlsoTo Create a Definition LinkIf you are linking to a term in the glossary, use the <term> element as shown:
ExampleThe following link creates a definition link that displays the copyright topic in the meta information:
The phrase "Version Information" becomes the hyperlink text (dashed underline). See AlsoTo Create a Man Page LinkUse the <link> element as shown:
Note: If you are writing help for an application and you include any man page links, your application must include special support for man pages. See "To Display a Man Page." (The desktop Help Viewer includes support for man page links.) ExampleHere's a link that displays the man page for the grep command:
"Man" is a keyword for the <link> element, so if you want to create a link that displays the man page for the man command, you must use the hyperlink parameter:
To display a man page in a particular section, precede the man page name with the section number. The following link displays the "mkdir" man page from section 2 (which is different from the man page of the same name in section 1):
See AlsoTo Create an Application-Defined LinkUse the <link> element with the AppDefined parameter as shown:
ExampleSuppose you are writing help for an application that prints three styles of reports. You might create three hyperlinks like this:
If your application is set up to handle these special links and to interpret the hyperlink strings, it could generate the appropriate report based on the hyperlink chosen by the user.
For a complete example, refer to the sample application code located in the To Link to a Meta Information TopicUse the <link> element as shown:
The predefined IDs for the meta information topics are listed below:
See Also
Execution Link ControlMost hyperlinks display a related help topic, but hyperlinks can also execute shell commands and scripts. Links of this type are called execution links. Because execution links interact with a user's system, the Help System provides an execution policy to control how execution links are handled.
The Help System uses resources to define the behavior of execution
links. The Execution Policy Default BehaviorWhen an execution link is selected, if the link has an execution alias, the Help System retrieves the value of the alias and executes the command. If an execution alias has not been defined, the Help System displays a confirmation dialog box that shows the command to be executed and asks the user whether to execute the command or to cancel the operation.Execution AliasesWhen using execution links in a help volume, it is recommended to create execution aliases. That is, in the application's application defaults file you define an alias (a name) that represents the actual command to be executed. One advantage of this method is that it isolates the actual commands from the help volume source files. This makes it possible to edit the commands in the application defaults file without changing the hyperlinks in the help volume. Each hyperlink references an alias name, which remains unchanged even though its content may have been edited. For instance, a tutorial help volume that uses scripts could be easily customized to accommodate a particular shell environment by modifying the shell script commands in the application defaults file.To Create an Execution AliasTo create an execution alias in an application's application defaults file, use this resource specification syntax:
Where:
ExamplesThis resource entry creates an execution alias named,StartDtterm , which starts a terminal emulator. The & (ampersand) starts the command in the background.
This entry creates an alias named, xclockAlias , that executes the xclock application in an application named NightAlert.
Using Execution Aliases in HyperlinksAn execution alias can be referenced using the<link> element or used in conjunction with elements that have a hyperlink parameter, such as <p> or <figure> . To Create an Execution Link Using an Execution AliasUse the <link> element as shown:
Note: If the command you are executing doesn't finish immediately, run it in the background by appending an &(ampersand) to the command. If you don't, the help window will not operate until the command finishes. ExamplesThis hyperlink references the execution alias named,xclockAlias . The resource definition for the alias is shown in the section "Execution Aliases."
The link starts the xclock program running in the background. The phrase "Start the Clock" becomes the hyperlink. Clicking the hyperlink runs the
Here is the same hyperlink including an optional default command.
DtNexecutionPolicy ResourceTheDtNexecutionPolicy resource enables a system administrator or user to select an appropriate level of security for a given application.The resource values that can be set are:
help_execute_query_unaliased . Any execution links defined as execution aliases will be automatically executed, whereas the Help System will display a confirmation dialog box for any other execution links.
It is not recommended for the application developer to set the See Also
Displaying GraphicsHelp supports four graphics formats:
To Create a Figure
If you want the figure to be a hyperlink, use the ghyperlink (graphic hyperlink) and glinktype (graphic link type) parameters as shown:
The ghyperlink and glinktype parameters work just like the hyperlink and type parameters for the <link> element. ExamplesFor these examples, assume that you've declared these two file entities at the top of your help volume:
See AlsoTo Display an Inline Graphic
Note: The <graphic> element is intended for small graphics, although larger images can be used. Additional white space is added between lines to accommodate the height of the graphic. ExampleHere's an example that uses a small X bitmap image in the middle of a sentence. First, at the top of the volume, the bitmap file must be declared as a file entity:
Within the help text, the image is inserted using the <graphic> element:
This markup produces this output.
To Wrap Text around a Graphic
ExampleSuppose you want to display an icon named sample.pm and wrap paragraph text around it. First, declare the file entity:
Then, enter the paragraph:
To right-justify the graphic, add the gposition parameter like this:
Here's the markup for a paragraph wrapped around an icon, where the icon is a hyperlink that displays a topic with the ID icon-editor in a new window:
See AlsoIncluding Special CharactersMany special characters and symbols are available within HelpTag. You display a particular character by entering the appropriate entity reference.Some special character entities are declared in the file helpchar.ent. The helpchar.ent file is located in the /usr/dt/dthelp/dthelptag directory. To access these characters, either copy the particular entity declaration into your own volume, or include the entire helpchar.ent file. Unused entity declarations are ignored. Refer to Chapter 6, "Summary of Special Character Entities," for a complete list of the available characters. To Include a Special Character
ExamplesThe entity for the copyright symbol (©) is a built-in special character, so all you have to do to display it is use this entity:
To display the uppercase greek letter sigma (), you must first include the helpchar.ent file (at the top of your help volume with your other entity declarations) as shown here:
Then you can place the following entity reference where the sigma character is to appear:
As with any entity, case is not significant in the entity names for special characters. See AlsoIncluding Comments and Writer's MemosFrequently 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 HelpTag 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.In addition to standard comments, HelpTag also provides a <memo> element for entering writer's memos. Memo notes appear in your help topics during reviews, but not when you make your final help files. Authors commonly use the <memo> element to write questions or make notes to reviewers. To Insert a CommentUse the comment begin marker (<!--) and end marker (-->) as shown:
ExampleHere's an example that has two comments, a line before the paragraph, and a single word within the paragraph.
To Insert a Writer's MemoUse the <memo> element as shown:
ExampleSuppose you are writing about your application and have a question for the project team. You can include the question within the text using the <memo> element like this:
If you process the help volume with the following command (or include memo in your helptag.opt file), the memo appears in the help text in a bold font.
If the memo option is not used (or the nomemo option is used), the text within the memo is ignored and does not appear in the help text. Creating an IndexThe 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.To Mark an Index EntryWithin the topic you want to index, use the <idx> element as shown:
ExamplesHere's the start of a topic with two keyword index entries:
The following example indexes the + (plus character), putting it in the keyword index where the word "plus" would appear:
Creating a GlossaryLike 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.Throughout your help volume, each key word or phrase that you enter with the <term> element automatically becomes a definition hyperlink to the term's definition in the glossary. See AlsoTo Mark a Glossary TermUse the <term> element as shown:
Where glossary form is the term exactly as it appears in the glossary. This is useful if the term must be plural in a help topic (because of its context), but must be singular in the glossary. Terms are displayed using a bold font and automatically become a definition hyperlink. When the term is chosen, its glossary definition appears in a quick help dialog.
Note: If you mark a term that you intentionally do not define in the glossary, add the nogloss attribute to the <term> element. This allows the term to be displayed in the bold font used for terms, but without creating a link to the glossary. ExamplesIf your glossary has a definition for the term "widget", you can enter it as a term like this:
If the glossary entry is "widget", but you need to use the plural form within the sentence, you could enter the term like this:
If you want to enter the same term, but you either don't want to include it in the glossary or you don't want it to be a hyperlink, use the nogloss parameter like this:
The equivalent short form is:
To Define a Term in the GlossaryEnter the <dterm> element into the glossary as shown:
ExampleHere's part of a glossary that includes the definition of the term SGML:
|