RE: [docbook-tc] questions on creating an assembly

["Rowland, Larry" <larry.rowland@hp.com>]

I am so glad you decided to chime in on this.  We are trying to get
as solid a proposal together as possible and discussion is always
helpful.

-----Original Message-----
From: Rzedzicki, Lech [mailto:Lech.Rzedzicki@uk.penguingroup.com] 
Sent: Tuesday, October 13, 2009 8:55 AM
To: Bob Stayton; Rowland, Larry
Cc: DocBook Technical Committee
Subject: RE: [docbook-tc] questions on creating an assembly

This is, I believe my first post on TC list, so let me introduce myselft
quickly.
I worked on XML Projects for Tech Writing, Law Publishing and now book
publishing in general for Motorola, Thomson Reuters and Penguin/DK
respectively. I am introducing more an more Docbook features in both
Penguin and Dorling-Kindersley and I think it's about time I started
participating more actively in the TC, if you're all right with that.
To start with, I have a couple of question about the naming conventions
and attributes vs elements in the assembly file.

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net] 
Sent: 12 October 2009 23:06

1.  An output element cannot just have a renderas attribute, it must
also have an outputformat.  If one wants
the same renderas for all outputs, then outputformat must be set to
"ALL".  I'm wondering of outputformat could be optional, with the
meaning that if it is not present on an output element, then the output
element applies to all outputs.

I wonder, if attributes are used here, would it not be far more simple
to use those attributes straight on <module> elements?
I also have a more general comment about it - I'd love to see output
profiling survive chunking and assebly - so that it works whether it's
one file or many...

>> The attributes were originally attached to the module element itself.
   however, that does not allow for different instructions applying to
   different outputs.  However, the outputformat is optional in the
   latest version of the schema.

   I am not entirely sure what "output profiling" means in this context.
   The conditions set in the assembly at any level are applied to the
   content referenced by a module and to the content referenced by
   any children of the module or structure the filter element occurs in.  
   I believe the current assumption is that the conditions apply to 
   referenced content, not to the assembly itself, although this has 
   not been discussed yet and should be.  All elements in the assembly 
   include the DocBook common attributes, but I have not used 
   conditions on anything other than the filterin and fileterout 
   elements, so the issue has not been exposed.  I suppose one could
   pass conditions into the assembly as another way of controlling the
   structures within them.  My head is swimming a little at that.

2.  I'm wondering if the indirection provided by a module element
pointing to a resource element which then points to a fileref is always
necessary. 
It seems the module element could accept fileref insted of resourceref
for those who don't want to separate their resources into a <resources>
element. 
For a simple book, requiring that extra level of indirection seems
intrusive. Did you consider that possibility?

Agreed, this should be optional but recommended. 
Furthermore, I have a general comment about element names - the
<resources> part is very much like a manifest file, so why not follow
that naming convention, for instance the ePub OPF one, which has
<manifest>/<item> documented quite nicely[1]
If a resource is defined in an <resource> element, I think it would also
be quite consistent to just call it from resourceref (or itemref for
item) rather than module?
I think otherwise it gets a little bit verbose.

>> The names of elements and attributes are open for discussion
   currently.  We decided to work out the syntax and semantics
   that are needed and defer the problem of what to call things
   until how to do what we were doing was resolved.  I think the
   choice of "module" was to emphasize the idea of assembling modules
   of content, but as I said, the names are subject to discussion.

   I have some concerns about the use of the manifest syntax. It
   specifically excludes the use of fragment identifiers in the URIs
   of items and we had decided we wanted to be able to address the
   XML content using ID matches.  It also requires including a 
   media-type attribute that certainly makes each item entry more
   complex than the design so far.  Since our model was based on
   combining XML source, it did not seem necessary to include them.
   There is also a stated assumption that relative URIs are relative 
   to the document containing the manifest, while I would prefer to
   have the flexibility of using xml:base on the resources element.
   I don't know if there is another, similar model for basing this
   on, but I would like to keep as much of the current capability
   as possible if we adopt some existing standard for describing
   resources.  Since one of the goals mentioned for the transforms
   that operate on the assembly is to produce a manifest, I am also
   a little concerned about using the term manifest to mean more
   than one thing.  I don't want users listing every graphic in a
   document -- the transforms should deal with the graphics based
   on the source references to them, not make the user deal with
   them by hand.  This is obviously a rich area for discussion.

3. A tiny bit, the topics/*.xml should have their RNC PI set to
../../rnc/topiccust.rnc rather than ../rnc/topiccust.rnc as it currently
is ;) For now I see this part is not taken care of in XSL, but it seems
easy enough.
 
Other than I am really glad to see this happening - getting benefits of
modular processing with benefits of well supported predefined vocabulary
of DocBook!

Lech Rzedzicki
Penguin Group UK

[1] http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html#Section2.3

Regards,
Larry Rowland