Collection of Hack-Phreak Scene Programs/cleanhpvac.zip/cleanhpvac/POVHELP.ZIP/source/helpdata.doc

Text File | 1994-08-16 | 21KB | 451 lines

/****************************************************************************
*                   HELPDATA.DOC - Version 1.0 - 4 July 1994
*
*  This document describes the format of the POVHELP database.
*
*  from Persistence of Vision Raytracer
*  Copyright 1994 Persistence of Vision Team
*  Copyright 1994 Christopher J. Cason.
*---------------------------------------------------------------------------
*  NOTICE: This data file is provided so that users may experiment with
*  enhancements to POV-Ray and to port the software to platforms other
*  than those supported by the POV-Ray Team.  There are strict rules under
*  which you are permitted to use this file.  The rules are in the file
*  named POVLEGAL.DOC which should be distributed with this file. If
*  POVLEGAL.DOC is not available or for more info please contact the POV-Ray
*  Team Coordinator by leaving a message in CompuServe's Graphics Developer's
*  Forum.  The latest version of POV-Ray may be found there as well.
*
*  POV-Ray files may also be obtained from ftp.uwa.edu.au in pub/povray.
*
*  This document was written in its entirety by Christopher J. Cason.
*  Its use is freely and permanently granted to the POV-Team and POV users
*  under the conditions specified in POVLEGAL.DOC.
*
*  Author : C. J. Cason ([e-mail], CIS 100032,1644)
*
*****************************************************************************/

               P O V - H E L P  -  D A T A B A S E  F O R M A T
               ------------------------------------------------

This file is provided to encourage people to write custom help converters
rather than taking an ASCII version of POVRAY.DOC and converting it manually.
Once a converter has been released, whenever we change the docs, the converted
versions can be re-generated easily. The intention is that this database be
ported to other, native, help formats, as well as to output formats such as
LaTeX, Postscript, RTF, etc.

NOTE : All 16 and 32-bit words referenced in this document are stored in the
database in Intel (least significant byte first) format.

                                DATABASE HEADER

typedef struct
{
  char                  signature [8] ;
  unsigned short        reader_version ;
  unsigned short        database_version ;
  char                  sec_number_len ;
  char                  sec_title_len ;
  unsigned long         flags ;
  unsigned short        author_count ;
  unsigned short        section_count ;
  unsigned short        appendix_count ;
  unsigned short        reference_count ;
  unsigned long         title ;
  unsigned long         title_length ;
  unsigned long         copyright ;
  unsigned long         copyright_length ;
  unsigned long         authors ;
  unsigned long         author_length ;
  unsigned long         table_of_contents ;
  unsigned long         table_of_contents_length ;
  unsigned long         reference_index ;
  unsigned long         reference_index_length ;
  unsigned long         reference_string_length ;
  unsigned long         references ;
  unsigned long         reference_length ;
} help_file_header ;

char                  signature [8] ;

Should be the string "POV-Help". Used for consistency check.

unsigned short        reader_version ;

The version of the reader needed to read the database. Version 1.0 == 100.
It is possible to have a newer database version that remains compatible with
older readers. This is to indicate if the reader can handle the database.

unsigned short        database_version ;

The version of the database. Version 1.0 == 100.

  char                  sec_number_len ;
  char                  sec_title_len ;

These give the maximum length of the section number and title arrays later
on in the database. Typically, these will be set to the length of the longest
example of each of these that occurred in the input file that created the
database.

unsigned long         flags ;

Currently don't do much ; later on, will be used to indicate compression, etc.
Also, will be used to indicate if the database was optimised for a specific
platform, what sort of graphics are embedded, etc., etc.

unsigned short        author_count ;
unsigned short        section_count ;
unsigned short        appendix_count ;
unsigned short        reference_count ;

The number, respectively, of

  o Author entries,
  o Sections,
  o Appendices, and
  o References

in the database.

unsigned long         title ;
unsigned long         title_length ;

The absolute offset of the title text in the database file, and its length.

unsigned long         copyright ;
unsigned long         copyright_length ;
unsigned long         authors ;
unsigned long         author_length ;

Ditto for copyright and authors.

unsigned long         table_of_contents ;
unsigned long         table_of_contents_length ;

The absolute offset of the table of contents entry in the database file. Also
its length.

unsigned long         reference_index ;
unsigned long         reference_index_length ;

Ditto for the reference index.

unsigned long         reference_string_length ;

The length of each reference string in the reference index. Typically the
length of the longest string.

unsigned long         references ;
unsigned long         reference_length ;

The absolute offset of the reference array, and its length.

General Overview.

The help database consists of blocks of 'section text' - which are individually
numbered subsections in the source, and include appendices - with embedded
formatting and linking information. Each section can have links that point to
one or several other sections. Users may browse these links.

The Table of Contents (TOC) is an array of section numbers (strings) and
section titles (strings again) the length of which is given in the header.
Associated with each entry in the TOC is the absolute 32-bit offset of the
relevant section in the database itself.

typedef struct
{
  unsigned long         section ;
  unsigned long         section_length ;
  char                  is_appendix ;
  char                  spare ;
} TOC_entry ;

Each entry in the TOC follows this format - the Section offset in the database,
followed by the length of the section, followed by a flag indicating if the
section is an appendix or not. Appendices are not treated very much differently
from non-appendices ; the difference mainly relates to how they are presented
to the ultimate user. NOTE : if your compiler pads structures out to word or
double-word boundaries, be sure (when reading the data from the database) to
read the correct amount of data, which is 10 bytes. (Though I suppose it won't
hurt to read more, as long as you seek back to the correct location.)

Immediately following the appendix flag is a character array whose length is
given by the header field 'sec_number_len'. This field contains the ASCII
representation of the section or appendix number, in the form '1.2.3', or
'E.1', for example. Only as many decimal points as needed are used.

Immediately following the section number is the section title. Again, the length
of this array is given in the header, by the field 'sec_title_len'.

After this array, the next section entry starts, with no padding.

Title

The title is plain ASCII text, LF delimited.

Authors

The authors section is a sequence of LF delimited lines, NULL (0x00) separated
between each author's entry.

Copyright

The copyright section is formatted in a fashion similar to that of the sections,
using the same codes. However, hypertext links are not supported.

References

The Reference Index is an array of 32-bit double words which represent offsets
into the database. At the location indicated by each offset is the actual
variable-length reference represented by the index into the array of offsets.

The reference itself is preceded by a 16-bit word known as the 'child count'
which gives a count of actual targets for this index, minus one. Each target is
represented by a 32-bit double word which gives the offset into the file of the
targeted text. This may be at the start of or anywhere within a section or
appendix.

Typically, the first target will be the most important one and for systems that
only support one target (or 'link') for each reference, this is the one to
choose. Subsequent ones (if the child count is > 0) will be to other sections in
the document which bear relation to the subject being referenced.

Remember, the child count gives the number of targets minus one. That is to say,
there is always at least one target (the 'parent') and any subsequent ones are
'children'. If the child count is 0, there are no children and only one 32-bit
double word will be present.

The section on 'Sections' gives more information on references.

Sections

The section text is a aggregation of ASCII text with special control codes
embedded. Control codes are between 0xe0 and 0xff. LF characters only appear
when a literal LF is required in the text (i.e. the CODE FRAGMENT or PRESERVE
FORMATTING keywords were used in the source text.) Lines are 'long', i.e., they
have had normal line feeds stripped out ; it is the help reader's job to wrap
the lines properly for the output medium in use.

Also embedded in the text are references and targets. A reference is a pointer
to a target, a target is something that a reference points to. Targets can
have multiple references pointing to them, and a single reference can have
multiple targets.

Take, for example, a reference to the word 'Sphere' in the POV-Ray documentation.
The word 'sphere' would be highlighted at the location of the reference,
indicating that link jumping is possible. If the user selects that reference,
the reader would jump to the first target for that reference, which might be
the definition of the 'Sphere' primitive. Any subsequent targets would be of
lesser importance, perhaps other examples of the usage of that keyword. This
is important, because some hypertext systems can only handle one target for
each reference, and as such the author of the converter program has to be able
to select the most appropriate target if more that one is defined.

In the source of the document, each target has a 'priority'. This defaults to
a given value, depending on the context, if one is not specified. After parsing
the document, each target with the same name is first sorted in order of
priority, and then in order of appearance. The author of the document would
presumably make the most important target of the highest priority.

All section and appendix titles and numbers are automatically made targets,
and given a higher priority than the default. In the absence of an explicit
override by the author, these targets will appear first in the list of targets.

As well as being used for hypertext jumping, targets have their original ASCII
names (as defined in the source text) stored in the database so that they may
be used for keyword searches. (In the section text, targets are identified by
index and not by name.)

Currently, the sections have the concept of embedded line drawings. These are
typically ASCII art and are delimited in the text so that an appropriate fixed-
pitch font can be selected by the display program. At a later stage, these will
go away and be replaced by a reference to the image database that will be bound
into the help file. The original ASCII art will be found there, along with IBM
line drawings, monochrome bitmaps, colour bitmaps, or whatever the author has
defined in the source. The reader will be able to choose whichever is best for
its particular output format.

                                Embedded Codes

If any code is escaped by the ESCAPE code, it loses any special meaning.
Note that the 'ESCAPE' code referred to here is not an ASCII escape (0x1b) but
the code defined in HELP.H as 'ESCAPE'.

See HELP.H for the current definition of each code. These have changed since
the first beta of POV-Help so make sure you've got a current database. [The
old one has a different signature in its header so you'll know it.]

BOLD_ON         BOLD_OFF
ITALIC_ON       ITALIC_OFF
HEADING_ON      HEADING_OFF
HIGHLIGHT_ON    HIGHLIGHT_OFF
UNDERSCORE_ON   UNDERSCORE_OFF

The above codes are used for formatting. For example, prior to a sentence that
should appear in bold in the output, the BOLD_ON code will appear. When the bold
text ends, the BOLD_OFF code shall appear.

The heading code refers to a 'sub-heading' within a section. How you format it
is up to you. You may like to centre the text if it is on a line of its own.

Highlight means that he document author wants to show up the text given in a way
other than bold, italic, or underline. Inverse text may be a good idea.

NOTE : in the existing database, HIGHLIGHT is used extensively, whereas ITALIC
and UNDERSCORE aren't used at all. This will change shortly, so please make sure
you support them. I suggest you display or print highlight as bold with
underscore, or whatever looks OK under the circumstance, until it is changed.
[Most of the existing highlighted text will be replaced with bold/underscore.]

LINE_ON         LINE_OFF

These relate to line drawings. They contain standard 7-bit ASCII characters, and
need to be displayed or printed in a fixed-pitch font.

CODE_ON         CODE_OFF

This delimits a code fragment, i.e., a fragment of source code or some such
thing. They are no different to line drawings (in that their formatting needs
to be preserved and that a fixed-pitch font needs to be used) but they are
delimited as such because -

  1) in printed text, different font conventions may be used for code, and
  2) on-line help readers may give the option of pasting the code.

For example, although it isn't documented, the ALT-TAB sequence in the DOS
help reader will highlight the current code fragment. This is preparatory to
allowing the code itself to be pasted via the keyboard buffer.

PRESERVE_ON     PRESERVE_OFF

Preserve refers to 'preserve formatting', a catch-all for any other text in the
source that needs to be displayed in a fixed-pitch font and for which no word-
wrapping should be performed. In all of the above cases, a single LF will end
a line of text.

TABLE_ON        TABLE_OFF

Currently, Tables are just treated the same as PRESERVE, so please use them
that way. Later on we may change that. Tables are intended for multi-column
data that needs to be aligned in some special way.

REFERENCE    REFERENCE_ON    REFERENCE_OFF

The Reference code is followed by a 16-bit word giving the reference index.
This value represents a index into the array of references as described earlier.
When this appears in the text of a section, it means that the following word(s)
(as delimited by REFERENCE_ON and REFERENCE_OFF) represent a link to the target
given by the reference index. If the user highlights (or clicks on) the word(s),
the help reader should jump to the first target.

REFERENCE_ON and REFERENCE_OFF are used to delimit the text referred to by a
previous REFERENCE, and an online help reader should display the text using
whatever conventions exist for that particular platform.

