Chapter 16: On-line Help Tags

This chapter describes the available On-line Help System tags. Tags are listed in alphabetical order.

The following categories of tags are available:

• Builder control tags, which control the On-line Help Builder
• Control tags, which define the general properties of the text
• Formatting tags, which define specific aspects of formatting

In addition, you can control the following:

• Text and attributes such as highlighting
• Hotspots and invisible text, providing the links between topics

On-line Help Builder Tags Syntax Guidelines

The following rules apply to On-line Help Builder tags :

• Tags preceded by period (.) must start in column one of a line.
• Tags preceded by colon (:) or a dollar sign ($) can start anywhere on a line.

  Tags preceded by ":" are terminated by a period, with the parameters normally appearing before the period.

• All tags can be followed by parameters.
• For tags followed by the parameter topic-name, this topic-name must follow the same syntax rules as a COBOL identifier. See your Language Reference for further information.

Builder Control Tags

Builder control tags are used to include or exclude sections of the source text. Below is a syntax summary of these tags, with a short summary of what they do. Click one for more information.

Control Tags

Control tags define properties of the text, but are not concerned with the way the text appears when displayed. Below is a syntax summary of these tags in alphabetical order, with a short description of what they do.

Formatting Tags

Formatting tags define the way the text appears when it is displayed. Formatting tags begin with a ":" and can start in any column, although you should use column one. Below is a syntax summary of these tags in alphabetical order, with a short description of what they do.

The Tags

*

The .* tag enables you to include comment or documentary text in your on-line help source files, which is ignored by the On-line Help Builder.

Syntax:

.* comment-text 

Parameters:

Comments:

Lines starting with this tag can be specified anywhere in the text file. You do not need any space between the tag and the following text.

Do not put a .* tag inside another tag (that is, between the colon that starts a tag and the period that ends it). Also, do not put a .* tag between another tag and its accompanying text or attributes.

This tag must start in column one.

Example:

.*This text is ignored when the source file is compiled.

browse

The .browse tag enables the author to control the destination of browsing to or from a topic.

Syntax:

.browse #chain-id @topic-name @topic-name 

Parameters:

Comments:

Use the .browse tag to vary from the default behavior of browsing topics in the order in which they appear in the on-line help source file.

This tag must start in column one.

Example:

The following topic is the first topic in the browse chain.

.context @main-menu 
.browse #1 @0 @submenu

When this topic is displayed, using the Browse > function in the On-line Help Viewer causes the @submenu topic to be displayed. Regardless of the topics which come before and after this topic in the text file, browsing < has no effect, while browsing > always goes to the @submenu topic.

caution

The :caution tag enables you to display a warning message.

Syntax:

:caution [text="caution-heading"].
caution-text
...
:ecaution.

Parameters:

Comments:

A blank line is inserted between the heading and the warning text. Also see :warning.

Examples:

:caution.
This is a warning message with a heading of CAUTION.
:ecaution.

:caution text="Extreme Caution".
This is a warning with a heading of Extreme Caution.
:ecaution.

cgraphic

The :cgraphic tag is similar to the :lines tag, except that the text is always displayed in a mono-spaced font. This allows you to create character diagrams which line up correctly when displayed.

Syntax:

:cgraphic.
text/graphics
...
:ecgraphic. 

Comments:

Example:

:cgraphic.
These lines all line up, retain indentation
and spacing and do not wrap:

+-------------------+ +------------------+
|                   | |                  |
|      Block A      | |     Block B      |
|                   | |                  |
+-------------------+ +------------------+
          |                     |
          +---------------------+
                     |
:ecgraphic.

color

The :color tag enables you to change the color of the text or its background.

Syntax:

color [fc=foreground-text-color]
[bc=background-text-color].

Parameters:

Comments:

The screen colors remain the same. Colors set with this tag remain in effect until either you specify another tag, or there is a heading definition. The values you can use are:

• default
• blue
• cyan
• green
• neutral
• red
• yellow

To return to the system colors, use fc=default and bc=default.

Example:

:color fc=red bc=neutral.
:p. This line of text is red on a neutral background.
:color fc=blue bc=red.
:p. This line of text is blue on a red background.

