[FEATURE] Add a scoped offline manual reader and pager #4
Labels
No labels
alpha-1
bug
ci
docs
duplicate
enhancement
help wanted
invalid
performance
phase-6
question
refactor
security
wontfix
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
erix/coreutils#4
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 SECTIONfor explicit sectionselection,
-afor all matching sections, and-kfor literal index search.Missing pages and ambiguous names report an error without hiding other requested
pages.
--plainforces plain output;--lines ROWSsets 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 DIRECTORYrequests a different exact store; it cannot overridebroker denial.
MANPATH,PAGER,MANPAGER,PATHandTERMnever discoverobjects, 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
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.
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.