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

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

1. The Unindicted Guilty Bystander

I realize that I am a guilty bystander here, because I am certainly not
offering to participate in a TC or working group of some sort to struggle
with this nut.  So I am not going to speculate further.

I hesitated to offer this response except I remembered that I have the
action item to describe template scenarios as part of the work of the OASIS
Open Document Format Interoperability and Conformance (OIC) TC.  It seems I
can't completely take my oars out of the water.

2. Ken, I understand what you are providing, and it is commendable to
provide that support.  It doesn't address my concern.

Templates and exemplars can be useful for folks prepared to use them, and I
don't mean to discourage their being provided.  This, for example, doesn't
address all of the tacit understanding that is lurking in the samples and
especially in the XML version and lurking in the phrase "replacing the
example text with your bona fide information": 

	The template example in this directory is based on the template at
	
http://docs.oasis-open.org/templates/OASISSpecificationTemplateV4.1.html

	This prototypical instance can be the basis of writing new documents
by
	replacing the example text with your bona fide information."

In particular, it is a big step from the PDF (which looks just like the PDF
one can get from the Word and the OO.o templates provided by the TC
Administrator), to knowing what is essential and correctly usable and
appropriately customizable in the actual template and all of the content
markup that follows its preamble:

	<?xml version="1.0" encoding="ISO-8859-1"?>
	<!--   
		For online publishing use:
		<?xml-stylesheet type="text/xsl" 
	
href="http://docs.oasis-open.org/templates/DocBook/spec-0.5/stylesheets/oasi
s-specification-html.xsl"?>
		<!DOCTYPE article
		  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
		"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; 

		For offline publishing use:
		<?xml-stylesheet type="text/xsl" 
	
href="file:///z:/oasis/spec-0.5/stylesheets/oasis-specification-html-offline
.xsl"?>
		<!DOCTYPE article
		  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
		"file:///z:/oasis/spec-0.5/docbook/docbookx.dtd" 
	-->
	<?xml-stylesheet type="text/xsl" 
	
href="http://docs.oasis-open.org/templates/DocBook/spec-0.5/stylesheets/oasi
s-specification-html.xsl"?>
	<!DOCTYPE article
	  PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; 
	[
	<!--the document properties-->
	<!ENTITY name "spectools-docbook-template">
	<!ENTITY pversion "0.4">
	<!ENTITY version "0.5">
	<!ENTITY stage "wd03">
	<!ENTITY standard "{stage and revision}">
	<!ENTITY this-loc
"http://docs.oasis-open.org/templates/DocBook/spec-&version;/template";>
	<!ENTITY previous-loc
"http://docs.oasis-open.org/templates/DocBook/spec-&pversion;/template";>
	<!ENTITY latest-loc
"http://docs.oasis-open.org/templates/DocBook/oasis-specification/template";>
	<!ENTITY pubdate "{8 July 2010}">
	]>	

(Not to mention all of the DTD files that my XML editor asked for permission
to cache so I could work with this XML document.  I assume that would
condition my editor to have me choose among the proper things as I introduce
content, although only having the names of allowed elements and attributes
to guide me is expecting me to have a lot of context that I might not
actually possess.)

There is some level at which we need an abstracted description that
establishes for a human operator what it is that is measurable,
reproducible, reliable and that is essential not merely according to the
template artifact but in the craft that that correct use of the template
depends on (but is not described in the template).


3. What Humans Need?

It is fine to say, "use this mumble-product template and you'll have
satisfied the requirement" although even then there is considerable
intuition required in recognizing the styling features in that template and
figuring out how to use them beyond just typing over place-holder text in a
document that is initialized with the template.  The moment we need to
introduce and decorate more structure, we need to know more.

It seems to me that the only requirement for a style guide is that it
establish the *essentials* and leave the discretionary. The problem with
examples and especially code (i.e., templates for a particular product) is
that one can't be certain which is which and what essential case might not
have been illustrated.  In addition, we underestimate the barrier to correct
understanding that a template derived with our *tacit* knowledge represents.

The problem is to make a human-understandable style guide and some reference
examples from which one could derive and/or appropriately employ a template
with a given authoring tool set.  

If the guide is carried in a template itself as part of exemplary text, the
proper use of the template in accomplishing what is essential must still be
conveyed.  The degree to which it must be intuited is the degree to which we
will have trouble.

If the digital form of the style guide is illustrative of the format and
template requirements, all the better, but the level of reverse engineering
required should not require an extraordinary level of expertise with the
product or tool or underlying document-representation format.  That's unless
there is a mandated set of tools that must be used and we can simplify into
our preferred silo the way these difficulties are typically resolved.

If there are final-form (e.g., PDF and HTML specimen) exemplars of what
following the style should achieve, then it provides a reference for someone
to confirm that their authoring is achieving an acceptable result, at least
as confirmed when using the authoring software on the author's platform and
configuration.  This can be particularly important when the interoperable
use of pre-built template documents across environments may be iffy and
there needs to be a well to tell when that is happening.

It also seems to me, if we look at the overall system and workflow to the
production and publishing of OASIS specifications, whatever is used has to
work for the TC Administrator, with tolerance for the fact that TCs are not
homogenous in their approach nor preferences for tools and how the same
tools are applied differently in the work of other TCs.

Please stand farther back and look from that perspective.


 - Dennis

-----Original Message-----
From: G. Ken Holman [mailto:gkholman@CraneSoftwrights.com] 
Sent: Tuesday, December 14, 2010 05:06
To: chairs@lists.oasis-open.org
Subject: RE: [chairs] Re: Publication templates [afterthought[

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.  
[ ... ]

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.]
>
[ ... ]
> >> -----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
>[ ... ]