V5.1 Assemblystructure

structure — Describes the structure of a document.

Synopsis

structure ::=

Attributes

Common attributes.

Additional attributes:

  • defaultformat (NMTOKEN)
  • renderas (QName)
  • resourceref (IDREF)
  • type (NMTOKEN)

Additional Constraints

  • The renderas attribute can be specified on either the structure or output, but not both.

Description

A structure is the top-level unit of an assembly. A structure represents the book, help system, web site, or other artifact to be produced by assembling modules, which are further composed of resources.

An assembly can contain several structure elements, but usually only one is specified for output at a time. For example, one structure could assemble a printed document, while a second structure could assemble an online help system from the same set of resources.

If a structure element has a resourceref attribute, then the resource that it points to becomes the root element and base content of the assembled document. If a structure does not have a resourceref attribute, then it should have a renderas attribute to specify the root element generated to contain the modules in the structure. It should also have a merge element to specify the title and any other info content of the generated root element.

You can also create modular structures. If a module element within in a main structure has a resourceref attribute that matches the xml:id of another structure, then the modules of that structure are incorporated into the main structure.

Processing expectations

A structure is rendered by assembling the modules that it contains into a new, assembled document.

Common attributes on the structure element are generally copied onto the output root element.

Attributes

Common attributes.

any attribute

Any attribute in any other explicit namespace

defaultformat

Identifies the default format of the structure

renderas

Specifies the DocBook element to which this unit should be renamed

resourceref

Indicates a single resource from which to construct this structure

type

Identifies the structure type of the structure

Parents

These elements contain structure: assembly.

Children

The following elements occur in structure: filterin, filterout, info (db.info), merge, module, output, revhistory.

Examples

This structure generates a book root element and incorporates two resources, one as a chapter and the other as an appendix.

1 |<structure renderas="book">
  |  <merge>
  |    <title>Name of the book</title>
  |  </merge>
5 |  <module resourceref="topic1" renderas="chapter"/>
  |  <module resourceref="topic2" renderas="appendix"/>
  |</structure>

This structure uses a resource to create the root article element, and incorporates two resources as sections in the article.

  |<structure resourceref="article-template">
  |  <module resourceref="topic1" renderas="section"/>
  |  <module resourceref="topic2" renderas="section"/>
  |</structure>

This example assembles two substructures into a main structure:

1 |<structure xml:id="chapter1-structure" resourceref="chap1">
  |  <module resourceref="topic1" renderas="chapter">
  |    <module resourceref="topic2" renderas="section"/>
  |  </module>
5 |</structure>

1 |<structure xml:id="chapter2-structure" resourceref="chap2">
  |  <module resourceref="topic3" renderas="chapter">
  |    <module resourceref="topic4" renderas="section"/>
  |  </module>
5 |</structure>

1 |<structure renderas="book">
  |  <merge>
  |    <title>Name of the book</title>
  |  </merge>
5 |  <module resourceref="chapter1-structure"/>
  |  <module resourceref="chapter2-structure"/>
  |</structure>