Skip to main content

Building an output

You have authored data modules. You have validated them against the BREX. You have assembled a publication module. The last step is to turn that source content into something a reader can use. This is the build (or publish) step.

This page explains the pipeline at a conceptual level, then shows illustrative commands. The build step does not add new information. It selects, resolves, and renders information that already lives in the CSDB.

Source-once, use-many

S1000D stores each fact once in the CSDB. A build reuses that single source for every deliverable. The same data modules can produce a PDF manual, an HTML page set, and an interactive IETP — without rewriting the content. This is the core S1000D promise: write once, publish many.

What "an output" means​

A deliverable is a finished product for an end user. S1000D content commonly produces three output kinds:

OutputWhat it isTypical use
IETPInteractive Electronic Technical Publication — a navigable, often interactive viewerOn-equipment maintenance; the "live" manual
PDFPaginated, print-ready documentFormal release; offline or contractual copies
HTMLStatic linked web pagesLightweight review and online reading
IETP and IETM

You will see both terms. IETM (Interactive Electronic Technical Manual) is the older, general term for an electronic manual. IETP (Interactive Electronic Technical Publication) is the S1000D term for the same idea — a publication delivered for interactive on-screen use rather than print. Treat them as near-synonyms in everyday use.

The conceptual pipeline​

A build moves source content through a fixed set of stages. The diagram below ties back to the CSDB: everything starts from the source objects in the database.

Each stage has a clear job.

1. Filter for the target​

A CSDB usually holds content for many variants — different customers, configurations, or serial numbers. Before building, you resolve applicability: keep only the content that applies to the product you are publishing for. Applicable content stays; non-applicable content is dropped.

This step uses the applicability conditions in each data module. The result is an instance of the source tailored to one product.

2. Resolve references and flatten​

A publication module is a structure, not the content itself. It references the data modules to include, in reading order. To build, the pipeline follows those references, pulls in each referenced data module (and its referenced ICNs and multimedia), and assembles a single resolved source set.

This is often called flattening: the publication module plus all the objects it points to become one combined source ready to render.

3. Render with stylesheets​

The combined source is still XML. A stylesheet (XSLT) maps that XML to the chosen output format — generating the page layout, table of contents, cross-links, titles, and figures. The renderer produces the final IETP, PDF, or HTML.

The split that makes this work

Content and presentation are kept apart. The data modules carry meaning; the stylesheet carries look. Change the stylesheet and you change every deliverable's appearance without touching a single data module.

Illustrative commands​

These commands are illustrative examples drawn from the s1kd-tools workflow. Exact options, file names, and DMCs are samples — adapt them to your own CSDB. The s1kd-tools toolchain is open source, so any standalone tool used below can be replaced by an equivalent in a commercial publishing engine.

The s1kd-tools project covers the filter and flatten stages directly. For the render stage, the companion S1000D-XSL-Stylesheets project (a separate project, also by the s1kd-tools author) supplies the stylesheets and a s1kd2pdf wrapper script that drives xsltproc and Apache FOP. The two projects are designed to be used together.

Filter for one product​

Produce an instance that applies to a single product, using an applicability value:

# Example: keep only content applicable to product version B
# -s takes an applicability assignment of the form <ident>:<type>=<value>
# where <type> is a product attribute (prodattr) or a condition (condition)
s1kd-instance -s version:prodattr=B -O ./build DMC-*.XML

s1kd-instance reads the source data modules and writes a filtered set to the ./build directory (the -O/--outdir option names each instance automatically). To filter exactly the set of objects a publication references, list them first with s1kd-refs and pipe them in, for example: s1kd-refs -s <PM> | xargs s1kd-instance -s version:prodattr=B -O ./build.

Flatten the publication module​

Combine the publication module and every data module it references into one file:

# Example: flatten a PM into a single combined XML document
# By default the referenced data modules are copied directly into the PM.
s1kd-flatten PMC-EXAMPLE-12345-00001-00.XML > publication.xml

s1kd-flatten follows the publication module's references and pulls the referenced objects into a single document ready for rendering.

Render to a deliverable​

Apply the stylesheets to produce the output. The S1000D-XSL-Stylesheets project provides the s1kd2pdf wrapper, which transforms the source (via DocBook and XSL-FO) and runs Apache FOP to emit a PDF:

# Example: render the flattened publication to PDF
# s1kd2pdf is part of S1000D-XSL-Stylesheets, used alongside s1kd-tools
s1kd2pdf publication.xml
note

The S1000D-XSL-Stylesheets toolchain targets PDF output (via DocBook and XSL-FO). It does not ship an HTML transform — other deliverables, such as HTML or an IETP package, are produced by your own XSLT or a separate publishing system applied to the same flattened source.

Prepare IETP metadata​

For an interactive viewer, an extra step generates neutral, viewer-independent metadata so an IETP application can index and navigate the content:

# Example: generate IETP neutral metadata for CSDB objects
s1kd-neutralize DMC-EXAMPLE-*.XML

s1kd-neutralize adds the navigation metadata an IETP needs; the interactive viewer then consumes the prepared CSDB objects.

A minimal build, end to end​

A small build script often chains the stages. The example below is illustrative.

#!/bin/sh
# Illustrative: filter -> flatten -> render to PDF

# 1. Filter the source for one product into a temp dir
s1kd-instance -s version:prodattr=B -O ./build DMC-*.XML

# 2. Flatten the publication module against the filtered set
s1kd-flatten -d ./build ./build/PMC-EXAMPLE-12345-00001-00.XML > ./build/publication.xml

# 3. Render the combined source to a deliverable
s1kd2pdf ./build/publication.xml

The three stages map one-to-one onto the conceptual pipeline: filter, flatten, render.

Where this fits​

StepPage
Author the contentCreating your first data module
Check it is validValidating against a BREX
Define the publicationAssembling a publication module
Build the deliverableThis page

The build closes the loop: validated source in the CSDB becomes a published deliverable, and any change to the source produces a new build without re-authoring the document.

Sources​