[FEATURE] Add indexed Exsh and builtin manual pages #26

Closed
opened 2026-10-24 01:16:29 +02:00 by erikinkinen · 2 comments
Owner

Problem and motivation

Internal help documents the shell's authoritative topics, but offline man cannot
yet resolve Exsh or its builtins. Pages should follow the implemented behavior
and stay in sync with that same registry.

Proposed behavior and scope

Add original exsh(1) documentation and a useful indexed page for each of the 33
current registry topics in section 1exsh. Literal builtin names remain the index
names, including punctuation. For example, man -s 1exsh true selects the builtin;
man -s 1 true selects the external Coreutils command.

Maintain an explicit component manifest. Bind page coverage and descriptive
fields to the authoritative registry with a closed, nonexecuting freshness check.
Compose explicitly selected component manifests into the same existing store,
rejecting duplicate(name,section) identities across components. Keep source
selection explicit and migrate maintained consumers before removing the old
individual-page packaging interface.

Authority, security and reliability

The reader keeps its existing exact read-only store lease. Packaging must not
search environment paths, enumerate directories for missing manuals or execute
page text. Open each selected component's descendants without following aliases,
encode retained validated snapshots and preserve original read/cleanup failures.
A source hash checks consistency with the selected component; it grants no access
and does not authenticate a publisher.

Acceptance criteria

  • Document stable exsh(1) and literal builtin(section 1exsh) names.
  • Write useful original syntax, behavior, examples, status and authority text for every current topic.
  • Require exact registry coverage and freshness through a maintained explicit manifest/checker.
  • Compose selected component manifests with duplicate/scope/malformed-input controls.
  • Adopt the manifests in image packaging and remove superseded individual-page consumers.

Alternatives and tradeoffs

Namespacing the builtin section preserves literal names without merging shell and
external-command behavior. Linking every topic to one generic page would make
lookup easy but provide weaker command-specific documentation.

Tracking and rollout

Extends shell help and
Coreutils manuals.
Coordinate Exsh PR3,
Coreutils PR2 and
Integration PR12.

## Problem and motivation Internal help documents the shell's authoritative topics, but offline man cannot yet resolve Exsh or its builtins. Pages should follow the implemented behavior and stay in sync with that same registry. ## Proposed behavior and scope Add original exsh(1) documentation and a useful indexed page for each of the 33 current registry topics in section `1exsh`. Literal builtin names remain the index names, including punctuation. For example, man -s 1exsh true selects the builtin; man -s 1 true selects the external Coreutils command. Maintain an explicit component manifest. Bind page coverage and descriptive fields to the authoritative registry with a closed, nonexecuting freshness check. Compose explicitly selected component manifests into the same existing store, rejecting duplicate(name,section) identities across components. Keep source selection explicit and migrate maintained consumers before removing the old individual-page packaging interface. ## Authority, security and reliability The reader keeps its existing exact read-only store lease. Packaging must not search environment paths, enumerate directories for missing manuals or execute page text. Open each selected component's descendants without following aliases, encode retained validated snapshots and preserve original read/cleanup failures. A source hash checks consistency with the selected component; it grants no access and does not authenticate a publisher. ## Acceptance criteria - [x] Document stable exsh(1) and literal builtin(section `1exsh`) names. - [x] Write useful original syntax, behavior, examples, status and authority text for every current topic. - [x] Require exact registry coverage and freshness through a maintained explicit manifest/checker. - [x] Compose selected component manifests with duplicate/scope/malformed-input controls. - [x] Adopt the manifests in image packaging and remove superseded individual-page consumers. ## Alternatives and tradeoffs Namespacing the builtin section preserves literal names without merging shell and external-command behavior. Linking every topic to one generic page would make lookup easy but provide weaker command-specific documentation. ## Tracking and rollout Extends [shell help](https://git.erikinkinen.fi/erix/exsh/issues/1) and [Coreutils manuals](https://git.erikinkinen.fi/erix/coreutils/issues/5). Coordinate [Exsh PR3](https://git.erikinkinen.fi/erix/exsh/pulls/3), [Coreutils PR2](https://git.erikinkinen.fi/erix/coreutils/pulls/2) and [Integration PR12](https://git.erikinkinen.fi/erix/integration/pulls/12).
Author
Owner

The shell manual and all 33 builtin/language-topic pages are published in 957772cb. The explicit manifest binds the help and invocation sources; section 1exsh keeps builtin names distinct from external commands. The pages state the current dot, exec, wait and trap limits. Per-topic examples and image adoption remain open.

The shell manual and all 33 builtin/language-topic pages are published in [957772cb](https://git.erikinkinen.fi/erix/exsh/commit/957772cbd111dce4c9e6adca60511e8ea93ccd6f). The explicit manifest binds the help and invocation sources; section `1exsh` keeps builtin names distinct from external commands. The pages state the current dot, exec, wait and trap limits. Per-topic examples and image adoption remain open.
Author
Owner

Integration 6abd74c7 adopts the complete Exsh inventory in the composed image store. Every topic has a concrete example, and builtin names remain distinct from external commands through section selection. All criteria in this issue are complete.

Integration `6abd74c7` adopts the complete Exsh inventory in the composed image store. Every topic has a concrete example, and builtin names remain distinct from external commands through section selection. All criteria in this issue are complete.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:50 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/exsh#26
No description provided.