[1] http://undeadly.org/cgi?action=article&sid=20110314142734
I like that groff is a typesetting system, it means that I can generate pretty postscript versions of manpages from the command-line and print them off, all in one go. It's really handy that way.
I haven't spent more than a day working with groff though, perhaps many people still use it (every website with info just looked about as old as your average man page), so I may be completely missing the point here. If so, tell me!
We can move to something new, but getting everyone to agree on what that is, then implementing and maintaining it... isn't that more work than just maintaining the working solution everyone already agrees on, and that solves the problem?
As a consumer you wouldn't need to care about the format behind the scene and the format is already well known by programmers, there are plenty of libraries that solve can read markdown and plenty of people who know it.
I only see this working if some big entity slams the gavel and decrees this as the new manpage standard, but I also don't see any such entity having much incentive to do so.
But you can create pretty hard-copy versions of the manpages on your system with groff, the same way these books were created with troff (which groff is a replacement for.)
> > Replacing man pages because 'they look old' is a terribly stupid idea.
> I fully agree, and it's not what I meant to say. What I meant is writing new pages in a newer language (insert random lightweight text based format, preferably one where the 'see also' part is linkable) and groff is simply deprecated and supported as well. Since there is currently support, why do we need a maintainer? That is my question.
How about we replace them because there is something better? Or because they no longer fill a need?
Things that are old and work are not to be messed with. Frankly, if you don't get that, I don't want you, or anyone else who thinks like you, making decisions about any UNIX I might work with.
I lament the poor documentation on Linux, and OSX, and I lament the FSF's obsession with info pages. There's nothing wrong with man pages. Maybe we don't need groff to prepare them, but we need man pages.
I fully agree, and it's not what I meant to say. What I meant is writing new pages in a newer language (insert random lightweight text based format, preferably one where the 'see also' part is linkable) and groff is simply deprecated and supported as well. Since there is currently support, why do we need a maintainer? That is my question.
> Things that are old and work are not to be messed with.
Agreed, so what's the maintainer going to do?
> Maybe we don't need groff to prepare them, but we need man pages.
Once again, I agree. Sorry if I sounded like man pages are unnecessary, that is not what I meant.
A little bit of manpage history:
Roff has been around since the beginning of Unix (in fact, the group at Bell Labs who developed Unix got funding by convincing managers they could come up with a good typesetting system). Roff supports a variety of macro sets; for a long time, the most common one for manpages was the “man” macros.
In the early 1990s, BSD came up with the “mdoc” macros, which are a significant improvement over the original “man” macros. mdoc is inherently semantic, and allows easy searching and conversion to other formats, including HTML. You can search for based based on function return type or argument type, program authors, include files and environment variables used, and many more. mdoc pages natively support hyperlinking, including links to other manpages, links within the same manpage, and external hyperlinks.
Mdoc is a very pleasant language, and since it’s used in roff you can combine it with other macro sets like tbl (for tables) and eqn (for mathematics). It supports UTF‐8, it can easily be converted to PDF and/or semantic HTML, and provides great searchability. It’s well‐documented and widely supported (mdoc pages are supported out of the box on any system using mandoc or groff for manpages, meaning Linux, OpenBSD, FreeBSD, NetBSD, Mac OS X, Illumos, Minix…).
But is it really all used? I have never heard of searching man pages by e.g. return type (in section 2 or 3 I assume this would be), nor does hyperlinking work (perhaps due to the pager, but still). If only 1% of the people use it, then either it's up to them to maintain it or we just deprecate it in favor of a new system.
And by the way, the new system doesn't have to be only one language, it can be some generic language that other languages can "compile" to if you have the right packages (just like markdown can be parsed to the current man page language).
I'm not sure what you mean by return type, but if you want to, I think you can section your manpages however you want; i.e. you can have section 1 be 'games' instead of 6 if you want to, it just makes installing manpages more difficult.
For example, here’s a search for “functions beginning with ‘str’ and with return type size_t”: http://www.openbsd.org/cgi-bin/man.cgi?query=Ft%3Dsize_t+-a+...
On OpenBSD you can do the same from a terminal:
$ apropos -s 3 Ft=size_t -a Nm~^str
As for hyperlinks, this of course depends on your output format. less(1) in a terminal doesn’t do hyperlinks. HTML output will, such as in this page: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/... And a distribution could, for example, configure man(1) to trigger Lynx (or even Firefox) looking at Mandoc’s HTML output.
These toolchains are still being actively developed and improved (semantic search, for example, has only been around for a couple years despite the format theoretically supporting it since the beginning). I try to do my part by contributing manpages to projects that don’t have one, converting to mdoc macros when practical, and explaining the great featureset available. The best part is that it is so widely supported—at worst, mdoc falls back to the manpage infrastructure we have now; deployment of a new toolsuite is not a problem compared to converting to some brand new format. At best, it supports all these great new features, and it does so today!
I would be interested to know your opinions on GNU info/Texinfo, and the possibility/difficulty of rewriting all the existing manpages in Texinfo format.
http://lwn.net/Articles/625072/
(It got no interest on HN: https://news.ycombinator.com/item?id=8911625)
There seems a desire among those users who comment in forums to see recent commits to the software they use as if infrequent commits or no commits in years suggests there is something wrong with the software.
To me, it is the constant changes and updates that give me pause when choosing software. I am actually more skeptical of large, complex software that requires constant updating.
I prefer software which can deliver reliable performance year after year without changes, e.g., daemontools. But hey, what do I know?
In any event, I am glad to see this comment. I wish more folks would call out this silly obsession.
As for groff, I think there is more to roff that just printing manpages. http://heirloom.sourceforge.net/doctools.html
I would be reluctant to start using a package that wasn't actively developed. Libraries, APIs and even languages evolve, and I don't want to be stuck relying on old versions of other things because of one package that isn't being updated. You might say that all the other pieces should take version compatibility much more seriously, to avoid this problem, but that's not the world we're in.
More importantly, since all non trivial software has bugs, if there have been no commits for years, either no-one's using it and finding the bugs, or the maintainer isn't merging people's patches. Both options sound bad for me as a user.
I understand that a program could theoretically be 'done', not requiring any further changes, but I think there's hardly any software that could conceivably be so 'done' it wouldn't have any commits in months or years. I've just looked up a few of the most stable major projects I can think of: the Linux kernel, Apache and Subversion all have multiple commits within the last day. GNU coreutils only has five in the last week.
This may not work for everything, they're not going to maintain any old system, but things that we want to keep around but for which there are not necessarily dedicated maintainers to keep it up...
http://www.gnu.org/software/groff/groff-mission-statement.ht...
One could even go a step further and argue that writing man pages would be much easier (and presumably more man pages would be written) if the markup language was switched to e.g. Markdown by default. For my own software, I am already using Pandoc to generate nroff input from Markdown.
I think so; producing high-quality printed manpages is useful, at least to me.
> the community of users is small
So tell your friends to use groff! :-D
> its capabilities are eclipsed by TeX
In what way? Yes, TeX can do complex mathematics better, but most documents that people want to publish don't terribly need complex math that much.
> and the language is quite arcane.
What specifically is 'arcane' about it, versus something like TeX or markdown?
> One could...argue that writing man pages would be much easier...if the markup language was switched to e.g. Markdown by default.
But then someone would have to rewrite the existing corpus of manpages, and as others have pointed out, using markdown loses some semantics.
I think keeping that functionality in pandoc is the right way to go.
I haven't hacked on groff, but I recently I did a whole bunch of work on the man2html program from the man tools. That code is extremely hacky, like you wouldn't believe!
http://www.kylheku.com/cgit/man/
I have it so that a man page can detect whether it's being compiled by groff or by man2html and re-target some of its macros.
That aforementioned large man page is here; the macros are upfront: http://www.kylheku.com/cgit/txr/tree/txr.1
HTML and PDF here: http://sourceforge.net/projects/txr/files/txr-104/
(The index and hyperlinks in the HTML are due to a post-processing pass, implemented in the "genman.txr" script.)
As an analogy to another software system, you wouldn't want to generate HTML from LaTeX by processing the DVI file.
What is needed is the high level macros of a specific package being recognized and translated to HTML at a high level.
However hacky, the man2html program does that (and I made it work better: it has better support for handling more sophisticated macros, and is less buggy. I likely won't invest any more time into it, however, and I'm not going anywhere near groff).
Unfortunately the -man macros (as opposed to the modern -mdoc macros) aren’t that good for conversion to other formats like HTML, because they’re by nature presentation‐focused. All major troff implementations support the -mdoc macros, though, and -mdoc is much better suited. It’s what I write all my manpages in these days (and it’s a drop‐in replacement—replace foo.1 written in -man with foo.1 written in -mdoc and groff, man, etc will handle it instantly). I also like to convert manpages from -man to -mdoc, or write new pages for programs that don’t have one. It gets a little exhausting to convert long pages like the one you linked, though.
Here’s some documentation on the format of -mdoc pages: http://mdocml.bsd.lv/man/mdoc.7.html
The long page that I wrote, though it is based on the old -man macros, is actually to a large extent based on its own macros which are retargettable.
As I started to polish the document for better PDF output, I needed to reach into more of the power of groff, while maintaining compatibility with man2html. That's when I started hacking on man2html to handle more of the troff language. I found that loops didn't work very well and there were issues with nested if/else and such.
Because the troff format was designed with the limitations on early 70's computers in mind and seem to be used exclusively for man pages. Why not upgrade to something that better correspond to how we actually code now (ie markdown)?
Remember that the worst bugs in the last couple of years have been in the code that nobody was looking at.
I haven't compared this with upstream though.
"The great strength of troff is the flexibility of the basic language and its programmability -- it can be made to do almost any formatting task." -- The UNIX Programming Environment, Brian W. Kernighan and Rob Pike.
Mandoc is very new and focuses on providing a complete solution for a system that uses manpages: it renders manpages in the terminal or to HTML on the fly, provides a database for semantic search of manuals, and is probably the second most common manpage renderer in common use (after Groff). It’s the default renderer on OpenBSD, FreeBSD, DragonFly BSD, NetBSD, Illumos, and Minix. Unlike the others, it’s not a complete troff implementation; it focuses on manpages (“mdoc”, “man”, “eqn”, and “tbl” macro sets).
Heirloom troff is descended from Sun’s troff, and focuses on nice typesetting supporting various PDF and OpenType features.
Plan 9 troff is, well, Plan 9’s troff, and is used by plan9port to render its own manpages.
There are a few other troff implementations (Neatroff, etc.), but these are the most widely distributed ones these days. I personally use Mandoc for everything except PDF output, for which I use Groff.
I have not seen a PDF made by mandoc that made me react that way. :-|
When money is changing hands with the expectation that software is maintained in good working order, you won't see abandonment like this. But when nobody is paying or getting paid, maintenance stops, regardless of whether the software is a key component of crypto on the internet or a fundamental part of the documentation of most Linux installations.
http://www.theguardian.com/technology/2014/apr/07/uk-governm...
The fact that someone might possibly be able to do something about it is a fundamental feature of open source software.