|
| 1 | +# Texinfo Authoring — Canonical Prose Format |
| 2 | + |
| 3 | +Reference for authoring Spacecraft Software prose documents in **Texinfo** — the canonical format for manuals, references, guides, reports, specs, and books (SKILL.md §1, Standard §8). Load this for any prose deliverable unless the user explicitly asked for a word-processor file. |
| 4 | + |
| 5 | +**Why Texinfo is canonical:** one `.texi` source compiles to plain text/Info, HTML, and PDF — and converts to GFM Markdown — from a single file. Structure and brand are defined once; every output stays in sync. No other format gives a diffable, plain-text source that fans out to all the distribution formats at once. |
| 6 | + |
| 7 | +Docs: GNU Texinfo manual (<https://www.gnu.org/software/texinfo/manual/texinfo/>). Texinfo 7.x+ is assumed. |
| 8 | + |
| 9 | +## §A — When a Texinfo manual is the deliverable |
| 10 | + |
| 11 | +Mirrors Standard §8.1: |
| 12 | + |
| 13 | +| Project type | Requirement | |
| 14 | +|---|---| |
| 15 | +| CLI / TUI / GUI app with substantive user-facing functionality | **MUST** ship a Texinfo manual (invocation, options, concepts, examples) | |
| 16 | +| Library with a public API | **SHOULD** ship a Texinfo reference manual covering all public interfaces | |
| 17 | +| Simple script / internal tooling | **MAY** skip — a well-structured `README.md` suffices | |
| 18 | + |
| 19 | +For software projects, the manual lives at `doc/<project>.texi` (Standard §8.2). For standalone document deliverables (a report, a book), put the `.texi` wherever the deliverable is organized; the build targets and brand rules below still apply. |
| 20 | + |
| 21 | +## §B — Minimal `.texi` skeleton (required structural elements) |
| 22 | + |
| 23 | +Every manual includes the Standard §8.3 elements: `@dircategory`/`@direntry`, `@copying`, `@titlepage`, `@node Top` + `@top`, and a `@menu` per chapter. |
| 24 | + |
| 25 | +```texinfo |
| 26 | +\input texinfo |
| 27 | +@c %**start of header |
| 28 | +@setfilename project.info |
| 29 | +@documentencoding UTF-8 |
| 30 | +@settitle Project Manual 1.0 |
| 31 | +@c %**end of header |
| 32 | +
|
| 33 | +@c SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org> |
| 34 | +@c SPDX-License-Identifier: CC-BY-SA-4.0 |
| 35 | +
|
| 36 | +@dircategory Spacecraft Software |
| 37 | +@direntry |
| 38 | +* Project: (project). One-line description for the Info directory. |
| 39 | +@end direntry |
| 40 | +
|
| 41 | +@copying |
| 42 | +This manual is for Project version 1.0. |
| 43 | +
|
| 44 | +Copyright @copyright{} 2026 Mohamed Hammad & Spacecraft Software. |
| 45 | +
|
| 46 | +@quotation |
| 47 | +Released under CC-BY-SA-4.0. (Use GFDL-1.3-or-later instead when distributing |
| 48 | +alongside GPL software for GNU-collection compatibility — Standard §8.5.) |
| 49 | +@end quotation |
| 50 | +@end copying |
| 51 | +
|
| 52 | +@titlepage |
| 53 | +@title Project Manual |
| 54 | +@subtitle Version 1.0 |
| 55 | +@author Mohamed Hammad |
| 56 | +@page |
| 57 | +@vskip 0pt plus 1filll |
| 58 | +@insertcopying |
| 59 | +@end titlepage |
| 60 | +
|
| 61 | +@contents |
| 62 | +
|
| 63 | +@node Top |
| 64 | +@top Project |
| 65 | +
|
| 66 | +@insertcopying |
| 67 | +
|
| 68 | +@menu |
| 69 | +* Introduction:: What Project does. |
| 70 | +* Invocation:: Command-line usage. |
| 71 | +* Index:: |
| 72 | +@end menu |
| 73 | +
|
| 74 | +@node Introduction |
| 75 | +@chapter Introduction |
| 76 | +Project is@dots{} |
| 77 | +
|
| 78 | +@node Invocation |
| 79 | +@chapter Invocation |
| 80 | +@cindex invoking |
| 81 | +Each documented program needs an @code{Invoking @var{program}} node. |
| 82 | +
|
| 83 | +@node Index |
| 84 | +@unnumbered Index |
| 85 | +@printindex cp |
| 86 | +
|
| 87 | +@bye |
| 88 | +``` |
| 89 | + |
| 90 | +Conventions worth keeping: structure by the user's concepts (one coherent topic per node), document every option with examples, provide an Index (`@cindex`/`@printindex`), use active voice and present tense. (These are the GNU documentation conventions; `gnu-coding-standards` covers them in depth for GNU-targeted work.) |
| 91 | + |
| 92 | +## §C — Build toolchain & targets |
| 93 | + |
| 94 | +Standard §8.2 requires three `Makefile` targets; §8.4 fixes the output set. |
| 95 | + |
| 96 | +| Output | Tool | Command | |
| 97 | +|--------|------|---------| |
| 98 | +| `.info` (+ plain text) | `makeinfo` / `texi2any` | `makeinfo project.texi` · plain text: `makeinfo --plaintext project.texi` | |
| 99 | +| `.html` | `makeinfo --html` | `makeinfo --html --css-include=steelbore.css project.texi` | |
| 100 | +| `.pdf` | `texi2pdf` (or HTML→PDF, §D) | `texi2pdf project.texi` | |
| 101 | + |
| 102 | +Minimal `Makefile`: |
| 103 | + |
| 104 | +```make |
| 105 | +project.info: project.texi ; makeinfo $< |
| 106 | +html: project.texi ; makeinfo --html --css-include=steelbore.css $< |
| 107 | +pdf: project.texi ; texi2pdf $< |
| 108 | +info: project.info |
| 109 | +.PHONY: html pdf info |
| 110 | +``` |
| 111 | + |
| 112 | +Build `.info`, `.html`, and `.pdf` and ship all three (Standard §8.4). Register `.info` at install time with `install-info` (§G). |
| 113 | + |
| 114 | +## §D — Brand application (palette §11 + typography §12) |
| 115 | + |
| 116 | +Texinfo's outputs theme differently; cover each: |
| 117 | + |
| 118 | +### HTML (full brand — the primary branded output) |
| 119 | + |
| 120 | +Pass a bundled CSS with `--css-include=steelbore.css`. Void Navy background, Molten Amber body, Share Tech Mono headings, Inconsolata body, palette-mapped headings and links (SKILL.md §7): |
| 121 | + |
| 122 | +```css |
| 123 | +/* steelbore.css — Standard §11 palette + §12 typography */ |
| 124 | +@import url('https://fonts.googleapis.com/css2?family=Share+Tech+Mono&family=Inconsolata&display=swap'); |
| 125 | +body { background: #000027; color: #D98E32; |
| 126 | + font-family: 'Inconsolata', monospace; } |
| 127 | +h1, h2, h3, h4 { font-family: 'Share Tech Mono', monospace; } |
| 128 | +h1, .chapter { color: #4B7EB0; } /* Steel Blue */ |
| 129 | +h2, .section { color: #50FA7B; } /* Radium Green */ |
| 130 | +h3, .subsection { color: #8BE9FD; } /* Liquid Coolant */ |
| 131 | +a:link { color: #8BE9FD; } /* unvisited */ |
| 132 | +a:visited { color: #4B7EB0; } /* visited */ |
| 133 | +code, pre, samp { font-family: 'Inconsolata', monospace; } |
| 134 | +``` |
| 135 | + |
| 136 | +Verify Void Navy is visible in a browser and both font families load. |
| 137 | + |
| 138 | +### PDF |
| 139 | + |
| 140 | +`texi2pdf` (stock Texinfo/TeX) produces a structurally correct PDF but does **not** support a page background colour through the standard path — accept the default page and rely on HTML for the fully-branded rendering, **or** take the brand-faithful route: |
| 141 | + |
| 142 | +- **HTML → PDF (brand-faithful):** render the branded HTML to PDF so the Void Navy CSS carries through — `weasyprint project.html project.pdf`, or a headless browser (`chromium --headless --print-to-pdf`). This keeps the §11 palette and §12 fonts in the PDF. |
| 143 | + |
| 144 | +Pick `texi2pdf` when structure/printability is what matters; pick HTML→PDF when the PDF must carry the full brand. Either way, A4 portrait geometry (SKILL.md §3). |
| 145 | + |
| 146 | +### Info / plain text |
| 147 | + |
| 148 | +`.info` and `--plaintext` output carry no embedded colour — they render in the reader/terminal, which already follows the palette on Steelbore OS (and via `spacecraft-theme-factory` themes elsewhere). No action needed beyond clean structure. |
| 149 | + |
| 150 | +## §E — Markdown & plain-text conversion |
| 151 | + |
| 152 | +A `.texi` is already plain text, so it needs **no** mandatory GFM companion (SKILL.md §2). Produce Markdown only when a consumer wants it: |
| 153 | + |
| 154 | +```sh |
| 155 | +pandoc -f texinfo -t gfm project.texi -o project.md # GFM rendering |
| 156 | +makeinfo --plaintext project.texi -o project.txt # plain-text rendering |
| 157 | +``` |
| 158 | + |
| 159 | +When you do emit a `.md` from a `.texi`, it follows the GFM house style in `markdown-companion.md` (ATX headings, GFM tables, no raw HTML beyond the metadata comment). |
| 160 | + |
| 161 | +## §F — Licensing |
| 162 | + |
| 163 | +Texinfo manuals are **document-class** (Standard §4.1.1): |
| 164 | + |
| 165 | +- **Default `CC-BY-SA-4.0`.** Use `CC-BY-4.0` only when maximal reuse is intended. |
| 166 | +- **`GFDL-1.3-or-later` is the permitted alternative** when the manual ships alongside GPL-licensed software and GNU-documentation-collection compatibility is wanted (Standard §8.5). |
| 167 | +- Declare the licence in the `@copying` block (§B) **and** as an inline two-tag SPDX header in the `.texi` (`@c SPDX-FileCopyrightText:` / `@c SPDX-License-Identifier:`). |
| 168 | +- Ship the licence text in `LICENSES/<id>.txt`; `reuse lint` must pass (Standard §4.3). |
| 169 | + |
| 170 | +## §G — Packaging integration (Standard §8.6) |
| 171 | + |
| 172 | +Package manifests install the `.info` and register it with `install-info`: |
| 173 | + |
| 174 | +| Package manager | Requirements | |
| 175 | +|---|---| |
| 176 | +| **Guix** (`packaging/guix.scm`) | add `texinfo` as a native input; run `install-info` in the install phase | |
| 177 | +| **Nix** (`packaging/default.nix`) | add `texinfo` to `nativeBuildInputs`; the standard Autoconf/Make `installPhase` runs `install-info` automatically | |
| 178 | +| **PKGBUILD** (`packaging/PKGBUILD`) | add `texinfo` to `makedepends`; `install -Dm644` the `.info`; call `install-info` in `post_install` | |
| 179 | + |
| 180 | +## §H — Acceptance checklist (Texinfo) |
| 181 | + |
| 182 | +In addition to SKILL.md §8 (general acceptance): |
| 183 | + |
| 184 | +- [ ] `.texi` carries the §8.3 structural elements (`@dircategory`/`@direntry`, `@copying`, `@titlepage`, `@node Top`/`@top`, per-chapter `@menu`). |
| 185 | +- [ ] Inline SPDX two-tag header present in the `.texi`; licence stated in `@copying`. |
| 186 | +- [ ] `make info`, `make html`, `make pdf` all succeed; `.info`/`.html`/`.pdf` produced. |
| 187 | +- [ ] HTML: Void Navy background visible, Share Tech Mono headings + Inconsolata body loaded via the bundled CSS. |
| 188 | +- [ ] PDF: A4 portrait; brand carried (HTML→PDF route) or structure-only (`texi2pdf`) as chosen. |
| 189 | +- [ ] `install-info` hook present in all three package manifests (Standard §5.5 / §8.6). |
| 190 | +- [ ] Licence text in `LICENSES/`; `reuse lint` clean. |
0 commit comments