DocBook Files

DocBook Assembly Toolkit
==============================
21 August 2011
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


This in a demonstration toolkit for test-driving the
new DocBook modular documentation elements and features.
It is intended to enable working with <topic> and
<assembly> elements, as currently defined.  Because these
new elements are not finalized, consider these elements
and this toolkit to be experimental and subject to
significant future changes.  

This kit currently supports only the basic features of
an assembly.  See the "Unsupported Features" section
below for details.  These more advanced features will be
supported as it is further developed.


Content of this kit:
--------------------------
topic-maker-chunk.xsl        - stylesheet to modularize an existing document.
topic-maker.xsl              - imported by topic-maker-chunk.xsl.
assemble.xsl                 - stylesheet to process an <assembly> element into a book.
doccbook51/                  - DocBook 5.1 beta 4 schemas 
sample/originalbook.xml      - sample book document before disassembly. 
sample/Makefile              - contains commands to round trip assembly.
cooked-sample/myassembly.xml - The assembly element generated by topic-maker.
cooked-sample/topics         - The modular topic chunks from topic-maker.
cooked-sample/reassembled.xml- The sample document after roundtrip processing.


The toolkit consists of an assemble.xsl XSL stylesheet
to process a DocBook <assembly> element to convert it
to an assembled DocBook document ready to be formatted.
This stylesheet will enable users to gain experience with
using <assembly> to structure a book from modular files.

To make it easy to create a modular book, this kit also
includes a topic-maker-chunk.xsl XSL stylesheet to break
apart an existing DocBook 5.0 book into modular files,
and also create the associated <assembly> document.
Then you can run the assemble.xsl stylesheet to put it back
together as a single DocBook document.


To run the demo
====================
Prerequisites:

a.  The docbook-xsl-ns-1.76.1 namespaced stylesheets installed.

b.  xsltproc in your path.

c.  A make utility, or the ability to read a simple Makefile to
execute the commands manually.

Steps:

1.  Edit topic-maker.xsl and topic-maker-chunk.xsl to change
the path of the import and include statements for the
docbook-xsl-1.75.2 stylesheets.

2. cd to the sample directory.

3. Type:
          make disassemble

That will process the originalbook.xml file to
generate a "myassembly.xml" file, as well as
a set of topic XML modules in the "topics" subdirectory.

4. Type:
         make assemble

That will process the myassembly.xml file back into a book
file named reassembled.xml.

You can compare your results to the files included in
"cooked-sample" directory.



To process an <assembly>
=============================
To convert an <assembly> and its associated modular
files into a single DocBook document, process
your assembly document with the assemble.xsl stylesheet.
You should then be able to process the resulting
document with a DocBook XSL formatting stylesheet.


To create an assembly from an existing document
===================================================
The topic-maker-chunk.xsl is a customization of the
DocBook XHTML chunking stylesheet.  

  NOTE: before using the stylesheet, edit topic-maker.xsl and
  topic-maker-chunk.xsl to change the paths to the imported
  DocBook NS stylesheet files.  


Chunking parameters
-------------------------
Because topic-maker-chunk is a customization of the XHTML
chunking stylesheet, you can use all the features,
parameters, and options of the chunking stylesheets to
control how the content is converted to modular files.
But instead of converting the content to XHTML, the content
is for the most part just copied through to DocBook XML
modular files.

For example, these chunking stylesheet params are useful:

  <xsl:param name="chunk.section.depth" select="3"/>
  <xsl:param name="chunk.first.sections" select="1"/>
  <xsl:param name="use.id.as.filename" select="1"/>
  <xsl:param name="base.dir">topics/</xsl:param>
  <xsl:param name="root.filename">index</xsl:param>


Using base.dir
------------------------
When an existing DocBook 5.0 document is processed,
it will generate the modular DocBook files in the directory
named in the 'base.dir' param (as with chunking, be
sure to include the trailing slash).  


The assembly document
---------------------------
The topic-maker-chunk.xsl stylesheet will also generate an
assembly document.  There will be a <resource> element
for each chunk, and a <module> element that references
each chunk.  The <module> elements are nested to
preserve the document structure.

The assembly file is named via this stylesheet parameter:

  <xsl:param name="assembly.filename">myassembly.xml</xsl:param>

By default the assembly element is *not* put into base.dir,
and the paths to the modular files include base.dir.
If you set the stylesheet param 'manifest.in.base.dir' to 1,
then the assembly file is created in the base.dir directory
and the paths to the modular files do not include base.dir
(since they are together in the same directory).


Converting elements to topics
------------------------------
The stylesheet can also convert selected elements to <topic>
elements.  The stylesheet param 'topic.elements' lets you
specify a whitespace separated list of element names.
For example the default is:

  <xsl:param name="topic.elements">preface section</xsl:param>

This setting will convert each <preface> and <section> element to
<topic> in its respective modular file. Note that for preface,
only the top of the file, before the first section, is included
in the preface topic.  

The stylesheet will also add to the <assembly> an <output>
element with a renderas attribute to indicate the original
element name for reassembly.

So if you were to add "chapter" to the list, then the top
of each chapter (before the first section) is converted
to a topic element in its modular file.


The root element as 'contentonly'
--------------------------------------
The root element of the original document is handled as a 
special case.  The root element is indicated in the <assembly>
document as the <structure> element, with @type="book".
Any content in the root element prior to the first
modular chunk is made into the root modular file
(default filename frontmatter.xml).  That file contains,
for example:

<book>
  <info>
    ...
  </info>
</book>

The generated <structure> element has a <module> for this
content, but with the attribute contentonly="true".  When
the book is reassembled, the <structure> element creates
the <book> element, and the content of the frontmatter.xml module
is brought in without its <book> wrapper, because of 
the contentonly="true" setting.

In general, if you have content that does not have its own
container element, you can put the content into a suitable
container element and then deselect the container element
upon assembly.

Useful params in assemble.xsl
-----------------------------
The $root.default.renderas param sets the name of the
root element of the assembled document, if it is not
otherwise specified with @renderas.  Its default value
is 'book'.

The $topic.default.renderas param sets the name of the
output element for any topic element included in the
assembly, if it is not otherwise specified with
@renderas.  It's default value is 'section'.

The $structure.id param lets you specify at runtime
the id value of the structure you want to reassemble.
This is only necessary if you have more than one
structure element in your assembly.

The $output.type param also lets you specify at runtime
which structure element to process.  In this case,
the value should match on an @type attribute on
the structure element.

The $output.format param lets you specify at runtime
which of several possible output formats are being generated.
The param value is compared to the @format
attribute on <output> elements to select specific properties
for a module.



Unsupported Features
-----------------------

The transforms and transform elements are currently ignored
by the assembly stylesheet.

The relationships and relationships elements are currently
ignored by the assembly stylesheet.

The filterin and filterout elements are not currently
supported.