Re: [docbook-tc] A first stab at documenting assemblies

[Scott Hudson <scott.hudson@flatironssolutions.com>]

Hi Norm, et al,

I think this has been very helpful, and shows the potential assemblies 
in increasing orders of complexity in a user-friendly manner. I think 
there is a typo in the 2nd para of 5. Example Assembling an Online Book. 
"but it will be in the long run" should be "but it will be better in the 
long run".

I'd like to include an example of adding the relationships to your last 
example. Perhaps something like this:

<relationship type="troubleshooting">
  <instance resourceref="tut3"/>
  <instance resourceref="tut5"/>
  <instance resourceref="task4"/>
  <instance resourceref="task3"/>
</relationship>

<relationship type="widget">
  <instance resourceref="tut1"/>
  <instance resourceref="tut2"/>
  <instance resourceref="task1"/>
  <instance resourceref="tut3"/>
  <instance resourceref="tut5"/>
  <instance resourceref="task4"/>
  <instance resourceref="task3"/>
  <instance resourceref="tut4"/>
  <instance resourceref="task2"/>
</relationship>

<relationship type="tutorial">
  <instance resourceref="tut1"/>
  <instance resourceref="tut2"/>
  <instance resourceref="tut3"/>
  <instance resourceref="tut5"/>
  <instance resourceref="tut4"/>
</relationship>

<relationship type="task">
  <instance resourceref="task1"/>
  <instance resourceref="task4"/>
  <instance resourceref="task3"/>
  <instance resourceref="task2"/>
</relationship>

Best regards,

--Scott

Scott Hudson
Senior XML Architect
+1 (303) 542-2146  |  Office
+1 (720) 663-SCOT [7268]  |  Gvoice
Scott.Hudson@flatironssolutions.com
http://www.flatironssolutions.com






