[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Lessons learned - DocBook conventions for documentation practices
Hello again, Regarding documentation practices for subcommittees, I was able to successfully deploy DocBook for our committee work with a twist that I think might be helpful to others. In my draft stylesheet documentation I utilized a custom XML document model in order to get formatting features I wanted in the finalized formatting specifications. I got exactly the result I needed, but the authored content was in a non-standard vocabulary. Upon founding the subcommittee, I learned (I guess I shouldn't have been surprised) that the OASIS subcommittee standard for documentation is DocBook. Yet DocBook doesn't provide some of the formatting features I wanted in our committee documents. BTW, DocBook is fine for committee administrative documents and I've been successfully using the <article> model for agendas and minutes: <article> <title>FPSC Agenda 20030522 - 17:00UTC (13:00EDT/10:00PDT) - DRAFT</title> <articleinfo> <copyright><year>2003</year><holder>OASIS</holder></copyright> <pubdate>$Date: 2003/05/21 11:56:03 $(UTC)</pubdate> </articleinfo> <section> <title> Roll call and quorum</title> <para> ... To get the numbering in the sections and table of contents, I invoke the XSLT processor with the section.autolabel=1 parameter. Examples of our agendas and minutes are at: http://www.oasis-open.org/committees/download.php/2173/agenda-20030522.html http://www.oasis-open.org/committees/download.php/2245/minutes-20030522.html http://www.oasis-open.org/committees/download.php/2269/agenda-20030529.html For the extra features I want and had in my custom model, I've created and tested a compromise that we will be trying out in our official committee formatting specification documents: augmenting DocBook to produce DocBook where extra features are needed. Through the use of the role= attribute in DocBook I can mark an otherwise standard DocBook construct as having extra meaning for our committee, and a "massaging" stylesheet takes the authored role= DocBook and augments it as desired to produce an augmented DocBook instance for publishing. This augmented publishing instance can then formatted using standard DocBook stylesheets for any target output. These custom requirements are only in two areas: the formatting of tables of XPath addresses (where I add table heading rows and I massage the content to include zero-width spaces to promote cleaner line-breaking), and the collection and reporting of outstanding editorial notes that must be addressed before the document is completed. At all times the instances validate against the DocBook document model, and standard DocBook stylesheets could be used with acceptable ... but for our formatting specifications we will run our authored instances through the massaging stylesheet to produce the publishing instances that can then use the standard publishing stylesheets. This gives us the extra features in all published outputs. This methodology focuses the committees custom work in a single place, independent of all publishing stylesheets, thus preventing having to customize all the target stylesheets duplicating the required functionality for each of the target presentation vocabularies. Although I don't get precisely the desired appearance I could get by tweaking the formatting stylesheet, I can live with what I see knowing that I don't have to tweak all possible formatting stylesheets and just have the one "production" stylesheet to produce the "publishing" instance. I've packaged this up for our committee members in the following ZIP file: <http://www.oasis-open.org/committees/download.php/1810/fpscdoc-20030429-2000z.zip>http://www.oasis-open.org/committees/download.php/1810/fpscdoc-20030429-2000z.zip However, I must confess that getting committee members to try out the XML authoring and document production has been less than successful. Perhaps editing a document in Word is easier, but I'm trying to convince (coerce?) members that we should practice what we preach about markup and try to use the document models for all our committee documents. As of the last meeting not a single committee member had yet tried the new DocBook-based authoring environment. I hope this helps. ................ Ken -- Upcoming hands-on courses: (registration still open!) - (XSLT/XPath and/or XSL-FO) North America: June 16-20, 2003 G. Ken Holman mailto:gkholman@CraneSoftwrights.com Crane Softwrights Ltd. http://www.CraneSoftwrights.com/o/ Box 266, Kars, Ontario CANADA K0A-2E0 +1(613)489-0999 (F:-0995) ISBN 0-13-065196-6 Definitive XSLT and XPath ISBN 0-13-140374-5 Definitive XSL-FO ISBN 1-894049-08-X Practical Transformation Using XSLT and XPath ISBN 1-894049-11-X Practical Formatting Using XSL-FO Member of the XML Guild of Practitioners: http://XMLGuild.info Male Breast Cancer Awareness http://www.CraneSoftwrights.com/o/bc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]