docbook-xml

Overview

docbook-xml packages DocBook XML catalog and DTD resources for systems that need to validate, transform, or process DocBook documents. DocBook is an XML vocabulary used for technical documentation, especially manuals, reference material, and other structured documents about software and hardware. (docbook.org)

In a Linux distribution, this package typically exists so that other tools and packages can resolve DocBook identifiers locally instead of relying on ad hoc copies. That makes it easier for build systems, documentation toolchains, and validation steps to work in a consistent way. If a downstream use depends on a specific catalog layout or DTD entry point, NiceOS maintainers should verify that assumption against the installed files in the package.

Purpose and typical use cases

Typical use cases include:

• validating DocBook XML documents during packaging or documentation builds
• transforming DocBook sources into HTML, man pages, PDF, or other output formats with external toolchains
• providing XML catalog entries and DTD references for tools that expect standard DocBook identifiers
• supporting documentation-heavy packages in build systems, CI pipelines, and local development environments

Typical users include:

• package maintainers who build or ship documentation
• release engineers and CI/CD maintainers who run documentation checks
• developers working on projects that store manuals in DocBook format
• technical writers and documentation toolchain maintainers
• occasionally desktop users who install software that ships DocBook-based documentation tooling

Upstream project

The upstream project is DocBook, available from the project home page and documentation site. DocBook describes itself as an XML vocabulary for technical documentation, and its schema documentation explains the available schema families and historical DTD-based releases. (docbook.org)

For package updates, NiceOS maintainers should check whether the upstream change affects:

• catalog or identifier layout
• DTD or schema filenames expected by dependent packages
• packaging guidance from upstream documentation
• any split between the canonical schema location and archived historical material

Dist-git repository contents

This dist-git repository contains the package sources and packaging metadata for NiceOS:

• SPECS/ — RPM spec files and related packaging logic
• SOURCES/ — source metadata and manifest files used to describe and verify upstream inputs
• METADATA/ — repository metadata used by the package 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 the metadata needed to identify and verify the expected sources.

Source storage and integrity policy

The package policy for this repository is that source integrity is tracked through manifest files in SOURCES/. The repository should not be treated as the place where large upstream archives live.

Before updating the package, NiceOS maintainers should confirm that:

• the SOURCES/ manifests still match the intended upstream inputs
• any referenced upstream material is still available from a stable canonical location
• no packaging change accidentally points to a moved, renamed, or obsolete DocBook resource

If a source change requires refreshed metadata or regenerated manifest content, regenerate only the packaging files that are meant to change and keep the rest of the repository stable.

NiceOS maintenance notes

Before accepting an update, check the following:

• whether upstream changed the DocBook schema or DTD layout in a way that affects consumers
• whether any installed catalog files, entity definitions, or XML identifiers need packaging adjustments
• whether downstream packages rely on old compatibility paths that should remain available
• whether SOURCES/ needs regeneration because the upstream inputs changed
• whether SBOM/ or other repository metadata should be refreshed if the packaging workflow requires it

Risks to consider:

• documentation builds can fail if a dependent package expects a different DocBook identifier or catalog path
• changes that look minor upstream may still affect validation, transformation, or packaging scripts
• removing old compatibility entries too early can break older consumers in the distribution

Build and verification checklist

For RPM maintainers, a practical update check should include:

• review the upstream change notes and confirm the update is actually needed
• verify that the intended upstream source is the one referenced by SOURCES/
• compare installed paths and catalog entries against what dependent packages expect
• rebuild the package locally
• run the package's standard RPM checks used in NiceOS, including spec validation and file-list review
• test at least one downstream consumer if available, especially a package that processes DocBook documentation
• confirm that the repository still reflects the expected packaging split between spec files, source metadata, and auxiliary metadata

References

• DocBook.org
• DocBook Schemas
• DocBook Documentation
• DocBook 4.5 specification

Russian documentation

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

Dist-git repository notes

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