[5.1 Assembly]module

module — A modular component within a structure.

Synopsis

module ::=

Attributes

Common attributes.

Additional attributes:

  • chunk (enumeration) [default=“auto”]
    • “true”
    • “false”
    • “auto”
  • contentonly (boolean)
  • omittitles (boolean)
  • renderas (QName)
  • resourceref (IDREF)

Additional Constraints

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

Description

Within a structure, the module elements describe the subunits of the structure. If the structure represents a book, then the modules are effectively the chapters, appendixes, etc. If the structure represents an interactive help system or web site, then the modules may be pages or sets of pages within that system.

In the simplest case, a module points to the resource that is the body of the module. To point to a resourse, set the module element’s resourceref attribute to the value of the xml:id on the resource element. In more complex cases, a module may impose more structure through nested modules.

You can also create structures that serve as modular components of a larger structure. A module in a larger structure can set its resourceref attribute to the value of the xml:id of a modular structure element in the same assembly to incorporate it.

You can also create new empty container elements within a structure by specifying a module element without a resourceref attribute, and with a renderas attribute to define the element’s name. Any modules contained in the module element will be inserted into the newly created container element during assembly.

If contentonly is true, then only the content of the referenced resource is included (that is, the children of the root element, but not the root element itself).

If omittitles is true, then the title elements of the referenced resource are not included.

Note

If the omittitles attribute is combined with the contentonly attribute, then both the root element and titles are stripped and the remaining raw content can be placed where the root element and titles are not allowed. For example, the remaining content can be added to the end of a section element taken from another resource.

Processing expectations

Never rendered directly. The content that results from processing a module is generally rendered in the normal fashion.

Attributes

Common attributes.

chunk

Specifies chunking for this module

Enumerated values:
“true”

This module will be in a chunk

“false”

This module will not be in a chunk

“auto”

Chunking of this module depends on the overall chunking algorithm

contentonly

Indicates if the root element should be omitted when including the resource (copying only the children)

omittitles

Indicates if titles should be omitted when including a resource

renderas

Changes the name of the root element of the included resource to the specified name

resourceref

Identifies a single resource or structure within the assembly from which to construct this module

Parents

These elements contain module: module, structure.

Children

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

Examples

This module renders the resource whose xml:id is “topic1” as a chapter, and includes the resources whose xml:id values are “topic2” and “topic3” as sections within the chapter, added after any content in “topic1”.

<module resourceref="topic1" renderas="chapter">
  <module resourceref="topic2" renderas="section"/>
  <module resourceref="topic3" renderas="section"/>
</module>

This module without a renderas attribute does not point to a resource, but can create a new element whose name is specified by its renderas attribute, and whose title and other info data are specified in its merge element. Other modules contained within this module will be assembled as descendants of this new element.

<module renderas="section">
  <merge>
    <title>Using a mouse</title>
  </merge>
  <module>
    ...
  </module>
</module>