The reference material in our documents is divided into reference entries, with one entry per command or function (or sometimes a group of related functions). These reference entries are usually grouped together into reference sections. That is the basic document structure.

The source document structure is a bit more complex, and requires some explanation.

First of all, our one-file books are simple: all the reference entries are in the bk_man.sgml, the main document source file. Our multiple-file books, on the other hand, have a separate file for each reference entry, and each file is included in the main document as an entity. How are they included? In the CIF Driver (and other Cascade Compatible drivers) and Cogent API manuals, all the reference entities are called by one file, doc/i/xx/reference.sgml and doc/i/api/reference.sgml respectively. This reference.sgml file is then included as an entity in wrapper documents, which are then included in the main.sgml document.

The Gamma and Gamma/Photon manuals are arranged differently. In addition to reference entry files, they also have a separate file for each reference section, which is a wrapper for the entities for the reference entries of that section. Here, for example, are the entire contents of a small Gamma reference section file, rs_EventsandCallbacks.sgml:

<reference id="rs-EventsandCallbacks">
	<title>Events and Callbacks</title>
    &readdsetfunction;
    &reflushevents;
    &renextevent;
    &reremovesetfunction;
    &rewhensetfns;
</reference>

Like the reference entries, each of these reference sections is also declared as an entity. For example, there is an entity, &rsEventsandCallbacks;, declared for the rs_EventsandCallbacks.sgml file. This gives us the flexibility to break up the reference sections in different ways, depending on the output we need to generate. For example, the Gamma wrapper used by the Cogent Documentation bookset (doc/i/gamma/wrapper.sgml) includes all the Gamma reference section entities. But the file that generates the PDF output for the first half of the Gamma reference (doc/o/gamref1-book/main.sgml) contains only the first half of those entities.

These entities are declared in each book's entity declaration file, entities.sgml, as shown in the appendix Entity declaration files.