command

The .command tag enables you to execute other programs, operating system commands, or shells from within the On-line Help Viewer.

Syntax:

.command 
tag 
...

Parameters:

Comments:

Any number of these tags can be specified in a command topic. They are carried out in the order specified.

This tag must be specified immediately after a .context, :h1, :h2 or :h3 tag. The syntax of a command topic is different from that for a normal topic.

When a command topic is accessed in the On-line Help Viewer, the specified sequence of commands is carried out, then the last-viewed topic is displayed. You can use the .browse tag to bypass command topics when browsing a file. The home topic must not be a command topic.

Example:

.context @test
.command
:exec dir /p
:exec list ohbld.doc
:shell

When you access this topic, dir/p is executed in the current operating system, list ohbld.doc is executed by the operating system, and you are returned to the Net Express command prompt.

From the Net Express command prompt, you can type:

exit

which returns you to the previous topic.

comment

The .comment tag enables you to include comment or documentary text in your on-line help source files, which is ignored by the On-line Help Builder.

Syntax:

.comment comment-text 

Parameters:

Comments:

Lines starting with this tag can be specified anywhere in the text file.

This tag must start in column one.

Example:

.comment  This text is ignored

context

Defines an id for a topic that can be used to link to it.

Syntax:

.context topic-name 

Parameters:

Comments:

Each topic is preceded by one or more (up to a maximum of 32) .context tags. topic-name is the topic-name that can be used to look up the topic. It is limited to 30 characters and can contain any character except a space. More than one topic-name can be associated with any given topic. All the .context tags associated with a topic must appear physically together.

This tag must start in column one.

Local topic-names are identified by a leading "at" character (@). They can only be referenced from the on-line help source files making up a single on-line help file. They are not saved in the file. Instead, all references to them are resolved at build time. Such references take up less space and are very quick to access. Local topic-names cannot start with a digit.

All topic-names should be local except those to which access could be required from an external source.

Example:

.context @entry-field 
.context entry-field

See Also:

:h1, :h2, :h3 and :h4, :h5, :h6.

define

The .define tag is used to reserve a context number for a given topic.

Syntax:

.define @topic-name @context-no 

Parameters:

Comments:

This is useful when the context number of a topic needs to be known; for example, when that topic is referenced directly from a COBOL program. All .define tags must appear before the start of the first topic.

This tag must start in column one.

If no .define tag has been specified for a given topic, the On-line Help Builder automatically assigns a context number to the topic. However, these context numbers change each time the file is built.

A topic can have more than one context number, but each context number can only be related to one topic. Context numbers are entirely arbitrary and do not relate to the structure of the file in any way.

Example:

.define @main-menu @13

dl.

Defines a definition list.

Syntax:

:dl [compact] [tsize=nn] [break=xxxx].
:dthd. term-hdg 
:ddhd. definition-hdg 
:dt. term
:dd. definition-text
:dt. term
:dd. definition-text
......
:dt. term
:dd. definition-text
:edl.

Parameters:

Comments:

An item in the list consists of two parts - a term and a definition. You can use other tags to highlight the headings for the term and definition columns.

Use compact to specify that items in the list are not separated by a blank line.

Headings for the two columns are defined using the :dthd and :ddhd tags. Terms are preceded by :dt. tags and descriptions by :dd. tags. The description can be followed by additional paragraphs, blocks or other lists. To finish the list, use the edl. tag.

$defmacro

Use macros when you want to include a number of occurrences of text that are the same, or fit a pattern. By specifying the base for the pattern in the definition of the macro, each time you call the macro you can use the same base pattern with different parameters.

Syntax:

$defmacro macro-name.
macro-text [macro-param ... ]
$edefmacro.

Parameters:

Examples:

$defmacro topic.
:h1 id=%id%.%title%
:p.%text%

$defmacro macro-1.
:p. This text is from macro-1. It takes no parameters.
$edefmacro.

$defmacro macro-2.
:p. This text is from macro-2. It takes parameters %a%, 
    "%b%", %c%.
$edefmacro.

