[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] Sample assembly 2
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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]