asciidoc

Overview

AsciiDoc is a plain-text markup language for technical writing. In practice, it is used for documentation that needs to stay readable in source form while still being publishable to formats such as HTML, PDF, and DocBook. The upstream project describes it as suitable for READMEs, books, manuals, articles, and similar technical content. (asciidoc.org)

For NiceOS, this package provides the toolchain and packaging needed to build and process AsciiDoc content inside the distribution. That makes it relevant to maintainers who ship documentation, package notes, or manual pages written in AsciiDoc.

Purpose and typical use cases

Typical use cases include:

• writing project documentation in a plain-text format that works well with version control;
• generating user guides, package notes, and manuals from the same source text;
• maintaining documentation that may be converted to multiple output formats;
• editing technical text with simple structure, links, tables, and reusable content blocks.

Typical users include:

• package maintainers and distribution engineers who need to rebuild documentation artifacts;
• developers who store technical documentation with source code;
• documentation writers who prefer a text-based authoring format;
• CI/CD maintainers who validate documentation builds as part of packaging or release pipelines.

Upstream project

The upstream project is the AsciiDoc language and its reference documentation at the canonical project site. The official documentation explains the language, syntax, and common authoring patterns. (asciidoc.org)

If NiceOS maintainers need to rely on any specific upstream behavior, they should verify it against the current upstream documentation before updating the package. This is especially important when packaging processors or extensions that may change behavior between releases.

Dist-git repository contents

This dist-git repository is organized as follows:

• SPECS/ — RPM spec files and related packaging logic;
• SOURCES/ — source control metadata and manifests used by the package workflow;
• METADATA/ — repository metadata used by the dist-git tooling;
• SBOM/ — software bill of materials material, when present for this package.

The repository layout is intentionally split so that packaging metadata stays in Git while large upstream source archives are not stored here.

Source storage and integrity policy

Large upstream source archives are intentionally not stored in this Git repository. Instead, source integrity is tracked through manifest files in SOURCES/.

For maintainers, this means the important review point is not just the spec file but also the source manifest state. Before accepting an update, check that the SOURCES/ manifests match the intended upstream content and that any packaging metadata was refreshed through the normal NiceOS workflow.

NiceOS maintenance notes

Before updating this package, NiceOS maintainers should check:

• whether the upstream documentation still describes the package purpose and build workflow in the same way;
• whether the spec file needs changes for build steps, file lists, or dependency handling;
• whether any source-manifest entries in SOURCES/ need regeneration or replacement;
• whether SBOM/ or other generated metadata should be updated by the packaging workflow;
• whether the upstream release introduces behavioral changes that could affect documentation rendering, build output, or downstream automation.

Practical risks to consider:

• documentation processors can change syntax handling or output formatting;
• generated output may differ even when the same source still builds successfully;
• packaging rules may need adjustment if upstream reorganizes its source tree or build process.

If any of these points are unclear, NiceOS maintainers should verify them before relying on the update.

Build and verification checklist

For RPM maintenance, a useful review checklist is:

• confirm the spec file still matches the current packaging intent;
• confirm the source manifests in SOURCES/ were updated through the expected workflow;
• rebuild the package in a clean environment;
• verify that the package installs the expected files and no unexpected files are pulled in;
• check that generated documentation or helper files, if any, are produced correctly;
• run the package’s standard checks, if the spec defines them;
• compare build logs for new warnings or changes in upstream behavior;
• review SBOM/ and other metadata if the packaging process updates them.

If the package is used to build documentation for other packages, also verify one representative downstream consumer after the update.

References

• AsciiDoc project home
• AsciiDoc Language Documentation
• AsciiDoc Syntax Quick Reference
• Cross References

Russian documentation

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

Dist-git repository notes

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