Re: [ubl-fpsc] Standard documentation format?

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

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