Hacker News Reader

Comment by ksynwa | Hacker News Reader

My dream feature in man page readers is to somehow go to the description of a specific flag. Maybe it already exists and I don't know about it. But as of now I resort to regex hacks like searching for `^\s+-p` or `, -p` to find where the flag is described.

View on HN

This feature exists, on systems that use mandoc as the default manpage formatter and viewer (such as OpenBSD).

In HTML output, definitions for flags, environment variables, and other such things are converted to hyperlinks, and hyperlinks can point directly to them. https://man.openbsd.org/ssh#D

In terminal output, this same capability is used to create a ctags file, which is supported by less(1). On OpenBSD, I can type “man ssh”, then :tD to jump to the tag named “D”.

This relies on the mdoc(7) language’s semantics, so unfortunately it won’t work for manpages using the older man(7) macros. But nearly all BSD manpages are written in mdoc(7), and a significant minority of manpages from packages.

Yes, ctags is not full hyperlinking but is is quite helpful for navigating a single man page in the terminal.

As far as I can tell, this is the missing feature: flags definitions are extremely semantically meaningful to humans and not even `mdoc` has expliict semantics for them (the closest you can get is that the pattern `.It Fl A` almost always means "the -A flag's definition", especially if it's in the DESCRIPTION section, but that's not a hard-and-fast rule).

And of course, even if your pager isn't `less`, by the time the content has been fed through `man` itself it's been crunched into a terminal representation, not a semantic representation. You'd have to `man -w whatever` to get the raw file and parse it yourself (and handle whether it's mdoc or man format, etc.).

The regex you have keyed that matches to "What these flag definitions usually look like on the terminal" is almost certainly the saddle-point solution between using the tooling as it is and burning it to the ground to build something better.

I'd love to be able to type:

    man ffmpeg "-ss"

And have it jump right to the -ss option so I can see the expected format. For me the 99+% use case of man is to look up parameters of a command line or parameters of a programming function call. It's shocking that the UX for what I presume is the single most used use case is so broken.

Does searching with /-ss not do this well enough?

For options, the first hit often is the description. When it's not, filtering with & can give you an idea how much further it is, so you can repeat the search with n.

It's not an exact, "semantic" jump, but I find it good enough.

Sometimes it works, sometimes it doesn't. Sometimes the application has options like -o and --original and --output, and they are littered throughout the man page, so if I only want -o, I'm getting dozens of false positives.

You know, I cut my teeth on AT&T SVR3. I loved reading up on the basic tools and learning their options and then putting them into everyday practice.

In those systems there were far fewer tools, far fewer options, and much simpler workflows, so honestly I didn’t need to endlessly flip through manpages to sift out hundreds of options with arcane, incompatible, unintuitive syntaxes. The few options we needed to memorize were always paired with consistent syntax and impeccable mnemonics to remember (who can forget ‘ls -l‘ or ‘rm -f‘?)

Ironically, ‘vi‘ was already quite evolved, complex, and arcane by this point, but that was completely different: it was required for us to acquire proficiency in order to code, and it was easy to build skills from basic to expert/power, and all ‘vi‘-editing commands still featured those standardized mnemonics and consistency that can only come from a proprietary single-entity codebase. Plus all possible legacy compat with ‘ed‘ which nobody used directly anymore!

So while we may today consider this a lacuna in the reader tool, it wasn’t by design, and I blame the explosion of “GNU long options” and lack of standardization, more than anything. But also ‘tar‘ and ‘ps‘ and BSD vs. the world. Eff those guys.

https://m.xkcd.com/1168/

It’s fun to compare BSD alternatives to GNU software and BSD documentation to GNU documentation. For example, OpenBSD refused to integrate GnuPG for package signing due to its complexity, instead developing its own signify(1):

https://man.openbsd.org/signify.1

https://www.gnupg.org/documentation/manuals/gnupg24/gpg.1.ht...

Oops, sorry, this is GNU software, so we need the real documentation from texinfo:

https://www.gnupg.org/documentation/manuals/gnupg/

GnuPG certainly has more features. Does that make it better software? For checking signatures (the only thing I’ve used GnuPG for in 15 years), I find the signify(1) documentation more readable and the signify(1) tool more usable.

Or how about tar(1), everyone’s favorite punching bag due to its weird options?

https://man.openbsd.org/tar.1

https://manpages.debian.org/bookworm/tar/tar.1.en.html

https://www.gnu.org/software/tar/manual/tar.html

Yikes!

I would recommend 'manly'[0] for that. It's a super convenient tool for looking up descriptions for specific flags.

No affiliation, just an avid user.

[0]: https://pypi.org/project/manly/

The `.Fl` macro identifies flags in mdoc, so what you're asking for is perfectly doable.

Reply on news.ycombinator.com