refactor and expand documentation

[anarcat]

this is a meta ticket covering many issues, taken out of #590.

• straightforward ipfs -h
• comprehensive ipfs --help -- in progress
• command reference in website -- sort of there: http://ipfs.io/docs/commands
• api reference in website -- not yet there: http://ipfs.io/docs/api
• examples -- started: http://ipfs.io/docs/examples <-- want a hundred!
• man pages generated from the ipfs --help output eventually (man pages #275)

The website can be edited here: https://github.com/protocol/websites/tree/master/ipn.io/src/ipfs.io

[anarcat]

i personnally think that ipfs --help and man pages should be distinct:

• ipfs -h - short, oneline usage?
• ipfs --help - longer options, one paragraph
• man ipfs - indepth discussion, design, security, see also, etc

or at least, the ipfs --help documentation should be expanded much more before it's actually good manpage material. note that, for example, git commit --help actually invokes man, and not the other way around. the manpages themselves are generated from markdown, using a rather convoluted process with asciidoc.

[notslang]

-h is just an alias for --help. Other than that, you're right... the man page should be full documentation for the command.

[whyrusleeping]

@RichardLitt could you go through this and close it if its been mostly addressed?

[RichardLitt]

I think this is being tracked elsewhere.