Looking for the latest version? Download docbook-xsl-1.78.1.tar.bz2 (5.0 MB)
Home / assembly
Name Modified Size Downloads / Week Status
Parent folder
Totals: 2 Items   198.8 kB 3
README 2011-11-17 8.4 kB 11 weekly downloads
assembly-xsl-2011-08-21.zip 2011-08-22 190.4 kB 22 weekly downloads
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.
Source: README, updated 2011-11-17