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.
>
>| 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?".
>
>What 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!),
>
>If that's not the default behavior for sections in an article, it can
>certainly be enabled with a parameter.
>
>| (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.
>
>| and (iii) tables of information that are
>| marked up semantically and formatted as simple tables for presentation.
>
>Well, how simple and what semantics?
>
>| 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.
>
>| 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
>
>I'm not sure I see any requirements that can't be addressed with a
>very simple customization layer on top of the stylesheets.
>
>| 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)
>
>What are you trying to markup here?
>
>| (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
>
>Bleh! Make the stylesheets do the numbering.
>
>| (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.
>
>| (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. Maybe you'd need to do that in your customization too for
>xpath expressions.
>
>| 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.
>
>                                         Be seeing you,
>                                           norm
>
>- --
>Norman.Walsh@Sun.COM    | Our culture peculiarly honors the act of
>XML Standards Architect | blaming, which it takes as the sign of virtue
>Web Tech. and Standards | and intellect.--Lionel Trilling
>Sun Microsystems, Inc.  |
>-----BEGIN PGP SIGNATURE-----
>Version: GnuPG v1.0.6 (GNU/Linux)
>Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>
>
>iD8DBQE+pB2cOyltUcwYWjsRAvxyAJ9xbcJqP06yYmK6jbpVGqUjGetMTQCgrGmn
>IDFavhwmEDYvrjwCyHSHysk=
>=WONR
>-----END PGP SIGNATURE-----


--
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