From 192f342769f6671629c8b22e35c864ec03609738 Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Wed, 9 Sep 2026 17:35:48 -0400 Subject: [PATCH] Restore the template's front and back matter 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 Signed-off-by: Bill Traynor --- modules/ROOT/nav.adoc | 6 ++++ modules/ROOT/pages/author-quickstart.adoc | 4 +-- modules/ROOT/pages/contributors.adoc | 16 +++++++++ modules/ROOT/pages/copyright.adoc | 9 +++++ src/docs-dev-guide.adoc | 40 ++++++++++++++++++++--- 5 files changed, 69 insertions(+), 6 deletions(-) create mode 100644 modules/ROOT/pages/contributors.adoc create mode 100644 modules/ROOT/pages/copyright.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 5f620f9..87aea65 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -14,3 +14,9 @@ * xref:linting.adoc[Linting] * xref:build-infrastructure.adoc[Build Infrastructure] * xref:bibliography.adoc[Bibliography] +// Back matter. Appended rather than placed up front (where the template puts +// them) so the chapter line numbers above do not shift: the central playbook's +// numbering_rules entry for this component keys chapters off LINE NUMBERS in +// this file. See MIGRATION.md Step 11. +* xref:contributors.adoc[Contributors] +* xref:copyright.adoc[Copyright and license information] diff --git a/modules/ROOT/pages/author-quickstart.adoc b/modules/ROOT/pages/author-quickstart.adoc index ca3175d..352eb31 100644 --- a/modules/ROOT/pages/author-quickstart.adoc +++ b/modules/ROOT/pages/author-quickstart.adoc @@ -105,8 +105,8 @@ src/spec-sample.adoc <9> <1> Images used in the spec. These are referenced from the chapter files and included in both PDF and HTML output. <2> Site landing / cover page. HTML-only -- **not** part of the PDF. Follow the instructions in this file to update the content. <3> The introduction chapter. Becomes "Chapter 1" in the PDF. -<4> Front matter that lists contributors. HTML only -- **not** part of the PDF. Follow the instructions in this file to update the content. -<5> Copyright and license information. HTML only -- **not** part of the PDF. Follow the instructions in this file to update the content. +<4> Front matter that lists contributors. Included in both PDF and HTML: the site navigation renders it as a page, and the PDF assembler includes it as a `[preface]` ahead of the first chapter. Follow the instructions in this file to update the content. +<5> Copyright and license information. Included in both PDF and HTML, the same way as the contributors file. Follow the instructions in this file to update the content. <6> Bibliography main page. Included in both PDF and HTML and uses the bibliography database (`riscv-spec.bib`) to render the references. <7> Bibliography database. <8> HTML navigation file -- Update references to your chapter files here. This is the site navigation that builds the HTML output. diff --git a/modules/ROOT/pages/contributors.adoc b/modules/ROOT/pages/contributors.adoc new file mode 100644 index 0000000..6f1040b --- /dev/null +++ b/modules/ROOT/pages/contributors.adoc @@ -0,0 +1,16 @@ +== Contributors + +This guide has been contributed to directly or indirectly by: + +[%hardbreaks] +* Kevin Broch +* Stephano Cetola +* Paul A. Clarke +* Brian Grayson +* Jeff Osier-Mixon +* Kersten Richter +* Elisa Sawyer +* Jeff Scheel +* Josh Scheid +* Rafael Sene +* Bill Traynor diff --git a/modules/ROOT/pages/copyright.adoc b/modules/ROOT/pages/copyright.adoc new file mode 100644 index 0000000..4f30a57 --- /dev/null +++ b/modules/ROOT/pages/copyright.adoc @@ -0,0 +1,9 @@ +[preface] +== Copyright and license information + +This documentation is licensed under the Creative Commons +Attribution 4.0 International License (CC-BY 4.0). The full +license text is available at +https://creativecommons.org/licenses/by/4.0/. + +Copyright 2026 by RISC-V International. diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index 1f5bcad..ab8cec1 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -9,11 +9,13 @@ ifndef::revnumber[:revnumber: v0.0] ifndef::revdate[:revdate: 1970-01-01] ifndef::spec_short[:spec_short: docs-dev-guide] :revinfo: +// Shared RISC-V attributes (:company:, :url-riscv:, :doctype: book) from the +// docs-resources submodule, so this document picks up changes to them centrally. +// PDF-ONLY: this cross-repo relative include cannot resolve under Antora, which +// is why it lives in the assembler and never in a page. See MIGRATION.md Step 7. +include::../docs-resources/global-config.adoc[] //:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] :description: A working template for documenting RISC-V architecture in asciidoc -:company: RISC-V.org -:url-riscv: http://riscv.org -:doctype: book //:preface-title: Preamble //:colophon: //:appendix-caption: Appendix @@ -34,7 +36,10 @@ ifndef::spec_short[:spec_short: docs-dev-guide] :lang: en :listing-caption: Listing :sectnums: -:toc: left +// `macro` rather than `left` so the toc::[] call below controls placement -- the +// TOC follows the front matter, as in the template's assembler. +:toc: macro +:toc-title: Table of Contents :toclevels: 4 :source-highlighter: pygments ifdef::backend-pdf[] @@ -57,6 +62,27 @@ endif::[] //This document is released under a Creative Commons Attribution 4.0 International License. +// This repo runs in doc mode, so there is no "Document State" preface to render +// ahead of the TOC -- see MIGRATION.md "Doc mode". +toc::[] + +[preface] +== List of figures +list-of::image[hide_empty_section=true, enhanced_rendering=true] + +[preface] +== List of tables +list-of::table[hide_empty_section=true, enhanced_rendering=true] + +[preface] +== List of listings +list-of::listing[hide_empty_section=true, enhanced_rendering=true] + +include::../modules/ROOT/pages/copyright.adoc[] + +[preface] +include::../modules/ROOT/pages/contributors.adoc[] + include::../modules/ROOT/pages/intro.adoc[] include::../modules/ROOT/pages/author-quickstart.adoc[] @@ -83,4 +109,10 @@ include::../modules/ROOT/pages/linting.adoc[] include::../modules/ROOT/pages/build-infrastructure.adoc[] +// The index must precede the bibliography. The index macro is PDF-only (Antora +// does not generate a back-of-book index), so it lives here in the assembler +// rather than in a page. +[index] +== Index + include::../modules/ROOT/pages/bibliography.adoc[]