See the description of the $macro tag later in this chapter for information on how to use these macros once you have defined them.

end

The .end tag forces the end of a topic, avoiding any unwanted blank lines being displayed.

Syntax:

.end 
                  

Comments:

You should use this tag to end a list topic in order to prevent the cursor moving below the last line of the display.

This tag must start in column one.

fig

The :fig tag is used to show text in the same format as it is entered, using a proportional font.

Syntax:

:fig.
text
...
:efig.

Parameters:

Comments:

If the text is larger than the window size, the text is clipped. Because the text is displayed in proportional font, individual letters and numbers might not be aligned, and this tag is not suitable for creating character diagrams.

You can specify a figure caption within this tag (see :figcap).

Example:

:fig.
Column1           Column2
------------------------------
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
:efig.

See Also:

:cgraphic. and :xmp.

figcap

The :figcap tag is used to specify a title for a figure.

Syntax:

:figcap. text 

Parameters:

Comments:

You must place this tag either immediately after the :fig tag, or immediately before the :efig tag. You can place the text for the title on the same line as the tag, or the next line. The title text must not contain colons (:) or semicolons (;). See :fig.

Example:

:fig.
Column1           Column2
------------------------------
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
Column1 text      Column2 text
:figcap. Title of the figure
:efig.

fn

The :fn tag is used to specify a footnote that can be displayed in a pop-up window when the user selects a hypertext link to the footnote.

Syntax:

:fn{id=topic-name}.
popup-text
...
:efn.

Parameters:

Comments:

Footnotes can appear in paragraphs, lists, highlighted phrases, and artwork. You cannot put index entries in a footnote, and one footnote must end before another begins.

You use this tag with the :link tag (see :link).

Example:

:fn id=footnote1.
This footnote can give further information
about a topic with a hypertext link specified 
using the :link tag with a refid of footnote1.
:efn.

freeze

The .freeze tag is used to specify text that should always be displayed in a fixed position.

Syntax:

.freeze nn 

Parameters:

Comments:

These lines should be part of a fixed-lines block.

The .freeze tag must appear before any text in a topic.

This tag must start in column one.

Example:

.context @main
.freeze 3
<Key>    <Overview>
------------------------------------------------------------
This is the first line of text for this topic.
This will scroll, but the three lines above will not.

h1, :h2, :h3

The heading tags are used to specify different level headings for topics.

Syntax:

 heading-tag {id=topic-name}
{name=topic-name}
[res=context-no]
[local]
[global].
heading-text

Parameters:

Comments:

Heading tags :h1, :h2 and :h3 are primary topic headings. They can be used as a substitute for .context and .topic tags to start a new topic.

Example:

:h1 id=help-menu id=help-option local global. The Help Menu

is the same as specifying

.context @help-menu
.context help-menu
.context @help-option
.context help-option
.topic The Help Menu

h4, :h5, :h6

The heading tags are used to specify different level headings for topics.

Syntax:

subheading-tag{id=topic-name}
{name=topic-name}
[local]
[global].
[subheading-text]

Parameters:

Comments:

Heading tags :h4, :h5 and :h6 are subheadings within a topic. As they do not start a new topic they are not entered into the contents list.

You can cross-reference these tags in the same way that you can cross-reference the heading tags :h1, :h2 and :h3.

Example:

:h1 id=on-line-topic-1 local global. Using the On-line Help 
    System
...
:h4 id=file-menu. The File Menu
...
:h4 id=options-menu. The Options Menu 
...
:h5 id=option-search. The Search function 
...
:h1 id=on-line-topic2 local global. Using the On-line 
    Reference

    See \aThe file menu\@vfile-menu\v.
...
    See \aThe Search function\v@option-search\v.

heading

The text specified is displayed centered in the top border of the topic window.

Syntax:

.heading text 

Parameters:

Comments:

The .heading tag has the same effect as the .topic tag, except that text does not appear in the Contents list.

This tag must start in column one.

Example:

.heading Main Menu

i1, :i2

The index tags are used to specify index entries for a topic when the index is created using the /INDEX directive at build time. You can create a subentry for an indexed item using the :i2 tag at any time; it need not be specified at the same time as the primary index entry.

