Chapter 11: On-line Help Source File Format

This chapter describes the ASCII text format of on-line help source files.

An on-line help source file is a standard ASCII text file. It contains the text required broken up into topics. Tags are used to define aspects of the topic, such as its title. Additional tags are used within the text to indicate how it should be formatted when displayed.

In most situations, topics are automatically formatted dynamically at display time to fit within the sides of the topic window so that no horizontal scrolling is necessary. This dynamic formatting is referred to as flexi-text. Some formatting tags prohibit this ability, so you should use these tags with care.

The tags for this On-line Help System have been designed to be compatible with IBM IPF System and Microsoft Advisor. However, we recommend you use the On-line Help System tags in preference to other tags.

Because the builder also processes Microsoft Advisor format source files, you must use a paragraph or list tag to define your first text line to ensure that the flexi-text processing is activated.

There are four types of text contained within the source file:

• Builder control tags

  These control the On-line Help Builder.

• Control tags

  These define the general properties of the text.

• Formatting tags

  These define specific aspects of formatting.

• Text lines and attributes

  These define the text to be displayed and any highlighting required.

All tags are preceded by a colon (:), a period (.) or a dollar sign ($). The tags preceded by ":" or "$" can start anywhere on a line. The tags preceded by "." must start in column one of a line. All tags can be followed by parameters. Tags preceded by ":" are terminated by a period, the parameters normally appearing before the period.

The source file must start with a .define, .title, .comment or .context tag. Blank lines are ignored unless they are within a fixed-lines topic or block.

11.1 IBM IPF System Compatibility

Ohbld recognizes all Information Presentation Facility (IPF) tags and symbols specified in IPF V2.00. Of these tags, the following are fully implemented in this On-line Help System and are described in the chapter On-line Help Tags:

.* :caution :cgraphic :color :dl :fig :figcap

:fn :hp1 through :hp9 .im :li :lines :lm :lp

:note :nt :ol :p :parm1 :pd :pt

:rm :sl :title :ul :userdoc :warning :xmp

The following IPF tags are partially implemented in this On-line Help System; some of them are described in the chapter On-line Help Tags:

:artlink
:artwork
:font
:h1 through :h6
:i1 and :i2
:link

The following IPF tags are not currently implemented in this On-line Help System, although Ohbld does recognize them if used:

:acviewport
:ctrl
:ctrldef
:ddf
:docprof
:fn
:hide
:icmd
:isyn
:pbutton
:table

For details on IPF, see the book Information Presentation Facility Guide and Reference in the IBM OS/2 2.0 Technical Library.

Ohbld recognizes IPF symbols, which you use to display special characters in your on-line help files. Each symbol begins with an ampersand (&) and ends with a period (.). Symbols are case sensitive; uppercase characters create different symbols from lowercase characters.

The following table gives some examples of IPF symbols, showing the character displayed, the name, and the IPF symbol.

Character	Name	IPF Symbol
&	Ampersand	&amp
@	At sign	&atsign
$	Dollar sign	&dollar
>	Right arrowhead	&rahead

For a complete list of IPF symbols, see the book Information Presentation Facility Guide and Reference in the IBM OS/2 2.0 Technical Library.

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

11.2.1 Syntax Summary

• Define a comment.

  .comment comment-text

• COPY source text.

  .im filename

• Conditional building.

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

• Define a macro.

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

• Conditional building in macros.

  $ifmdef macro-param.
  true-text
  $elsem.
  false-text
  $endm.

• Use a macro.

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

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

11.3.1 Syntax Summary

• Browse chains

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

• Command topics

  .command 
  :exec 
  :call 
  :shell

• Contexts

  .context topic-name

• Define context numbers

  .define @topic-name @context-no

• End topic

  .end

• Frozen lines

  .freeze nn

• Headings

  :h1, :h2, :h3

• Index entries

  :i1. index-text
  :i2. index-text
  ..index index-text

• Linking hotspots

  :link.
  :elink.

• Lists of cross-references

  .list

• Pop-up windows

  .popup

• Subheadings

  :h4, :h5, :h6

• Title of file

  .title title-text

• Title of topic

  .heading text
  .topic text

• User Document

  :userdoc.
  :eusrdoc.

11.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 are recommended to use column one. A summary of tags available is shown below in alphabetical order and is followed by a description of each.

11.4.1 Syntax Summary

• Caution

  :caution.
  :ecaution.

• Color

  :color [fc] [bc]

• Examples

  :xmp.
  :exmp.

• Figures

  :fig.
  :figcap
  :efig

• Fixed-lines blocks

  :cgraphic.
  :ecgraphic. 
  
  :lines.
  :elines.

• Footnotes

  :fn [id=].
  :efn.

• List parts

  :lp.

• Margins

  :lm margin=n.
  :rm margin=n.

• Notes

  :note [heading-text=] text

  or

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

• Paragraphs

  :p.text
  

• Text lists
  • Definition lists

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

  • Ordered lists

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

  • Parameter lists

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

  • Simple lists

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

  • Unordered lists

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

  Text lists can also contain paragraphs, fixed-lines blocks and further lists.

• Warnings

  :warning [heading-text] text
  :ewarning.

The formatting tags are listed alphabetically and described below, apart from the text list tags which have been grouped together at the end of the list.

11.4.2 Using Lists - Simple, Unordered and Ordered

The list tags are used to create various types of lists.

A list is started by using one of the :sl, :ul or :ol tags. A single parameter, compact, can be specified. This creates a list without blank lines between each item.

Each item in the list is preceded by the :li. tag. The text for the item can follow the tag on the same line, indented by any amount to allow visual structuring of the source text.

The item can contain additional paragraphs, each preceded by a :p. tag, or blocks of fixed-lines, using :lines or :cgraphic tags. An item can also contain another list of any type.

