Hacker News Reader

Comment by tomjen3 | Hacker News Reader

Why not format manpages as markdown?

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.

View on HN

markdown isn't semantic. roff macros allow one to clearly specify that function arguments (Fa) and command line flags (Fl) are different things, even if they render similarly.

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.

ASCII is not the only possible output format, and yes, semantic search is useful.

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.

> While I like the venerable look they have, those books aren't what you use daily to document yourself on how your machine works.

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

As others have noted, there is a semantic difference between Markdown and roff. But if you really want to write them in Markdown, you can with ronn: http://rtomayko.github.io/ronn/ Ronn also supports outputting to HTML.

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 successfully convincing the diverse Linux ecosystems they should jump onboard.

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.

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?

But existing pages would be served with the already existing groff, right? Software doesn't rot, so the existing software will continue to work in the future.

Software doesn't rot but libc changes...

ikiwiki's source code contains a rudimentary mdwn2man program. It doesn't handle the majority of markdown, but it works for simple pages.

Reply on news.ycombinator.com