@dnephin failures are real

@dnephin Do you know why we need go-md2man in main Dockerfile?

LGTM

hum, make manpages failed for me :

[ERROR] Failed to set version on github.com/spf13/cobra to dc45219961f875acff5ee07ed263e5dc19e0c5f1: exit status 128
[INFO] Setting version for github.com/spf13/viper to c1ccc378a054ea8d4e38d8c67f6938d4760b53dd.
[INFO] Setting version for golang.org/x/sys to 62bee037599929a6e9146f29d10dd5208c43507d.
[INFO] Setting version for gopkg.in/yaml.v2 to a83829b6f1293c91addabc89d0571c246397bbf4.
An Error has occurred
The command '/bin/sh -c glide install && mv vendor src' returned a non-zero code: 2

I was waiting for the spf13/cobra PR (which included some bug fixes for this) to get merged before tagging. I has been merged now, so I'll update the sha here.

Fixed the tag. I'm using v1.3 as the version now.

I think the representation of options with arguments in the synopsis is wrong.
Given that expressions inside of brackets are optional, the general syntax of an option with a mandatory argument should be

[--option[=]value]

in order to describe both legal syntax variants --option value and --option=value.

Here is an example from the generated man pages:

[--net[="bridge"]]

This means that --net=bridge and --net are both valid argument expressions, which is not true:

$ docker run --net
flag needs an argument: --net

The wrong syntax is also used in most current static man pages, so I understand why the generated output picked up this syntax. This is a good moment to tidy this up.

Please ignore my previous comment.
I did not notice that only selected commands have been ported so far and picked a non-generated one.

That's really awesome 👍 LGTM (cc @tianon @SvenDowideit who might be interested too).

LGTM - we'll want to consume this into the cli docs eventually too

I'm still a bit on the fence on this one. I'm happy with it being generated
automatically, but on the other hand, there's some things "attached" to it.
I was writing down some things, but not finished, so I'll paste my quick notes here;

• making "documentation" PR's becomes more difficult; to make
  changes to this part of the documentation now requires contributors
  to touch the actual code
• related to the above; we still have to maintain the online documentation
  /reference (which has a lot of the same content). Can we still copy/paste
  between the Markdown files and the embedded docs (looking at it,
  back-tics will break?)

I kinda like that but I'm wondering how to handle more complicated manpages, like docker-ps.1.md or docker-run.1.md where we have longer description for some/most of the flags than what we have/describe in the code (and thus in --help). For example the list of possible --filter for ps (or --format) or the big description for --cpu-shares in run, …

There is also some manpages where we have an EXAMPLES section that should be taken care of.

So I'm torn 😅. I like that but I feel we should see how to handle these more complex command manpages before doing anything.

If we need additional text, we can add it to the description. It's not uncommon for man pages to have sections for things that require more explanation. If we really want a more verbose man page for some commands we can keep the md around for those. There is always an override from .md file.

The default should really be automatic generation from the source. If that's insufficient for some flags or commands we have the ability to extend the generated docs, but I think that is more the exception than the rule.

For example the list of possible --filter for ps

This is an excellent example. We can document that by adding the following section to the description:

## Filters

exited=<int>
  filter to containers which have an exit code of <int>
...

Putting this detail into a section in the description gives us more space to describe things.

There is also some manpages where we have an EXAMPLES section

cobra supports the example section as well. I use it in this PR for volume rm. In the end this is just another section, so it could just as easily go into the description.

I feel we should see how to handle these more complex command manpages before doing anything.

Hopefully that covers it, but if not I'd be happy to provide more examples.

@thaJeztah any outstanding concerns on this?

@dnephin I still have concerns, but perhaps the best way is to test/try it and see if it works well in our workflow. We can evaluate after a while. So "lgtm"

@dnephin really appreciated though, please don't take it the wrong way 👍

Alright let's go for it then 😇 LGTM

Not sure if we want to cherry-pick this.

@tiborvass @thaJeztah Adding the label, but up to you!