Skip to main content

Assembling a publication

A data module is one self-contained unit of information. A real deliverable — a manual, a handbook, an IETP — is many data modules in a defined order. In S1000D, a publication module (PM) holds that order. It lists the data modules of a publication and lays out their hierarchy. This page shows how to create a publication module with s1kd-newpm and assemble data modules into a single deliverable with s1kd-tools.

Why this page exists

techwriter.ai watches the s1kd-tools repository and writes these docs. Because documenting an S1000D toolchain means explaining S1000D itself, this site doubles as an S1000D knowledge base. This page covers the last step before output: turning a folder of data modules into one ordered publication.

Commands here are illustrative

The commands below show the shape of the workflow. The publication module code, tool flags, and exact XML change over time. Confirm against the upstream usage examples and the repository before you run anything.

What a publication module is​

A publication module is itself a CSDB object, like a data module. It does not hold maintenance content. Instead it points to other data modules and arranges them. As the upstream documentation puts it, "the publication module lays out the hierarchical structure of the data modules in a publication."

ObjectHoldsRole
Data module (DM)One unit of contentThe reusable source, written once
Publication module (PM)An ordered list of referencesThe table of contents and structure
DeliverablePM plus its referenced DMs, combinedThe file a publishing system renders

Each data module is referenced by its Data Module Code (DMC), so the same data module can appear in more than one publication. This is the "write once, use many" idea at the publication level.

Step 1 — Create the publication module​

You can create a publication module two ways: from the project's Data Management Requirements List (DMRL), or "on-the-fly" with the s1kd-newpm tool. The on-the-fly form takes a publication module code:

# Illustrative — creates a new publication module file
s1kd-newpm -# MYPRJ-12345-00001-00

The publication module code has these parts:

FieldExampleMeaning
modelIdentCodeMYPRJThe project or product identifier
pmIssuer12345The issuing organization code
pmNumber00001The publication number
pmVolume00The volume number
note
MYPRJ is an example

MYPRJ-12345-00001-00 is the sample code from the upstream examples. Replace it with your own project's codes. The publication module code identifies the publication the same way a DMC identifies a data module.

This produces an empty publication module: it has the identification and status metadata, but no entries yet. The next step is to add the data modules.

Step 2 — Add data module references​

Inside the publication module, content is organized with pmEntry elements. Each pmEntry can hold a title and one or more dmRef elements. A dmRef is a reference to a data module by its code. Nesting pmEntry elements builds the hierarchy — chapters, sections, and sub-sections.

A single entry looks like this (illustrative):

<pmEntry>
  <pmEntryTitle>Description</pmEntryTitle>
  <dmRef>
    <dmRefIdent>
      <dmCode modelIdentCode="MYPRJ" systemDiffCode="A"
              systemCode="00" subSystemCode="0" subSubSystemCode="0"
              assyCode="00" disassyCode="00" disassyCodeVariant="A"
              infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
    </dmRefIdent>
    <dmRefAddressItems>
      <dmTitle>
        <techName>My project</techName>
        <infoName>Description</infoName>
      </dmTitle>
    </dmRefAddressItems>
  </dmRef>
</pmEntry>

You do not have to type the dmCode by hand. The s1kd-ref tool generates the reference XML for a CSDB object, so you can produce each dmRef quickly and paste it into the publication module.

# Illustrative — generate reference XML for a data module
s1kd-ref DMC-MYPRJ-A-00-00-00-00A-040A-D
Order is meaningful

The order of pmEntry and dmRef elements is the reading order of the finished publication. Arrange them the way the publication should be read, top to bottom.

Step 3 — (Optional) Filter by applicability​

If your data modules carry applicability (for example, content that applies only to one variant or configuration), you can resolve it before delivery with s1kd-instance. This produces a tailored set of objects for a specific applicability, so the deliverable shows only the content that applies. This step is optional and only matters when your project uses applicability.

Step 4 — Flatten into one deliverable​

A publishing system usually wants one file, not a folder of separate data modules linked by reference. The s1kd-flatten tool does this. Its own documentation describes it as combining "a publication module and the data modules it references in to a single file for use with a publishing system."

# Illustrative — combine the PM and its referenced DMs into one file
s1kd-flatten PMC-MYPRJ-12345-00001-00_001-00_EN-US.XML > publication.xml

How it works, in plain terms:

  • It reads the publication module.
  • For each dmRef, it finds the matching data module. By default it searches the current directory, matching on the data module code, language, and issue info in each reference.
  • It copies the referenced content into one combined file, keeping the order and hierarchy from the publication module.
Containers are not followed by default

If the publication references a container data module, s1kd-flatten will not descend into it unless you ask it to. Pass the -c (--containers) option and the tool copies the references from inside the container directly into the publication module. By default the referenced data modules are copied into the PM; pass -x (--use-xinclude) to use XInclude instead, or -m (--modify) to rewrite the references without flattening them. Check the tool's help (s1kd-flatten -h) for the current options before you rely on this.

The assembly flow at a glance​

After flattening, the single file is ready for a publishing system to render — for example, into an IETP or a PDF. That output step is covered on the next page.

Quick reference​

ToolJob in this workflow
s1kd-newpmCreate a new publication module
s1kd-refGenerate reference XML (dmRef) for a CSDB object
s1kd-instanceResolve applicability into a tailored instance (optional)
s1kd-flattenCombine a PM and its referenced DMs into one file
Verify tool names and flags

This page names real s1kd-tools programs, but flags and behavior evolve. Always confirm against the upstream usage examples and each tool's own -h help output.

Sources​