Stories

Comment by amanthanvi

Comment

Comment by amanthanvi

Hi HN. BetterMan is a web reader for Unix manual pages. I've been working on it for a while; version 2 is a large rework, which is why I'm posting it now. It has 107,143 pages from about 17,300 Debian trixie (13) packages, plus full archive imports of Ubuntu (104,763), Fedora (87,890), Arch (49,306) and Alpine (41,920), FreeBSD (12,096) and macOS (447). There are no accounts. Bookmarks, history and reading preferences stay in your browser.

Why. I look up flags constantly, and the existing options each do part of the job. man7.org and manpages.debian.org are faithful but plain. tldr shows the examples but not the manual. explainshell parses a command line but is a separate tool. I wanted one place where the exact manual is the base, and everything I add sits on top of it, marked as mine.

What it does.

- `betterman.sh/tar`, `/tar.1`, `/tar/-x` go to the page or flag. A bare name opens the section `man` itself would pick on that distro. `curl -L betterman.sh/tar.txt` returns plain text: a running header, then NAME, with each option listed once. Browsers can add it as a search engine.

- Each page opens with a one-sentence summary, up to five examples (each labelled with its source) and the most-used flags. The upstream manual follows unchanged, with a filterable options index.

- Search matches task phrases ("extract a tarball" finds tar(1)), manual citations such as `open(2)` and clustered flags.

- Explain: paste a shell line, get each command and flag linked to its definition. Clustered flags are split. It is a deterministic parser, not a model. For input it can't parse safely it says so instead of guessing.

- Flags that differ between distros get a marker, computed by diffing the actual manuals. Where several packages ship the same page, a provided by switch lists them.

- Translations in six languages (de, fr, es, pt-BR, ja, ru) come from Debian's manpages-l10n packages, 9,552 pages in all. Add `?lang=`; each page credits its source package and notes the options it lacks compared with English, and a page with no translation shows in English. The UI is localized into the same six languages.

How it's built.

- Ingestion is Python. `mandoc -Thtml` renders each page, and I convert that into a typed block/inline document model that is mirrored in TypeScript, with golden fixtures keeping the two in sync. Debian pages come from checksum-verified `.deb` archives that are unpacked, not installed (the way debiman does it). Installing everything is not feasible: it would be 18 GB to download and 74 GB installed, with conflicts.

- The data lives in Convex. Releases are immutable once sealed. A dataset update goes ingest, verify, seal, stage, then promote, with a compare-and-swap on the release ID, so a bad release can be rolled back by pointing at the previous one. Next.js reads Convex server-side only; there are no client subscriptions.

- Man pages are plain server-rendered HTML. The only script is one hashed inline boot script (theme and reading preferences before first paint) plus a small static bundle. The CSP is hash-based, with no per-request nonce, which lets Vercel's CDN cache pages. The cache key includes the active release, so a promotion changes it.

- CI enforces budgets (`pnpm perf:check`): JS and HTML bytes per route, Convex calls and documents read per page view, and a cap on LCP minus FCP. A change that raises one needs an explanation in the PR.

What's generated and what isn't. The manual text is upstream, parsed, not rewritten. Generated at build time by DeepSeek V4.1 Flash (`deepseek-v4.1-flash`): the one-sentence summaries, task phrases, and some examples when a page has fewer than three. There is no model call when you load a page. Generated text is labelled with the model and date. A generated example must be one simple command, and every flag in it is checked against that page's options table; if a flag isn't there, the example is dropped. Pages for commands that destroy data (`rm`, `dd`, `mkfs` and the like) get no generated text. Examples from tldr-pages (CC BY 4.0) are credited and link to the exact upstream file.

Limits.

- Translations cover 9,552 pages, so most pages are English only.

- Ubuntu 24.04, Fedora 44, Arch and Alpine 3.23 are full archive imports like Debian. FreeBSD (15.1) is base-system manuals. macOS is limited to pages whose license allows it.

- One current release per distro. There is no history, so you can't read what tar(1) said in an older release.

- Portability compares distros, not versions of a distro.

- Explain covers a defined shell grammar. It will refuse some valid lines.

- Generated summaries can be wrong or flat. Every page has a report a problem link that opens a prefilled GitHub issue.

- Search engines may index pages in sections 1, 5, 7 and 8, plus pages from packages with at least 10,000 installations in Debian's popularity contest. That is 48,416 of Debian's 107,143 pages and 49,744 of Ubuntu's 104,763. Every other page is served and searchable but marked `noindex` and left out of sitemaps, to avoid 100k thin pages. Translated pages are `noindex`, with the English page as canonical when that page is indexable.

- Parsing man pages is messy. Pages that mandoc warned about carry a note, and some will still render badly.

- No CLI, API or editor extension for now. `/api/` is disallowed for crawlers.

