Hacker News new | past | comments | ask | show | jobs | submit login
For the Love of Troff (2020) [pdf] (schemamania.org)
66 points by tannhaeuser 30 days ago | hide | past | favorite | 21 comments

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


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.

The Go Programming Language by Alan Donovan and Brian Kernighan [1], published in 2016, was typeset using groff [2].

[1] http://www.gopl.io/ch1.pdf

[2] http://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.ht...

The one big problem with groff (a system I otherwise admire) is the exceeding difficulty of using anything but the built-in fonts. Adding fonts requires conversions using FontForge or other tools to an old PostScript format, followed by multiple steps to get it recognized properly by groff. And you have to do this for every font file--including the bold, italic, condensed, etc. variants one at a time.

[0] http://www.port.de/cgi-bin/groff/AddingFonts

Adding fonts is indeed a chore. Fortunately Peter Schaffter (mom macro set author) wrote a script[0] to automate this. Details are available on his website[1].

[0] https://www.schaffter.ca/mom/bin/install-font.sh

[1] https://www.schaffter.ca/mom/momdoc/appendices.html#install-...

> The system developed by Bell Labs, troff, was as different [from SGML] as could be: a direct typesetter with no imposed structure ...

Actually, the point of SGML's tag omission, content model, and shortform/alternate syntax features is to infer a document hierarchy from a flat, printer instruction representation. Though I'm not aware this has ever been applied to troff/nroff. James Clark should know, as not only did he develop the SGML reference implementation (SP/OpenSP) but also groff.

AsciiDoc and ReStructuredText are big names missing, but also https://en.wikipedia.org/wiki/List_of_document_markup_langua...

I can only guess that publishing this as a PDF “paper” is some kind of a meta-joke to rub the reader's nose in the state of toolchains.

I understand that the point of this is to imagine something better, but I feel like the Emacs info reader is already most of the way to the ideal viewer described here.

> the Emacs info reader

Feel Plan 9's Acme editor also an excellent interface

- SEE ALSO section links via plumber (right click to view page)

- Acme's Font command gives flexibility

gnome-help-browser had an ability to render all of the documentation formats well.

It is superseded by yelp, which is much better at DocBook and custom-XML-documentation-built-for-GNOME schema (edit: Mallard), but you can still do "yelp man:ls" or "yelp info:find" to get man pages or GNU texinfo pages rendered directly with it.

Documentation is catalogued by ScrollKeeper.

Indexing is the missing bit, I guess, and a more of a "directory view" into all available documentation.

I think it is more realistic to accept the nature of different tools and see what we can do to make it more manageable for consumption (browsing, reading, searching and discovery). But it's such a non-glorious problem that nobody will bother with it.

This article claims that Markdown has no standard, but this has to at some extent been rectified, right (e.g. CommonMark)?

Whatever you do, open this PDF in a distinct viewer[1].

[1] Firefox rendering is horrible. With Evince it is a pleasure.

Is this some kind of joke? Can't read it with FFs inbuilt PDF renderer nor with Acrobat.

The PDF doesn't have embedded fonts. Try this: https://files.catbox.moe/px77ns.pdf

Applications are open for YC Winter 2022

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact