topic.txt

来自「开放源码的编译器open watcom 1.6.0版的源代码」· 文本 代码 · 共 371 行 · 第 1/2 页

	
In a 0x20 node, those records are not included.

The final section is included once in a 0x20 node, once for each column in
a 0x23 node.  This section includes paragraph attributes and text attributes.

The paragraph attributes begin with a 5-byte record:
	Bytes		Meaning
	-----------------------
	0		Unknown, usually 0x80
	1-4		Paragraph flags
	
See below for a list of known flags.  If any flags require arguments
(for example, if a line spacing flag is set) these arguments follow
the flags.  If more than one flag requires arguments, the arguments are
stored in order of the flags to which they correspond, from the flag in the
lowest bit to the flag in the highest bit.

Known paragraph flags are:

No Line-Wrap			0x10000000	Takes no argument

Centre justification		0x08000000	Takes no argument
Right justification		0x04000000	Takes no argument
(Left justification seems to be default)

Tab Stops			0x02000000	Takes variable argument
						(See below)

Bordered paragraph		0x01000000	Takes 3-byte argument

First Line Indent		0x00400000	Takes 1- or 2-byte argument
Right Indent			0x00200000	Takes 1- or 2-byte argument
Left Indent			0x00100000	Takes 1- or 2-byte argument

Line Spacing			0x00080000	Takes 1- or 2-byte argument
Space After			0x00040000	Takes 1- or 2-byte argument
Space Before			0x00020000	Takes 1- or 2-byte argument

The first byte of the argument to the "Bordered paragraph" flag is itself
a set of flags:
	Dotted Border		0x80
	Double Border		0x40
	Thick Border		0x20
	Right Border		0x10
	Bottom Border		0x08
	Left Border		0x04
	Top Border		0x02
	Boxed Border		0x01
The meaning of the remaining word is unknown so far.

Most of the other flags take a variable-length argument which measures a
distance in units of tens of twips (ten twips is half a printer's point,
or 1/144 of an inch).   The format used to store these numbers is
ridiculous, and I had better take a moment to go over it here.
I call it "Bass-ackwards three's complement", or "Wha?" for short.

   To convert x to "Wha?":
      if abs(x) > 0x3FFF or x == -1 stop;
      let sign = (x >= 0);
      let x = 2*abs(x);
      if x < 0x80 then
         let x = x & 0x80;
	 if sign == TRUE then
	    let x = x ^ 0xFE;
	    let x = x + 0x4;
	 end if;
	 store x as a BYTE;
      else
         let x = x & 0x8001;
	 if sign == TRUE Then
	    let x = x ^ 0xFFFE;
	    let x = x + 0x4;
	 end if;
	 store x as a WORD;
      end if;
      
I am not making this up.
Converting from "Wha?" back to normal numbers is simpler.  The low bit
signals whether the number is two bytes long instead of one byte, while the
high bit acts as a reversed sign bit, which is set when the number is
positive.  However to convert negative numbers to positive ones, once you've
flipped the bits and dropped the low bit, you have to add two to the result
(which is why I call it three's complement).  You'll note that -1 cannot
be represented in this scheme, and as a result you cannot specify indents
between -1 and -19 twips in a help file (they will be ignored if you do).
Who wrote this???

There's one addition complication with the tab-stop flag.  That flag
takes a series of numbers.  The first is the number of stops that were
set, in the above format.  The remaining numbers are the positions of
the individual stops, but since tab stops can't be negative the above format
is modified: the low bit is still a "size bit", but the high bit is just
a normal bit an isn't automatically set.

There are other paragraph flags whose purpose has not
been determined.

Text attributes are better understood, and immediately follow the paragraph
attributes.  The text attributes are a list of bytes, each indicating
a change that happens in some part of the text.  The changes are listed 
in order that they appear in the text.  Known changes are:

	0x80 -- Font change.  Followed immediately by a WORD index, which
		refers to one of the font attributes in the |FONT file
		(see font.txt).
	0x81 -- New Line.
	0x82 -- New paragraph.
	0x83 -- Horizontal tab.
	0x89 -- End of a text hotlink.
	0xC8 -- Start of a macro hotlink.  Followed by a two-byte value
	        giving the length of the macro string, then the zero-
		terminated macro string itself.
	0xE2, 0xE3 -- start of a pop-up and jump hotlink, respectively.
	        Each is followed immediately by a 4-byte hash value
		used to 'dereference' the hotlink via the |CONTEXT table.
		(see context.txt)
	0xEA, 0xEB -- start of a "complex" popup or jump hotlink respectively.
	        By "complex" I mean a jump involving another file or a
		secondary window.  These flags are followed by a two-byte
		value giving the length of the remaining data, then a
		one-byte flag:
			0x01 -- This hotlink uses a secondary window
			0x04 -- This hotlink uses another help file.
			0x06 -- Both a secondary window and another file.
		Finally the data is given: first the 4-byte hash value
		of the context string to jump to, then (optionally) the
		window to use (as a one-byte number if the destination topic
		is in this file; as an ASCII string if in another file)
		and then the destination filename if applicable.
	(NOTE:  With any of the above 5 hotlink flags, setting bit 3 makes
	        the hotlink "invisible"; that is, not coloured green in the
		document.  Thus there are 5 other attribute flags: 0xCC,
		0xE6, 0xE7, 0xEE, and 0xEF )
	0xFF -- End of the list of attributes.
	
The end of the text attributes is the end of the first data block in a 0x20
node.  In a 0x23 node, there is one set of paragraph+text attributes for
each column.

(Whew!)  The SECOND data area for these nodes is much simpler.  It's just
raw ASCII text with certain additional bytes inserted:
	-- A 0x00 byte signifies a change in the text.  The next text
	   attribute from the first section is read and applied.  (I'm not
	   sure how this works in 0x23 records; they have multiple sets
	   of text attributes but only one second data area.)
	-- A byte between 0x01 and 0x0A is the first byte of a two-byte
	   phrase code.  See phrases.txt.
	   

Offsets within the |TOPIC file
------------------------------

There are two different (and highly annoying) ways of referring to text
within the |TOPIC file, both using unsigned longs as offsets.  Both make
use of the fact that text in the |TOPIC file is broken into pages (see below).
The simpler form is the "Extended" offset (Pete Davis's words), with the
following format:

	Bits		Meaning
	-----------------------
	Upper 18	Page number
	Lower 14	Offset within data of that page
			(AFTER decompression, if applicable)

"Extended" offsets are used only within the |TOPIC file.

The other, more complex offset is (suprise) used more often; it appears in
|TOPIC occasionally, and is the only offset used in other files which refer
to |TOPIC, that is: |CONTEXT, |KWDATA, |SYSTEM, |CTXOMAP, and |TTLBTREE.
This form, called the "Character" offset (again, Pete Davis's words) is as
follows:

	Bits		Meaning
	-----------------------
	Upper 17	Page number
	Lower 15	Offset within TEXT of that page
	
The offset here is tricky; it is as if you calculated a normal offset within
that page, but ignored everything that wasn't text.  Here, 'text' refers to
the actual help text AFTER decompression but BEFORE phrase replacement and
BEFORE processing formatting codes (see the section on Data Blocks) -- in
short, the text as it appears in the uncompressed page.  'Text' does NOT
include the linked list structures and other internal gobbledygook.