Conversation
Hand-written end-to-end manual covering installation, daily use, configuration, metadata, schema validation, schema lifecycle, type detection, troubleshooting, and a command reference appendix. Tooling: pandoc + xelatex (both already installed; nothing exotic). Fonts pulled from system: Noto Serif body, Noto Sans headings, DejaVu Sans Mono for code — all common Linux distribution defaults, all selected for screen readability and clean copy-paste. 23 pages A4, scrbook class for proper book typography (running headers, numbered sections, page numbers, generous margins). Tango syntax highlighting on code blocks with subtle background tint. Files: - docs/manual.md — markdown source, single file with YAML metadata - docs/manual.pdf — committed artifact so readers don't need pandoc - docs/build_manual.sh — single-command rebuild - README link added Closes #59.
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.
Summary
Adds `docs/manual.pdf` — a hand-written end-to-end manual in book form. Markdown source, build script, and the rendered artifact are all under `docs/`. README links to the PDF.
Tooling Choice
`pandoc --pdf-engine=xelatex`. Both binaries were already on the system; no extra toolchain. All layout settings (fonts, classoptions, geometry, color) live in the YAML metadata block at the top of `manual.md` — no separate template file. Build is one command:
```bash
bash docs/build_manual.sh
```
Typography
All three are common defaults on Linux distributions and ship with most Noto/DejaVu packages. Picked for screen readability (Noto Serif has good x-height, clean curves) and clean copy-paste behaviour from monospace blocks (DejaVu's character distinctions are unambiguous: `Il1`, `O0`, `{[`).
`scrbook` class with running headers, numbered sections, and page numbers gives the document a real book feel. Tango syntax highlighting on code blocks with a subtle gray background separates them from prose without being noisy.
Content
23 A4 pages, eleven chapters:
Hand-written prose, not a flat `--help` dump. Each chapter shows commands in context with realistic examples. AI-detection security is a one-paragraph summary that points to `docs/SECURITY.md` for the full architecture — no duplication.
Why a PDF and Not Just More Markdown
The README is the surface — "what is this and how do I get the first secret read in two minutes". The manual is the book — "sit down for 30 minutes and learn vaultctl properly". Different reading modes, different artifacts. A monospace-friendly PDF reads better on a quiet evening than a long markdown scroll, and the typesetting (line breaks in long commands, hyphenation, generous margins) actually helps comprehension.
Maintenance
Source is plain markdown — edits go in `docs/manual.md`. Re-running `bash docs/build_manual.sh` regenerates the PDF. The committed PDF is intentional: readers shouldn't need pandoc + xelatex installed to read the manual.
Closes #59.