[FEATURE] Add a scoped offline manual reader and pager #4

Closed
opened 2026-10-24 00:13:28 +02:00 by erikinkinen · 1 comment
Owner

Problem and motivation

EriX needs an offline manual reader for its commands and interfaces. Shell help
covers built-ins, but there is no native tool for indexed manual pages or safe
interactive reading.

Proposed behavior and scope

Add man [options] [section] name..., with -s SECTION for explicit section
selection, -a for all matching sections, and -k for literal index search.
Missing pages and ambiguous names report an error without hiding other requested
pages. --plain forces plain output; --lines ROWS sets the pager viewport.

Use one versioned manual store in an explicit directory, initially
/usr/share/man/erix-manual-v1. Its UTF-8 text index records names, sections,
summaries, page lengths and SHA-256 digests; page bytes follow in the same file.
Canonical index ordering rejects duplicate identities. Pages are plain UTF-8
text, not a programming or typesetting language.

Page only when authenticated stdin and stdout are the fixed terminal aliases.
Redirected or pipeline streams receive plain text without consuming navigation
input. The built-in pager supports line/page movement, beginning/end, literal
forward/backward search, repeated search and quit. It launches no pager process.

Authority, security and reliability

Acquire one exact read-only file lease through the existing job broker. The
manual directory selects that file only: index entries contain no filesystem
paths. --root DIRECTORY requests a different exact store; it cannot override
broker denial. MANPATH, PAGER, MANPAGER, PATH and TERM never discover
objects, choose executables or expand the manual scope.

Validate complete caller-owned index and selected-page snapshots before display.
Check lengths, arithmetic, UTF-8 and page digests. Reject ESC, C0, DEL and Unicode
C1 controls, except page LF/TAB; print macro-looking text and backslashes
literally. Search is literal and never executes a pattern or shell command.

The installed store should come from the selected image's manual packaging.
A read-only child lease does not freeze other writers or authenticate publisher
identity. Changing, truncated or inconsistent reads must fail safely, and every
exit retires the original lease and erases retained scratch/workspace. Caller
storage determines capacity; there is no fixed page-count or page-size ceiling.

Acceptance criteria

  • Specify selection, ambiguity, multiple-page and index-search behavior.
  • Document the versioned store, provenance and control-byte rules.
  • Add the authenticated applet with only the exact-file read operation ceiling.
  • Implement indexed lookup and complete validated page snapshots through existing mediated I/O.
  • Implement terminal paging/navigation/search/quit and plain redirected output.
  • Cover malformed input, changing reads, capacity, denial, stream failures and lease cleanup.
  • Add native VM fixture sources for terminal and redirected reading, missing pages and denied stores.
  • Document CLI behavior, packaging needs and the technical manual.

Alternatives and tradeoffs

A roff interpreter or external pager would add executable input and authority
without helping the initial offline reader. Separate page files would need more
lookup and grant transitions. One indexed store keeps every page inside the
same exact object while allowing packaging to generate it from original text.

Tracking and rollout

Part of native shell and build utilities.
Coordinate Coreutils PR 2 and
Integration PR 12.
Publish the format and reader together; the complete command/API page inventory
and image-wide freshness coverage remain separate follow-ups.

## Problem and motivation EriX needs an offline manual reader for its commands and interfaces. Shell help covers built-ins, but there is no native tool for indexed manual pages or safe interactive reading. ## Proposed behavior and scope Add `man [options] [section] name...`, with `-s SECTION` for explicit section selection, `-a` for all matching sections, and `-k` for literal index search. Missing pages and ambiguous names report an error without hiding other requested pages. `--plain` forces plain output; `--lines ROWS` sets the pager viewport. Use one versioned manual store in an explicit directory, initially `/usr/share/man/erix-manual-v1`. Its UTF-8 text index records names, sections, summaries, page lengths and SHA-256 digests; page bytes follow in the same file. Canonical index ordering rejects duplicate identities. Pages are plain UTF-8 text, not a programming or typesetting language. Page only when authenticated stdin and stdout are the fixed terminal aliases. Redirected or pipeline streams receive plain text without consuming navigation input. The built-in pager supports line/page movement, beginning/end, literal forward/backward search, repeated search and quit. It launches no pager process. ## Authority, security and reliability Acquire one exact read-only file lease through the existing job broker. The manual directory selects that file only: index entries contain no filesystem paths. `--root DIRECTORY` requests a different exact store; it cannot override broker denial. `MANPATH`, `PAGER`, `MANPAGER`, `PATH` and `TERM` never discover objects, choose executables or expand the manual scope. Validate complete caller-owned index and selected-page snapshots before display. Check lengths, arithmetic, UTF-8 and page digests. Reject ESC, C0, DEL and Unicode C1 controls, except page LF/TAB; print macro-looking text and backslashes literally. Search is literal and never executes a pattern or shell command. The installed store should come from the selected image's manual packaging. A read-only child lease does not freeze other writers or authenticate publisher identity. Changing, truncated or inconsistent reads must fail safely, and every exit retires the original lease and erases retained scratch/workspace. Caller storage determines capacity; there is no fixed page-count or page-size ceiling. ## Acceptance criteria - [x] Specify selection, ambiguity, multiple-page and index-search behavior. - [x] Document the versioned store, provenance and control-byte rules. - [x] Add the authenticated applet with only the exact-file read operation ceiling. - [x] Implement indexed lookup and complete validated page snapshots through existing mediated I/O. - [x] Implement terminal paging/navigation/search/quit and plain redirected output. - [x] Cover malformed input, changing reads, capacity, denial, stream failures and lease cleanup. - [x] Add native VM fixture sources for terminal and redirected reading, missing pages and denied stores. - [x] Document CLI behavior, packaging needs and the technical manual. ## Alternatives and tradeoffs A roff interpreter or external pager would add executable input and authority without helping the initial offline reader. Separate page files would need more lookup and grant transitions. One indexed store keeps every page inside the same exact object while allowing packaging to generate it from original text. ## Tracking and rollout Part of [native shell and build utilities](https://git.erikinkinen.fi/erix/exsh/issues/1). Coordinate [Coreutils PR 2](https://git.erikinkinen.fi/erix/coreutils/pulls/2) and [Integration PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12). Publish the format and reader together; the complete command/API page inventory and image-wide freshness coverage remain separate follow-ups.
Author
Owner

The native reader and its VM fixture sources are pushed. It reads one scoped store, validates retained page snapshots, pages only authenticated terminal streams and leaves input after q queued for the shell. The command contract and technical-manual chapter are published. Terminal-size handling continues in #7; the wider CLI/API inventory remains separate.

The native reader and its VM fixture sources are pushed. It reads one scoped store, validates retained page snapshots, pages only authenticated terminal streams and leaves input after q queued for the shell. The command contract and technical-manual chapter are published. Terminal-size handling continues in [#7](https://git.erikinkinen.fi/erix/coreutils/issues/7); the wider CLI/API inventory remains separate.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:35 +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/coreutils#4
No description provided.