cli: add --pager for long help / man / markdown output - #397
Merged
Conversation
…wn output Pages the long meta / doc surfaces (--help, --help=TOPIC, --man, --markdown) through a pager on a terminal, mirroring --color's tri-state: bare --pager == always, --no-pager == never, default auto (page only on a tty). It never touches the file listing - pipe that to a pager yourself. The pager command is $XFF_PAGER, else $PAGER, else the built-in 'less -FRX' (-F quits if it fits one screen so short help never traps, -R keeps ANSI color, -X leaves short output on the normal screen); an explicitly-empty env value disables paging. Paging runs via 'sh -c' so a $PAGER with args or a pipeline works, feeding the rendered text on the child's stdin; a missing tty, empty command, or fork/pipe failure falls back to stdout so output is never lost. New xff/cli/pager lib (ResolvePagerWhen / ResolvePagerCommand / EmitPaged), --pager + --no-pager global flags (self-documented), and the main.cc meta dispatch routed through EmitPaged. pager_test (resolvers) + pager_test.sh (binary behavior). XFF.md regenerated for the new flag.
helly25
enabled auto-merge (squash)
August 8, 2026 14:09
helly25
added a commit
that referenced
this pull request
Aug 8, 2026
…xff (#400) --man emits roff source; #397 paged it through the plain text pager, which shows raw roff markup. Make paging surface-aware: --man now resolves a man pager - $XFF_MANPAGER, else a built-in that formats with mandoc and pages (honoring $PAGER, else less -FRX). If mandoc is absent the built-in exits 127 so EmitPaged falls back to raw roff (never an empty page). Gated by the same --pager tri-state: on a tty (auto) or --pager=always, --man is formatted+paged like 'man xff'; --pager=never and a redirect stay raw roff (for mandoc / man -l - / installing xff.1). The text surfaces (--help / --markdown) are unchanged. PagerKind{kText,kMan} threads through EmitPaged/ResolvePagerCommand; the man pager is independent of $XFF_PAGER (which needs no formatter). pager_test + pager_test.sh cover the man resolution and behavior without depending on mandoc being installed (via an XFF_MANPAGER pass-through).
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.
Adds a git/bat-style pager for xff's long meta output, building on the help color work (#396).
Design
--pager[=auto|always|never], mirroring--color's tri-state:--pager==always,--no-pager==never, defaultauto(page only on a tty), last-wins.--help,--help=TOPIC,--man,--markdown. It never touches the file listing - that is what a shell pipe to a pager is for (the fd/rg stance).Why not
--help-pageror--help=paged? Paging is a cross-cutting behavior, not a help-specific flag nor a content selector.--help=Xpicks which reference; whether it pages is governed by--pager. So--help=longstays pure content andxff --pager=always --help=printfcan page a short topic too.Command resolution:
$XFF_PAGER, else$PAGER, else the built-inless -FRX(-Fquits if it fits one screen so short help never traps you,-Rkeeps the ANSI color from #396,-Xleaves short output on the normal screen). An explicitly-empty env value disables paging (the git / aws convention).Default
auto: because-Fno-ops the pager on anything under one screen, only genuinely-long references actually page - no aws-v2-style "why is my--helpinteractive" surprise on short help.How
New
xff/cli/pagerlib:ResolvePagerWhen(raw-arg scan, like--color),ResolvePagerCommand, andEmitPagedwhich pipes throughsh -c(so a$PAGERwith args or a pipeline works) feeding the rendered text on the child's stdin, with SIGPIPE ignored during the write and a stdout fallback on any failure.--pager+--no-pagerare self-documented global flags; themain.ccmeta dispatch routes throughEmitPaged.Tests
pager_test(cc):ResolvePagerWhen(bare/values/--no-pager/last-wins) +ResolvePagerCommand(env precedence, empty-disables).pager_test.sh(binary):--pager=neverprints,--pager=alwayspipes verbatim through acatpass-through,autostays unpaged off a tty (would deadlock on asleeppager if it paged), empty env disables,--no-pageraccepted on a real search,--helpdocuments it.bazel test //xff/...(87 + 5 skips) and--config=xff_full(92, incl. the regenerated XFF.md drift guard) green.