4 ms·

40-Plus Years of Man Page History

63 points by matt_d 10y ago

pattisapu 10y ago
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...
- jandrese 10y ago
  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.
- mzs 10y ago
  I use -ms when tex is overkill: http://www.troff.org/using-ms.pdf http://www.troff.org/using-ms.pdf
  - pattisapu 10y ago
    tyft
- privong 10y ago
  > 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 10y ago
    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 10y ago
      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 10y ago
        No two latex installations are the same.
        privong 10y ago
        > 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.
        jff 10y ago
        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 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.
        mzs 10y ago
        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.
- AceJohnny2 10y ago
  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.html https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h... HN discussion: https://news.ycombinator.com/item?id=11470905 https://news.ycombinator.com/item?id=11470905
- thechao 10y ago
  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.
  - stroustrup 10y ago
    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.
- emmelaich 10y ago
  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.
- carussell 10y ago
  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.
teddyh 10y ago
See also the History section of the GNU Troff (groff) manual: https://www.gnu.org/software/groff/manual/html_node/History.html https://www.gnu.org/software/groff/manual/html_node/History....
mturmon 10y ago
"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.
smarks 10y ago
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?
- ulysses 10y ago
  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.
- JoshTriplett 10y ago
  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.
sebnukem2 10y ago
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)

63 points by matt_d 10y ago

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

jandrese 10y ago
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.
mzs 10y ago
I use -ms when tex is overkill: http://www.troff.org/using-ms.pdf http://www.troff.org/using-ms.pdf
- pattisapu 10y ago
  tyft
privong 10y ago
> 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 10y ago
  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 10y ago
    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 10y ago
      No two latex installations are the same.
      - privong 10y ago
        > 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.
        jff 10y ago
        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 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.
        mzs 10y ago
        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.
AceJohnny2 10y ago
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.html https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h... HN discussion: https://news.ycombinator.com/item?id=11470905 https://news.ycombinator.com/item?id=11470905
thechao 10y ago
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.
- stroustrup 10y ago
  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.
emmelaich 10y ago
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.
carussell 10y ago
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.

teddyh 10y ago

See also the History section of the GNU Troff (groff) manual: https://www.gnu.org/software/groff/manual/html_node/History.html https://www.gnu.org/software/groff/manual/html_node/History....

mturmon 10y ago

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

smarks 10y ago

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?

ulysses 10y ago
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.
JoshTriplett 10y ago
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.

sebnukem2 10y ago

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)