HP's SGML hypertext help system
Dave_Raggett <dsr@hplb.hpl.hp.com>
From: Dave_Raggett <dsr@hplb.hpl.hp.com>
Message-id: <9301051213.AA20032@manuel.hpl.hp.com>
Subject: HP's SGML hypertext help system
To: www-talk@nxoc01.cern.ch
Date: Tue, 5 Jan 93 12:13:08 GMT
Mailer: Elm [revision: 66.25]
Long description of HP HelpTag SGML format for hyptertext help system
=====================================================================
I have just been shown HP's new hyptext help system for VUE 3 (HP's user
desktop environment for X11, Motif). It uses SGML for the authoring language
and is a very professionally package. The group may be interested in its
scripting language which has a lot of similarities with HTML, although it
isn't a networked application.
Unlike WWW, the HP Help system requires you to compile the source files. It
does this to compile keyword indexes and to provide a more compact format.
The HP Help system's features appear to draw heavily on Microsofts help
system for Windows 3 on the PC.
For full information order the "HP Help System Developer's Guide"
part number B1171-90055 from an HP supplier.
Summary features:
o multi font
o multi language (defaults to ISO 8859-1 character set)
o resizeable - reformats to match new window size
o keyword indexes (see below)
o glossaries
o hypertext links to anchors in same and other help volumes
o figures with captions (tiff, x bitmap, x pixmap, x window dump: xwd)
o small inline graphics
o optional text flow around figures
o control over launching new window or changing view in current window
o It doesn't support networked hypertext links.
o richer use of SGML than HTML
o metainfo section at front of help volume
The keyword index mechanism is similar to that on Windows 3. You choose
search from a menu, and a dialog box appears. The index is an alphabetical
list of important words and phrases along with a list of each occurrence in
the help volume.
The dialog allows you to type the first few letters and see matching
keywords. You can then click on a keyword to see a list of matching topics.
You then click on a topic name to view that topic. This approach allows
you to explore what keywords are available, unlike the W3 and WAIS approach
which leave you in the dark!
Glossary terms are shown with a dashed underline. Clicking on such a term
pops up a small dialog box with an explanation from the glossary. The
glossary itself is defined separately, rather than embedding each
explanation with each term.
Help volumes have the following generic structure:
<helpvolume>
<metainfo>
<title> Volume title
<copyright>
Copyright topic goes here ...
<abstract>
The abstract describing your help system goes here.
.
. There may be other meta information topis.
.
<\metainfo>
<hometopic> Home topic title
Body of home topic goes here ...
<s1> Title of First Subtopic goes Here
Body of first subtopic goes here ...
<s2> Title of Second Subtopic goes Here
Body of second subtopic goes here ...
.
.
.
<glossary>
The body of the glossary, which contains term definitions, goes here ...
<\helpvolume>
Notes:
=====
a) The ETAGO (end tag open) uses "<\" rather than "</"
b) frequent use is made of entity declarations
e.g. <!entity MyPic FILE "picture.tif">
c) &< gives "<", &\ gives "\", && gives "&"
d) title text is typically terminated by end of line
rather than an end tag, e.g. <hometopic>
e) many tags support an id attribute for defining anchors
<chapter>, <figure>, (idx>, <image>, <item>, <location>,
<otherfront>, <p>, <rsect>, <s1> ... <s9>
f) many tags support the shorthand <tag|text| for <tag>text<\tag>
The full set of tags is:
Meta info:
<metainfo> ... <\metainfo>
<title>
<copyright>
<abstract> ... <\abstract>
<otherfront> (other front matter)
Structure of a help volume:
<!entity>
<helpvolume> ... <\helpvolume>
<hometopic>
<chapter>
<s1> ... <s9> (headings introducing topic in the hierarchy)
<rsect> (reference section)
<rsub> (reference subsection heading)
<otherhead>
<procedure> (starts a section within a topic)
<p> (paragraph, optionally wrapped around a graphic)
Inline elements:
<book> ... <\book>
<computer> ... <\computer> (shorthand ``text'')
<emph> ... <\emph> (emphasis - shorthand !!text!!)
<ex> ... <\ex> (example)
<vex> (verbatim example)
<image> ... <\image> (keep line breaks, no wrapping or justification)
<term>text<\term> (occurrence of glossary entry - shorthand ++text++)
<user>response<\user> (distinguishes user input in example dialog)
<var>text<\var> (distinguishes user supplied variable, shorthand %%text%%)
<newline> (starts a newline within same paragraph)
<p> (paragraph, optionally wrapped around a graphic)
<quote>text<\quote> (language dependent directional quote marks)
&....; (see <!entity>)
Important information:
<note> ... <\note> (can use a standard icon)
<caution> ... <\caution> (can use a standard icon)
<warning> ... <\warning> (can use a standard icon)
<emp> ... <\emph> (emphasis - shorthand !!text!!)
Lists:
<list> ... <\list>
<item> (for <list>, shorthand *)
<lablist> ... <\lablist> (labeled list)
<labheads> (list headings for lablist)
Graphics:
<figure> ... <\figure> (captioned figure)
<graphic> (small graphic embedded in text line)
Glossary and keyword index:
<glossary>
<dterm> (definition of term)
<term> (occurrence of glossary entry - shorthand ++text++)
<idx> ... <\idx> (defines entry to occur in the keyword index)
Cross-references and hyperlinks:
<xref id> (hyperlink to given anchor point in this volume)
<link> ... <\link>
<location> ... <location> (defines anchor point)
<term>
Hidden text:
<!-- ... --> (comment)
<memo> ... <\memo>
Titles and headings:
<abbrev> (used in help dialog in place of long heading)
<head>
<otherhead>
<procedure>
Override meaning of HelpTag markup:
<esc> ... <\esc> (escape from markup recognition)
<vex> (verbatim example, no tags are recognised)