
40-Plus Years of Man Page History - matt_d
https://truss.works/blog/2016/12/9/man-splained
======
smarks
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?

~~~
JoshTriplett
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.

------
pattisapu
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...

~~~
privong
> 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?

~~~
jff
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/](https://9p.io/sys/doc/)

~~~
privong
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?

~~~
mzs
No two latex installations are the same.

~~~
privong
> 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.

~~~
mzs
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.

~~~
privong
Gotcha, thanks for the clarification. I guess I don't use very many "exotic"
packages, so I haven't had much of an issue with old LaTeX files not
compiling. Though, I also rarely have to go back and recompile them.

------
sebnukem2
Archive of the first edition of the Unix Programmer's Manual, 1971:
[https://www.bell-labs.com/usr/dmr/www/1stEdman.html](https://www.bell-
labs.com/usr/dmr/www/1stEdman.html) (PDF, PS, and images)

------
mturmon
"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.

------
teddyh
See also the _History_ section of the GNU Troff (groff) manual:

[https://www.gnu.org/software/groff/manual/html_node/History....](https://www.gnu.org/software/groff/manual/html_node/History.html)

