For the Love of Troff (2020) [pdf]
schemamania.org
schemamania.org
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 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.
[1] http://www.gopl.io/ch1.pdf
[2] http://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.ht...
[0] https://www.schaffter.ca/mom/bin/install-font.sh
[1] https://www.schaffter.ca/mom/momdoc/appendices.html#install-...
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.
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
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.
[1] Firefox rendering is horrible. With Evince it is a pleasure.