PreviousConfiguration Option Tags Ohbld Error MessagesNext

Chapter 14: 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:

In addition, you can control the following:

14.1 On-line Help Builder Tags Syntax Guidelines

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


14.2 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.

Tag
Description
. Define a comment.
$if Conditional building.
$else Conditional building.
$end Conditional building.
$defmacro Define a macro..
$edefmacro Define a macro..
$ifmdef Conditional building in macros.
$elsem Conditional building in macros.
$endm Conditional building in macros.
$macro Use a macro.
.comment Define a comment.
.im COPY source text.

14.3 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.

Tag
Description
.browse Browse chains
.command Command topics
:exec
:call
:shell
.context Contexts
.define Define context numbers
.end End topic
.freeze Frozen lines
:h1 Headings
:h2
:h3
:h4 Subheadings
:h5
:h6
.heading Title of topic
:i1. Index entries
:i2.
..index
:link Linking hotspots
:elink
.list Lists of cross-references
.title Title of file
.topic
:userdoc User document
:eusrdoc

14.4 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.

Tag
Description
:caution Caution
:ecaution
:cgraphic Fixed-lines block
:ecgraphic
:color Color
:dl Definition lists
:dthd
:ddhd
:dt
:dd
:dt
:dd
:edl
:fig Figures
:efig
:figcap Figure caption
:fn Footnotes
:efn
:lines
:elines
:lp list
:note Notes
:nt
:ent
:ol Ordered lists
:li
:eol
:p Paragraphs
:parml Parameter lists
:pt
:pd
:eparml
:sl Simple lists
:li
:esl
:ul Unordered lists
:li
:eul
:xmp Examples
:exmp
:warning Warnings
:ewarning

*

Syntax:
.* comment-text
Parameters:

comment-text A line of text that is ignored by the On-line Help Builder.

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.

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

Syntax:
.browse #chain-id @topic-name @topic-name
Parameters:

chain-id Identifies a browse chain. At present, this tag must be specified as #1 as only one chain is allowed per topic.
topic-name The local topic-name or number of another topic. The first topic-name identifies the topic which precedes the current topic in the chain. If this is @0, then the current topic is the first topic in the chain.

Likewise, the second topic-name identifies the topic which follows the current topic in the chain. If this is @0, then the current topic is the last topic in the chain.

Apart from the special case @0, neither of these topic-names should be a number, or a string starting with a digit.

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

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

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

caution-heading Enables you to change the heading of the caution. If you do not specify a heading, the text CAUTION: is displayed on the screen.
caution-text The text to appear in the warning message.

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

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

Syntax:
:cgraphic.
text/graphics
...
:ecgraphic.
Comments:

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.

Example:
:cgraphic.
These lines all line up, retain indentation
and spacing and do not wrap:
+-------------------+ +------------------+
|                   | |                  |
|      Block A      | |     Block B      |
|                   | |                  |
+-------------------+ +------------------+
          |                     |
          +---------------------+
                     |
:ecgraphic.


color

Syntax:
color [fc=foreground-text-color]
[bc=background-text-color].
Parameters:

foreground-text-color The color of the text.
background-text-color The color of the text background.

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

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:

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.

Comments:

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.

Syntax:

The .command tag must be immediately followed by any of the following tags:

Tag
Description
.topic Inserts an entry in the contents list. Selecting this entry from the contents list would run the commands. You should only use this tag if the topic begins with a .context tag.
..index, :i1, :i2 Inserts an index entry.
:call Calls a COBOL program. The text following a :call tag should be exactly the same as you would enter after a RUN command.
:exec Executes an operating system instruction or an executable file. The parameter following this tag should be exactly the same as you would enter at the Net Express command prompt.
:shell Starts up a shell in the current operating system.

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

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

Syntax:
.comment comment-text
Parameters:

comment-text A line of text that is ignored by the builder.

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.

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

Syntax:
.context topic-name
Parameters:

topic-name The name of the topic.

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.

