man pages

[whyrusleeping]

Any real unixy tool worth its salt has verbose man pages, Personally, I love being able to just say 'man ThisFunctionImWorkingWith' and get help in my terminal.

There exist a few different solutions for generating man pages from godoc information, this will probably be good enough for us. (as long as they can do per function breakdowns!)
https://code.google.com/p/mango-doc/

[chriscool]

It would be nice if there was a way to easily generate HTML doc too.

Git uses Asciidoc to generate HTML and XML files and then Xmlto is used to generate man pages from xml files.

By the way, git help -m <command> displays the man page and git help -w <command> opens the HTML page in a browser. git help <command> by default displays the man page on Linux and OSX and opens the HTML page in a browser on Windows which is nice for Windows users.

[whyrusleeping]

@chriscool i always use git help -m by default, i love the attention to detail you guys have for documentation, and I want to strive for the same with ipfs.

[chriscool]

After googling a bit (see for example: http://serverfault.com/questions/109490/how-do-i-write-man-pages), it looks like some other possible solutions could be:

• ronn that can convert Markdown to man and HTML
• Pandoc that can convert from and to many different formats
• xmltoman that can convert XML to man and HTML
• yodl a special format that can be converted to man and HTML
• Zoem a special format that can be converted to man, HTML and other formats

[whyrusleeping]

Ideally, I would like to be able to use godoc to generate all other documentation types. That way, all of our documentation stays consistent across mediums.

[chriscool]

Yeah, it looks like godoc has an -html flag, so using godoc and mango together can work.

Also if we use Mango, we can still create HTML pages from the man pages as there are tools to do that like groff and man2html.

But anyway maybe we should check that the HTML output looks nice.

[whyrusleeping]

that would be a good first step, haha. Although, I think that godocs generated html looks quite nice, no need to convert man pages to html

[whyrusleeping]

closing old issues.

[jbenet]

we may still want real man pages someday -- agreed to close until then. (if people really need this poke us here!)

[anarcat]

poke.

[notslang]

+1 for man pages... (working on an Arch package to make installation easier, which traditionally comes with a man entry)

[jbenet]

we could generate them from the cli help

[whyrusleeping]

I'd love to have this... how does man work with subcommands?

[whyrusleeping]

It would be really cool to have a program/library that could accept one of the command objects from our commands lib and use it to generate a manpage.

[notslang]

@whyrusleeping: take a look at man git - that's a pretty well written manpage that includes subcommands

@jbenet: probably not. the man page is supposed to explain the commands and workings of the program in depth. it would be better to generate it from the full documentation.

[unbeatable-101]

Poke

[rampaq]

Are there any manpages, yet? It would be really nice to have everything in one place.