Syntax:

:i1[id=i1-id-name].index-text 
:i2[refid=i1-id-name].index-text 

Parameters:

Comments:

Index tags can appear anywhere in a topic. The location within the topic is recorded along with the topic number. When the index item is selected from the On-line Help Viewer, the topic is aligned at the appropriate place.

The resulting index is alphabetically sorted first by :i1 entries, then by the :i2 entries for each primary entry.

Example:

.context @main-menu
:i1 id=help-menu. Help menu option 
... 
:i2 refid=help-menu. Index 
... 
:i2 refid=help-menu. Using help 
... 
:i2 refid=help-menu. General help

This results in the following index:

Help menu option 
    General help
    Index
    Using help

$if, $else, $end

Used to conditionally include or exclude lines.

Syntax:

$if condition.
true-text
[$else. false-text]
$end.

Parameters:

Comments:

The Boolean variables used in condition must be defined using the /INCLUDE and /IGNORE directives. You can nest conditional building tags to any level.

Example:

.context @cond-build
$if cond-1.
$if cond-2.
:p. Both conditions are true
$else. :p. Only condition one is true.
$end.
$else.
$if cond-2.
:p. Only condition two is true.
$else.
:p. Neither condition is true.
$end.
$end.

$ifmdef, $elsem, $endm

Syntax:

$defmacro macro-name.
...
$ifmdef macro-param.
true-text
$elsem.
false-text
$endm.
...
$edefmacro.

Parameters:

Comments:

The $ifmdef, $elsem, $endm structure can only be used within $defmacro and $edefmacro tags.

Example:

$defmacro macro-1.
...
$ifmdef param-1.
:p. The value of the parameter is %param-1%.
$elsem.
:p. No parameter specified to this macro.
$endm.
...
$edefmacro.

im

Embeds another file in an on-line help source file.

Syntax:

.im filename 

Parameters:

Comments:

The .im tag behaves like the COBOL COPY statement.

This tag must start in column one.

Example:

.context @main-menu
:p. Text about the main menu,
including source text from other files:
.im e:\help\menus\filemenu.txt
.im e:\help\menus\loadmenu.txt
.im e:\help\menus\savemenu.txt

index

The ..index tag does not allow more than one level of indexing. The text specified is entered in the index if the /INDEX directive was specified. .

Syntax:

..index index-text 

Parameters:

Comments:

Example:

.context main-menu
..index Main menu
..index Menu, main
:p. This is the main menu.

See Also:

:i1, :i2

lines

The :lines tag is used to mark any set of lines so that they are not reformatted when they are displayed.

Syntax:

:lines
text
...
:elines

Parameters:

Comments:

This forms a fixed-lines block which use the standard font.

These lines use the standard font. Thus, on systems that allow it, the lines can be displayed in proportional text and therefore do not maintain alignment with each other. (See the section :cgraphic.)

Example:

:lines. The text on the next line does not
     wrap onto the previous line. The indent
     on these lines is maintained.

However, don't expect this                        1234567890
to line up with this              - OTTFFSSENT
:elines.

link

The :link tag specifies a link to additional information. You can specify a link to a topic or a footnote (see :fn).

Syntax:

:link reftype=hd
[refid=topic-name]
[res=context-no]
[database="filename"]
.hotspot-text
:elink.

Parameters:

Example:

.context @main-menu
:p. Text about the main menu
...
.context @secondary-menu
:p. Text about the secondary menu
...
.context @file-menu
:p. Text about the file menu
:link reftype=hd refid=main-menu. Select this to see text
  about the main menu:elink.

:p. Additional information about 
:link reftype=hd refid=footnote1.using footnotes:elink.
is given in the footnote.

list

The .list tag is used to indicate that the topic is a cross-reference list.

Syntax:

.list

Comments:

The topic must be a fixed-lines topic, so no formatting tags can be used. Each full line forms a cross-reference to another topic. The cross-referenced topic is identified either by specifying a hotspot in the usual way at the start of each line or by the first word on the line.

This tag must start in column one.

