6 ms·

Write Unix manpages in Markdown with md2man

59 points by TerminalPrgrmr 15y ago

rubynerd 15y 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 https://github.com/rtomayko/ronn, simply for the pretty HTML pages though
- TerminalPrgrmr 15y 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 15y ago
  For gem man pages I recommend checking out http://defunkt.io/gem-man/ http://defunkt.io/gem-man/
  - TerminalPrgrmr 15y 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 https://github.com/defunkt/gem-man/issues/8
qubital 15y ago
Pandoc http://johnmacfarlane.net/pandoc/index.html http://johnmacfarlane.net/pandoc/index.html can do that and much more.
- dfc 15y 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 15y 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?
    - dfc 15y ago
      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 https://github.com/jgm/pandoc/issues/388
- julian37 15y 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 http://www.methods.co.nz/asciidoc/userguide.html#_manpage
- antris 15y ago
  Funny how I'm instantly repulsed to try it because it's not a GitHub link.
  - dfc 15y ago
    The funnier part is that its actually distributed via github. Sorry not the troll food you were looking for.
- TerminalPrgrmr 15y ago
unimpressive 15y 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.
- TerminalPrgrmr 15y ago
  md2man's input is already Markdown and its Roff output already supports hyperlinks: https://github.com/sunaku/md2man/blob/master/test/md2man/roff_test.rb#L306-344 https://github.com/sunaku/md2man/blob/master/test/md2man/rof...
- thristian 15y 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.
  - unimpressive 15y 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.
methoddk 15y 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!
- methoddk 15y ago
  Addendum: your app is pretty cool and I like it. Keep making cool stuff.
  - TerminalPrgrmr 15y ago
    Hurray! Thanks. :)
- TerminalPrgrmr 15y 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
- dfc 15y 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 http://news.ycombinator.com/item?id=3653331

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 https://github.com/rtomayko/ronn, simply for the pretty HTML pages though

TerminalPrgrmr 15y 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 15y ago
For gem man pages I recommend checking out http://defunkt.io/gem-man/ http://defunkt.io/gem-man/
- TerminalPrgrmr 15y 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 https://github.com/defunkt/gem-man/issues/8

qubital 15y ago

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

dfc 15y 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 15y 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?
  - dfc 15y ago
    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 https://github.com/jgm/pandoc/issues/388
julian37 15y 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 http://www.methods.co.nz/asciidoc/userguide.html#_manpage
antris 15y ago
Funny how I'm instantly repulsed to try it because it's not a GitHub link.
- dfc 15y ago
  The funnier part is that its actually distributed via github. Sorry not the troll food you were looking for.
TerminalPrgrmr 15y ago

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

TerminalPrgrmr 15y ago
md2man's input is already Markdown and its Roff output already supports hyperlinks: https://github.com/sunaku/md2man/blob/master/test/md2man/roff_test.rb#L306-344 https://github.com/sunaku/md2man/blob/master/test/md2man/rof...
thristian 15y 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.
- unimpressive 15y 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.

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

methoddk 15y ago
Addendum: your app is pretty cool and I like it. Keep making cool stuff.
- TerminalPrgrmr 15y ago
  Hurray! Thanks. :)
TerminalPrgrmr 15y 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
dfc 15y 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 http://news.ycombinator.com/item?id=3653331