Hacker News Reader

Comment by immita | Hacker News Reader

Well... manpages are still very much alive and widely used, and they're so prevalent that moving to something new is a nearly ridiculous requirement. Half the things with manpages in the wild are probably themselves not maintained. Now you have two problems.

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?

View on HN

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.

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.

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 with you. Like I replied to another post:

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

Reply on news.ycombinator.com