66 lines
3.9 KiB
Markdown
66 lines
3.9 KiB
Markdown
# Chapter 6 — Help, man, and the documentation map
|
||
|
||
**Prerequisites:** [Home, identity, and vault](05-home-identity-and-vault.md). **Time to read:** about five minutes.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [`man` inside the image](#man-inside-the-image)
|
||
- [`help` and discoverability](#help-and-discoverability)
|
||
- [Four documentation trees](#four-documentation-trees)
|
||
- [Where JSON and schemas live](#where-json-and-schemas-live)
|
||
- [Regenerating `man.json`](#regenerating-manjson)
|
||
- [Searching topics (`man -k`)](#searching-topics-man--k)
|
||
|
||
---
|
||
|
||
## `man` inside the image
|
||
|
||
The stock image ships **`man(1)`** backed by a **merged JSON database** built from coreutils pages and handbook-derived material. After **`npm run build -w bare-os-coreutils`** and a fresh seed, you can run **`man ls`**, **`man sh`**, and many other topics the same way you would on a traditional Unix-like system, with the understanding that coverage follows what Bare OS packages—not every host **`man`** page exists here.
|
||
|
||
For how pages are ingested and how **`help`** differs from **`man`**, read [Handbook — Chapter 10: Manual pages and online help](../handbook/10-manpages-and-online-help.md).
|
||
|
||
**Handbook as a man page:** the merged database includes long-form narrative topics. Try **`man handbook`** (section **7**) for the full handbook text inside the guest when your image build includes it.
|
||
|
||
---
|
||
|
||
## `help` and discoverability
|
||
|
||
Some commands expose a **`help`** subcommand or usage text aimed at **interactive** discovery. Use **`help`** when you want a short reminder; use **`man`** when you want structured sections and cross-references that match the JSON database.
|
||
|
||
---
|
||
|
||
## Four documentation trees
|
||
|
||
These four areas are intentional; each serves a different job:
|
||
|
||
1. **User manual** ([users-manual/README.md](README.md)) — run and use Bare OS without reading the whole architecture first.
|
||
2. **Handbook** ([handbook/README.md](../handbook/README.md)) — narrative explanation of design, protocol, runtime, identity, POSIX surface, operations, and research context.
|
||
3. **Developer guide** ([developer-guide/README.md](../developer-guide/README.md)) — practical instructions for scripts, **`ctx`**, kernel **`start(ctx)`**, coreutils development, testing, Pear integration, telemetry scrubbing.
|
||
4. **Reference** ([docs/reference/README.md](../docs/reference/README.md)) — inventory of packages and files, environment variable appendix, architecture data-flow notes, compatibility matrix, capability index.
|
||
|
||
If you are lost, start at the [documentation hub](../docs/README.md) on the **`docs/`** tree, which links outward to the handbook and developer guide.
|
||
|
||
---
|
||
|
||
## Where JSON and schemas live
|
||
|
||
Telemetry, boot policy, and related artifacts are documented next to **JSON Schemas** under **`docs/schemas/`**. You usually touch these when integrating observability or strict boot checks, not for everyday shell use. Pointers appear in the root [README](../README.md) and in [Kernel extensions](../docs/reference/kernel-extensions.md).
|
||
|
||
---
|
||
|
||
## Regenerating `man.json`
|
||
|
||
The on-disk manual lives at **`kernel/share/man/man.json`** after **`npm run build -w bare-os-coreutils`**. If **`man <topic>`** is missing or stale, rebuild coreutils on the **host**, re-run the **seeder** so the system drive picks up the new JSON, then boot again. CI’s **`verify-man-coverage`** ensures every **`/bin`** command has a matching page—local edits to **`packages/bare-os-coreutils`** should keep that invariant.
|
||
|
||
---
|
||
|
||
## Searching topics (`man -k`)
|
||
|
||
**`man -k <word>`** (same as **`--apropos`**) searches keywords compiled into **`man.json`**. It is the fastest way to discover which utilities document a feature (for example **`man -k color`**). Results depend on the keyword index produced during the coreutils build; if nothing matches, fall back to **`ls /bin`** and **`man <cmd>`** directly.
|
||
|
||
---
|
||
|
||
_Previous: [Chapter 5](05-home-identity-and-vault.md)_ · _Next: [Chapter 7 — Troubleshooting and operations](07-troubleshooting-and-operations.md)_
|