diff --git a/src/author-quickstart.adoc b/src/author-quickstart.adoc new file mode 100644 index 0000000..051e057 --- /dev/null +++ b/src/author-quickstart.adoc @@ -0,0 +1,209 @@ +[[author-quickstart]] +== Author Quickstart: Writing a Spec from the Template + +This guide is for a specification author who has just been given a repository an +administrator created from `docs-spec-template`. It covers where content goes, +why you never duplicate it, and the manual steps that keep the ARC submission +PDF and the Antora site in lockstep. + +The single most important idea: your chapter content lives **once**, in +`modules/ROOT/pages/`. Both the PDF and the site read those same files. What you +maintain by hand is a one-line _pointer_ to each chapter in two glue files -- the +site navigation (`modules/ROOT/nav.adoc`) and the book header file +(`src/.adoc`, the master document that assembles the PDF) -- not a +second copy of the content. + +=== Before you write: rename the template + +The admin created the repo, but the example "spec-sample" identity is still baked +in. Do this one-time rename pass first. + +[cols="1,2,3",options="header"] +|=== +| What | File | Change + +| Component name (site path) +| `antora.yml` -> `name:` +| `spec-sample` -> your short name (e.g. `zilch`) + +| Component title +| `antora.yml` -> `title:` +| Your spec's title + +| Book header file (PDF master document) +| `src/spec-sample.adoc` +| Rename the file; the Makefile derives the PDF name from its basename + +| Makefile source pointer +| `Makefile` -> `DOCS :=` +| Point at your renamed header file + +| Header file title / authors +| `src/spec-sample.adoc` (lines 1-2) +| Your title and author list + +| Bibliography database +| `modules/ROOT/resources/riscv-spec.bib` +| Your citations + +| README title +| `README.adoc` +| Your spec +|=== + +The released PDF filename (`-vX.Y.Z-YYYYMMDD.pdf`) is derived +automatically from the header file's basename via `SPEC_SHORT`, so renaming that +file is all that's needed. + +Also confirm the template mode in `.docmode`: + +* `spec` (default) -- a ratified RISC-V specification on the ARC / Policies & + Procedures process (milestone phases, "Document State" preface, ARC PDF). +* `doc` -- non-ratified documentation that still needs the PDF, Makefile HTML, + and Antora site, but none of the ratification layer. + +The admin normally sets this. If it is wrong, run `make set-mode MODE=doc` (or +`MODE=spec`) -- you do **not** need to recreate the repo. + +=== Where the content files go + +All chapter content goes in `modules/ROOT/pages/`, one file per chapter. Each +page is a standalone Antora page that starts with a **level-0 title** +(`= Chapter Title`) -- Antora requires exactly one per page. When the PDF is +built, `leveloffset=+1` demotes that level-0 title to a level-1 book chapter +(`== Chapter Title`), so it reads as a numbered chapter in the PDF even though +the page source is level-0. That file is the single source of truth for that +chapter. + +[source] +---- +modules/ROOT/pages/ + index.adoc <1> + intro.adoc <2> + chapter2.adoc + contributors.adoc <3> + bibliography.adoc <4> +modules/ROOT/resources/riscv-spec.bib <5> +src/spec-sample.adoc <6> +---- +<1> Site landing / cover page. Site-only -- **not** part of the PDF. Edit freely. +<2> A chapter. Becomes "Chapter 1" in the PDF. +<3> Front matter. +<4> Back matter. +<5> Bibliography database. +<6> Book header file -- glue, not content (see below). + +=== You do NOT duplicate the .adoc files + +This is the core design of the template. The content exists once; both outputs +read it. + +* The **Antora site** reads the pages in `modules/ROOT/pages/` directly. +* The **PDF** is assembled by the book header file (`src/spec-sample.adoc`), the + master document that pulls each page in with + `include::../modules/ROOT/pages/intro.adoc[leveloffset=+1]`. The + `leveloffset=+1` demotes the page's level-0 `= Title` to a level-1 chapter + heading, reproducing the historical PDF chapter numbering. + +So there is no copy to keep in sync. What you _do_ maintain is a one-line pointer +to each page in **two** glue files. Whenever you add, remove, or reorder a +chapter, edit both: + +. `modules/ROOT/nav.adoc` -- add an `xref:` line (site navigation and numbering). +. `src/spec-sample.adoc` (the book header file) -- add an + `include::...[leveloffset=+1]` line (PDF assembly order). + +[WARNING] +==== +Miss the `include::` and the chapter is on the site but missing from the PDF. +Miss the `xref:` and it's in the PDF but absent from the site navigation. Update +both together. +==== + +==== Keep PDF-only constructs out of pages + +Pages must stay portable AsciiDoc so Antora can render them. PDF-only constructs +live only in the book header file (`src/spec-sample.adoc`), never in a page: + +* `include::../docs-resources/global-config.adoc[]` -- a cross-repo relative + include that breaks under Antora. +* the back-of-book `[index] == Index` macro (Antora generates no index). +* `:title-logo-image:`, `:pdf-theme:`, `:pdf-fontsdir:`, `:doctype: book`, and + similar PDF attributes. + +=== What is manual + +==== One-time site registration + +Your spec must be added as a `content.sources:` entry in the central playbook +(the dev mirror first). Antora fetches from GitHub, so **push your branch before +expecting the spec to appear** on the site. See "Registering this spec" in +`ANTORA.md`. + +==== At release time (the version bridge) + +The site version must match the PDF version exactly -- the `vX.Y.Z` release tag, +an ARC requirement. Antora reads a _static_ `version:` from `antora.yml`, so it +must be **stamped** to match. + +CI does this for you: the release build stamps `antora.yml` and opens a PR +against `main`. **The one manual step is merging that PR** -- it is part of +cutting the release. Never hand-edit the `version:` or `page-*` keys in +`antora.yml` yourself; they are stamped from the same source the PDF uses. + +If you ever need to stamp by hand (fallback only): + +[source,shell] +---- +make stamp-antora VERSION=vX.Y.Z # then commit antora.yml +---- + +==== Content you edit as ordinary files + +No dual-source concern -- just edit these directly: + +* `modules/ROOT/pages/index.adoc` -- the site cover / landing page. Replace the + placeholder paragraph (it begins "Replace this text with a short abstract...") + with your spec's abstract and links into your chapters. Leave the stamped + revision line (`Version {page-revnumber}, {page-revdate}...`) and the phase + banner (the `{page-phase-*}` attributes) alone -- those come from `antora.yml`. +* `MAINTAINERS.md` and `CONTRIBUTING.md` (project metadata), the contributors + page (`modules/ROOT/pages/contributors.adoc`), and the bibliography database + (`modules/ROOT/resources/riscv-spec.bib` -- the BibTeX file your citations + live in, not `bibliography.adoc`, which just renders it). + +==== Versioning -- don't do these by hand + +* **Version bumps.** Pushing `src/**` changes to `main` triggers the version bot, + which creates the next patch tag, builds the PDF, and publishes a GitHub + Release. Milestone phases (`Developed` / `Stable` / `Frozen` / + `Ratification-Ready` / `Ratified`) are derived from the version. + +=== Local build and preview loop + +[source,shell] +---- +make # ARC PDF (+ HTML) into build/ (Docker-based) + +npm install # once: Antora + kroki/mathjax preview extensions +docker compose up -d kroki # local diagram server on :9870 +npm run preview # builds the site into build/site/ +docker compose down # stop Kroki when done +---- + +Two expected local-preview gaps -- neither is a build error: + +* **Citations and `bibliography::[]` render as raw text** locally. The ASAM + bibliography extension exists only in the central playbook. Check citations in + the `make` PDF or on the dev site. +* **The cover logo** (`common::risc-v_logo.svg`) logs one unresolved-image + warning locally, because the shared `common` component only exists on the + central build. + +=== See also + +* `ANTORA.md` -- how the dual build works and why, plus the section-numbering + rule and site-registration details. +* `MIGRATION.md` -- checklist for bringing an existing repo in line with this + toolchain. +* `ARC_SUBMISSION.md` -- ARC submission conventions (spec mode). diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index 3e5238e..d2af237 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -72,6 +72,8 @@ include::colophon.adoc[] //While some documents need several levels of introductory material, other documents need only a brief introduction. You can choose to have either colophon or an overview, or to have both. include::intro.adoc[] +include::author-quickstart.adoc[] + include::authoring.adoc[] include::a_few_basics.adoc[]