Repository navigation
Restore the template's front and back matter - #169
Merged
Merged
Conversation
The PDF assembler was missing five structural elements the template's carries, and PR #165 deleted the contributors and copyright pages without replacing them. UPGRADING.md calls the assembler "the one file that is both" -- the file ownership rules say not to touch, where the structural requirements actually live. Assembler: * include ../docs-resources/global-config.adoc for the shared :company:, :url-riscv: and :doctype: attributes, replacing local copies. PDF-only: the cross-repo relative include cannot resolve under Antora, which is why it belongs here and never in a page. * :toc: left -> :toc: macro plus an explicit toc::[], so the TOC follows the front matter rather than floating to a sidebar. * List of figures / tables / listings prefaces. * [index] == Index ahead of the bibliography. PDF-only; Antora does not generate a back-of-book index. Pages: recreate contributors.adoc and copyright.adoc. Both are included by the assembler and listed in the nav, so each has a single source rather than the template's duplicated copyright text. Contributors are the real commit authors from git history, de-duplicated and alphabetised by surname -- the file PR #165 deleted still held the template's Author1/Author2 placeholders. Names only, no addresses; worth curating before a release. The license follows LICENSE (CC-BY 4.0). nav.adoc: both entries appended as back matter rather than placed up front as the template does, so the chapter line numbers do not shift -- the central playbook's numbering_rules keys chapters off line numbers in this file (MIGRATION.md Step 11). author-quickstart.adoc: callouts <4> and <5> claimed contributors and copyright were "HTML only -- not part of the PDF". That was already wrong about the template, whose assembler includes both, and this change makes it self-contradictory. Callout <2> is untouched: the landing page really is HTML-only. Verified: PDF renders TOC (p1-4), the three lists (p5-7), copyright (p8), contributors (p9) and Index (p73); Antora builds clean with both new pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>
Bill Traynor (wmat)
added a commit
that referenced
this pull request
Sep 11, 2026
Match the template's nav.adoc: the title page (index.adoc) is the
top-level entry, and copyright, contributors, the introduction and then
the chapters are nested under it, in that order. The PDF already opens
title page, copyright, contributors, Chapter 1.
The nav had no title-page entry at all, which MIGRATION.md Step 9 asks
for ("landing page first"), and carried copyright and contributors at the
end. They went there in #169 on the stated grounds that the central
playbook numbers this component's chapters by line number in this file.
That was never checked and is wrong: docs-dev-guide's content source is
commented out in both antora.riscv.org and antora-dev.riscv.org, and
neither has a numbering rule for docs-guide. The comment asserting it is
removed. In its place is the template's own header comment, which warns
about line-number coupling in general terms -- true once this guide is
registered centrally.
The `.Authoring and Editing RISC-V Specs` nav title goes too: the
title-page entry, labelled with the component title, takes its place, as
in the template.
antora-structure.adoc: the guide's example nav -- the one template users
copy -- listed spec-sample.adoc as the landing page (the template's is
index.adoc), put contributors after the chapters, and left out copyright.
It now matches the template's nav.adoc entry for entry.
Verified: Antora builds with the same single pre-existing warning and no
errors; the rendered sidebar reads RISC-V Authoring and Editing Guide >
Copyright and license information > Contributors > Introduction > ...,
nested under the title page.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Bill Traynor <wmat@riscv.org>
This was referenced Sep 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #168. That PR merged while this commit was still being written, so
it needs its own.
#168 aligned the tooling with
docs-spec-template. Comparing the resultfile-by-file against the template afterwards showed the tooling matched — 19 of 20
template-owned files byte-identical — but the document did not. Two gaps:
1. The PDF assembler was missing the template's structure
UPGRADING.mdcallssrc/<spec>.adoc"the one file that is both": ownership rulessay don't copy it, but the structural requirements live in it. Ours was missing
five elements the template's carries.
include::../docs-resources/global-config.adoc[]:company:,:url-riscv:,:doctype:— local copies removedtoc::[](:toc: left→:toc: macro)list-of::image/table/listing[index] == IndexBoth the
global-config.adocinclude and the[index]macro are PDF-only andlive in the assembler, never in a page — the cross-repo relative include cannot
resolve under Antora, and Antora generates no back-of-book index (MIGRATION.md
Step 7).
2.
contributors.adocandcopyright.adocwere deleted and never replacedPR #165 removed
src/contributors.adocandsrc/colophon.adoc. Both arerecreated as pages, included by the assembler (copyright p8, contributors p9) and
listed in the nav, so each has a single source — rather than the template's
arrangement, which duplicates the copyright text inline in the assembler.
The contributor list is real and needs curating. The deleted file still held
the template's
Author1 <required1@email.com>placeholders, so restoring itverbatim would have published fake names. These are the actual commit authors from
git shortlog, de-duplicated across aliases (wmat/Bill Traynor, threeelisavariants), bots dropped, alphabetised by surname. Names only, no addresses. Git
authorship is not the same as consent to be listed publicly, so please review
before a release.
The license text follows
LICENSE(CC-BY 4.0).Also fixed: the guide contradicted itself
author-quickstart.adoccallouts<4>and<5>stated that contributors andcopyright are "HTML only -- not part of the PDF". That was already wrong about
the template — whose assembler includes both — and this change would have made the
guide contradict its own build output. Corrected. Callout
<2>is deliberatelyuntouched: the landing page really is HTML-only.
Nav placement
Both entries are appended as back matter rather than placed up front where the
template puts them. The central playbook's
numbering_rulesfor this componentkeys chapters off line numbers in
nav.adoc(MIGRATION.md Step 11), soinserting at the top would silently shift every chapter's numbering on the central
site.
Verification
npm run preview→ exit 0;contributors.htmlandcopyright.htmlrendercommon::logo) →no matches
make build-container→ PDF and HTML build; all seven new sections confirmed inthe extracted PDF text, not just in source
Rebased onto
mainafter #168 merged; both builds re-run green on the new base.🤖 Generated with Claude Code