Norman Walsh wrote:
> Hi folks,
>
> I'm offline for a bit, distracting myself from other things by trying
> to tie up some loose ends. Attached, find my first attempt to document
> the assembly proposal.
>
> I did this partly to see if I understood it. No doubt, there are
> places where I *miss*understood it; there are certainly a few places
> where I changed it to suite what I think are the requirements.
> Consequently, I've documented what amounts to a slightly different
> proposal.
>
> I'd be interested, in particular, to know what capabilities of the
> original proposal cannot be addressed with this one.
>
> The description has two parts, an attempt at high-level exposition and
> a few narrative examples. The examples are probably better than the
> high-level exposition.
>
>   
>
> ------------------------------------------------------------------------
>
> OASIS logo
>
>
>   DocBook Assemblies Version
>
>
>       Specification URIs:
>
> This Version:
>     http://docs.oasis-open.org/docbook/specs/--spec--.html <--spec--.html>
>     http://docs.oasis-open.org/docbook/specs/--spec--.pdf <--spec--.pdf>
>     http://docs.oasis-open.org/docbook/specs/--spec--.xml <--spec--.xml>
>
> Technical Committee:
> Chair
> Editor
>
>
>       Abstract:
>
>
>       Status:
>
>
>     Notices:
>
> *Table of Contents*
>
> 1. Physical structure <#physical>
> 2. Logical structure <#logical>
> 3. Assembly Files <#R.1.15>
>
>     3.1. Resources <#resources>
>     3.2. Structures <#structures>
>     3.3. Relationships <#relationships>
>     3.4. Transformations <#transformations>
>
> 4. Example: Assembling a Printed Book <#ex-book>
> 5. Example: Assembling an Online Book <#ex-html>
> 6. Example: Assembling an Online Reference <#ex-ref>
>
> One modern school of thought on technical documentation stresses the 
> development of independent units of documentation, often called 
> topics, rather than a single narrative. Instead of writing something 
> that DocBook users would easily recognize as a book consisting of a 
> preface, several consecutive chapters, and a few appendixes, the 
> author (or authors) write a set of discrete topics covering aspects of 
> the system as if they were wholly independent.
>
> In a typical online presentation system, for example the world wide 
> web or online help, each topic is a page that stands alone. Except, of 
> course, that just as no man is an island, no topic is completely 
> unrelated to the other topics that are available.
>
> From any given topic, there may be topics of obviously related 
> interest. The nature of the relationships may vary. Some topics are 
> related by physical proximity (if you're interested in the ink 
> cartridges in a printer, you may also be interested in the print 
> head), others by their procedural nature (adding or replacing memory, 
> adding or replacing a hard drive, or even changing the CPU are all 
> topics that might logically follow a topic that describes how to open 
> the computer case).
>
> In a single narrative, it is the responsibility of the author to 
> manage these relationships. He or she can reasonably assume that 
> anyone reading chapter 4 has read chapters 1, 2, and 3. If the reader 
> needs to be directed elsewhere, a cross reference can be used (for 
> example, “for more information on paper jams, see Section 3.5, /The 
> Paper Path/”).
>
> In a topic-oriented system, authors are explicitly instructed to write 
> independent units. No linear order can be assumed and many forms of 
> explicit cross-reference are discouraged.
>
> Documentation managers treat the library of available topics very much 
> as programmers treat libraries of available functions. Just as any 
> given program can pick and choose from the available libraries, the 
> documentation for any given system can pick and choose from the 
> available topics.
>
> If you imagine a large documentation group managing the documentation 
> for several related systems (different models of printer, different 
> configurations of a software system, automobile engines assembled from 
> different components, etc.) it's easy to see the appeal of 
> topic-oriented authoring.
>
> In a successful deployment, you might find a library of say 1,000 
> topics which, taken together, document five or six related systems, 
> each of which uses 700-800 topics. Some topics are used in every 
> system, many are used in several systems, and a small number of topics 
> are unique to a specific system.
>
> In order to make such a documentation platform functional, you need 
> not only the individual topics, but also some sort of “map” or 
> “assembly” file that describes which topics from the library are used, 
> what relationships exist between them and, at least for print 
> presentation, what linear order should be imposed upon them.
>
> DocBook uses an assembly for this purpose.
>
> Editorial Notes
>
> I've taken some liberties with the assembly proposal. Mostly this was 
> to make it simpler where I thought I could, without sacrificing 
> expressive power. I could be wrong about the latter part.
>
>    *
>
>       Resources can directly contain arbitrary DocBook content, not
>       just strings.
>
>    *
>
>       Structures can not contain arbitrary DocBook content, only info
>       elements. Everything else can be included by reference to a
>       resource. The indirection may be a bit inconvenient, but I think
>       it simplifies structure quite a bit.
>
>    *
>
>       I removed type on structure because I couldn't figure it out.
>
>    *
>
>       I've moved renderas exclusively to output.
>
>    *
>
>       I harmonized chunking, output filenames, rendering, and
>       transformation to output. Maybe output isn't the best name for
>       this element.
>
>    *
>
>       I made some explicit choices about processing expectations that
>       may not be exactly the same as we've previously discussed.
>
>
>   1. Physical structure
>
> The notion of a DocBook assembly is predicated on a few assumptions 
> about the physical layout of the topics that are to be combined 
> together into units of documentation. We call the units of 
> documentation “structures” and the topics from which they are composed 
> “resources”.
>
> For the most part, we assume that resources exist as stand alone 
> documents accessible via URIs. The structures that result from 
> assembling the resources together may be a single file (as in a single 
> PDF book) or a collection of files (as in a web site or help system).
>
> Other arrangements are possible, but for simplicity in this document 
> we assume that the resources are accessible via URIs and the resulting 
> structures can be written to the local filesystem as one or more files.
>
>
>   2. Logical structure
>
> Many features of an assembly allow the assembly to update metadata 
> associated with a document, for example changing the title or removing 
> the metadata altogether.
>
> Throughout the description of assemblies, we assume that all metadata 
> always occurs inside an info wrapper. In other words, although the 
> following is perfectly legal:
>
> <chapter>
>   <title>Chapter Title</title>
>   <info>
>     <pubdate>2009-11-23</pubdate>
>   </info>
>   <para>Some chapter content.</para>
> </chapter>
>   
>
> we always assume that this is instead represented with a single info 
> element:
>
> <chapter>
>   <info>
>     <title>Chapter Title</title>
>     <pubdate>2009-11-23</pubdate>
>   </info>
>   <para>Some chapter content.</para>
> </chapter>
>   
>
> Even in cases where there is no info element:
>
> <section>
>   <title>Section Title</title>
>   <para>Some section content.</para>
> </section>
>   
>
> we assume one is present:
>
> <section>
>   <info>
>     <title>Section Title</title>
>   </info>
>   <para>Some section content.</para>
> </section>
>   
>
> Authors /are not/ required to author in this way in order to use 
> assemblies. Processing systems are to behave /as if/ they had.
>
> The assumption that all metadata is always present in a single, 
> explicit info wrapper /greatly/ simplifies the exposition of 
> assemblies without introducing any actual limitations.
>
>
>   3. Assembly Files
>
> An assembly has four major parts:
>
> resources
>
>     Identifies a collection of topics. An assembly may identifer one
>     or more collections.
>
> structure
>
>     Identifies a single document. A document in this case is the
>     particular collection of topics that forms the documentation for a
>     product or system. An assembly may identify one or more structures.
>
> relationships
>
>     Identifies relationships between resources. These relationships
>     may be manifested in any number of structures during assembly. An
>     assembly may identify any number of relationships.
>
> transformations
>
>     Identifies transformations that can be applied during assembly. An
>     assembly may identify any number of transformations.
>
>
>     3.1. Resources
>
> Individual resources are identified through a resource element:
>
> <resource xml:id="topicA" fileref="uri/for/topicA.xml"/>
>   
>
> Here the resource “topicA” is associated with the URI 
> uri/for/topicA.xml. Relative URIs are made absolute with respect to 
> the element on which they appear. An optional description attribute 
> may also be used to provide a description of the resource.
>
> A collection of resources may appear in a resources wrapper. The 
> primary motivation for the resources wrapper is to group physically 
> and logically colocated resources together. The resources wrapper is a 
> convenient place, for example, to specify a common xml:base or 
> xml:lang and description.
>
> If the resource element does not have a fileref attribute, then the 
> content of the resource element itself is the resource. This is often 
> used to create modules which trigger the automatic generation of 
> content, for example Tables of Contents or Indexes:
>
> <resource xml:id=”toc”>
>   <toc/>
>   <toc role=”procedures”/>
> </resource>
>   
>
> It is an error if the fileref attribute is specified and the element 
> is not empty.
>
>
>     3.2. Structures
>
> Structures are where the real work is performed. There is considerable 
> tension between the goal of providing structure elements that are 
> simple for the simple cases and simultaneously allowing them to be 
> complex enough to describe the full richness of possibility.
>
> This inherent tension is compounded by the fact that the nature of 
> structure outputs is naturally open ended. The goal is that DocBook 
> assemblies should be able to handle both the richness of the 
> structures that we produce today as well as the structures we will 
> want to produce tomorrow.
>
> The principle task of the structure element is to identify the 
> resources that are to be combined for that structure. The processing 
> expectation of a structure is that after combining the resources 
> together, the result will be a single document, the /realized 
> structure/. The realized structure is then processed to produce the 
> desired output. (Whether or not a processor actually realizes the 
> structure as a single document in memory or on disk is an 
> implementation detail; logically, that's what happens.)
>
> It is important to observe that the realized structure is often, but 
> not necessarily, a valid DocBook document. What is important is not 
> it's validity from an authoring perspective, but rather it's validity 
> with respect to what the downstream processor is expecting.
>
> For example, if the structure is defining a book, then the realized 
> structure should be a valid book. If, on the other hand, what is 
> defined is a help system, then the realized structure may be a 
> collection of nested topic elements. Even though authors are not 
> allowed to nest topics (per the currently proposed topic element), the 
> assembly process may be allowed to nest them.
>
> A structure consists mostly of module elements.
>
>
>     3.3. Relationships
>
> A relationship, in the context of an assembly, is an assertion that a 
> particular collection of resources are related. The nature of the 
> relationship is specified with a type attribute. For example:
>
> <relationship type="seealso">
>   <instance resourceref="tut1"/>
>   <instance resourceref="tut2"/>
>   <instance resourceref="task1"/>
> </relationship>
>   
>
> This asserts that there is a “seealso” relationship between these 
> resources. The processor might use this information to automatically 
> generate a “See Also” section at the end of any of these topics.
>
> Relationships are often, but not necessarily, unordered. This 
> relationship establishes a path through a set of resources:
>
> <relationship type="path">
>   <info>
>     <title>New User Introduction</title>
>   </info>
>   <instance resourceref="over1"/>
>   <instance resourceref="over2"/>
>   <instance resourceref="task3"/>
>   <instance resourceref="cleanup"/>
> </relationship>
>   
>
> A sophisticated help system could use this path to guide a new user 
> through a sequence of resources.
>
>
>     3.4. Transformations
>
> An assembly can identify a collection of transformations that can be 
> used during the assembly process. A transformation can be associated 
> with a resource (for example, to translate from some other format into 
> DocBook), or with a module (to address requirements beyond the limited 
> transformation capabilities of the assembly).
>
> <transformations>
>   <transform name="dita2docbook" type="text/xsl" fileref="dita2db.xsl"/>
>   <transform name="tutorial" type="text/xsl" fileref="db2tutorial.xsl"/>
>   <transform name="art2pi" type="text/xsl" fileref="art2pi.xsl"/>
>   <transform name="office" type="application/xproc+xml" fileref="office2db.xpl"/>
>   <transform name="office" type="text/xsl" fileref="extractoffice.xsl"/>
> </transformations>
>   
>
> If there are several ways to provide a transformation, they may all be 
> listed provided that they have different types. In the example above, 
> it may be that the XProc transformation from office documents to 
> DocBook is superior to the XSLT-only transformation, but the XSLT-only 
> transformation is better than nothing. If no type is specified, the 
> default is implementation dependent.
>
> Note
>
> Not all systems may support arbitrary transformations, nor can all 
> systems support all possible transformation languages. To maximize 
> interoperability it is best to use as few explicit transformations as 
> possible, ideally none.
>
> Given the transformations above, a DITA resource might be included in 
> the assembly:
>
> <resource xml:id="overview" fileref="dita/over.xml"
>           transform="dita2docbook"/>
>   
>
> Whenever a module refers to this resource, it will receive the 
> transformed, DocBook result.
>
> If a module needs to perform a transformation to get from one DocBook 
> format to another, it can name a transform as well:
>
> <module resourceref="overview">
>   <output type="book" renderas="partintro" transform="art2pi"/>
> </module>
>   
>
> In this case, two transformations will occur. This can be generalized 
> to an arbitrary number by listing more than one transformation in the 
> transform attribute on an output. The transforms are applied in the 
> order specified.
>
> If the output specifies a renderas, it is applied to the result of the 
> last transformation.
>
>
>   4. Example: Assembling a Printed Book
>
> For the purposes of this section, let's assume that we have the 
> following resources available:
>
> <resource xml:id="full-toc">
>   <toc/>
>   <toc role="figures"/>
>   <toc role="tables"/>
>   <toc role="procedures"/>
> </resource>
>
> <resource xml:id="index">
>   <index/>
> </resource>
>
> <resources xml:base="tutorial/">
>   <resource xml:id="tut1" fileref="tut1.xml"/>
>   <resource xml:id="tut2" fileref="tut2.xml"/>
>   <resource xml:id="tut3" fileref="tut3.xml"/>
>   <resource xml:id="tut4" fileref="tut4.xml"/>
>   <resource xml:id="tut5" fileref="tut5.xml"/>
> </resources>
>
> <resources xml:base="tasks/">
>   <resource xml:id="task1" fileref="task1.xml"/>
>   <resource xml:id="task2" fileref="task2.xml"/>
>   <resource xml:id="task3" fileref="task3.xml"/>
>   <resource xml:id="task4" fileref="task4.xml"/>
> </resources>
>   
>
> Further, let's assume that each of the tutorials and tasks is authored 
> as a standalone topic.
>
> Our first challenge is to create a PDF user guide. A subject matter 
> expert has informed us that the proper linear presentation for the 
> user guide is tutorials 1 and 2, task 1, tutorial 3, task 4, and an 
> index.
>
> Our first attempt at a structure might look like this:
>
> <structure xml:id="user-guide">
>   <output renderas="book"/>
>   <module resourceref="full-toc"/>
>   <module resourceref="tut1"/>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module resourceref="tut3"/>
>   <module resourceref="task4"/>
>   <module resourceref="index"/>
> </structure>
>   
>
> The output element identifies the kind of output to be generated. 
> There may be more than one type. The renderas attribute on the output 
> tells us that the realized structure should be a book.
>
> The module elements identify the resources to be included. That's fine 
> as far as it goes. Processing this structure will create a realized 
> structure that is a book (because that's what the renderas on the 
> output tells us) consisting of the tables of contents and the correct 
> six topics:
>
> <book xmlns="http://docbook.org/ns/docbook";>
>   <toc/>
>   <toc role="figures"/>
>   <toc role="tables"/>
>   <toc role="procedures"/>
>   <topic xml:base="tutorial/tut1.xml">
>     <title>Introduction</title>
>     ...
>   </topic>
>   <topic xml:base="tutorial/tut2.xml">
>     <title>Getting Started</title>
>     ...
>   </topic>
>   <topic xml:base="tasks/task1.xml">
>     <title>Engaging the spindle</title>
>     ...
>   </topic>
>   <topic xml:base="tutorial/tut3.xml">
>     <title>Troubleshooting</title>
>     ...
>   </topic>
>   <topic xml:base="tasks/task4.xml">
>     <title>Diagnosing spindle problems</title>
>     ...
>   </topic>
>   <index/>
> </book>
>   
>
> The trouble is, that's not a valid book. Not only does it consist of 
> topics instead of the expected chapters and such, but it's lacking 
> necessary metadata like a title.
>
> We can address the first problem by allowing output elements inside 
> modules.
>
> Most high-level elements (chapter, appendix, book, section, topic, 
> etc.) in DocBook have the same general structure: they contain an 
> (optional) info element followed by a collection of block elements.
>
> The semantic of renderas in a module that points to a resource is that 
> it renames the root element of that resource. This simple 
> transformation will allow us to turn all those topics into elements 
> more appropriate for book content. (We'll consider how to address the 
> situation where more complex transformation is necessary later.)
>
> We can address the problem of missing metadata by creating a new 
> resource that contains an info element containing the appropriate 
> metadata and then pointing to it. But this case is so common, that we 
> simply allow the info element to be placed in the structure.
>
> With these amendments, here's our new structure:
>
> <structure xml:id="user-guide">
>   <output renderas="book"/>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <module resourceref="full-toc"/>
>   <module resourceref="tut1">
>     <output renderas="chapter"/>
>   </module>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>   </module>
>   <module resourceref="task4"/>
>   <module resourceref="index">
>     <output renderas="index"/>
>   </module>
> </structure>
>   
>
> By default, the renderas value is inherited from a module's preceding 
> sibling. Even though the index is an index, because there is an 
> explicit rendering on a preceding module, it must be explicit on the 
> index.
>
> The realized structure that this produces is:
>
> <book xmlns="http://docbook.org/ns/docbook";>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <toc/>
>   <toc role="figures"/>
>   <toc role="tables"/>
>   <toc role="procedures"/>
>   <chapter xml:base="tutorial/tut1.xml">
>     <title>Introduction</title>
>     ...
>   </chapter>
>   <chapter xml:base="tutorial/tut2.xml">
>     <title>Getting Started</title>
>     ...
>   </chapter>
>   <chapter xml:base="tasks/task1.xml">
>     <title>Engaging the spindle</title>
>     ...
>   </chapter>
>   <appendix xml:base="tutorial/tut3.xml">
>     <title>Troubleshooting</title>
>     ...
>   </appendix>
>   <appendix xml:base="tasks/task4.xml">
>     <title>Diagnosing spindle problems</title>
>     ...
>   </appendix>
>   <index/>
> </book>
>   
>
> That realized structure is a valid book so you would expect the 
> processing system to produce the correct results.
>
> Except that it's not the right book. Upon further review by our 
> subject matter expert, it's been decided that tutorial 3 and task 4 
> shouldn't be separate appendixes, they should instead both be sections 
> in a single appendix called “Troubleshooting”.
>
> We can address this issue with nested modules. Instead of having 
> separate top-level modules for the tutorial and task, we'll make them 
> subordinate modules in a new top-level module:
>
> <structure xml:id="user-guide">
>   <output renderas="book"/>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <module resourceref="full-toc"/>
>   <module resourceref="tut1">
>     <output renderas="chapter"/>
>   </module>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module>
>     <output renderas="appendix">
>     <info>
>       <title>Troubleshooting</title>
>     </info>
>     <module resourceref="tut3">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task4"/>
>   </module>
>   <module resourceref="index"/>
> </structure>
>   
>
> The semantics of renderas on a module that does not have a resourceref 
> is that it simply generates that element.
>
> The realized document is now:
>
> <book xmlns="http://docbook.org/ns/docbook";>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <toc/>
>   <toc role="figures"/>
>   <toc role="tables"/>
>   <toc role="procedures"/>
>   <chapter xml:base="tutorial/tut1.xml">
>     <title>Introduction</title>
>     ...
>   </chapter>
>   <chapter xml:base="tutorial/tut2.xml">
>     <title>Getting Started</title>
>     ...
>   </chapter>
>   <chapter xml:base="tasks/task1.xml">
>     <title>Engaging the spindle</title>
>     ...
>   </chapter>
>   <appendix>
>     <info>
>       <title>Troubleshooting</title>
>     </info>
>     <section xml:base="tutorial/tut3.xml">
>       <title>Troubleshooting</title>
>       ...
>     </section>
>     <section xml:base="tasks/task4.xml">
>       <title>Diagnosing spindle problems</title>
>       ...
>     </section>
>   </appendix>
>   <index/>
> </book>
>   
>
> That's probably not quite what was intended. Given that tutorial 3 has 
> the title “Troubleshooting”, what we probably wanted was to make that 
> tutorial the appendix and make the task a subordinate section of that 
> appendix.
>
> We can achieve that by nesting the modules differently:
>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>     </module>
>   </module>
>   
>
> Now the appendix in the realized structure has the form that we want:
>
>   <appendix xml:base="tutorial/tut3.xml">
>     <title>Troubleshooting</title>
>     ...
>     <section xml:base="tasks/task4.xml">
>       <title>Diagnosing spindle problems</title>
>       ...
>     </section>
>   </appendix>
>   
>
> If a module “A” is nested within a module “B” that refers to a 
> resource, the result of processing “A” is inserted into “B” as the 
> last child of “B”. (in the case of several nested modules, they are 
> inserted as the last children in the order specified.)
>
> After further review of the content, the subject matter expert decides 
> that tutorial 5 and task 3 are also relevant to trouble shooting. 
> Tutorial 5 also has the title “Troubleshooting” and naturally follows 
> tutorial 3. Task 3 is about diagnosing bearing issues.
>
> It's easy to combine them the new content into the appendix:
>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <module resourceref="tut5">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task4"/>
>     <module resourceref="task3"/>
>   </module>
>   
>
> but that doesn't produce a pleasing result:
>
>   <appendix xml:base="tutorial/tut3.xml">
>     <title>Troubleshooting</title>
>     ...
>     <section xml:base="tutorial/tut5.xml">
>       <title>Troubleshooting</title>
>       ...
>     </section>
>     <section xml:base="tasks/task4.xml">
>       <title>Diagnosing spindle problems</title>
>       ...
>     </section>
>     <section xml:base="tasks/task3.xml">
>       <title>Diagnosing bearing problems</title>
>       ...
>     </section>
>   </appendix>
>   
>
> What we really want to do is combine tutorials 3 and 5, not make 5 a 
> subordinate section of 3. While we're at it, let's change the title of 
> the appendix to “Troubleshooting spindle and bearing problems” since 
> that's what it's really about.
>
> We can solve the first problem with the contentonly attribute on module:
>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   
>
> If contentonly is true, then only the content of the document element, 
> and not the document element itself, is included. Any metadata 
> associated with the document element is also discarded. (If the 
> referenced resource has several top-level element children, then this 
> processing is applied to each, in turn.)
>
> The realized structure for this appendix is now:
>
>   <appendix xml:base="tutorial/tut3.xml">
>     <title>Troubleshooting</title>
>     ...
>     ...content (only) of tutorial 5...
>     <section xml:base="tasks/task4.xml">
>       <title>Diagnosing spindle problems</title>
>       ...
>     </section>
>     <section xml:base="tasks/task3.xml">
>       <title>Diagnosing bearing problems</title>
>       ...
>     </section>
>   </appendix>
>   
>
> There are two ways that we can change the title. The first uses only 
> semantics we've already encountered:
>
>   <module>
>     <output renderas="appendix"/>
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut3" contentonly="true"/>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   
>
> The only disadvantage of this approach is that we lose all of the 
> metadata associated with tutorials 3 and 5. This might include 
> publication dates, copyright information, etc. We could add those 
> fields to the info wrapper for the appendix in the assembly, but then 
> it may have to be maintained in two places.
>
> Instead, we introduce one more convention: if a module refers to 
> another resource /and/ contains an info element, then the elements 
> within that info replace any elements of the same name in the 
> referenced resource's metadata. (If the referenced resource has no 
> metadata, then the specified info becomes the first child of the 
> referenced resource.)
>
> The second approach uses this convention:
>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   
>
> In the realized structure for this example, the appendix metadata 
> includes everything in tutorial 3's metadata, with the title changed 
> as indicated. Of course, all of the metadata for tutorial 5 is still 
> lost, but there's nothing we can do about that because there's no 
> where to put it.
>
>
>   5. Example: Assembling an Online Book
>
> This example extends the book example, see Section 4, “Example: 
> Assembling a Printed Book” <#ex-book>. In addition to the printed user 
> guide, we want to produce an online user guide. The online guide is, 
> by design, a straightforward, linear rendering of the book. We'll look 
> at a more intricately structured example later.
>
> We could create a separate assembly for the online guide, but it will 
> be in the long run if we can manage the structure of the user guide in 
> one place.
>
> The first step is to create a new output type:
>
> <structure xml:id="user-guide">
>   <output type="book" renderas="book"/>
>   <output type="web" renderas="book"/>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <module resourceref="full-toc"/>
>   <module resourceref="tut1">
>     <output renderas="chapter"/>
>   </module>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   <module resourceref="index"/>
> </structure>
>   
>
> Now we can process this structure either as a “book” type structure or 
> a “web” type structure. At the moment, there's no difference between 
> them. Let's consider some of the changes we need to make for the 
> online site:
>
>   1.
>
>       We want to control the names of the HTML documents produced.
>
>   2.
>
>       We want to control how chunking is performed.
>
>   3.
>
>       We want to suppress some “print only” content.
>
> The first two of these we can address with output elements:
>
> <structure xml:id="user-guide">
>   <output type="book" renderas="book"/>
>   <output type="web" renderas="book" file="user-guide.html"/>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <module resourceref="full-toc">
>     <output type="web" chunk="false"/>
>   </module>
>   <module resourceref="tut1">
>     <output renderas="chapter"/>
>   </module>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>       <output type="web" chunk="false"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   <module resourceref="index">
>     <output type="web" file="book-index.html"/>
>   </module>
> </structure>
>   
>
> Specifying a file on an output tells the assembly where to write the 
> chunk. (If it occurs on a module which is not chunked, it is simply 
> ignored.) The chunk attribute can be used to specify which modules 
> should (or should not) be placed in separate chunks. The implied value 
> on modules where it is not specified depends on the name of the 
> rendered element and the output type.
>
> When processing a module, all of the relevant output directives are 
> combined. An output is relevant if it does not specify a type or if 
> the type specified matches the type of processing that is being 
> performed. If conflicting values are specified for any attribute, the 
> last value specified (in document order) is used.
>
> To exclude (or include) content, we add the filterout (and filterin) 
> elements to the assembly. Each may have a type and specifies some 
> number of effectivity values.
>
> If no conditions are specified on filterout, the module is 
> unconditionally excluded. (Specifying no conditions on a filterin has 
> no effect.)
>
> If filters are used at the structure level, they apply to the entire 
> document. If they are used at the module level, they apply only to 
> that module.
>
> With filters, our structure might look like this:
>
> <structure xml:id="user-guide">
>   <output type="book" renderas="book"/>
>   <output type="web" renderas="book" file="user-guide.html"/>
>   <filterout type="web" condition="print"/>
>   <info>
>     <title>Widget User Guide</title>
>   </info>
>   <module resourceref="full-toc">
>     <output type="web" chunk="false"/>
>   </module>
>   <module resourceref="tut1">
>     <output renderas="chapter"/>
>   </module>
>   <module resourceref="tut2">
>     <filterin type="web" condition="print"/>
>     <filterout type="web" userlevel="advanced"/>
>   </module>
>   <module resourceref="task1"/>
>   <module resourceref="tut3">
>     <output renderas="appendix"/>
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4">
>       <output renderas="section"/>
>       <output type="web" chunk="false"/>
>     </module>
>     <module resourceref="task3"/>
>   </module>
>   <module resourceref="index">
>     <filterout type="web"/>
>   </module>
> </structure>
>   
>
> This structure applies the following filters when rendering for the 
> web: print only content is excluded globally; in tutorial 2, print 
> only content /is/ included, but advanced material is excluded; and the 
> entire index is excluded.
>
>
>   6. Example: Assembling an Online Reference
>
> The online reference differs from the preceding book-based examples in 
> that no total, linear order is imposed on the content. Instead, 
> navigation is performed either by search (which is outside the scope 
> of assemblies) or through related links.
>
> Using the resources defined in Section 4, “Example: Assembling a 
> Printed Book” <#ex-book>, here's a plausible structure for our online 
> reference.
>
> <structure xml:id="user-guide">
>   <output renderas="topic"/>
>   <filterout type="web" condition="print"/>
>   <info>
>     <title>Widget Reference</title>
>   </info>
>   <module resourceref="tut1"/>
>   <module resourceref="tut2"/>
>   <module resourceref="task1"/>
>   <module resourceref="tut3">
>     <info>
>       <title>Troubleshooting spindle and bearing problems</title>
>     </info>
>     <module resourceref="tut5" contentonly="true"/>
>     <module resourceref="task4"/>
>     <module resourceref="task3"/>
>   </module>
>   <module resourceref="tut4"/>
>   <module resourceref="task2"/>
>   <module resourceref="index"/>
> </structure>
>   
>
> The resulting realized structure will be a nested set of topic 
> elements. Topics don't nest in DocBook (at least under the current 
> proposal), so this isn't a valid DocBook document. However, the nested 
> topics provide a navigational structure for the online presentation. 
> The rendering system is, we assume, smart enough to render each of the 
> topics separately, as if they were all top-level siblings.
>
> ------------------------------------------------------------------------
>
>
>                                         Be seeing you,
>                                           norm
>
>