nicer help?
Closed this issue · 2 comments
help should have a description of what this tool is used for, and an example. look at the man pages for wget and curl. so instead of:
Retrieve and save IPFS objects.
maybe:
ipget - retrieve and save IPFS objects
ipget is a tool for non-interactive downloading of files or objects from IPFS to the
user's filesystem, similar to wget or curl. It supports /ipfs and /ipns paths. ipget
is meant to be used in scripts and pipelines.
or something.
Nice! I think you're 100% right: wget and curl do a great job in most of these regards.
I think we can do better than their usage output though -- theirs is very terse:
wget
stephen // ~ $ wget
wget: missing URL
Usage: wget [OPTION]... [URL]...
Try `wget --help' for more options.
curl:
stephen // ~ $ curl
curl: try 'curl --help' or 'curl --manual' for more information
We shouldn't mimick blindly here. I think something that offers a description like you said and common options is better usage output. This can be complemented with excellent man pages.
Let's not copy these tools' --help output though (check it out; it's a massive many-page dump). The scope of ipget shouldn't get so massive that the list of possible invocations becomes that bloated.
Summary:
- usage output that describes the tool's use, provides an example, and describes usage
- a great
manpage that gives background on IPFS, what multiaddresses are, includes full step-by-step examples, and any other context a brand new user would need to understand the tool (curl --manualdoes a great job; talks about what URLs are, etc) - should offer hooks throughout that invite the user to learn more about IPFS; act as a gateway into the IPFS community / suite of tools