When the topic is displayed, a full-width highlight is placed on the first line. This is a selection bar which can be moved to the required line. Pressing Enter then selects the topic.

lm

The :lm tag is used to set the width of the left margin to n characters. The left margin is set to be n characters from the left-hand edge of the text window. The default is zero.

Syntax:

:lm margin=n.

Example:

:lm margin=2.

lp

The :lp tag is used to add text to a list, for example, the explanation of an item, that does not interrrupt the list sequence.

Syntax:

:lp. list-text 

Parameters:

Example:

:ol.
:li. Item one
:li. Item two 
:lp. Explanation of item two
:li. Item three
 :eol.

$macro

Syntax:

$macro macro-name [macro-param=[']value['] ... ].

Parameters:

Comments:

When you call a macro, the On-line Help Builder includes in the on-line help source file the text defined by that macro, adding any macro parameters you specify.

Example:

The following example of how to use a macro uses the macro defintions from the description of the $defmacro tag earlier in this chapter.

$macro topic id=t1 title='topic one' 
    text='This is the first topic.'.

$macro topic id=t2 title='topic two' 
    text='This is the second
topic. $macro macro-1. $macro 
    macro-2 a=1 b="xyz" c=2.'.

Using these macros has the same effect as entering the following in your on-line help source file:

:h1 id=t1.topic one
:p. This is the first topic.

:h1 id=t2.topic two
:p. This is the second topic.
:p. This text is from macro-1. It takes no parameters.
:p. This text is from macro-2. It takes parameters 1, xyz, 
    2."

note

The :note tag is used to start a single paragraph note in the text.

Syntax:

:note [text="note-heading"]. 
note-text

Parameters:

Comments:

The note heading is at the left-hand margin of the text, and the note text follows on the same line. If the note wraps onto another line, it aligns with the note heading. If you start a note inside a list, the text aligns with the margin of the list items. The note ends at the next tag in the source file.

Example:

:note text="New Note Title:".
The title of this note is New Note Title:
and the rest of the note follows it.
:p. This, or any other, tag ends the note.

nt

The :nt tag is used to specify a multi-paragraph note in the text.

Syntax:

:nt [text="note-heading"].
note-text
...
:ent.

Parameters:

Comments:

The note heading is at the left-hand margin of the text, and the note text follows on the same line. Succeeding lines of text align with the start of the first line, to the right of the note heading. You can use the :p tag in the note to start a new paragraph. You can use the :nt tag in paragraphs or lists. You must end a note before you start another note.

Example:

:nt text="Long Note:".
The title of this note is Long Note:
and the rest of the note follows the title.
:p.This is the second paragraph of the note.
:p.This is the third paragraph of the note.
:ent.

ol.

Defines an ordered list.

Syntax:

:ol [compact].
:li. text
...
:eol.

Parameters:

An ordered list is similar to an unordered list except that each item is numbered. If you have nested lists, the first, third, fifth, etc. level of ordered list is preceded by a number, the second, fourth, etc., by a letter.

Use compact to specify that items in the list are not separated by a blank line.

p.

The :p. tag is used to mark the beginning of a new paragraph.

Syntax:

:p. text 

Parameters:

Comments:

All paragraphs are preceded by this tag, and all text lines between the tag and the next format tag or the end of the topic are treated as part of the paragraph. A paragraph is held as a single unit - all line information from the source file is discarded. When a paragraph is displayed, it is followed by a blank line. A :p. tag followed immediately by another formatting tag is treated as a null paragraph and is displayed simply as a trailing blank line.

The paragraph text can immediately follow the tag on the same line. Spaces between the tag and the text are ignored as are those at the beginning of any text line.

Example:

:p. This is a normal paragraph that you would
expect to enter with single spaces between
words and covering several lines.
:p. This is a less normal paragraph with text
        that goes over several lines with different indents,
                 but is all one paragraph with single
     spaces between all words when it is formatted on the 
 screen.

parml.

Syntax:

:parml [compact] [tsize=nn] [break=xxxx].
:pt. term
:pd. definition-text
:pt. term
:pd. definition-text
...
:pt. term 
:pd. definition-text
:eparml.

