docbook-style-dsssl

Overview

docbook-style-dsssl provides Norman Walsh’s DocBook DSSSL stylesheets. These are the formatting rules and support files used to transform DocBook documents into printable and HTML output with a DSSSL processor such as Jade. In a Linux distribution, this package is typically needed when building documentation rather than when running applications.

For maintainers, the practical point is that this package helps other packages render DocBook-based manuals, guides, and reference material in a reproducible way. If a package builds documentation from DocBook sources, it may depend on these stylesheets at build time.

Purpose and typical use cases

Typical use cases include:

• building DocBook documentation into HTML or print-oriented output
• providing a consistent stylesheet set for package documentation builds
• supporting local customization of DocBook processing through driver files
• integrating with packaging workflows that convert upstream documentation sources during build time

Typical users are:

• RPM and distribution maintainers
• documentation builders and technical writers
• developers who maintain DocBook-based project documentation
• CI/CD maintainers who need documentation builds to pass reliably
• sometimes release engineers who verify that documentation output still renders correctly after updates

Upstream project

The upstream project is the DocBook DSSSL stylesheet distribution associated with the DocBook Project and Norman Walsh’s stylesheets. The official project documentation describes the stylesheets as a set of DocBook processing rules for DSSSL-based rendering, with separate support for HTML and print output. (docbook.sourceforge.net)

The project documentation also notes that a working DocBook documentation toolchain typically involves a DSSSL processor, the DocBook DTD, and the DocBook stylesheets. That is useful context for package maintainers: if documentation builds fail, the issue may be in the surrounding toolchain rather than in this package alone. (docbook.sourceforge.net)

Dist-git repository contents

This dist-git repository is organized as follows:

• SPECS/ — RPM spec file(s) and packaging logic
• SOURCES/ — source metadata and manifest files used to track upstream inputs
• METADATA/ — package metadata used by the distro packaging workflow
• SBOM/ — software bill of materials material, when present in the repository layout

Large upstream source archives are intentionally not stored in this Git repository. Instead, the repository keeps source integrity metadata in SOURCES manifest files so that maintainers can verify what should be fetched and built without committing bulky upstream tarballs to Git.

Source storage and integrity policy

The repository uses manifest-based source tracking. In practice, that means:

• the actual upstream source payload is fetched outside the Git history
• SOURCES records which inputs belong to the package
• integrity checks are tied to those manifests and the packaging workflow, not to files copied directly into the repository

NiceOS maintainers should verify that the manifests still match the intended upstream source set before updating the package. If upstream repackages files, renames archives, or changes the documentation layout, the manifests and packaging metadata may need to be refreshed together.

NiceOS maintenance notes

Before updating this package, check the following:

• confirm that the upstream project still provides the same DocBook DSSSL stylesheet set
• review whether the package still builds with the same DSSSL processor expectations used in NiceOS
• inspect changes to installed file paths, stylesheet driver files, catalog files, and other packaging inputs
• verify whether any repository metadata under SPECS/, SOURCES/, METADATA/, or SBOM/ needs regeneration
• check whether downstream patches or distro-specific adjustments remain valid
• consider whether the update could affect documentation builds in other packages that depend on these stylesheets

Risks to consider:

• documentation output changes can be subtle and may only appear in rendered manuals
• a change in the upstream file layout can break package build scripts or document toolchain assumptions
• if the surrounding DocBook toolchain changes, a package update may appear to be the problem even when the issue lies elsewhere

Build and verification checklist

For RPM maintenance work, a reasonable checklist is:

• review the spec file for changed source handling or install paths
• refresh source manifests if upstream inputs changed
• rebuild the SRPM and RPMs in a clean environment
• verify that all packaged files are installed where the spec expects them
• check that documentation examples or installed stylesheet drivers still resolve correctly
• run any available doc build or smoke test that exercises the stylesheets with a simple DocBook input
• inspect build logs for missing catalog entries, missing stylesheet modules, or path resolution issues
• compare installed file lists against the previous package to catch accidental additions or removals
• confirm that packaging metadata remains consistent with the repository layout

References

• DocBook Project
• Customizing the Stylesheets
• Installation and Setup
• The Print Stylesheet
• The HTML Stylesheet

Russian documentation

See also: README_RU.md

Dist-git repository notes

• Package repository: rpms/docbook-style-dsssl
• NiceOS branch: niceos-5.2
• This README is intentionally stable and does not include EVR, source archive checksums or lock hashes.