
Tell HN: Groff needs your help - cogburnd02
GNU Groff (which is probably doing the behind-the-scenes formatting work when you use man pages on GNU&#x2F;Linux) currently has no maintainer, and the most recent stable release was in 2013. Who would like to step up and help?
======
justincormack
OpenBSD replaced groff with mandoc[1] which is a much simpler program, once
you known that it is just for manpages not a typesetting system.

[1]
[http://undeadly.org/cgi?action=article&sid=20110314142734](http://undeadly.org/cgi?action=article&sid=20110314142734)

~~~
cogburnd02
> not a typesetting system.

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.

~~~
anjbe
You can do that with Mandoc too, although the quality of the PDF output is not
as nice. What makes Mandoc less of a typesetting system than Groff is that it
supports fewer macro sets (mdoc, man, eqn, and tbl, the macro sets commonly
used in manpages); Groff supports more (ms, me, mom…) because it’s a more
general typesetting system.

------
lucb1e
I'm going to be frank: why? I've recently looked into making my own manpage
and it's a pretty old looking system. The docs are not really clear but using
some examples and trial and error I got there. My point is though, why does it
need a maintainer? The system feels old enough to get deprecated instead of
keeping it alive, let alone bring out new releases.

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!

~~~
smutticus
Replacing man pages because 'they look old' is a terribly stupid idea.

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.

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

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

~~~
anjbe
> 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)

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

~~~
lucb1e
Okay, I didn't know all that. Perhaps groff is a better language than I was
aware of and there is sure something to say for keeping it available.

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

~~~
anjbe
> 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)

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+...](http://www.openbsd.org/cgi-
bin/man.cgi?query=Ft%3Dsize_t+-a+Fn~^str&sec=3&apropos=1)

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/...](http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-
current/man8/afterboot.8) 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!

------
zokier
I think the obsession with "being maintained" is somewhat unhealthy phenomenon
in the FOSS world. If the code works and does what you want then why would it
need constant fiddling and consistent stream of releases?

~~~
rhizome31
The code may need to be adapted to evolving environments. Security bugs might
be discovered. In this case I guess "being maintained" just means that someone
will react to such events if they happen.

~~~
lucb1e
Couldn't programmers from major GNU/Linux distributions be signed up for this
duty? They compile new OSes and if they want man pages (heck, who _doesn 't_
want man pages?) then it's also up to them to make it work in the new OS.
Security bugs can be forwarded to those people by Gnu (assuming they support
and host the project).

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

------
djeps
it doesn't look abandoned:
[http://git.savannah.gnu.org/cgit/groff.git](http://git.savannah.gnu.org/cgit/groff.git)

------
DanBC
The Groff Mission Statement looks interesting.

[http://www.gnu.org/software/groff/groff-mission-
statement.ht...](http://www.gnu.org/software/groff/groff-mission-
statement.html)

~~~
danieldk
The question is - do we really need the typesetting part? I had a troff phase
(bought some books) ten years ago. But the community of users is small, its
capabilities are eclipsed by TeX, and the language is quite arcane.

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.

~~~
cogburnd02
> do we really need the typesetting part?

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.

------
kazinator
I am the maintainer of a man page that turns into a 260+ page PDF document in
letter size.

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/](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](http://www.kylheku.com/cgit/txr/tree/txr.1)

HTML and PDF here:
[http://sourceforge.net/projects/txr/files/txr-104/](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.)

~~~
anjbe
Mandoc, which is what the BSDs and some other systems use for formatting
manpages, has very good HTML output. In fact, the program used to be named
“mdocml” because it was written to be a mdoc‐to‐HTML converter.

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](http://mdocml.bsd.lv/man/mdoc.7.html)

~~~
kazinator
I wonder how good is mandoc's handling of the troff language as such.

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.

------
tomjen3
Does it currently have any important bugs?

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)?

~~~
immita
If nobody is maintaining it, how can you tell it doesn't currently have any
important bugs?

Remember that the worst bugs in the last couple of years have been in the code
that nobody was looking at.

~~~
chm
Some people must have reported bugs since 2013. If not, then either it's
unused or bug free?

~~~
voltagex_
For one example: [https://bugs.debian.org/cgi-
bin/pkgreport.cgi?dist=unstable;...](https://bugs.debian.org/cgi-
bin/pkgreport.cgi?dist=unstable;package=groff)

I haven't compared this with upstream though.

------
stonogo
GNU Groff is terrible and the only reason it hasn't been replaced with a
superior implementation is that all the better versions are politically
incompatible with GNU. It's no surprise they're having a hard time finding
someone interested in effectively code-laundering and slapping a GPL on it.

~~~
thristian
Really? What are these better versions?

~~~
anjbe
There are a couple of other troff implementations in use today.

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.

~~~
cogburnd02
I've looked at the kind of PDFs heirloom troff can make, on an iPad, and my
eyes, just, wow. There aren't words. If Debian would put heirloom troff in its
base-install (along with, say, E.B Garamond or Junicode) instead of groff,
there'd probably be more people (1) making beautiful man pages, and (2)
viewing man pages graphically (with evince or another PDF viewer) than ever
before. It's not like there's a licensing problem, AFAICT.

I have not seen a PDF made by mandoc that made me react that way. :-|

~~~
anjbe
Yes, PDF output is one place where mandoc is not as good as groff/heirloom
yet. (The other major one being support for generic preprocessors and other
macro sets.) Mandoc works very well for terminal output, HTML output, and
semantic searching though.

------
immita
In which the fundamental problem with not paying for your open source software
is revealed.

~~~
gress
This is a fundamental problem with open source software.

~~~
immita
I'd limit it to FOSS that people don't pay for (directly or indirectly).

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.

~~~
lollipop331
oh you mean things like windows XP which people have paid for? I rest my case.

~~~
geofft
You're talking about the same Windows XP which people are currently paying for
and receiving support for?

[http://www.theguardian.com/technology/2014/apr/07/uk-
governm...](http://www.theguardian.com/technology/2014/apr/07/uk-government-
microsoft-windows-xp-public-sector)

