OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: A first stab at documenting assemblies


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.

Title: DocBook Assemblies

OASIS logo

DocBook Assemblies Version

Specification URIs:

This Version:
http://docs.oasis-open.org/docbook/specs/--spec--.html
http://docs.oasis-open.org/docbook/specs/--spec--.pdf
http://docs.oasis-open.org/docbook/specs/--spec--.xml
Technical Committee:
Chair
Editor

Abstract:

Status:

Notices:

Table of Contents

1. Physical structure
2. Logical structure
3. Assembly Files
3.1. Resources
3.2. Structures
3.3. Relationships
3.4. Transformations
4. Example: Assembling a Printed Book
5. Example: Assembling an Online Book
6. Example: Assembling an Online Reference

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.

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”. 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”, 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

-- 
Norman Walsh <ndw@nwalsh.com>      | Faith makes many of the mountains
http://www.oasis-open.org/docbook/ | which it has to remove.--W. R. Inge
Chair, DocBook Technical Committee |

PGP signature



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]