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