docker man pages need some love

[kolyshkin]

Executive summary: there are a number of docker-* man pages available under man/, they all need some love.

Formatting

For one thing, formatting/typesetting needs to be cleaned up. The rules (from the top of my head) are:

• literals (like option names, literal values like true or false, or examples) should be bold;
• variable parts (like option values to be substituted) should be italic (note this is frequently rendered as underlined when viewing a man page in a terminal);
• optional parts should be enclosed into square brackets;
• in general, = between the --option and the value should be omitted;
• angle brackets (like <value>) should not be used.

For more rules and examples, check man-pages(7).

For example, here's the correct formatting:

--memory-limit value[SUFFIX]

Sets the memory limit. SUFFIX is optional and can be one of b (bytes), k (kilobytes), m
(megabytes), or g (gigabytes).

Source:

**--memory-limit** *value*[*SUFFIX*]

Sets the memory limit. *SUFFIX* is optional and can be one of
**b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes).

As an example of such work, please see #922

[chriscoffee]

I'm happy to take this. I'll start on it tomorrow.

[silvin-lubecki]

Thank you for taking care of this @chriscoffee !

[kolyshkin]

@chriscoffee I suggest start with a small patch, fixing just a few things first. Don't try to fix all at once.

[chriscoffee]

@chriscoffee I suggest start with a small patch, fixing just a few things first. Don't try to fix all at once.

Sure, I'll put in some smaller PRs. Thanks for the advice 👍

[Joshua-Rowe]

I was thinking about working on this during the weekend. Can anyone confirm that I would not be duplicating work etc. I could not find an open PR from @chriscoffee or a branch on his fork. Not sure if there are guidelines with deciding when someone else can work on something claimed by another from a quick skim thorugh the guidelines. Thanks!

[chriscoffee]

@Joshua-Rowe feel free to take this, apologies. I got some initial work done on it then got sidetracked with other things.

[Joshua-Rowe]

I took a few hours here and there over the weekend to familiarize myself with man page concepts and formatting, building the Docker man pages, and looking at how generate.go does its work. I looked the Docker man pages and compared them to ones on my Mac (such as tar, vim, etc.), and then I scoped out a reasonable approach to modify what's currently in the man directory. I think I am going to start with docker-build.1.md as it is the smaller of the MD files and seek to fix the above bullet points and see if there is anything else on man7 and other internet resources that can also be addressed.

Look for a PR soon with first changes.

[thaJeztah]

Related discussion in moby/moby#25615

Curious what the convention is in manpages to indicate required values, and if different kind of values are allowed. Or would that have to be explained in the description? Thinking of;

  -u, --user string                    Username or UID (format: <name|uid>[:<group|gid>])

But also the -p / --publish syntax (which is quite involved); moby/moby#27917 (comment)

description	example
publish a container's port to an ephemeral port on the host	-p 80
publish a container's port to a specific port on the host	-p 1234:80
publish a container's port to an ephemeral host port within a specified range	-p 8000-9000:80
publish a range of container ports to ephemeral ports on the host	-p 8000-8010
publish a range of container ports to a range of host ports	-p 8000-8010:9000-9010
specify the protocol to publish (udp, tcp)	-p 80/udp, -p 1234:80/udp, -p 8000-9000:80/udp, -p 8000-8010/udp, -p 8000-8010:9000-9010/udp
publish the port only on specific IP-addresses	-p 127.0.0.1:90:80 -p 192.168.202.120:90:80
publish a container port on an ephemeral port on a specific IP-address	-p 127.0.0.1::80 (double colon means value omitted)
publish a container port to multiple ephemeral ports on a specific IP-address	-p 127.0.0.1::80 -p 127.0.0.1::80

[ppxl]

Hi All,

I stumbled over this issue when I wanted to add a different issue for a manpage typo in docker-image-load. While I am more than happy to provide a PR I am unsure if this issue would fit better?

If you could provide some guidance in this situation, I'd be happy to hear from you.

[ppxl]

I am just realizing the last active comment was half a year ago. Is this thing still on? 🤔 I could jump in because I am using the cli manpages a lot for reference.

I'll be happy to take this task, so I could start somewhere. I'll need a little guidance at first.