assembly/README

   1 DocBook Assembly Stylesheets
   2 ==============================
   3 bobs@sagehill.net
   4
   5 This directory provides XSL stylesheets for working with
   6 DocBook assemblies.  It is intended to enable working with
   7 <topic> and <assembly> elements, as defined in DocBook 5.1
   8 and later.
   9
  10 This kit currently supports most features of an assembly.
  11 See the "Unsupported Features" section below for details
  12 of what is not currently supported.  These more advanced
  13 features will be supported as it is further developed.
  14
  15
  16 Content of this directory:
  17 --------------------------
  18 topic-maker-chunk.xsl        - stylesheet to modularize an existing DB5 document.
  19 topic-maker.xsl              - imported by topic-maker-chunk.xsl.
  20 assemble.xsl                 - stylesheet to process an <assembly> into a document.
  21
  22
  23 The toolkit consists of an assemble.xsl XSL stylesheet
  24 to process a DocBook <assembly> element to convert it
  25 to an assembled DocBook 5 document ready to be formatted.
  26 This stylesheet will enable users to structure a book from
  27 modular files.
  28
  29 To make it easy to initially create a modular book, this
  30 kit also includes a topic-maker-chunk.xsl XSL stylesheet
  31 to break apart an existing DocBook 5 book into modular
  32 files, and also create the associated <assembly> document.
  33 Then you can run the assemble.xsl stylesheet to put it
  34 back together as a single DocBook document.
  35
  36
  37 To create an assembly and topic files from a book or article document
  38 =======================================================================
  39
  40 If you have an existing DocBook 5 book or article document,
  41 you can convert it to an assembly and a collection of
  42 modular topic files.  If you want to convert a DocBook 4
  43 document, you must first convert it to version 5.
  44
  45 For example, to disassemble a DocBook 5 book document named book.xml:
  46
  47 xsltproc --xinclude \
  48          --stringparam assembly.filename myassembly.xml \
  49          --stringparam base.dir topics/  \
  50          topic-maker-chunk.xsl  \
  51          mybook.xml
  52
  53 This command will result in a master assembly file named
  54 'myassembly.xml' with a root element of <assembly>, containing
  55 a single <structure> element. It will also break up the
  56 content of the book into modular chunks that are output
  57 to the 'topics/' subdirectory as specified in the 'base.dir'
  58 parameter.
  59
  60 Options
  61 ----------
  62 The name of the assembly file is set by the stylesheet param
  63 named 'assembly.filename', which should include the filename suffix.
  64
  65 Modular files are output to the directory location specified
  66 by the 'base.dir' parameter.  If you want them in the current
  67 directory, then don't set that  param.
  68
  69 By default the assembly element is output to the current
  70 directory, *not* into base.dir with the modular files.
  71 The <resources> element in the assembly has its xml:base
  72 attribute set to the value of 'base.dir', so that it is
  73 added to the paths to the modular files when processed.
  74 If you set the stylesheet param 'manifest.in.base.dir'
  75 to 1, then the assembly file is created in the base.dir
  76 directory and the xml:base attribute is omitted (since
  77 they are together in the same directory).
  78
  79 If you want the assembly file in 'base.dir' instead of
  80 the current directory, then set the stylesheet param
  81 'manifest.in.base.dir' to 1.
  82
  83 The stylesheet chunks a document into modules at the
  84 same boundaries as the chunking XHTML stylesheet, because
  85 it reuses many of the chunking stylesheet templates.
  86 You can alter the chunking behavior with the same options
  87 as for XHTML chunking.
  88
  89 For example, the stylesheet will chunk sections into topics
  90 down to section level 3 by default.  To change that level,
  91 change the stylesheet param 'chunk.section.depth' to
  92 another value.
  93
  94 Finer control of chunking can be achieved by using
  95 the <?dbhtml stop-chunking?> processing instruction in
  96 the source file.
  97
  98 Many modular elements retain their original element name,
  99 such as glossary, bibliography, index, and such.  By default, the
 100 stylesheet converts chapter, article, preface and section elements
 101 into <topic> modules.  To change that list of
 102 converted element names, alter the stylesheet param named
 103 'topic.elements'.  If that param is empty, then no elements
 104 will be converted to <topic>, so they will all retain their
 105 original element names.
 106
 107 Modular filenames use the same naming scheme as the chunking
 108 XHTML stylesheet, and supports the same file naming options such as
 109 the param 'use.id.as.filename', which is set to 1 by default.
 110 Note that the stylesheet param 'html.ext' is set to '.xml'
 111 because it is producing modular XML files, not HTML files.
 112
 113 Root element conversion
 114 ------------------------
 115 By default, the root element of the original document is
 116 also converted to a module, and <structure> gets a resourceref
 117 attribute to reference it.  If you set the stylesheet
 118 param 'root.as.resourceref' to zero, then the root element
 119 is handled differently, as described as follows.
 120
 121 If the structure element does not have a resourcref
 122 attribute, the root element is constructed rather
 123 than copied from a resource. The structure element must
 124 have a renderas attribute (or its child output element must
 125 have such) to select the output root element name.
 126
 127 Any content between the root element start tag and the
 128 first module is put into a resource with the original
 129 root element.  To pull this content in, the first
 130 module in the structure points to this resource but
 131 uses a contentonly="yes" attribute. The effect of
 132 that attribute is to pull in all content *except*
 133 the root element of that resource.
 134
 135 In general, if you have content that does not logically
 136 have its own container element, you can put the content
 137 into a suitable container element and then deselect the
 138 container element upon assembly with the contentonly="yes"
 139 attribute.  That attribute can also be used to avoid
 140 pulling in a resource's xml:id when you want to change it.
 141
 142
 143 To process an <assembly> into an assembled DocBook document
 144 ==============================================================
 145
 146 To convert an <assembly> and its associated modular
 147 files into a single DocBook document, process
 148 your assembly document with the assemble.xsl stylesheet.
 149 You should then be able to process the resulting
 150 document with a DocBook XSL formatting stylesheet.
 151
 152
 153
 154
 155 Useful params in assemble.xsl
 156 -----------------------------
 157 The $root.default.renderas param sets the name of the
 158 root element of the assembled document, if it is not
 159 otherwise specified with @renderas.  Its default value
 160 is 'book'.
 161
 162 The $topic.default.renderas param sets the name of the
 163 output element for any topic element included in the
 164 assembly, if it is not otherwise specified with
 165 @renderas.  It's default value is 'section'.
 166
 167 The $structure.id param lets you specify at runtime
 168 the id value of the structure you want to reassemble.
 169 This is only necessary if you have more than one
 170 structure element in your assembly.
 171
 172 The $output.type param also lets you specify at runtime
 173 which structure element to process.  In this case,
 174 the value should match on an @type attribute on
 175 the structure element.
 176
 177 The $output.format param lets you specify at runtime
 178 which of several possible output formats are being generated.
 179 The param value is compared to the @format
 180 attribute on <output> elements to select specific properties
 181 for a module.
 182
 183
 184
 185 Unsupported Features
 186 -----------------------
 187
 188 The transforms and transform elements are currently ignored
 189 by the assembly stylesheet.
 190
 191 The relationships and relationship elements are currently
 192 ignored by the assembly stylesheet.
 193
 194 The filterin and filterout elements are not currently
 195 supported.