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