See also the sections :h1, :h2, :h3 and :h4, :h5, :h6.

Example:
.context @entry-field 
.context entry-field


define

Syntax:
.define @topic-name @context-no
Parameters:

topic-name The local topic-name.
context-no The context number, in the range 1 through 65,535, assigned to that topic.

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

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.

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:
nn The number of characters to be allocated for the term. The definition paragraphs are indented by this amount. The default is 10.
xxxx The spacing between a term and its definition.
term-hdg A heading to be displayed over the term (first column).
definition-hdg A heading to be displayed over the definition (second column).
term Text to be displayed as a term.
definition-text Text to be displayed as a definition.
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.

The possible values for xxxx are:

none The first line of the definition is always displayed on the same line as the term. If the term is longer than nn, the definition follows after one space. This is the default.
fit The first line of the definition follows on the same line as the term if the term is shorter than nn. If the term is not shorter than nn, the first line of the definition follows on the next line.
all The first line of the definition is always displayed on the line following the term.

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

Syntax:
$defmacro macro-name.
macro-text [macro-param ... ]
$edefmacro.
Parameters:

macro-name The name of the macro you are defining.
macro-text The text to be included in the macro. You can include the parameters passed to a macro by enclosing them in percent characters (%).
macro-param A parameter accepted by the macro.

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.

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

Syntax:
.end

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

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

Syntax:
:fig.
text
...
:efig.
Parameters:
text The text you want to display in a proportional font.

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

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. See also :cgraphic. and :xmp.

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.


figcap

Syntax:
:figcap. text
Parameters:
text The caption.

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

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

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

topic-name The topic-name of the footnote.
popup-text The text to be displayed.

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.

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

Syntax:
.freeze nn
Parameters:

nn The number of lines of the topic which are to be frozen at the top of the window, and not to be scrollable.

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

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

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

heading-tag One of :h1, h2 or :h3 which specifies the level of the topic entry in the contents list (they have no effect on the outcome of the topic) as follows:
:h1 A level one heading, not indented in the Contents list.
:h2 A level two heading, indented in the Contents list by four characters, and must follow an :h1 or another :h2 heading.
:h3 A level three heading, indented in the Contents list by eight characters, and must follow an :h2 or another
:h3 heading.
topic-name A topic-name for the topic. You must specify at least one topic-name for each topic. Specifying id=topic-name is the same as specifying name=topic-name.
context-no A context number to be reserved for the topic. You must specify the /PASS2 directive in order to be able to reserve a context number. Alternatively, you can use the .define tag which does not require the On-line Help Builder to make a second pass.
heading-text The text that appears as the title of the topic and as its entry in the contents list.
local Indicates that all topic-names specified are local. This is the default, but it can be specified.
global Indicates that all topic-names specified are external.

You can specify both local and global to indicate that all context names specified are both local and external.

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

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

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

subheading-tag One of :h4, :h5 or :h6 which specifies the sublevel of the topic entry in the contents list as follows:
:h4 A level one subheading
:h5 Is a level two subheading, and must follow an :h4 or another :h5 level subheading
:h6 A level three subheading, and must follow an :h5 or another :h6 level subheading.
These tags do not start a topic; they specify a heading within a topic that can be accessed from elsewhere.
topic-name A topic-name for the subheading. You can specify topic-name any number of times, including zero. Specifying id=topic-name is the same as specifying name=topic-name.
local Indicates that all topic-names are local. This is the default, but it can be specified.
global Indicates that all topic-names are external.
subheading-text The text that appears as the title of the topic. It is displayed in bold, followed by a blank line.

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

Syntax:
.heading text
Parameters:

text The heading to appear in the border of the topic window.

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

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

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

:i1 The primary index entry.
:i2 The secondary index entry. This entry is indented underneath the index entry for i1-id-name.
i1-id-name The name of the primary index entry, which can be up to 30 characters long.
index-text The text to appear in the index.

Comments:

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.

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

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

