Write Unix manpages in Markdown with md2man | Hacker News Reader

Write Unix manpages in Markdown with md2man

github.com

59 pointsTerminalPrgrmr29 comments

Open articleView on HN

Pandoc http://johnmacfarlane.net/pandoc/index.html can do that and much more.

Also, Asciidoc (used e.g. for the git documentation) has been supporting this for a long while.

http://www.methods.co.nz/asciidoc/userguide.html#_manpage

"Much more" is a drastic understatement. Pandoc is awesome.

The only "convert X.txt to Y.txt" task that pandoc can not handle is X=wikipedia

I noticed that a few years ago and found it surprising but figured it would show up soon. Is there a technical reason it hasn't, or just lack of sufficient motivation an anyone's part?

Apparently wikipedia's format is a pain to parse. I think jgm posts here as fiddlosopher he is the best source for the gory details...

But there is definitely sufficient motivation just google "convert wikipedia to" for some examples. I think that the arcane syntax is a big lockin factor with large wikipedia based sites...

There is a ticket for it: https://github.com/jgm/pandoc/issues/388

Pandoc is indeed excellent. I suggest that anyone needing to write a man page just write it in Markdown and -- if a man page is necessary -- have Pandoc convert it.

"Write programs that do one thing and do it well." --Doug McIlroy

Pandoc does, it converts text from one format to another and it does it superbly...

Nobody was attacking you or your project. They are simply speaking about tools with similar uses.

Thanks for clarifying. Defensive instincts engage when one's pet project fades from the spotlight on its own stage. You're right about Pandoc fulfilling my quoted aspect of Unix philosophy; I realized it later but was too proud to admit it. :)

Funny how I'm instantly repulsed to try it because it's not a GitHub link.

The funnier part is that its actually distributed via github. Sorry not the troll food you were looking for.

That looks kinda cool, that it's mountable as a Redcarpet renderer

One feature I would love to see in RubyGems is man pages for gems, because man pages are underused and I can't go and look Github documentation up quickly as I have to break out of my dev box and go and open Chrome and look it up there

I would still use https://github.com/rtomayko/ronn, simply for the pretty HTML pages though

Ronn's HTML output is indeed pretty, but I cannot say the same of its input. In particular, I find md2man's syntax for tagged paragraphs (all lines indented by +2 spaces except the first line) to be less intrusive and easier to maintain than Ronn's (list items that begin with boldface and end with a colon, followed by +2 space indented lines).

For gem man pages I recommend checking out http://defunkt.io/gem-man/

One drawback is that it doesn't follow the standard $MANPATH directory structure (man/manX/Y.X where X is the section number and Y is the manual page) but instead uses a single flattened directory (man/Y.X).

I filed an issue about this here: https://github.com/defunkt/gem-man/issues/8

Post something cool you've been working on to HN:

Have everyone shit on it because something similar exists.

Down with competition! Down with creating!

Nobody is "shitting" on his project. Ynnv said it best the last time you made a comment like this.

"HN is not your mom's fridge. If you want unconditional validation, ask someone who cares about you. I expect that anything posted here will be fixed with fire, because that's a valuable service that only skilled peers can provide. Annoying less is wasting everyone's time."

http://news.ycombinator.com/item?id=3653331

"when you don't create things, you become defined by your tastes rather than ability. your tastes only narrow & exclude people. so create." --Why The Lucky Stiff

Addendum: your app is pretty cool and I like it. Keep making cool stuff.

Hurray! Thanks. :)

I'd rather see a system that replaces man entirely. Maybe with a modern markup language like XML, Markdown, or HTML.

A system that makes documentation less painful by letting me connect to a server to downnload man pages potentially written by people other than the project maintainers. I'm not sure how you would match man pages to programs, but it would be preferable to the current situation where unless the project maintainers don't see docs as an afterthought, the on-line doc system gives you sub-par information.

