Skip to content

WGML whpcvt interaction

Jump to bottom Edit New page
Jiří Malák edited this page Feb 28, 2021 · 24 revisions

Interaction between WGML and whpcvt utility

OW documentation support only base ASCII character set 0-127 codes. Higher characters 128-255 are used for whpcvt control codes and some special "extended" characters. Now OW documentation can use only English text, it is not capable to use other Languages as Japanese. It could be solvable to use ESC sequences for whpcvt control codes and get full character set space 0-255 for data. It will enable to support double-byte (Japanese) and other multi-byte encodings as UTF-8 etc. It will need to change whpcvt utility and appropriate definition changes in WGML macros.

Below is list of all whpcvt control codes used by OW documentation. They are generated by WGML compiler into output file and next process by whpcvt utility into source file for appropriate Help Compiler. A few codes are generated by WHELPDRV WGML driver.

Hex Dec Control code Notes
0x7F 127 WHP_HLINK
0x9D 157 WHP_FONTTYPE generated by WHELPDRV
0x9E 158 WHP_PAR_RESET
0x9F 159 WHP_EXCLUDE_OFF_BLANK
0xA0 160 WHP_UP_TOPIC
0xA7 167 WHP_TOPIC_LN
0xAA 170 WHP_TABXMP
0xB0 176 WHP_BMP
0xB4 180 WHP_EXCLUDE_OFF
0xB9 185 WHP_DLIST_DESC
0xC3 195 WHP_EXCLUDE_ON
0xC8 200 WHP_OLIST_START
0xC9 201 WHP_OLIST_END
0xCA 202 WHP_DLIST_START
0xCB 203 WHP_DLIST_END
0xCC 204 WHP_DLIST_TERM
0xD2 210 WHP_LIST_START
0xD3 211 WHP_LIST_ITEM
0xD4 212 WHP_LIST_END
0xD5 213 WHP_SLIST_START
0xD6 214 WHP_SLIST_END
0xDB 219 WHP_BOX_ON
0xE8 232 WHP_FLINK
0xEC 236 WHP_CTX_KW
0xEE 238 WHP_TOPIC
0xEA 234 WHP_DFN
0xEF 239 WHP_FONTSTYLE_START generated by WHELPDRV
0xF0 240 WHP_FONTSTYLE_END generated by WHELPDRV
0xF7 247 WHP_CTX_DEF
0xF8 248 WHP_TOPIC_NOLN
0xFE 254 WHP_BOX_OFF
0xFF 255 WHP_SPACE_NOBREAK

whpcvt Control Codes

The WHP file contains key code characters. These are ASCII codes greater than 127 which are unlikely to appear as normal GML text.

The format descriptions are BNF:
[] means optional stuff
<> means a necessary component described later
| is one of
anything else means actual text.

WHP_EXCLUDE_OFF ( Include On )

  • Location: column 0, no following text, default at start
  • Format: WHP_EXCLUDE_OFF

Text from the next line and on is to be included in processing.

WHP_EXCLUDE_ON ( Include Off )

  • Location: column 0, no following text
  • Format: WHP_EXCLUDE_ON

Text from the next line and on is to be excluded completely until the next '>' character is encountered. Include On/Off are not 'stackable'; the next include on always turns on processing.

WHP_CTX_DEF ( Topic Definition )

WHP_TOPIC_NOLN ( Popup definition topic )

Indicates that the <title> should not appear in a non-scrolling region at the top of the topic. The title will scroll with the topic text.

WHP_TOPIC_LN ( Normal definition topic default )

Indicates that the <title> will appear in a non-scrolling region at the top of the topic. The title will not scroll away as the topic is scrolled.

  • Location: column 0
  • Format: WHP_CTX_DEF<level>WHP_CTX_DEF[WHP_TOPIC_NOLN|WHP_TOPIC_LN]<ctx_name>WHP_CTX_DEF<title>[WHP_CTX_DEF<browse_list>[WHP_CTX_DEF<keywords>]]
  • <level> is the heading level of this topic. This is used for OS/2 IPF help, as well as in RTF and InfoBench "up" buttons. Heading levels can be skipped. Valid heading levels are from 0 to 6.
  • <ctx_name> is the help topic context name for the topic. Blanks (and other non-variable-like characters) are not allowed in this name.
  • <title> is the Title displayed at the top of the Topic. It may be any text.
  • <keywords> is a list of search keywords (actually, key word groupings), separated by commas and semi-colons. The <title> is usually put in here as well.
  • <browse_list> is the name of the browse list that this topic belongs to.

Topic text may follow immediately, or a topic section.

WHP_HLINK ( Hyperlink )

  • Location: in text lines, not split across lines
  • Format: WHP_HLINK<ctx_name>WHP_HLINK<text>WHP_HLINK
  • <ctx_name> is the help topic context name to which this hyperlink should go.
  • <text> is any arbitrary text which represents the hyperlink.

WHP_DFN ( Definition popup )

  • Location: in text lines, not split across lines
  • Format: WHP_DFN<ctx_name>WHP_DFN<text>WHP_DFN
  • <ctx_name> is the help topic context name to which this popup definition should go.
  • <text> is any arbitrary text which represents the definition link.

WHP_TOPIC ( Topic Section )

  • Location: column 0
  • Format: WHP_TOPIC<ctx_name>[WHP_TOPIC<order_nun>]
  • <ctx_name> name of new topic section.
  • <order_num> can be 0 or greater.

Defines a new topic section. If no <order_num> is provided, then this section is placed as the next unordered topic. If <order_num> is provided, then this section is ordered by its order number (lowest first). Ordered sections come after unordered sections.