The list is terminated by the appropriate end of list tag; that is, one of :esl., :eul. ,or :eol.

11.4.3 Using Lists - Definition and Parameter

Definition and parameter lists are used to present text as a term followed by one or more paragraphs of description. These lists are displayed as two columns, with the first column containing the terms and the second their definitions. You specify the width of the first column according to the nature of your terms.

Following paragraphs can be indented, and the first line can be made to follow the term, suitably indented, or start on the next line.

Definition lists are the same as parameter lists apart from the default setting of the break parameter, and the fact that parameter lists do not include headings for the terms and definitions.

11.4.3.1 Definition Lists

A definition list presents the terms and their values as two columns with, by default, the description starting on the same line as the term.

To specify a definition list, start with the :dl tag.

11.4.3.2 Parameter Lists

A parameter list is used to present a list of parameters and their meanings or values. The list is displayed in a similar manner to the definition list except that, by default, the beginning of the second column (the definition text) is always displayed one line below the first column (the term). Heading tags are not included.

To specify a parameter list, start with the :parml tag.

11.4.4 List Parameters

compact	specifies that the items in the list are not separated by blank lines.
tsize=nn	specifies the space in characters to be left for the term. The definition paragraphs are indented by this amount. The default is 10.
break=xxxx	specifies the spacing between the term and its definition, where xxxx is one of the following: none Always follow the term by the first line of the definition. If the term is longer than tsize, the line follows after one space. fit Place the first line of the description on the same line if the term is shorter than tsize. If not, start the description on the next line. all Always start the description on the next line. The default value is none for definition lists and all for parameter lists.

For a description of the available On-line Help System tags, see the chapter On-line Help Tags.

11.5 Text Lines and Attributes

The body of a topic is made up of text lines. A text line begins with a non-period character. The following flags can be embedded within the text to change the attribute of the topic text:

Text	Effect
\a	Start of hotspot text (visible).
\b	Bold.
\i	Italic.
\u	Underline.
\p	Plain.
\v	Hotspot cross-reference delimiter (invisible).
:hp1.	Italic, :ehp1. to end.
:hp2.	Bold, :ehp2. to end.
:hp3.	Bold and italic, :ehp3. to end.
:hp4.	Red, :ehp4. to end.
:hp5.	Underline, :ehp5. to end.
:hp6.	Underline and italic, :ehp6. to end.
:hp7.	Underline and bold, :ehp7. to end.
:hp8.	Blue, :ehp8. to end.
:hp9.	Magenta, :ehp9. to end.

Bold, Italic and Underline are toggles and can be turned on, off and combined. \p resets the current attribute to plain text. \a displays the visible hotspot text in the attribute defined for the color-hotspot parameter in the configuration file (see the section Configuring the On-line Help Viewer in the chapter On-line Help System for details).

If you need to use the backslash character (\) in your topic, use a pair of backslashes. Hence c:\\cobol\\demo appears on the screen as c:\cobol\demo.

---

Note: All special characters (\, :, ., $) should be preceded by "\" when they are part of the text.

---

Example

.context @file-menu
:p. Make sure that your current drive is :hp1. c:\\cobol\\demo:ehp1.

This results in the drive being correctly displayed, in the attribute defined to be italics.

11.5.1 Hotspots and Invisible Text

A hotspot is visible text within a text line that has a topic-name associated with it. When the hotspot is activated in the On-line Help Viewer, the cross-referenced topic is displayed.

By default, hotspots are highlighted automatically. If you have defined an attribute for hotspots in the configuration file, you must use the \a flag to display the hotspot in the configured attribute; otherwise, it is displayed in the current text attribute.

Cross-references are embedded using invisible text, delimited using the \v tag. By default, the hotspot for the cross-reference is the string of characters preceding the first \v tag, up to but not including the first space. The \a (anchor) flag can be used to override this. When used, the \a flag indicates that the hotspot for the cross-reference is the string of characters between the \a flag and the first \v tag. Alternatively, you can use the :link and :elink. tags to define hotspots.

The cross-reference is a topic-name. If the topic being referenced lies within the same file, then we recommend that you use a local reference since this is built to a direct pointer to the topic.

In addition to topic-names you have defined, you can use the following topic-names as cross-references:

Topic-Name	Description
!B	Back - causes the previously displayed topic to be displayed when the hotspot is selected.
!C	Contents - cause the contents list to be displayed when the hotspot is selected.
!I	Index - causes the index to be displayed when the hotspot is selected.

If a context number is used (having been previously defined using a .define tag), it can be followed by a further number (separated by a colon) which indicates the point in the referenced topic that should appear on the top line when the topic is first displayed. As yet there are no automatic methods of defining this number. Consequently, you have to work out the offset of the required point by trial and error.

Alternatively, you can use cross-referencing to the :h4, :h5 and :h6 tags to specify the point in the topic that should appear on the top line when the topic is first displayed.

Example

In the following examples the word "highlights" and the phrase "Nested menu" are hotspots cross-referencing to topics @hilite and @submenua at offset 123 respectively.

.context @menu
:p. You can find out about highlights\v@hilite\v 
and \aNested menu\v@submenua:123\v by selecting these items.

11.5.2 Microsoft Advisor Format Source Files

A subset of the commands used for creating a Microsoft Advisor help file is recognized by this system. This allows source files used with the Microsoft Advisor system to be used to create .hnf files. Topics created using this format are treated as fixed-lines blocks. Consequently, these are not reformatted when the window size is changed.

Unless you need to share source files between the two systems, you should make use of the formatting tags described earlier in this chapter when creating source files for this system.

Microsoft Advisor format files are supported only in character environments; that is, by Hyhelp in GUI emulation mode.