▲ 63 points
back
30 comments
I'm curious as to how many people care about nroff/troff style man pages. I work in the group that delivers the Java JDK, and for many years we delivered nroff/troff man pages for the commands such as java, javac, javap, etc.
Some time ago because of "Corporate Documentation Standards" the sources were converted into some XML-based markup, from which nroff/troff markup was produced -- not entirely successfully. More recently because of "Revised Corporate Documentation Standards" the XML sources were converted into yet another format, and the team responsible has given up maintaining the tool that converted that format into nroff/troff. So the plan now is to deliver straight HTML, with the rationale being "nobody looks at man pages anymore."
As an old UNIX hack I opposed this, to no avail.
Are man pages really irrelevant?
Manpages still matter for Linux systems. Not necessarily for GUI-only tools, but any command-line tool should have a manpage. They remain the most convenient and consistent form of documentation for command-line tools, with the possible exception of --help.
If you need to know which command-line option to use for a particular behavior, consider the relative amount of time needed to find out via a browser and search engine, versus installed documentation, versus a manpage. And if the search engine comes close, half the time it does so by finding the relevant manpage (or excerpting the relevant manpage snippet).
The troff markup language remains terribly baroque, and in truth it hardly matters except as "the thing that existing manpages all use so the man tool handles it". Nothing but inertia and existing infrastructure keeps that format necessary, but learning the small subset of it needed for manpages doesn't take long, especially if you copy an existing manpage as a starting point.
Groff knows how to produce HTML from a manpage, and the result can help if you want to provide documentation that works on other platforms.
The conventions of manpages matter far more than the markup details. If "man sometool" popped up with troff-formatted documentation that didn't have the expected sections and section order, it wouldn't have anywhere near the same value.
I look at at least one man page probably every day. And I'd be really surprised if this wasn't the case for anyone who works on the command line.
I look at man pages all the time.
On the other hand, I avoid Java as much as possible, so I might not be the best test market.
I don't use the terminal for viewing man pages. I often reach one via a web search. Plenty of websites host them. I think traditional unix man pages are extremely useful as documentation for two reasons.
The most important thing is how detailed they are. Man pages contain everything one needs to know for unix programming. If applicable, they specify standards conformance and document behavior that standards leave undefined or implementation-defined. They document system calls, functions, files, programs... Everything a capable user could ever want information on. They provide detailed technical information.
Another nice thing about man pages is how they don't require an internet connection. They're usually installed alongside the packages they document. This is useful if the system is disconnected from the internet.
I don't think the man command itself is essential to unix man pages. I think the detailed documentation they provide are the most important thing. One could install documentation in HTML format and use a browser for viewing -- wouldn't that be just as good?
In fact, git has an option¹ for doing just that. Passing --web instructs git to display the manual page in HTML format in the user's browser of choice. It could be a graphical web browser or a text browser such as Lynx.
The Debian packaging guidelines requires a man page for every command line program. Any missing manual page is regarded as a bug.
Of course they are.
Any significantly tasked sysadmin probably uses them on a daily basis and as *nix systems programmer I'll find myself using manpage reference when I jump into something that I haven't used for awhile.
Many situations they are much more convenient and accessible than online or html docs.
sure, if you ship broken man pages, people will stop using them.
Dumb question: Are man pages the only place where any footprint of troff really survives these days?
Sometimes I feel that contemporary markup languages like Markdown, Textile, etc. fall short compared to the syntax that was just as readable and quite a bit more powerful in troff...
The Go Programming Language book, published 08/2015, was typeset using troff (well, groff, the GNU version). Maybe because it was written by Kernighan (of K&R C fame):
https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h...
HN discussion: https://news.ycombinator.com/item?id=11470905
Probably. Everybody these days seems to just implement a random handful of markdown tags and call it good. It is really frustrating trying to remember the different syntaxes used on every website and what features they support. I've more than once posted stuff with the wrong markup because I forgot which site I was on.
> Sometimes I feel that contemporary markup languages like Markdown, Textile, etc. fall short compared to the syntax that was just as readable and quite a bit more powerful in troff...
I've never used troff myself, but your comment prompted me to look at the spec for it. I also searched for a "markdown vs troff" comparison, but didn't have much luck. Do you know of a head-to-head comparison? I've been using markdown for the past year or so when I don't need the full power of LaTeX. But your comment has me wondering if I'd be better off just using troff?
It's not bad. It's got some not-entirely-awful metaprogramming features; a while back I got interested in it and wrote a 'modern' macro package proof-of-concept for it:
Example input follows. Defining a paragraph style in meta:
.STYLE TITLE
. FONT SANS
. FACE B
. FONTSIZE 30
. ALIGNMENT CENTER
./STYLE
.TITLE
The meta macro package
./TITLE
This is a very simple, noddy example of how to use the meta
macro package. It's not intended to be a reference (there currently isn't one).
troff takes a little bit more work but it can put out some very nice-looking documents with a lot of control over the formatting and some pretty handy utilities for tables and math and such. For example, pretty much all the Plan 9 papers were written in troff: https://9p.io/sys/doc/
Okay. I guess what I'm wondering is, if I'm already reasonably proficient in LaTeX (for documents where I want/need lots of control) is there an advantage to learning/using troff versus using markdown?
No two latex installations are the same.
> No two latex installations are the same.
Sure, but that doesn't address my question about whether I should use troff versus markdown for things where I don't need the power and complexity of LaTeX.
In my opinion, I'd say pull out troff if you're thinking about making a PDF, or if you want tables or equations (see http://www.troff.org/prog.html). Personally, I mostly use markdown when I want to generate some HTML but don't feel like typing tags by hand, or just as a sort of "style guideline" when writing text files.
I meant when in two years you add something to your tex file and make blows-up, that's a reason to use roff if you can get away with it.
The troff suite includes eqn for equations, pic for diagrams, etc. that make it more like TeX in its capabilities than HTML like for Markdown etc.
http://www.troff.org/prog.html#pic
And the basic inline markup tags are, at least in my opinion, just as simple as Markdown, Textile, or AsciiDoc.
I use -ms when tex is overkill: http://www.troff.org/using-ms.pdf
tyft
roff is readable? Unhappy memories from my past of reading through roff and mdoc pages on a system with no viewer has led me to the opposite conclusion.
It's been a secret promise to myself for a while now that if ever I fall headlong into Shuttleworth levels of cash, one of the first things I would do is to throw some money at a project for the express purpose of writing missing pages, keeping existing ones up to date, bridging the man/info divide, and to singlehandedly push for weening the world off of roff onto a more human-readable format.
I don't know about recently—it looks like he's switched to Word—but Bjarne Stroustrup used to use troff to write & typeset his books.
I (still) use troff for "The C++ Programming Language" and "A Tour of C++". I use Tex for academic articles (mostly because of co-authors). I use html and markup for web documents. I use Word for quick articles and notes. I'm not a tool fanatic.
I wrote my cv/resume in troff (groff), not so long ago (this millenium)
Didn't have Word, didn't want to learn LaTeX, printed html looked worse.
Archive of the first edition of the Unix Programmer's Manual, 1971: https://www.bell-labs.com/usr/dmr/www/1stEdman.html (PDF, PS, and images)
"If you’re familiar with HTML, this won’t be a complete departure (though there are no closing tags). .TH is the tag for titles, while .SH is for section header. You can format text to be bold or italic with .B or .I, respectively."
I love this retrospective explanation of nroff in terms of HTML.
See also the History section of the GNU Troff (groff) manual:
https://www.gnu.org/software/groff/manual/html_node/History....