You could also add radical concepts like hyperlinks. And you could fix the broken linear paging metaphor. Which doesn't work for documentation more than about a page or two long.

As for backwards compatibility. Symlink man to the new system. Done.

Somebody already came up with a system to replace man entirely. It was designed to use a tried-and-trusted document format, it added hyperlinks, interactive navigation, and a unified hierarchy for all documentation in the system.

It's called GNU TeXInfo, and it's terrible. Even with a third-party Info viewer like pinfo, it's still clunky and awkward and difficult to find things. The bash manpage may be a thousand pages long, but I can search for "BUILTIN" or "REDIRECTION" and pretty quickly find what I'm looking for, without much fuss.

The problem with texinfo has nothing to do with it's document format, hyperlinks, interactive navigation, or a unified hierarchy. It does however have everything to do with the info reader being totally unusable. From the texinfo documentation (Read through the info reader.):

" This all probably seems insultingly simple so far, but _please don't_ start skimming. Things will get complicated soon enough! Also, please do not try a new command until you are told it is time to. You could make Info skip past an important warning that was coming up."

It's a bloody text reader. It shouldn't ever get "complicated". For that matter, it has the most obnoxious scrolling ever. It's hard to tell where one page starts and the other ends. (Contrast with: Less.) I shouldn't have to memorize keyboard shortcuts to navigate. (At least not in a system that wants to be used and supported by anyone who isn't the most hardcore of users.)

On top of that, part of the reason I can't use the texinfo reader is because it very often doesn't have the "info" I want. And just takes me to the top node or whatever. So let me go ahead and append to "As for backwards compatibility". The system should also be able to take and render man pages as though you were using man, because expecting 30 years of projects to all move to any new system is ridiculous. And supporting man page format really shouldn't be that hard.

The closest thing to what I'm thinking of is something like the links web browser. Which still falls short. And with all that in mind, it's not like I expect anyone else to do it. Thats probably like the first rule of project ideas. Unless you do it, it won't be done the way you want it to be.

For what it's worth I thought about what I said and noticed some flaws. (Which I would correct through an edit but enough time has elapsed so that I can no longer do so.)

You mentioned pinfo, which you say still sucks. That probably IS a fault of the document format. (Which can be outputted to HTML, XML, DVI, etc, but is not itself a widely used text format.) After all, it was designed for a broken reader. And if you design something for something that's already ill designed, the end result is usually something as bad as or worse than the original article.

You also mentioned search. The thing about search is that even if the bash documentation was split into multiple parts, it's still a text file. So you could have your hypothetical man+ reader do something like:

  cat /wherever/your/docs_are_stored/* | grep '-A 100' '-e search_term'

And then let you go through the matches to find what you want.

For what it's worth, the "pinfo" tool I mentioned works like the links web browser, searches texinfo documentation and falls back to manpages if it can't find relevant docs. It's definitely the Least Bad way to browse info documents by a significant margin... and yet, I keep using man.

Thats worth quite a bit. As a result of this I am going to have to seriously reconsider my position. I'll try using pinfo for a while (Since it DOES use a curses library.) and see if it's what I had in mind. If so, and it does suck, I'll drop large portions of the idea. The main change I'm interested in is the "networked man pages" concept anyway.

Troff is domain specific and even worse than info, man has one good thing going for it - it's a simple text stream.

*roff is domain-specific in that it's a typesetting system, like TeX but much, much simpler. It has output drivers for rendering to PostScript, ASCII output with overstrike (as emulated by, say, less(1)), and in modern versions, even UTF-8 and HTML. I have production code at $EMPLOYER, for instance, that uses it to generate properly-formatted tables in plain-text emails (easier than building HTML and rendering it with elinks, since groff is already installed).

md2man's input is already Markdown and its Roff output already supports hyperlinks: https://github.com/sunaku/md2man/blob/master/test/md2man/rof...

Reply on news.ycombinator.com