RE: [docbook-tc] Sample assembly 2

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

Hopefully, this will provide some clarifications.  I had hoped to revise
the file before the meeting but ran out of bandwidth.

Larry Rowland (comments prefaced with LRR)

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Saturday, July 11, 2009 12:32 PM
To: docbook-tc@lists.oasis-open.org
Subject: [docbook-tc] Sample assembly 2

A few random questions. Apologies if these were covered in my absence.

| <assembly xmlns="http://docbook.org/ns/docbook";>
|   <info>
|     <!-- Example DocBook assembly for a document set using modular source. --></info>
|   
|   <resources xml:base="file:///./source-repository">
|     <!-- This resource set is for the XIDI document source. -->
|     <resource xml:id="xidi.overview" fileref="xidi-overview.xml">
|       <!-- Overview of the XIDI system and the XML build environment. -->
|     </resource>

I get that resources nest, but xidi.overview should be empty,
shouldn't it? I wouldn't expect to allowe both fileref *and* content.

LRR: These comments simply describe the content that is pointed to, since the
content is not provided in the sample.  They are for clarity, not the
actual content.  A fileref means there is no content.  Content would be
instead of a fileref.

|   <!-- Another resource collection from a different source location -->
|   <resources xml:base="http://svn.repo.corp.com/repos/common-source";>
|     <!-- This resource set is for shared source across document projects.  -->
|     <resource xml:id="tutorial.overview" fileref="tutorial/overview.xml"
|       grammar="dita">
|       <!-- Describes how to use the controls on the tutorial viewer.  From a
|         DITA collection -->
|     </resource>

Does grammar="dita" imply that the content of that
tutorial/overview.xml is a literal DITA map? If not, what does it
imply?

LRR: The grammar means that the source pointed at is coded using
DITA markup (I assume a topic, but DITA is not my field of
expertise -- a DITA topic map might make sense, although 
I was thinking more of a module of content, which I associate
with a topic).

|   <!-- Description of a help system for the project -->
|   <structure xml:id="xidi.help.system" renderas="helpsystem">

What are the possible values of renderas and what do they mean?
(And I agree with the other comments that 'renderas' is probably not
the right name.)

LRR: This is open right now.  After some discussions with Dick and 
Scott, this may actually be two attributes, one of which would be
constrained to DocBook elements (and might well be renderas) and
one of which is more likely NMTOKENS and would be more open, with
hints to the render system.  Helpsystem would be the open type.

|     <module renderas="helpnode: sys-toc.html">

Structured attribute values? Couldn't we say

  <module renderas="helpnode" uri="sys-toc.html">

or something like that instead?

LRR: That was the conclusion after meeting with Scott and Dick.  Not
sure about uri versus outputfile (which is more explicit as to what
it means, where uri is more ambiguous).  Instead of renderas it would
likely be outputformat.

|     <module resourceref="xidi.overview" renderas="helpnode: xidi-overview.html">

Random thought: resourceref or linkend?

|   <structure xml:id="user.guide">
|     <title>XIDI User Guide</title>
|     <toc/> 
|     <toc role="figures"/>
|     <toc role="tables"/>
|     <module resourceref="ug.intro" renderas="preface"/>

So ug.intro is defined as:

    <resource xml:id="ug.intro" fileref="user-guide-intro.xml">

what's the expected content of user-guide-intro.xml? Is it allowed
to be a <chapter> or <section> or <topic> and renderas is supposed
to make the system pretend that it was <preface>?

LRR: yes, that is the idea, although I was looking more at using
something like an article for the "generic" root element for a
module of content.

That strikes me as a completely different kind of processing. I'd want
to think carefully about what that mapping meant, when it applied, and
what happens when it is absurd (<setindex> renderas "procedure").

LRR: The more flexibility the system has, the more potential for 
bad design.  Decoupling the source from the destination always
introduces the potential for bad design.  One of my favorite
quotes in this area is "There is not now, nor will there ever
be, a programming language in which it is the least bit difficult
to write bad code." Don't know the author.

It really sounds like we're thinking of applying some sort of
transformation to the source before including it. If that's what we
mean, I wonder if we can really keep it so simple that we don't end up
inventing our own transformation language.

LRR: Yes, there is definitely the idea of a transform being applied,
otherwise I think we could do this with xincludes.

If we really want to talk about allowing transformations, I start to
think about assembly documents as some sort of XProc pipeline
extensions or something.

LRR: I tend to use Ant with temporary files on the file system, myself, 
since I find it easier to debug things that way, but I think that is
an implementation detail. ;-)

That's quite a different direction than I thought we were going.

LRR; I came in on this part way through, so I am not sure exactly
what the intended direction was.  I was mostly trying to mark
things up and see what would work for some things I was thinking
about.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Klein bottle for rent; enquire
http://www.oasis-open.org/docbook/ | within.
Chair, DocBook Technical Committee |