Re: [ubl-fpsc] Standard documentation format?

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

At 2003-04-21 12:34 -0400, Norman Walsh wrote:
>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA1
>
>/ "G. Ken Holman" <gkholman@CraneSoftwrights.com> was heard to say:
>| 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.
>
>Thanks, Ken.

I appreciate you could take from your time, Norm, as Eduardo has, to help 
me with this.

>| So this leads me to the question "how should UBL-FPSC utilize DocBook
>| when DocBook doesn't meet some of our specific documentation
>| requirements?".
>
>What requirements?

The numbering, note collection, table header adding, etc. that I described 
later in the note.

>(i) numbered sections in formatted result (not numbered in
>| source!),
>
>If that's not the default behavior for sections in an article, it can
>certainly be enabled with a parameter.

Ummmmmmm ... really? .... I confess that I could not find this and had 
thought it should have been something easy to request.  I went to 
http://docbook.sf.net, downloaded the XSL 1.60.1 package, looked in 
doc\index.html of the unzipped set and saw nothing about parameters.  Are 
these command-line invoked parameters that will engage different results?

Okay ... I now see the reference to a "param.xsl" that I did not see before 
... and I just found section.autolabel and guessed it was what I needed for 
that part.  Thanks.  And I can easily document that for committee <article> 
documents this parameter is to be set, or as I describe below, create a 
wrapper DocBook stylesheet for committee use.

Is there documentation for the selection of parameters, or should one read 
the stylesheets to see how they are used?  I don't readily see a reference 
to a summary of the available parameterization.

>| (ii) coloured editorial notes in the flow with a summary at
>| the end of the document,
>
>Well, I think I'd probably use <remark role="editorial">, or perhaps
><note role="editorial"> if you want more complex notes.
>
>Making them come out in color and in summary would require some
>stylesheet customization. I'd be happy to help.

Well, I'm trying to grok DocBook without help (though I confess from what 
you witness above that I did not do a very good job, sorry) and you've 
helped a lot so far getting me over the hump regarding the available 
parameters.  Did

>| and (iii) tables of information that are
>| marked up semantically and formatted as simple tables for presentation.
>
>Well, how simple and what semantics?

I didn't think it mattered to the answer.  The fact that that I want to 
capture concepts that are not software documentation concepts (and I can 
accept that; I'm not trying to criticize DocBook), means I have to shoehorn 
my needs into existing constructs.

>| But, to quote DocBook: "If You Change DocBook, It's Not DocBook Anymore!".
>
>As Eduardo pointed out, that's for changes to the DTD, not the stylesheets.

My mistake.  I can now comfortably propose the use of a 
DocBook-stylesheet-importing stylesheet for our committee's use.

>I'm not sure I see any requirements that can't be addressed with a
>very simple customization layer on top of the stylesheets.

Granted ... I was worried about breaking form, not about capabilities.

>| (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)
>
>What are you trying to markup here?

Our formatting specifications will document UBL instance locations as XPath 
addresses.  Based on our conference call and a comment from our member, 
Jean, I now plan a three column presentation of field height in lines, 
field width in characters (or probably a metric measurement given font 
issues), and a lengthy XPath address of the component of the UBL instance 
that is to be formatted in the cell of the result.

In my non-DocBook model, I just had an <xpath> element, and to ensure 
completeness, a <noxpath> element so the author acknowledged that a 
particular cell didn't have an associated XPath address.  Following the 
"don't change DocBook" credo, I would have to just put this stuff into a 
table and get the table formatted.

But given your comment about role= below, I suppose I'm covered.

>| (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
>
>Bleh! Make the stylesheets do the numbering.

Oh I agree it is distasteful ... but I didn't see the parameterization that 
was available.

>| (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
>
>Sure, if you won't need note for anything else.
>
>| (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.
>
>Use <table role="xpath"> or something so that the stylesheets can tell
>which tables need automagic formatting.

Now *that* is interesting to use the role= attribute to distinguish my 
"private use" of the DocBook constructs.

>| (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
>
>I think there's a parameter for that, too. At least for ulink
>elements.

Oh ... which this isn't and I wouldn't want it to be ulinked when presented.

>Maybe you'd need to do that in your customization too for
>xpath expressions.

Okayyyyyy .... so are you now indicating this "massage" stylesheet I've 
posited is an acceptable use of DocBook?

Eduardo, would this be consistent with the OASIS subcommittee utilization 
of DocBook?  By "this" I mean that UBL-FPSC would have authoring guidelines 
for DocBook constructs dictating which roles for standard DocBook 
constructs would reflect UBL-FPSC semantics, that the default presentation 
using a DocBook stylesheet would be acceptable (though not desired by 
UBL-FPSC), and that UBL-FPSC would have a "massaging" stylesheet converting 
a instance of DocBook to an instance of DocBook getting the extra features 
(I'm not talking numbering, I'm talking note collection and table headings)?

>| 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?"
>
>Without a more complete understanding of your requirements, I can't
>really comment in detail on your proposed solution. If you have
>technical requirements that can't be met with DocBook, I'd like to
>know what they are, though.

My goal is to mimic the editorial comments and their summary, and the table 
heading rows as shown in ...

   http://www.oasis-open.org/committees/ubl/lcsc/0p70/fs/UN220Order.html

... in section 4.11 and at the end of that document.

Given I get section numbering from the stylesheet by using a parameter, I'm 
proposing (1) the collecting of editorial notes into a new section at the 
end of the document in duplication of the notes found throughout (my custom 
stylesheet for my custom document model had a nice feature of hyperlinking 
back to the editorial comment in context from the summary collection), and 
(2) the addition of titles to the tables whose role is to document the 
XPath addresses following our (yet to be developed) committee authoring 
guidelines.

I'm hesitant to make wholesale changes to DocBook behaviour in an importing 
stylesheet by duplicating template rules that may be changing in future 
versions of the stylesheet library.  It would oblige me to keep up with the 
changes by retrofitting any changed behaviours in the template rules I was 
mimicking in my importing stylesheet.  It would also force me to do it in 
*all* stylesheet implementations, whereas a DocBook to DocBook 
transformation is only done once and the end result can use all existing 
stylesheet implementations.  This last reason is most compelling to me.

So, with a DocBook to DocBook transformation I can get much of what I 
need.  So I hope such a strategy doesn't conflict with the OASIS committee 
doctrine for DocBook.

Thanks again, Norm!

.................... 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/m/
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/m/bc