WHP_LIST_START ( Unordered List Start )

  • Location: column 0, no following text
  • Format: WHP_LIST_START[c]

Starts an unordered list (with bullets). 'c' is optional, and indicates a compact list (no spaces between list items). Otherwise, spacing is as indicated in the definition.

WHP_LIST_END ( Unordered List End )

  • Location: column 0, no following text
  • Format: WHP_LIST_END

Ends an unordered list.

WHP_OLIST_START ( Order List Start )

  • Location: column 0, no following text
  • Format: WHP_OLIST_START[c]

Starts an ordered and numbered list. 'c' is optional, and indicates a compact list (no spaces between list items). Otherwise, spacing is as indicated in the definition.

WHP_OLIST_END ( Order List End )

  • Location: column 0, no following text
  • Format: WHP_OLIST_END

Ends an ordered list.

WHP_SLIST_START ( Simple List Start.

  • Location: column 0, no following text
  • Format: WHP_SLIST_START[c]

Starts a simple list (no bullets). 'c' is optional, and indicates a compact list (no spaces between list items). Otherwise, spacing is as indicated in the definition.

WHP_SLIST_END ( Simple list End )

  • Location: column 0, no following text
  • Format: WHP_SLIST_END

Ends a simple list.

WHP_DLIST_START ( Definition List Start )

  • Location: column 0, no following text
  • Format: WHP_DLIST_START

Starts a definition list.

WHP_DLIST_END ( Definition List End )

  • Location: column 0, no following text
  • Format: WHP_DLIST_END

Ends a definition list.

WHP_DLIST_TERM ( Definition List Term )

  • Location: column 0
  • Format: WHP_DLIST_TERM<term>

The text lines after the <term> are displayed below the <term> as paragraphs. There is nothing closer for defined terms since font styling and other effects can be inserted.

WHP_DLIST_DESC ( Definition Description )

  • Location: column 0
  • Format: WHP_DLIST_DESC<description>
  • <description> Definition Description Text

Starts a definition description.

WHP_LIST_ITEM ( List item )

  • Location: column 0
  • Format: WHP_LIST_ITEM<list_item>
  • <list_item> List Item Text

Item for a unordered, ordered or simple list. All list types can be nested arbitrarily.

WHP_CTX_KW ( Keyword )

  • Location: in text lines, or on their own lines
  • Format: WHP_CTX_KW<keyword>WHP_CTX_KW

<keyword> is added to the list of keywords for the current topic. If a line is defined containing only keywords, it does not generate a blank line.

WHP_PAR_RESET ( Paragraph Reset )

  • Location: in text lines
  • Format: WHP_PAR_RESET

Causes the next paragraph to be reset properly. Useful for RTF, when boxing and other wierd stuff require a paragraph reset to gets things back to normal.

WHP_EXCLUDE_OFF_BLANK ( Include On and Eat Blank Line )

  • Location: column 0
  • Format: WHP_EXCLUDE_OFF_BLANK

Same as Include On, but also eats the next blank line, if any.

WHP_BMP ( Bitmap Picture )

  • Location: in text lines
  • Format: WHP_BMP[i|l|r|c]WHP_BMP<file>WHP_BMP
  • 'i' is for inline, 'l' for left, 'r' for right, and 'c' for centered.
  • <file> is the name of the bitmap file.

WHP_FONTSTYLE_START ( Font Style start )

WHP_FONTSTYLE_END ( Font Style end )

  • Location: in text lines
  • Format: WHP_FONTSTYLE_START<font_styles>WHP_FONTSTYLE_START ... WHP_FONTSTYLE_END
  • <font_styles> is any combination of the following characters: b (bold), i (italic), u (underline), s (underscore).

The ending WHP_FONTSTYLE_END restores the font to plain with no styles. Hence, font stylings do NOT nest (this is due to the stupidity of OS/2 IPF).

WHP_FONTTYPE ( Font Type )

  • Location: in text lines
  • Format: WHP_FONTTYPE<facename>WHP_FONTTYPE<point_size>WHP_FONTTYPE
  • valid <facename> are recognized by the following subwords: Courier, Helv, Roman, Tmns, Symbol.
  • common <point_size> are: 8, 10, 12, 14, 18, 24.

Setup new Font Type. The Windows default is Helv 10.

WHP_BOX_ON ( Box On )

  • Location: column 0, no following text
  • Format: WHP_BOX_ON

Turns box mode on.

WHP_BOX_OFF ( Box Off )

  • Location: column 0, no following text
  • Format: WHP_BOX_OFF

Turns box mode off.

WHP_TABXMP ( Tab example )

  • Location: column 0
  • Format 1: WHP_TABXMP<tab_char>[ <stops>]*
  • <tab_char> TAB character used
  • <stops> TAB stop positions used

Setups up a tabbed example.

  • Location: column 0, no following text
  • Format 2: WHP_TABXMP

Ends a tabbed example.

WHP_FLINK ( File hyperlink )

  • Location: in text lines, not split across lines
  • Format: WHP_FLINK<file_name>WHP_FLINK<topic_title>WHP_FLINK<text>WHP_FLINK
  • <file_name> is the name of help file to jump to.
  • <topic_title> is the help topic name to which this hyperlink should go.
  • <text> is any arbitrary text which represents the hyperlink.

WHP_SPACE_NOBREAK ( Hard space )

  • Location: in text lines
  • Format: WHP_SPACE_NOBREAK

WHP_UP_TOPIC ( Up topic )

  • Location: ?
  • Format: WHP_UP_TOPIC ?
Add a custom footer
C++
OW Development
WGML Development
Clone this wiki locally