docbook-xsl

Overview

docbook-xsl provides XSL stylesheets for transforming DocBook XML documents into presentation formats such as HTML and other output types supported by the upstream toolchain. In a distribution, this package fills the role of a reusable documentation-processing component rather than an application end user runs directly.

For maintainers, the main point of the package is predictable transformation of DocBook sources used by documentation projects, build systems, and publishing workflows. If a downstream package produces manuals, guides, or other XML documentation in DocBook format, it may depend on these stylesheets during the build or documentation generation step.

Purpose and typical use cases

Typical uses include:

• converting DocBook XML documents into HTML for web publication
• generating other supported output formats as part of a documentation pipeline
• providing a standard stylesheet set for packaging or rebuilding existing DocBook-based documentation
• integrating DocBook rendering into CI/CD or release automation for projects that publish technical manuals

Typical users include:

• distribution package maintainers
• documentation and build engineers
• developers who publish project manuals from DocBook sources
• CI/CD maintainers running documentation builds
• release engineers and publishing workflows that need reproducible DocBook transformations

Upstream project

The upstream project is the DocBook project. DocBook is an XML vocabulary used for technical documentation, and the official project site provides documentation for the schemas and stylesheets. The upstream DocBook stylesheets page describes the classic DocBook XSL stylesheets as XSLT 1.0 stylesheets that are still widely deployed. NiceOS maintainers should verify the exact upstream branch or release series used by this package before relying on details from a particular update. (docbook.org)

Upstream documentation explains how the stylesheets are used and customized, including the common pattern of applying the docbook.xsl stylesheet from the distribution tree with an XSLT processor. (xsltng.docbook.org)

Dist-git repository contents

This dist-git repository is organized as follows:

• SPECS/ — RPM spec files and packaging logic
• SOURCES/ — source metadata and manifest files used by the RPM build
• METADATA/ — repository metadata maintained by the packaging workflow
• SBOM/ — software bill of materials artifacts, when produced by the packaging process

The repository does not store large upstream source archives directly. Instead, source integrity is tracked through manifest files in SOURCES/, which record the expected upstream sources for the package. NiceOS maintainers should treat those manifests as the packaging authority for what is fetched during the build.

Source storage and integrity policy

Large upstream archives are intentionally excluded from this Git repository.

This means:

• the repository remains smaller and easier to review
• source material is fetched or assembled through the packaging workflow rather than committed as large binary blobs
• integrity checks are based on the manifest metadata stored in SOURCES/

Before updating the package, maintainers should confirm that the source manifests still match the intended upstream source set and that any packaging metadata remains consistent with the spec file.

NiceOS maintenance notes

Before updating docbook-xsl, check the following:

• whether upstream changed the stylesheet layout, file names, or installation paths
• whether the package still ships the same transformation entry points expected by dependent builds
• whether any local patches are still needed or should be dropped
• whether packaging metadata in SOURCES/, SPECS/, METADATA/, or SBOM/ needs regeneration
• whether downstream consumers depend on behavior that may change across upstream releases

Practical risks to consider:

• documentation builds may fail if a stylesheet path or parameter changes
• downstream output differences may require rebuilds or manual review
• old local overrides may no longer apply cleanly
• generated metadata may need to be refreshed after upstream source changes

If any upstream detail is uncertain, NiceOS maintainers should verify it directly against the packaged upstream sources before relying on it.

Build and verification checklist

For an RPM update, a maintainer should usually check:

• the spec file parses cleanly
• the source manifest in SOURCES/ matches the intended upstream inputs
• any patches apply cleanly or are removed if no longer needed
• the package builds in a clean environment
• installed file paths and symlinks match what downstream packages expect
• the resulting package contains the expected stylesheet tree and metadata
• basic DocBook transformation tests still work with a representative input document
• no unintended packaging changes were introduced in METADATA/ or SBOM/

A practical verification step is to rebuild at least one simple DocBook document with the packaged stylesheets and compare the output with expectations from the previous package state.

References

• DocBook.org
• DocBook stylesheets documentation
• DocBook documentation portal
• DocBook XSL Stylesheets reference documentation
• Release notes for the DocBook XSL Stylesheets

Russian documentation

See README_RU.md for the Russian version of this document.

Dist-git repository notes

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