condition An expression involving Boolean variables. condition can include the Boolean operators and, or, and not.
true-text The source that is built if condition is true.
false-text The source that is built if condition is false. false-text can contain further conditional build tags.

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:

macro-name The name of the macro containing conditional macro text.
macro-param The parameter whose value you can check.
true-text The text to be included in the macro if macro-param is passed to macro-name.
false-text The text to be included in the macro if macro-param is not passed to macro-name.

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

Syntax:
.im filename
Parameters:

filename A file to be incorporated in the build.

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

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

Syntax:
..index index-text
Parameters:

index-text The text to be entered into the index.

Comments:

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. See also the section :i1, :i2.

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


lines

Syntax:
:lines
text
...
:elines
Parameters:
text The text you want to display.

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

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

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

topic-name The topic-name of a topic being referenced. Specifying a subheading name for topic-name results in the subheading being accessed.
context-no The context number of the topic being referenced. You can specify either topic-name or context-no for a link to a topic, but not both.
"filename" The name of a different on-line help file containing the topic being cross-referenced. If this is not specified, the topic is assumed to exist in the current on-line help file. You must include the quotation marks (") around the database name.
hotspot-text Any amount of text, delimited by the :elink. tag, that is displayed in the topic as a hypertext link. Selecting this text causes the cross-referenced topic to be displayed.

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

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

Syntax:
.list

The .list tag is used to indicate that the topic is a cross-reference 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

Syntax:
:lm margin=n.

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.

Example:
:lm margin=2.


lp

Syntax:
:lp. list-text
Parameters:

list-text Text within a list that does not interrrupt the list sequence. The text starts at the left margin of the current list item.

Comments:

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.

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:

macro-name The name of a previously-defined macro.
macro-param The name of a parameter to the macro macro-name.
value The value to pass to macro-name for macro-param. This can include calls to other macros.

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

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

note-heading Text used as a heading for the note. If you do not specify this, the default is Note.
note-text A single paragraph of text.

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

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

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

note-heading Text used as a heading for the note. If you do not specify this, the default is Note.
note-text Text to include under the note heading.

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

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.

Syntax:
:ol [compact].
:li. text
...
:eol.
Parameters:
text List item.

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.

Syntax:
:p. text
Parameters:
text Paragraph text.

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

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.


Note: If the first text line following a .context tag is not preceded by a :p. tag it is assumed to be a fixed-lines topic, as if :lines. was the first tag. These topics are not reformatted to fit the topic window. Using formatting tags within such a topic is not allowed.


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:
nn The number of characters to be allocated for the term. The definition paragraphs are indented by this amount. The default is 10.
xxxx The spacing between a term and its definition.
term Text to be displayed as a term.
definition-text Text to be displayed as a definition.

The possible values for xxxx are:

none The first line of the definition is always displayed on the same line as the term. If the term is longer than nn, the definition follows after one space.
fit The first line of the definition follows on the same line as the term if the term is shorter than nn. If the term is not shorter than nn, the first line of the definition follows on the next line.
all The first line of the definition is always displayed on the line following the term. This is the default.

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

Syntax:
.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.

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

Syntax:
:rm margin=n.

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.

Example:
:rm margin=5.


sl.

Syntax:
:sl [compact].
:li. text
...
:esl.
Parameters:
text List item.
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

Syntax:
.title title-text
Parameters:

title-text The title of the on-line help file. The title can be up to 32 characters long.

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

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

Syntax:
.topic topic-text
Parameters:

topic-text The title of the topic. The title can be up to 32 characters long.

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

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.

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

text List item.
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

Syntax:
:userdoc.
...
:euserdoc.
Parameters:

None.

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

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

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

warning-heading Enables you to change the heading of the warning. If you do not specify a heading, the text Warning: is displayed on the screen.
warning-text Text to be displayed as a warning.

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

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

Syntax:
:xmp.
text
...
:exmp.
Parameters:

text The text to display in a monospaced font.

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

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. See also :cgraphic and :fig.

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.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousConfiguration Option Tags Ohbld Error MessagesNext