

Write Unix manpages in Markdown with md2man - TerminalPrgrmr
https://github.com/sunaku/md2man#readme

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

~~~
dfc
"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
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?

~~~
dfc
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>

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

~~~
hecticjeff
For gem man pages I recommend checking out <http://defunkt.io/gem-man/>

~~~
TerminalPrgrmr
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>

------
methoddk
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!

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

~~~
TerminalPrgrmr
Hurray! Thanks. :)

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

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

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

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

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

