[README.md] Add detail description of oci-image-tool

[coolljt0725]

Signed-off-by: Lei Jitang [email protected]

[vbatts]

LGTM

[wking]

To avoid duplication, I'd rather link to the man pages and have the examples and such live in the man pages. For more background, see opencontainers/runtime-tools#47 and here.

[caniszczyk]

It's very useful to have this information in the README, we can have it in both locations.

[wking]

On Mon, Oct 24, 2016 at 08:55:12AM -0700, Chris Aniszczyk wrote:

It's very useful to have this information in the README…

Can you explain why? A line or two of context and then a link to the man page seems like it would be just as useful.

… we can have it in both locations.

Without a strong reason to duplicate the information, that just gives you two places to keep in sync when we have future updates.

[caniszczyk]

A lot people simply read the README, I'm fine with a quick summary of the available commands and maybe a quick example, which then links to the man page for more info.

[wking]

On Mon, Oct 24, 2016 at 09:19:10AM -0700, Chris Aniszczyk wrote:

A lot people simply read the README, I'm fine with a quick summary of the available commands and maybe a quick example, which then links to the man page for more info.

So we both agree on a line or two of summary and a man-page link (which is part of this current pull-request). In #5's c8c9708, I've submitted oci-image-tools(7) with one-line descriptions and references to per-tool man pages. This PR is doing something similar in the README, but also adding examples. This early in the ecosystem, I expect examples are going to be hard to keep current. But it's maintainer time to keep repeated examples in sync. If they feel that's a good use of their time, more power to 'em ;).

[xiekeyang]

I agree that customers want to find and read man pages conveniently, which are not linked to README.md yet.
IMO, it had better to set up man directory and put all command manual in it. In README.md, we should link to these man pages (as some popular repo done).
In future image-tool may include many commands, if we put all them in readme page, it will be a little hard to find what consumer want.
And I agree that we should avoid duplication, for updating usage easily.
Just personal view.

[vbatts]

please rebase

[coolljt0725]

@vbatts rebased

[coolljt0725]

It's redundant with #92 close