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

61–67 of 67 posts

Re: Tell HN: Groff needs your help

#61

Post by anjbe »

cogburnd02 wrote: post #46
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.

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.

Re: Tell HN: Groff needs your help

#62

Post by anjbe »

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

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

Re: Tell HN: Groff needs your help

#63

Post by anjbe »

cogburnd02 wrote: post #59
anjbe wrote: post #42

Earlier quoted context omitted.

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

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…

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.

Re: Tell HN: Groff needs your help

#64

Post by anjbe »

lucb1e wrote: post #47
anjbe wrote: post #41

Earlier quoted context omitted.

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

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

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!

Re: Tell HN: Groff needs your help

#65

Post by kazinator »

cogburnd02 wrote: post #60
kazinator wrote: post #56

Earlier quoted context omitted.

The HTML from groff's HTML back-end is pretty much useless garbage.

Well, get into that code, and improve it! :-)

No thanks; that is broken by design. HTML is treated as a typesetter device, more or less, when what is needed is a semantic translation of the high level document structure.

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

Re: Tell HN: Groff needs your help

#66

Post by kazinator »

tomjen3 wrote: post #11

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

Does markdown have macros equal in power to those of troff?

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

Re: Tell HN: Groff needs your help

#67

Post by kazinator »

anjbe wrote: post #62
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.…

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

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.

Post reply on HN