If the output medium is hard copy, and you want to be particularly clever,
you may like to generate a reference to a footnote here, which in turn will
provide a 'see section xxx on page yyy' type message. The difficulty here is
in determining the page numbers in advance (if it is a forward jump) and that
is left as an exercise for the reader. It may be necessary to scan the input
file twice. Alternatively, if you know you are outputting to a file, you may
like to enter dummy data and return later to fix it up with the real page.

LIST_ON         LIST_OFF        LIST_ENTRY_ON   LIST_ENTRY_OFF

A List is considered a table with two columns - one with the list delimiters,
and the other with the text. For example, all of these are lists -

  +Iname                  use alternate file name (default HELP.HLP)
  +N123                   go to the 123rd section {/HIL/} (NOT section 123!)
  +S4.5.6                 go to section '4.5.6'
  +Tsphere or "+Tsphere"  go straight to the first section found with

  Up, Down    move highlight bar
  Enter       view selected item
  Escape      exit help viewer

  *   Standard include files that pre-define many shapes, colors and textures
  *   Shapes can easily be combined to create new complex shapes. This
      feature is called Constructive Solid Geometry (CSG). POV-Ray
      supports unions, merges, intersections and differences in CSG.
  *   Objects are assigned materials called textures.  (A texture describes
      the coloring and surface properties of a shape.)

As you can see, you need to know the length of the longest of the left part
of the table so you know how far to indent the right. In the help database,
the entire list will be bracketed with a LIST_ON and LIST_OFF. Immediately
following the LIST_ON will be a single 8-bit value giving the number of
character units to indent the right-hand column for that list. If you are
using a proportional font, you may want to read the entire list to come up
with a more appropriate value, rather than use the indent value times the
maximum (or average) character width for the font you are using.

The 'List Entry' is considered the left hand side of the table, i.e., the left
column. Each of these (whether one single character or a whole sentence) is
bracketed with a LIST_ENTRY_ON and LIST_ENTRY_OFF. Anything after a OFF is part
of the right-hand column of the portion contained in the list entry. You should
not find any line feeds in this text ; it is up to you to align it correctly.

[Note that some beta versions of the database have a LF immediately after the
length byte following the LIST_ON. This should be ignored.]

PARAGRAPH

A Paragraph code indicates the end of a paragraph. In the context of the help
system, it is considered the same as a hard line feed followed by a blank line.

More specifically, if the current character position is not at the left-hand
side of the output medium, perform a LF. Then, in either case, perform another.

INDENT

The Indent code means you should indent the text following the code by whatever
is considered the standard for your output medium. The indent should apply for
the current line only ; that is, until the next LF or Paragraph code.

TARGET

The Target code delimits a location where a target exists. You don't really
need to do anything about this, so just ignore them.

                                  CONVENTIONS

Currently, there's no way to really tell what text belongs in which document.
For example, the help database has instructions for using the DOS online help
reader built in, and a FAQ at the end also. Obviously, you don't want to print
that information on hardcopy. Later on, the database will include information
that indicates the nature of each section so you can decide whether to include
it or not. Properly, help for the online help reader should be built into it
and not into the database, and eventually this will be the case. For now,
though, use this convention -

  o ignore any section with a section number of less than 1.0. the help for
    the help reader has the section number 0.0.
  o optionally ignore any sections after a section that has the title
    'FREQUENTLY ASKED QUESTIONS' as these are not part of POVRAY.DOC.

                                   EXAMPLES

Please peruse the source of POVHELP.EXE for an example of an online help reader.
POVHELP may be suitable for porting as it maintains its output in a virtual
screen, the width and length of which can be set from the command line.

Please also peruse the source of PHE2TXT.EXE. This is a program derived from
POVHELP that reads the database and outputs a title, table of contents, and
plain ASCII text sections in a page width of the users specification. This
program keeps 'attributes' for each character according to bit flags defined
in HELP.H, which define bold, underline, etc., but doesn't actually use them.
This program may be suitable for porting as the basis of a hardcopy output
converter, provided that the hardcopy uses fixed-pitch characters.

PHE2RTF.C is a better (albeit not yet working) example of a converter. It has
all the code needed to read the POV-Help database and issue the appropriate
formatting codes ; the only problem with it is that the RTF it issues is not yet
compatible with Microsoft Word. But that doesn't stop it being used as a basis
of a converter to another format.