RE: [chairs] Re: Publication templates [afterthought[

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

For the DocBook environment, Dennis, you'll find two directories of 
interest.  The directory specifying how the DocBook publishing 
environment is used and including the downloaded ZIP file:

   http://docs.oasis-open.org/templates/DocBook/spec-0.5/

... and the directory of a template in DocBook XML, with HTML, PDF-A4 
and PDF-US renderings of the template using the stylesheets:

   http://docs.oasis-open.org/templates/DocBook/spec-0.5/template/

It is the template's responsibility to guide the specification writer 
in the sections of an OASIS document, not to teach how to use DocBook 
at lower levels of the hierarchy.

One should be able to copy the template DocBook XML and know exactly 
where and how to plug in their committee and document 
information.  The section content is then just section content 
specific to the document.  Though I grant the environment is geared 
to specification documents ... I haven't reviewed the requirements 
for other types of documents to know if the author has any more 
responsibilities than just changing the title.  It was my 
understanding that the document structure and presentation is 
unchanged for the different committee artefacts, the only thing that 
differs is how the documents are titled/labelled and put through the 
OASIS process.

And the directory includes sample invocations in both Windows and 
Linux to produce the template results from the template input.  I 
tried very hard to make the environment as turnkey as possible for chairs.

This may not use the *latest* DocBook, but it is a self-contained 
environment that does not require anyone to fetch any DocBook 
artefact in order to use.  I'm not sure why not using the latest is a 
hindrance if it meets the OASIS requirements.  The documents spit out 
by the environment are acceptable to Mary without modification (as 
far as I know).  A few committees have embraced this environment and 
I haven't received reports of problems since the final revision of 
version 0.5 was released.

I hope this helps.

. . . . . . . . . . . Ken

At 2010-12-13 20:53 -0800, Dennis E. Hamilton wrote:
>A two-birds one-stone approach is possible by specifying and illustrating
>the template in the template document, although it depends on folks having
>something that allows them to open such a file and provide some level of
>fidelity.
>
>So an annotated template is a good idea, but not a good substitute for a
>simple-text specification that does not depend on the rendering
>template-handling capabilities of different products.  A faithfully-derived
>PDF might provide a better presentation of such a template, also
>illustrating active links in cross-references, from the table-of-content,
>and to external resources), and the expected preservation of page capacity,
>line width, page breaks and numbering, etc.  [It would therefore be good to
>document the expected format choices for a PDF export that such a
>specification would also illustrate.]
>
>Having the PDF would also help people determine whether their product and
>template are producing what the template author sees and expects.  Template
>interoperability and adjustments of products to platform and configuration
>differences is not such a sure thing that one can be totally confident that
>the template in use will exemplify to an user the desired result and lead to
>the expected rendering of the document that was intended for the template.
>Having the PDF to consult provides a rendition that is presumably less
>variable than what an authoring product might introduce.
>
>  - Dennis
>
>PS: I hesitate to suggest that an HTML form of the template would be very
>workable, although there is certainly some additional concern for how the
>document is mapped to an [X]HTML that renders acceptably with current
>browsers and those that are to follow.
>
>-----Original Message-----
>From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org]
>Sent: Monday, December 13, 2010 19:03
>To: 'Jon Bosak'
>Cc: 'Kristen Eberlein'; 'Mary McRae'; 'Norman Walsh';
>chairs@lists.oasis-open.org
>Subject: RE: [chairs] Re: Publication templates
>
>[ ... ]
>
>I think there is an appropriate mid-point.  Not sure how it gets done, but
>there should be a style sheet that names the styles, what they are (so
>someone can figure out how to engineer a template that conforms in whatever
>their tool is), when and where it is used, and also what are the conditions
>on page layout, headers, footers, sections, tables of content, and
>appendices/annexes/indexes (to the extent allowed).  If there are
>illustrations, figures, and tables, more needs to be said about what is
>required.  It doesn't have to be down to the pixel, only enough to be
>specific about what is essential under the understanding that silence on a
>matter is permission to be creative.
>
>But then, I am revealing my generation.
>
>
>  - Dennis
>
>Dennis E. Hamilton
>------------------
>NuovoDoc: Design for Document System Interoperability
>mailto:Dennis.Hamilton@acm.org | gsm:+1-206.779.9430
>http://NuovoDoc.com http://ODMA.info/dev/ http://nfoWorks.org
>
>
>
>-----Original Message-----
>From: Jon Bosak [mailto:bosak@pinax.com]
>Sent: Monday, December 13, 2010 18:13
>To: Bruce Nevin (bnevin)
>Cc: Kristen Eberlein; Mary McRae; Norman Walsh;
>members@lists.oasis-open.org; chairs@lists.oasis-open.org
>Subject: Re: [chairs] Re: Publication templates
>
>OK, I get it -- this is about whether DITA should join DocBook,
>Word, and ODF as an approved OASIS publishing format.
>
>
>[ ... ]
>
>
> >> -----Original Message-----
> >> From: Kristen Eberlein [mailto:keberlein@sdl.com]
> >> Sent: Monday, December 13, 2010 5:59 PM
> >> To: Jon Bosak
> >> Cc: Mary McRae; Norman Walsh; members@lists.oasis-open.org;
> >> chairs@lists.oasis-open.org
> >> Subject: RE: [chairs] Re: Publication templates
> >>
> >> Jon, it's hard to write XSL transformations if you don't know
> >> what the requirements are :)
> >>
> >> Why should multiple TCs go through the work of reverse
> >> engineering a Word or OpenOffice template?
> >>
> >> I'm not raising *any* points about the look-and-feel of the
> >> prescribed styles; I just want clear specifications that
> >> volunteers on my TCs can code to.
> >>
> >> Best regards,
> >>
> >> Kris
>[ ... ]


--
Contact us for world-wide XML consulting & instructor-led training
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal