2.1.��Assembling a Document

A How-To Recipe

Jeff Elpern


Task

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

Solution

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 -| 1
           |---- DocumentSettings
           |
           |---- ChapSystem 
           |                 
           |---- ChapText -| 
           |               |---- highlight
           |
           |---- ChapCode -| 
           |               |---- inline
           |               |
           |               |---- listing
           |               |
           |               |---- annotateLine
           |               |
           |               |---- annotateCallout
           |               |
           |               |---- publishedResults

1

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


[Note]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.

Document Settings Page

Example��2.��Document Structure Definition

#format docbooksettings
{
  // Document Settings
  "title": "DocBook Cookbook",  1
  "options": {
    "style":"manual"  2
  },
  "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"}
      ]
    }
  ]
}

1

This provides the wrapper for the document's components which are enumerated within the sitemap . The second part of the title value-pair provides the document title that is used at the top level in the Web based document navigation bar.

2

This allows you to set the style of the document. Here is a list of possible stypes:

howto Provides a How-To style document. This includes single-level section numbering and page breaks before every section.
manual Provides a tight format good for manuals. Headers and titles are smaller and have less spacing. Sections are labeled up to 6 levels deep (eg, Section 1.2.3.4.5.6). Table of contents list sections one level deep.
techbook Sections are numbered like manual, but have the full size titles. Also, the page margins are reduced.
book The PDF has a two column layout. Only chapters are numbered.

Discussion

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.

Example��3.��XML before Restructure

<?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.

Example��4.��XML after Restructure

The chapter 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">
<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
      ...

Univ/CIE/KA/StrucDoc/HowToBookProto/ChapSystem/assembly (last edited 2013-04-22 20:57:17 by jeff)