Feedback I'd like. Pages that render wrongly, or flags missing from the options index. Explain results that are wrong or too cautious. Portability markers that don't match what you see on your machine. A package that owns the wrong clean URL (`nc`, `awk`, `vi` were the hard ones). And whether the answer-first layout helps or just gets in your way.

It's MIT licensed: https://github.com/amanthanvi/BetterMan. I'll be around to answer questions.

Replies amanthanvi · 45m
Open on HN
Loading the discussion…

Domain filters

Stories from these domains are hidden from every list. Subdomains match too: blocking substack.com also hides danluu.substack.com. Type a domain, or paste a link to block its site, and press Enter.

New collection

Delete this collection?

About YAVCHN

YAVCHN is a reader for Hacker News and Lobsters, with articles and discussions in separate windows or Classic pages.

Created by Paul Parks and built with PUDL.

YAVCHN source code on GitHub

Privacy policy · Terms of use

Help

Keyboard

j / k
Move down and up the story list. The arrow keys scroll whatever has focus.
Enter
Read the marked story in the article reader.
[ / ]
Read the story above or below in the list, in the same article reader. Back returns to the story you came from.
p
Pin or unpin the marked story, which keeps it in Pinned.
n / N
Move to the next or previous top-level comment in the window in front.
c
Collapse or expand that comment.
f
Hide or show the story list.
Esc
Close a menu or this help.
Access key m
Go to the menu bar. Most browsers take it with Alt on Windows and Linux, and Safari with Control and Option.
?
Show this help.

Windows

Each story opens in a window holding its article above its discussion; drag the bar between them to share the room differently. A window can be moved by its title bar, resized from any edge, snapped to a half or a corner by dragging it there, maximised, or minimised to the bar at the foot of the page. Use Window > New reader window to open an empty reader, or Story > Open in new reader window to open another reader for the current article. Docked readers keep their articles when you select another story from the sidebar. Minimized readers can be restored and reused for their site. A window's Previous and Next buttons read up and down the list in the same window.

A link in a comment or an article to another Hacker News or Lobsters thread opens that thread in a window too. A link to a single HN comment opens the comment above its replies.

While a story's window is in front, the Story and Discussion menus in the menu bar hold its commands: pinning, Previous and Next story, sorting, collapsing every thread, jumping to the first new comment. Each window also remembers where you were in its article and discussion, so a reload, or Back to a story that Next took you past, finds your place again. Closing a window forgets it.

The whole arrangement lives in the address, so a bookmark or a shared link brings it back, and Back undoes the last change. Moving between Hacker News, Lobsters, their lists, Pinned and Find changes only the list, and leaves the windows open.

The list

The pin at the start of a row keeps the story in Pinned, and the cross at its end hides it. Pinned can be narrowed by words in the title, site or author, by source, and to the stories you haven't opened yet, and ordered by when you pinned them, by points or by comments; the filters are part of the address, so a filtered view can be bookmarked. Scroll past the end of the list to load more. Domain filters, in the View menu, hide every story from a site.

Collections are named lists of stories. Story > Add to collection files the story in front into one or more of them, and the Collections feed shows them all or one at a time; the menu that chooses collections also creates, renames, and deletes them. A note is your own text on a story. Choose Add note in a story's toolbar to write one; it saves as you type. Rows with a note carry the note mark, and the Notes feed lists every noted story and searches the text of your notes.

Browsing view

View > Windowed and View > Classic select the browsing view and save your default in this browser. Window view reuses a reader for each feed. Classic view opens stories and applets as pages. Open as a page is a one-off action that does not change your saved default. Use the Windowed selector to return an article to a window. Direct page links always open as pages.

Applets

The Applets menu in the menu bar holds three tools, each a window of its own. Replies to me takes your Hacker News user name and lists the replies to your last thirty comments and stories, checking again every three minutes while it is open, and marking what is new since you last marked them read. Look up a user opens a profile on Hacker News or Lobsters, with their submissions and recent comments, as a commenter's name in any discussion does; the bar at the top of a profile looks up someone else in the same window, and Back returns to the one before. Who is hiring? filters the posts of HN's monthly hiring threads by the words you type.

They read only what the sites publish to everyone, so none of them asks for a login, and your user name stays in this browser anonymously and is included in retained applet state when signed in.

Find

Find takes any link and lists every time it was submitted to Hacker News and Lobsters, so you can read each discussion of it.

About

YAVCHN never sees your Hacker News or Lobsters login. The discussion is fetched from each site's public API; to vote or reply, follow the link above the discussion, or the arrow beside a comment, to the source's own site. Without a YAVCHN account, your data stays in this browser. When signed in, pins, collections, notes, blocked domains, and retained reading state are stored with your account and synchronized across devices. Hidden stories and layout stay in this browser. The privacy policy has the details.

Open source: github.com/paulmooreparks/yavchn. Built with PUDL.