Parameters:

Use compact to specify that items in the list are not separated by a blank line.

Comments:

An item in the list consists of two parts, each preceded by its own tag. Terms are preceded by :pt. tags and descriptions by :pd. tags. The description can be followed by additional paragraphs, blocks or other lists. To finish the list, use the :eparml. tag.

popup

The .popup tag is used to indicate that the window is a pop-up window which is to be displayed on top of any other window. Pop-up windows do not stack.

Syntax:

.popup 

Comments:

This tag must start in column one.

You cannot browse from a pop-up window, and hotspots cannot be used in a pop-up window. The only topic available from a pop-up window is the topic from which the pop-up window was invoked. Pop-up windows are available only in On-line, and cannot be defined in paragraph text.

Example:

.context @main-menu
:p. Text about the main menu
\aPop-up for secondary menu\v@secondary-menu\v
...
.context @secondary-menu
.popup
:p. Text about the secondary menu. This appears in a pop-up.

rm

The .rm tag is used to set the width of the right margin to n characters. The right margin is set to be n characters from the right-hand edge of the text window. The default is zero.

Syntax:

:rm margin=n.  

Example:

:rm margin=5.

sl.

Defines a simple list.

Syntax:

:sl [compact].
:li. text
...
:esl.

Parameters:

Comments:

A simple list is just a list of lines. The lines in the list reformat if the window width is changed. A simple list always starts in the current left-hand margin. A simple list within a simple list is indented by four characters.

title

The .title tag is used to provide a title for an on-line help file.

Syntax:

.title title-text 

Parameters:

Comments:

It must appear before the start of the first topic; the last one becomes the file title. This title is displayed along with the filename in the On-line Help Viewer.

This tag must start in column one.

Example:

.title My Application Help File

topic

The .topic tag is used to specify the title of a topic.

Syntax:

.topic topic-text 

Parameters:

Comments:

This title is displayed centered in the top border of the topic window in the On-line Help Builder. It is also added to the contents list if the /CONTENTS directive was specified.

This tag must start in column one.

If no .topic tag is specified, the topic-name used on the first .context tag is used.

Example:

.topic Main Menu Description

ul.

Defines a bulleted list.

Syntax:

:ul [compact].
:li. text
...
:eul.

Parameters:

Comments:

An unordered (or bulleted) list is a list of items which can consist of one or more paragraphs. The first line of each item is preceded by "o", unless it is embedded within another unordered list, in which case it is preceded by "-". The bullet is indented by one character, the text by four characters from the current indent.

Use compact to specify that items in the list are not separated by a blank line.

userdoc

The :userdoc tag is used to identify a source file that is to be built.

Syntax:

:userdoc.
...
:euserdoc.

Parameters:

None.

Comments:

This tag must be the first tag in the source file. It signals the On-line Help Builder to begin compiling the tagged text that follows. The end of the tagged text is identified by the :euserdoc tag, which must be the last tag in the source file.

Example:

:userdoc.
.
.
.
:euserdoc.

warning

The :warning tag enables you to display a warning message.

Syntax:

:warning [text="warning-heading"].
warning-text
...
:ewarning.

Parameters:

Comments:

The text appears on the same line as the message. Also see :caution.

Examples:

:warning.
This is a warning message with a heading of Warning:.
:ewarning.

:warning text="Error Condition".
This is a warning about a possible error with a heading of 
Error Condition.
:ewarning.

xmp

The :xmp tag is used to display text as it is entered, in monospaced font.

Syntax:

:xmp.
text
...
:exmp.

Parameters:

Comments:

You can use this tag for an example of code, or text when you want single letters or numbers to align. The text begins indented two spaces from the left margin of the window. If the text size is greater than the window size, the text is clipped.

Examples:

:xmp.
$set ans85
 identification division
 
 program-id. new-program
 
 environment division
:exmp.

:xmp.
Number Column    Description Column
------------------------------------
1                Description 1
2                Description 2
3                Description 3
4                Description 4
5                Description 5
:exmp.

See Also:

:cgraphic and :fig.

Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.