Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Tell HN: Groff needs your help

news.ycombinator.com

Post reply on HN
Print view View original

41–50 of 67 posts

Re: Tell HN: Groff needs your help

#41

Post by anjbe »

lucb1e wrote: post #36
smutticus wrote: post #28

Earlier quoted context omitted.

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…

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

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

Re: Tell HN: Groff needs your help

#42

Post by anjbe »

thristian wrote: post #33
stonogo wrote: post #5

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.

Really? What are these better versions?

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.

Re: Tell HN: Groff needs your help

#43

Post by vertex-four »

fortytw2 wrote: post #18
immita wrote: post #13

Earlier quoted context omitted.

I agree that might be a good choice for a more modern alternative, but it still doesn't solve the problem of existing manpages. You could cleverly upconvert on the fly of course, but that's basically the same thing as keeping groff around, except with the added friction of informing everyone that they should be using Markdown now, with new tooling and conventions. Don't underestimate the marketing costs of successful…

Well, for one time only, you can convert all (make a little converter) existing groff to markdown and then stop supporting groff at all.

This works fine if you're working on a cathedral (one of the BSDs or UNIXes, for example), not so much if you're trying to work with the bazaar that is the Linux software ecosystem. What's your plan? Submit a patch for every piece of software written in the past 15 years?

Re: Tell HN: Groff needs your help

#44

Post by 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/

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

Re: Tell HN: Groff needs your help

#45

Post by cogburnd02 »

kazinator wrote: post #44

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

Keep in mind, groff can itself generate HTML. I think it may need some pre- and post-processing to do it, though too, because (I think) what are links in the HTML version end up being footnotes in the pdf/ps version. Could be wrong about that, though.

Re: Tell HN: Groff needs your help

#46

Post by cogburnd02 »

justincormack wrote: post #17

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

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

Re: Tell HN: Groff needs your help

#47

Post by lucb1e »

anjbe wrote: post #41
lucb1e wrote: post #36

Earlier quoted context omitted.

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

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

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

Re: Tell HN: Groff needs your help

#48

Post by rakoo »

mseepgood wrote: post #39
rakoo wrote: post #26

Earlier quoted context omitted.

Is this really needed in a manpage, though ? AFAIK manpages are ASCII document created with any variation of troff/nroff/groff and piped into less -s. There is no need for any semantical distinction if display is the same, since the best interaction you can have is searching for something.

These are manpages http://imgur.com/a/JZfTr

While I like the venerable look they have, those books aren't what you use daily to document yourself on how your machine works. I was speaking about those manpages we use when we don't know what the letters are for in the itemized output of rsync, for instance.

Re: Tell HN: Groff needs your help

#49

Post by cogburnd02 »

smutticus wrote: post #28
lucb1e wrote: post #9

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,…

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…

> How about we replace them because there is something better? Or because they no longer fill a need?

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.

Re: Tell HN: Groff needs your help

#50

Post by geofft »

lollipop331 wrote: post #27
immita wrote: post #6

Earlier quoted context omitted.

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 installati…

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

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

Post reply on HN