Skip to main content

Publication modules

A data module holds one piece of content. It does not know where it belongs in a manual. The publication module (PM) supplies that missing structure. It is a list that says which data modules to include, in what order, and under what headings, to form a deliverable publication.

The publication module is what turns a pool of reusable parts in the CSDB into a finished book, manual, or interactive publication.

note

A publication module is itself a kind of data module. It has its own schema, its own identification and status metadata, and a content section. The difference is that its content is a structure — references to other objects — not reader-facing text.

What a publication module references​

A publication module does not copy content. It points to it. Each entry in a publication module can reference one of the following.

Reference targetWhy you use it
A data moduleThe normal case — include a unit of content at this place in the structure.
Another publication moduleNest a whole sub-publication inside this one (for example, a chapter that is also published on its own).
A legacy publicationPoint to an external document (such as a PDF) that is not authored in S1000D.

Because a publication module can reference other publication modules, publications nest. A large manual can be built from smaller publication modules, and a shared sub-publication can be reused by more than one parent — the same "source once, use many" idea that drives the rest of S1000D.

The structure: pmEntry​

The body of a publication module is built from pmEntry elements. A pmEntry is a node in the publication's tree. It can carry a title (a chapter or section heading) and it can contain references to data modules, references to other publication modules, and further nested pmEntry elements.

So the publication module is a hierarchy:

The order of the entries is the order the reader meets the content. The nesting of the entries is the chapter-and-section hierarchy of the finished publication.

tip

Think of the publication module as the table of contents, written first. You decide the structure and the order, and each leaf of the tree names a data module to drop into that slot. The renderer walks the tree to build the output.

The Publication Module Code (PMC)​

Every publication module has a unique identifier: the Publication Module Code (PMC). It works like the Data Module Code but is shorter, because a publication module identifies a whole publication rather than a place in the product breakdown.

The PMC is built from these fields.

FieldXML attributeWhat it identifies
Model identification codemodelIdentCodeThe product or project the publication applies to.
PM issuerpmIssuerThe organization that issues the publication (often a CAGE code).
PM numberpmNumberThe number of this specific publication.
PM volumepmVolumeThe volume, when a publication spans more than one.

In XML, the code appears as a single element with those attributes. The following is an illustrative example — a made-up code, not a real publication:

<!-- Example only -->
<pmCode modelIdentCode="MYPRJ" pmIssuer="12345" pmNumber="00001" pmVolume="00"/>
info

The first field, modelIdentCode, is the same model identification code used in the Data Module Code. This is how a publication and the data modules it assembles are tied to the same product. The shared model code is the thread that runs through the whole CSDB.

One source, two kinds of output​

A single publication module is format-independent. The same assembled publication can be rendered two ways, from the one source.

OutputWhat it isWhen you want it
IETP / IETMAn Interactive Electronic Technical Publication — navigable on screen, with hotspotted graphics, video, 3D, and applicability filtering.Delivery on a device; rich media; content that changes with the equipment.
Page-orientedA laid-out, paginated document, usually a PDF.A printable or fixed-page manual; contractual paper deliverables.

Both outputs draw on the same publication module and the same underlying data modules. You do not maintain two copies. You author once, assemble once, and render to whichever format the reader needs.

note

The publication module is the assembly stage of the pipeline. Authors create data modules and graphics; the CSDB stores them; each data module is validated against the project's BREX; the publication module then selects and orders the valid data modules; finally a renderer produces the IETP or the page-oriented output. See The Common Source Database for the full pipeline diagram.

Building one with s1kd-tools​

This site is generated by techwriter.ai watching the s1kd-tools repository — a free, open-source command-line toolchain for S1000D. Those tools work directly on a folder of XML files, so you can create and assemble a publication module on the command line.

The example commands below are illustrative; check the exact syntax against the s1kd-tools tutorial for the version you have installed.

# Example only — create a new publication module shell
s1kd-newpm -# MYPRJ-12345-00001-00

# Example only — list the data modules a publication module references
s1kd-refs PMC-MYPRJ-12345-00001-00_001-00_EN-US.XML

After the publication module is filled in, a build step gathers the referenced data modules in the order the pmEntry tree defines, and a formatting engine renders the result to IETP or PDF.

How it fits with the other concepts​

ConceptRelationship to the publication module
Data moduleThe unit of content that a publication module references and orders.
Data Module CodeIdentifies each referenced data module; shares the model code with the PMC.
CSDBStores both the data modules and the publication modules.
BREXValidates the content before the publication module assembles it.

A publication module adds no new content. Its whole job is to choose, order, and structure content that already exists in the CSDB. That separation — content in data modules, structure in publication modules — is what lets one source serve many publications and many formats.

Sources​