Comment by smcameron | Hacker News Reader

Comment by smcameron | Hacker News Reader

Parent Full thread

If not troff, at least a love of nroff.

I think it is a crime against humanity to publish a binary executable for a unix-like system with out a corresponding man page.

That being said, one of my first tasks at my 2nd summer job during college was some really gross combination of C, Oracle, troff and Postscript. My memory fails me a bit, but it was something like, I needed to write a C program to query an Oracle database for various real estate records, spit out troff to print out a table of stuff, then, after the troff was converted to Postscript, automatically edit the postscript to make it draw a bunch of lines to demarcate the table rows and columns, convert it to encapusulated postscript (EPS), etc. It was kind of a nightmare on the one hand, but it was also kind of cool.

Been too long since I seriously used troff, but I am skeptical that it would hold its own against latex for "serious" writing (e.g. typesetting a paper or a especially a book.)

For man pages though, it's definitely good enough, and splitters like info can diaf.

> I am skeptical that it would hold its own against latex for "serious" writing

https://www.troff.org/pubs.html

Less than one time in my life (one time exactly but not really) has a man page helped me to figure out how to use a command. To me it seems man pages are written for extraterrestrial beings, hard to understand, only featuring some examples (which don't cover even the very basic use cases anyway) hidden among pages deep down below. The first thing I find when I google a command are examples, usually covering exactly what I need. So I believe the entire man pages system is a crime against humanity or a piece of obscure art like the Voynich manuscript at best.

> The first thing I find when I google a command are examples, usually covering exactly what I need.

I see a lot of people reflexively reaching for Google or Stackoverflow when working with a command (or even a programming language) that they aren't familiar with. Often it will get the job done, but I feel it only provides a shallow understanding of what the tools can do. Do you similarly search for examples when trying to use an API in your language of choice, or do you consult the reference documentation?

Take, for example, fio(1), a tool for running I/O benchmarks. It probably has over 100 options. It is insanely flexible. You might not even consider using it if you didn't know what it was capable of. You can either sift through dozens of mailing list conversations and stackoverflow threads to find the perfect benchmark, or you can browse the man page that explains all the options.

I guess what I'm saying is that one is not a replacement for another. If you're skipping the man page, you're losing something. Whether or not you'll miss it is another question.

God knows man pages aren't perfect. But they're what all the extraterrestrial beings around you are reading to create the docs with examples that suit you better when you perform searches on the internet.

It's encouraged for manpages to have an EXAMPLES section, though I feel you. I think a big problem is that command line options have gone ad absurdum with hundreds of options decades ago already (prompting GNU-style long options) and the more recent trend towards "subcommands" as in git, docker, etc.

I recently discovered and am enjoying [0] for the cli, and [1] for decoding shell fragments encountered in scripts

[0] https://tldr.sh/ [1] https://explainshell.com/

Yes, tldr is an awesome and I used it for some time but its library wasn't rich enough. Perhaps it got bigger nowadays, maybe I'm going to revisit it.

Reply on news.ycombinator.com