Bookreader Design Document

This document details the Bookreader's design, focusing on its terminology and the routines required for an authoring tool to interface with it through the Book Writer Interface (BWI). A "book" is composed of "topics," which are collections of information further broken down into "data chunks."

Key types of data chunks include:

• Ftext packets: Used for storing text and rules, structured in a tag-length-value format.
• Subchunks: Non-addressable units for graphical objects, supporting formats like FSE (bitmapped images), RAGS, and Display PostScript (DPS).
• Extensions: Define shaded areas within content.
• References (hotspots): Define interactive regions (either rectangular or polygonal) that link to other data chunks or even different books.

The BWI provides a structured set of routines for building a book, typically following this sequence:

1. Book Creation: Initialize a book and obtain a unique identifier (bwi_book_create).
2. Initial Content: Optionally define copyright information (bwi_book_copyright) or set the first topic to be displayed (bwi_book_first_topic).
3. Metadata: Provide optional LMF licensing details (bwi_book_license, bwi_book_license_alt), define the book's title (bwi_book_title), and symbolic name (bwi_book_symbol).
4. Font Definition: Define fonts for use within the book (bwi_book_font).
5. Topic and Chunk Creation: Create topics (bwi_topic_create), populate them with addressable data chunks (bwi_topic_data_chunk), and add non-addressable subchunks (bwi_topic_data_subchunk). Rectangular (bwi_topic_extension_rect, bwi_topic_reference_rect) and polygonal (bwi_topic_extension_poly, bwi_topic_reference_poly) extensions and references can also be defined. Symbolic names can be assigned to chunks (bwi_symbol_define).
6. Topic Closure: Close topics once their content is defined (bwi_topic_close).
7. Directory Management: Create directories (e.g., Table of Contents, Index) (bwi_directory_create) and add entries to them (bwi_directory_entry).
8. Directory Closure: Close directories (bwi_directory_close).
9. Book Closure/Abortion: Close the entire book (bwi_book_close) or abort the build in case of errors (bwi_book_abort).

Chapter 2 of the document provides detailed descriptions for each BWI routine, outlining their formats, arguments, and return values.