[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [ubl-fpsc] Standard documentation format?
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]