Write Unix manpages in Markdown with md2man

by TerminalPrgrmr • 14 years ago

59 29 14 years ago

rubynerd• 14 years ago

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

TerminalPrgrmr7• 14 years ago

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

hecticjeff• 14 years ago

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

TerminalPrgrmr7• 14 years ago

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

qubital• 14 years ago

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

dfc5• 14 years ago

"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

nknight• 14 years ago

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?

julian37• 14 years ago

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

antris• 14 years ago

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

dfc5• 14 years ago

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

TerminalPrgrmr7• 14 years ago

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

dfc5• 14 years ago

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.

limly• 14 years ago

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.

unimpressive4• 14 years ago

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.

TerminalPrgrmr7• 14 years ago

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

thristian3• 14 years ago

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.

unimpressive4• 14 years ago

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.

nwmcsween• 14 years ago

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

methoddk2• 14 years ago

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!

methoddk2• 14 years ago

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

TerminalPrgrmr7• 14 years ago

Hurray! Thanks. :)

TerminalPrgrmr7• 14 years ago

"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

dfc5• 14 years ago

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

Write Unix manpages in Markdown with md2man

Related Stories