home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Simtel MSDOS - Coast to Coast
/
simteldosarchivecoasttocoast.iso
/
dv_x
/
dvxhlp10.zip
/
DVXHELP.DOC
next >
Wrap
Text File
|
1992-06-03
|
11KB
|
277 lines
The DESQview/X Help File Format
By Daniel J. Bodoh
Copyright 1992 by Daniel J. Bodoh
Permission is granted to copy this document free of charge in
whole or in part, as long as the copyright notice is included.
----------------------------------------------------------------------------
WARNING: The help file format that I describe in here may not be 100%
accurate. QOS has not (yet) published the help file spec, so I figured it
out for myself with a binary editor. Use this information at your own risk!
I cannot be held responsible for any damage caused by the use this
information or the MDVXHELP program. I AM NOT EMPLOYED BY QUARTERDECK,
AND THIS IS NOT AN OFFICIAL QUARTERDECK DOCUMENT.
----------------------------------------------------------------------------
INTRODUCTION
------------
One of the enhancements offered by DESQview/X is its extensive online help.
Quarterdeck supplies help files for the window manager, file manager, etc. in
the /DVX/HELP directory. Two programs are used to display the help files:
/DVX/DISPHELP.EXE and /DVX/HELP/DVXHELP.EXE. The help files are hypertext
documents, which means that a help file can have cross references to other
parts of the document to which the user can jump with the click of a mouse.
The help files allow you to create bold, underlined and highlighted text; to
indent paragraphs; and to include icons created by the DESQview/X icon
editor. The help file spec is very powerful, although I wish there were more
text formatting options. For example, I have not found a way to "TAB".
DEFINITIONS
-----------
Let's establish some definitions:
CR Carriage return, ASCII 13 decimal
DWORD A 4-byte value.
END The ASCII value 1Ah
Icon A .XPM file created by the DESQview/X Icon Editor.
LF Line feed, ASCII 10 decimal
NL A CR followed by a LF
Offset The position in the file, relative to the beginning of
the file, in bytes. The first byte of the file is at
offset 0. Offsets are expressed in hex numbers.
Section A synonym of "topic".
Tag The index marker that you see sticking out the bottom of
the notepad on the help screen.
Topic A logical unit of text. The topic is the smallest unit
of text to which a cross-reference can refer.
WORD A 2-byte value.
OVERVIEW
--------
The help files are stored in the \DVX\HELP directory with the extension
".HLP". To view a help file, you must run the DISPHELP program:
CD \DVX
DISPHELP -f <help-file-name>
DISPHELP assumes that the help file is in \DVX\HELP, so you should not
specify a path. For example, to view the Icon Editor help file, type the
following:
CD \DVX
DISPHELP -f ICONED.HLP
DISPHELP actually runs \DVX\HELP\DVXHELP.EXE, the Help Engine, to display the
help file.
THE HELP FILE FORMAT
--------------------
The help file consists of six sections, in the following order:
(1) the header,
(2) the front cover,
(3) the body,
(4) the tags,
(5) the icons, and
(6) the directory.
In the following description, text in single quotes appear in the file
just as typed. "NL" represents the byte combination 0Ah and 0Dh
(carriage return and line feed) and "END" represents 1Ah. Spaces are
provided for ease of reading and are not part of the format unless they
are in single quotes. Descriptions are placed within "<" and ">" signs.
Optional elements are enclosed in "[" and "]".
HEADER
------
The header gives the position and size of the directory.
OFFSET SIZE DESCRIPTION
0h DWORD Offset of directory
4h WORD Size of directory, in bytes.
FRONT COVER
-----------
The front cover contains the title and subtitle on the front cover of
the displayed notebook. Its name in the directory is "FRCOVER". The
front cover starts at offset 6h:
'/FT' <front cover title> NL '/FS' <subtitle> NL END
BODY
----
The body consists of "sections" which are terminated with END. Each
section is made up of one or more paragraphs which end with NL. There
must be no NL's within a paragraph; DVXHELP formats the text based on
the width of the help window.
Codes are embedded into the text for formatting and cross-referencing.
The specification for an individual section is:
[<paragraph text>] NL [[<paragraph text>] NL [...]] END
The body consists of a concatenation of the sections. Each section is
given a name in the directory.
CODES
-----
Here are the codes that can be embedded in <paragraph text>.
CODE DESCRIPTION
-----------------------------------------------------------------
'//' Becomes a single '/'
'/JB' <text> '/' <section name> '/' Highlights <text>. If user
clicks on <text>, jump to
section <section name>.
'/FH' Turn on a larger, bold font
'/FL' Turn on a bold font
'/FB' Turn off /FH and /FL
'/U' Toggle underlining of text
'/CH' Highlight text
'/CN' Turn off text highlight
'/IL' <icon name> '/' Place the icon referenced in
in the directory as <icon
name> here.
'/IE' <icon name> '/' Similar to /IL, I'm not sure
what the difference is yet.
'/ML' <n> '/' Set the left margin for all
remaining text in the
section <n> pixels to the
right from the current
margin. If <n> is negative,
move the margin left.
TAGS
----
The tags are shown at the bottom of the notebook, and allow the user to
jump to one or more sections by clicking on the tag. The tag section is
called "BKCOVER" in the directory. You can specify the color of each
tag as well as the color of the notebook cover in this section. The
first part of the section specifies the notebook cover color, like so:
'/CC' <color> '/' NL
I haven't tried any <color> values besides 'blue'.
Then the tags are listed:
'/CT#' <rrggbb> '/' NL '/JB' <tag text> '/' <section> '/'
['/CT#' <rrggbb> '/' NL '/JB' <tag text> '/' <section> '/'
[...]] END
The <rrggbb> value specifies the red-green-blue color mix for the tag.
Each primary color is specified with a 2-digit hex value, 00h to FFh.
For example, a pure red tag would be
'/CT#FF0000/'
which actually turns out to be a pretty dark red. Quarterdeck's version
of red tags are
'/CT#FF5555/'.
The <tag text> appears in the tag, and is preceded by an underlined
digit. Clicking on that tag will cause a jump to section <section>.
The tags appear from left to right in the order specified in the help
file, and the width of the notebook is adjusted to fit all the tags.
ICONS
-----
One of the nicest features of the help file is the ability to place
icons anywhere using /IL and /IE. The icons section is simply a
concatenation of all the .XPM files. They are NOT delimited with ENDs.
The name and offset of each icon is stored in the directory.
DIRECTORY
---------
The directory is the most important section of the help file. It
associates section and icon names with their offsets into the file.
Every time DVXHELP encounters a /JB, /IL or /IE, it takes the icon or
section name and gets the offset of that icon or section from the
directory.
Each directory element consists of the following. The offset is
relative to the beginning of the directory element.
OFFSET SIZE DESCRIPTION
-----------------------------------------
0h 12 BYTES The name of the section, padded to
right with 0's. If the name is
exactly 12 bytes, it is NOT
NULL-terminated. The section name is
not case-sensitive.
12h DWORD Offset of this section
There must be ((number of sections in body)+(number of icons)+4)
directory elements. The directory elements must appear in this order:
SECTION NAME DESCRIPTION
-----------------------------------------
'directory' Special directory element. The
must be the offset this directory
element (the same value as the first
DWORD of the help file).
'FRCOVER' Offset of the Front Cover.
'CONTENTS' Offset of the first body section.
Note that this section *must* be
named 'CONTENTS'.
Remaining body sections
'BKCOVER' Offset of the TAGs section.
Icon names Offset of each icon
Terminator Directory element is completely
filled with 0's.
CORRECTIONS, SUGGESTIONS, ETC.
------------------------------
If you find errors or have any suggestions, please let me know. I can be
reached from a variety of networks:
From the Internet or Usenet: write to ``bodoh@xraylith.wisc.edu''.
From Fidonet: write to ``Daniel Bodoh 1:121/99.0''
From Compuserve: write to ``>INTERNET:bodoh@xraylith.wisc.edu''.
From DECnet: write to ``cxrl::bodoh''
From Bitnet: write to ``bodoh@xraylith''
And my old-fashioned address is:
1402 Regent #417
Madison, WI USA 53711