PluckerToCExtension

From Tomes Support Wiki

Plucker Table of Contents Extension

Note that the this extension has been included in the official Plucker specification, so please see that document for the definitive description. This page will remain for posterity, and as of 26-Jul-2009 exactly matches the changes made to the Plucker document.

This document describes an extension to the Plucker document format. Its purpose is to introduce a Table of Contents section to the document which can be easily parsed by reader applications without requiring string parsing, entire document searching, or other data or computationally intensive tasks. It is believed that this extension should be transparently ignored by existing readers which do not support it, though at the time of this writing, this fact has not been verified on actual reader software.

The Table of Contents record begins with a standard Plucker data record header containing uid, paragraph count, size, type, and flags. Following the header are one or more data records specifying one ToC entry each. The paragraphs field of the standard header indicates the number of data records which follow in the current Palm database record.

Additional ToC records may follow the first one if additional room is needed. All but the last record must set the Continued record flag in the header.

The value of the type field in the header must be 23 for uncompressed data or 24 for compressed data.

ToC records must appear in order, consecutively in the document, but no restriction is made on the location of the group of records within the entire Plucker document.

The first ToC record in the document must be listed as a reserved record in the Plucker Index record. The name id of the reserved record is 8.

The data of ToC records is always compressed according to the compression type in the Index Record Version field.

Standard Plucker record header, plus some

Field	Bytes	Type	Notes
uid	2	Numeric	Unique ID for record. IDs must be sorted in increasing order. Currently the ID is not allowed to be 0xFFFF. Moreover, some earlier versions of the viewer had a bug that crashed on records numbered 0x8000-0xFFFE.
paragraphs	2	Numeric	Number of ToC entries in this record
size	2	Numeric	Total length of the record before compression
type	1	Numeric	Datatype - DATATYPE_TABLEOFCONTENTS (23) DATATYPE_TABLEOFCONTENTS_COMPRESSED (24)
flags	1	Bitfield	Continued record - 0x01 - If set, indicates that an additional record of this type immediately follows and should continue this one.

Per-entry detail record

Field	Bytes	Type	Notes
uid_target	2	Numeric	UID to which this ToC entry points
paragraph_target	2	Numeric	Paragraph index to which this entry points
name_length	2	Numeric	Number of bytes (not characters) which follow for name, including terminator & any padding.
indent_level	1	Numeric	Indent level for the entry. Must be in the range 0..63 inclusive.
name	variable	String sequence	NUL terminated string containing name of the ToC entry. Must be in the default charset encoding for the document. Must be an ODD number of characters, padded with an extra NUL if necessary such that the next entry will begin WORD aligned.
...	...	...	Repeat for a total of (entry_count) times as indicated by the Paragraphs field in the header.