[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [ubl-fpsc] Standard documentation format?
Thanks, Dan ... I've cc'ed Eduardo and Norm on this response. Neither will be able to respond to the list because they aren't subscribed, but I will be pleased to forward any comments should they choose to respond directly to me. At 2003-04-17 12:11 -0700, Danny Vint wrote: >The response from Eduardo was: > >It's Docbook, the official DTD for OASIS documentation. >goto: http://www.oasis-open.org/spectools/#documents I can easily accept this for standard book-like documentation, and have converted our minutes and agendas to both <book> and <article> instances to analyze the results. The April 17 agenda and minutes are posted using <book> because of the numbering of chapters. I am now using <article> for some UBL-FPSC work, and though I miss the numbering of sections, I'm uncomfortable using the "chapter" boilerplate used by the <book> stylesheets. So this leads me to the question "how should UBL-FPSC utilize DocBook when DocBook doesn't meet some of our specific documentation requirements?". I can think of three special requirements, and three approaches to addressing them. From an OASIS or UBL "official documentation practice" guideline, The document model I used for: http://www.oasis-open.org/committees/ubl/lcsc/0p70/fs/UN220Order.html was custom because it uses three facilities I could not find in DocBook: (i) numbered sections in formatted result (not numbered in source!), (ii) coloured editorial notes in the flow with a summary at the end of the document, and (iii) tables of information that are marked up semantically and formatted as simple tables for presentation. But, to quote DocBook: "If You Change DocBook, It's Not DocBook Anymore!". To support DocBook, I could do the following for each of these requirements: I see three strategies: (1) - seed a DocBook instance with non-DocBook constructs - pro - "most" of it is DocBook - con - cannot use standardized DocBook stylesheets (2) - write customized stylesheets - pro - can do anything I want for the result - con - any change for one result vocabulary would have to be repeated for all vocabularies (3) - massage the "master" DocBook-conformant instance into another "transient" DocBook-conformant instance solely for the purposes of rendering the desired result - pro - anything I do once in the massage can be formatted by any DocBook-conformant stylesheet - con - I'm not sure there are any cons here So, I'm proposing (3) for our FPSC formal formatting specifications that respect both the DocBook model and the DocBook stylesheets as sacrosanct: we don't change them for any presentation of our work, and they can apply equally well to both the unmassaged authored content as to the massaged processed content, with the massaged processed content giving more "utility" to the reader. To do this, I propose: (A) - we adopt conventions of use of DocBook tables and author our XPath reporting content according to those conventions (we aren't using tables for any other purpose) (B) - I write a "massage" script that transforms an instance of DocBook assuming the expectations of (A) into an instance of DocBook that formats the result more-or-less (I don't see how I can get the colour from the standardized sacrosanct stylesheets) from what we did in the prototype (C) - users of our formatting specifications can either work with the unmassaged instance and get an acceptable result or utilize the massaging script to get an "enhanced" presentation of the original instance In this "enhanced presentation" I would read through the authored DocBook <article> instance and: (1) - prefix every section and subsection title with "1.2.3" tumblers that would then show up both in the table of contents and in the titles in the body (2) - assume <note> is <editorial-comment-to-be-removed-before-finalizing> and create an "Editorial comment summary" section at the end of the document summarizing all of the <note> constructs found in the body (3) - assume <table> is a wrapper for our XPath documentation construct (I'm planning to add a couple of more columns), the massaging stylesheet would add a title row to each table rather than have the author of the document duplicate that. (4) - I forgot to mention above that in my custom stylesheet for my custom model I also pepper the lengthy XPath addresses with zero-width spaces to promote "clean" line breaking after "/" on very long addresses; I would do this in the massaging stylesheet as well This would also get me my multiple-level tumblers in my section headings in my <article> use for agendas and minutes. My question, then, to Eduardo and Norm would be "is this use of a massage script from DocBook to DocBook acceptable following of the DocBook faith or are there other strategies adopted by other committees to meet their specific non-DocBook requirements while treating the DocBook resources as sacrosanct?" Thanks! .................................. Ken -- Upcoming hands-on courses: Europe (XSLT/XPath): May 5, 2003 - Europe (XSL-FO): May 16, 2003 - (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-10-1 Practical Formatting Using XSL-FO Male Breast Cancer Awareness http://www.CraneSoftwrights.com/o/bc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]