Provide an overall document structure for a set of DocBook web pages that comprise a book.

The Document Settings configuration page combines with the Knowledge Base web-based page structure to provide the technology for organizing a large document from and number of DocBook web pages.

Sub-page Structure of DocBook Components

In the SQI DocBook System large documents are assembled form from individual Knowledge Based pages. For example, this How-To book is comprised of section pages for each How-To, chapter pages for each major area, and one book page.

The file structure (from a very early working draft of this book) is displayed below in Example��1, ���Model File Structure���.

Example��1.��Model File Structure

HowToBook -| 
           |---- DocumentSettings
           |
           |---- ChapSystem 
           |                 
           |---- ChapText -| 
           |               |---- highlight
           |
           |---- ChapCode -| 
           |               |---- inline
           |               |
           |               |---- listing
           |               |
           |               |---- annotateLine
           |               |
           |               |---- annotateCallout
           |               |
           |               |---- publishedResults

This is the root, or master, page. It is a DocBook markup with a document <book> or <article> tag.

Note Best Practices. The only absolute page structure requirement is for the DocumentSettings page to be a sub-page of the top level page. However, it is Best Practice to make all of the DocBook component pages organized as sub-pages to the master. This produces a relative page structure that can easily be moved.

#format docbooksettings
{
  // Document Settings
  "title": "DocBook Cookbook",  
  "options": {
    "style":"manual"  
  },
  "sitemap": [
    {"id": "ChapSystem"},
    {"id": "ChapText",
      "sitemap":[
        {"id": "ChapText/highlight"}
      ]
    },
    {"id": "ChapCode",
      "sitemap":[
        {"id": "ChapCode/inline"},
        {"id": "ChapCode/listing"},
        {"id": "ChapCode/annotateLine"},
        {"id": "ChapCode/annotateCallout"},
        {"id": "ChapCode/publishedResults"}
      ] 
    },
    {"id": "ChapLinks",
      "sitemap":[
        {"id": "ChapLinks/xref"},
        {"id": "ChapLinks/olink"}
      ]
    }
  ]
}

As a document is being developed material is rappidly added. A common issues is that the web page for an element such as a cchapter may get too long.

In the example below a chapter that is being displayed as a single HTML page is refactored into the chapter and front materials on one web page and each section on a separte web page.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
  "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://sqi-inc.com/docbook/xml/4.4/docbookx.dtd">
<chapter>
  <title>Example of Refactoring a Chapter<title/>
  <para>Chapter intro stuff.<para/>
  <section>
    <title>First Section<title/>
    <para>.....<para/>
  <section/>
  <section>
    <title>Second Section<title/>
    <para>.....<para/>
  <section/>
<chapter/>

In this relative file structure:

ExampleBook -|---- DocumentSettings
             |
             |---- ChapterRefactor
             |
             ...

Is refactored into the following three files.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC 
  "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://sqi-inc.com/docbook/xml/4.4/docbookx.dtd">
<chapter>
  <title>Example of Refactoring a Chapter<title/>
  <para>Chapter intro stuff.<para/>
<chapter/>

The first section file is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC 
  "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://sqi-inc.com/docbook/xml/4.4/docbookx.dtd">
<section>
  <title>First Section<title/>
  <para>.....<para/>
<section/>

The second section file is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC 
  "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://sqi-inc.com/docbook/xml/4.4/docbookx.dtd">
<section>
  <title>Second Section<title/>
  <para>.....<para/>
<section/>

These three files are shown in the full file structure below.

ExampleBook -|---- DocumentSettings -|
      | 
      |  
      |
      |
      |---- ChapterRefactor --|
      |                       |
      |                       |---- SectionFirst
      |                       |
      |                       |---- SectionSecond
      ...