docker man pages need some love
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 6.1k
- Forks
- 2.2k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 43
Description
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 https://github.com/docker/cli/pull/922
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in the docker-* man pages under man/ and compare their formatting with the man-pages(7) style guide and the example in pull request 922. Update the pages so options, values, literals, optional parts, separators, and angle brackets follow the stated rules; done means the affected pages consistently match those conventions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100