From 6566f5ff2c416cba0fdb2cfe84a9914704aed3bf Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Mon, 12 Feb 2018 11:41:18 -0800 Subject: [PATCH 1/2] Bump cpuguy83/go-md2man to v1.0.8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The biggest motivation for this is proper table rendering; in the old version it was broken so tables were not rendered at al (i.e. anything that was put into table was lost, for example, description of LOG_* log levels in dockerd(8) page). This also fixes lists, including nested lists. This fixes the description of behavior in docker-cp(1) which is rendered as a tree: BEFORE: ``` Assuming a path separator of /, a first argument of SRC_PATH and second argument of DEST_PATH, the behavior is as follows: · SRC_PATH specifies a file · DEST_PATH does not exist · the file is saved to a file created at DEST_PATH · DEST_PATH does not exist and ends with / · Error condition: the destination directory must exist. ... ``` AFTER: ``` Assuming a path separator of /, a first argument of SRC_PATH and second argument of DEST_PATH, the behavior is as follows: · SRC_PATH specifies a file · DEST_PATH does not exist · the file is saved to a file created at DEST_PATH · DEST_PATH does not exist and ends with / · Error condition: the destination directory must exist. ... ``` Manually checking the diff between the man pages generated by the old and the new version, there are no changes other than the indentation (.RS/.RE) for lists, and proper formatting for tables. Formatted man pages also look decent, nothing seems broken. Signed-off-by: Kir Kolyshkin --- vendor.conf | 2 +- .../github.com/cpuguy83/go-md2man/README.md | 7 +- .../github.com/cpuguy83/go-md2man/md2man.go | 4 +- .../cpuguy83/go-md2man/md2man/md2man.go | 1 + .../cpuguy83/go-md2man/md2man/roff.go | 79 ++++++++++--------- 5 files changed, 50 insertions(+), 43 deletions(-) diff --git a/vendor.conf b/vendor.conf index fb8fddd8f6fe..d04b094a336a 100755 --- a/vendor.conf +++ b/vendor.conf @@ -2,7 +2,7 @@ github.com/agl/ed25519 d2b94fd789ea21d12fac1a4443dd3a3f79cda72c github.com/Azure/go-ansiterm d6e3b3328b783f23731bc4d058875b0371ff8109 github.com/containerd/continuity 35d55c5e8dd23b32037d56cf97174aff3efdfa83 github.com/coreos/etcd v3.2.1 -github.com/cpuguy83/go-md2man a65d4d2de4d5f7c74868dfa9b202a3c8be315aaa +github.com/cpuguy83/go-md2man v1.0.8 github.com/davecgh/go-spew 346938d642f2ec3594ed81d874461961cd0faa76 github.com/docker/distribution edc3ab29cdff8694dd6feb85cfeb4b5f1b38ed9c github.com/docker/docker e11bf870a3170a1d2b1e177a0d7ccc66200bd643 diff --git a/vendor/github.com/cpuguy83/go-md2man/README.md b/vendor/github.com/cpuguy83/go-md2man/README.md index b7aae65d25e4..29ed7c9e9f51 100644 --- a/vendor/github.com/cpuguy83/go-md2man/README.md +++ b/vendor/github.com/cpuguy83/go-md2man/README.md @@ -12,7 +12,10 @@ Uses blackfriday to process markdown into man pages. ### How to contribute -We use [govend](https://github.com/govend/govend) for vendoring Go packages. +We use [dep](https://github.com/golang/dep/) for vendoring Go packages. +See dep documentation for how to update. -How to update dependencies: `govend -v -u --prune` +### TODO +- Needs oh so much testing love +- Look into blackfriday's 2.0 API diff --git a/vendor/github.com/cpuguy83/go-md2man/md2man.go b/vendor/github.com/cpuguy83/go-md2man/md2man.go index 8f6dcdaedfeb..c35dd3352e06 100644 --- a/vendor/github.com/cpuguy83/go-md2man/md2man.go +++ b/vendor/github.com/cpuguy83/go-md2man/md2man.go @@ -24,7 +24,7 @@ func main() { os.Exit(1) } } - defer inFile.Close() + defer inFile.Close() // nolint: errcheck doc, err := ioutil.ReadAll(inFile) if err != nil { @@ -41,7 +41,7 @@ func main() { fmt.Println(err) os.Exit(1) } - defer outFile.Close() + defer outFile.Close() // nolint: errcheck } _, err = outFile.Write(out) if err != nil { diff --git a/vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go b/vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go index 8f44fa155064..af62279a6154 100644 --- a/vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go +++ b/vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go @@ -4,6 +4,7 @@ import ( "github.com/russross/blackfriday" ) +// Render converts a markdown document into a roff formatted document. func Render(doc []byte) []byte { renderer := RoffRenderer(0) extensions := 0 diff --git a/vendor/github.com/cpuguy83/go-md2man/md2man/roff.go b/vendor/github.com/cpuguy83/go-md2man/md2man/roff.go index b8cea1c73ea7..8c29ec68738a 100644 --- a/vendor/github.com/cpuguy83/go-md2man/md2man/roff.go +++ b/vendor/github.com/cpuguy83/go-md2man/md2man/roff.go @@ -9,10 +9,12 @@ import ( "github.com/russross/blackfriday" ) -type roffRenderer struct{} - -var listCounter int +type roffRenderer struct { + ListCounters []int +} +// RoffRenderer creates a new blackfriday Renderer for generating roff documents +// from markdown func RoffRenderer(flags int) blackfriday.Renderer { return &roffRenderer{} } @@ -55,7 +57,7 @@ func (r *roffRenderer) BlockQuote(out *bytes.Buffer, text []byte) { out.WriteString("\n.RE\n") } -func (r *roffRenderer) BlockHtml(out *bytes.Buffer, text []byte) { +func (r *roffRenderer) BlockHtml(out *bytes.Buffer, text []byte) { // nolint: golint out.Write(text) } @@ -86,19 +88,20 @@ func (r *roffRenderer) HRule(out *bytes.Buffer) { func (r *roffRenderer) List(out *bytes.Buffer, text func() bool, flags int) { marker := out.Len() - if flags&blackfriday.LIST_TYPE_ORDERED != 0 { - listCounter = 1 - } + r.ListCounters = append(r.ListCounters, 1) + out.WriteString("\n.RS\n") if !text() { out.Truncate(marker) return } + r.ListCounters = r.ListCounters[:len(r.ListCounters)-1] + out.WriteString("\n.RE\n") } func (r *roffRenderer) ListItem(out *bytes.Buffer, text []byte, flags int) { if flags&blackfriday.LIST_TYPE_ORDERED != 0 { - out.WriteString(fmt.Sprintf(".IP \"%3d.\" 5\n", listCounter)) - listCounter += 1 + out.WriteString(fmt.Sprintf(".IP \"%3d.\" 5\n", r.ListCounters[len(r.ListCounters)-1])) + r.ListCounters[len(r.ListCounters)-1]++ } else { out.WriteString(".IP \\(bu 2\n") } @@ -118,11 +121,24 @@ func (r *roffRenderer) Paragraph(out *bytes.Buffer, text func() bool) { } } -// TODO: This might now work func (r *roffRenderer) Table(out *bytes.Buffer, header []byte, body []byte, columnData []int) { - out.WriteString(".TS\nallbox;\n") - + out.WriteString("\n.TS\nallbox;\n") + + maxDelims := 0 + lines := strings.Split(strings.TrimRight(string(header), "\n")+"\n"+strings.TrimRight(string(body), "\n"), "\n") + for _, w := range lines { + curDelims := strings.Count(w, "\t") + if curDelims > maxDelims { + maxDelims = curDelims + } + } + out.Write([]byte(strings.Repeat("l ", maxDelims+1) + "\n")) + out.Write([]byte(strings.Repeat("l ", maxDelims+1) + ".\n")) out.Write(header) + if len(header) > 0 { + out.Write([]byte("\n")) + } + out.Write(body) out.WriteString("\n.TE\n") } @@ -132,24 +148,30 @@ func (r *roffRenderer) TableRow(out *bytes.Buffer, text []byte) { out.WriteString("\n") } out.Write(text) - out.WriteString("\n") } func (r *roffRenderer) TableHeaderCell(out *bytes.Buffer, text []byte, align int) { if out.Len() > 0 { - out.WriteString(" ") + out.WriteString("\t") } - out.Write(text) - out.WriteString(" ") + if len(text) == 0 { + text = []byte{' '} + } + out.Write([]byte("\\fB\\fC" + string(text) + "\\fR")) } -// TODO: This is probably broken func (r *roffRenderer) TableCell(out *bytes.Buffer, text []byte, align int) { if out.Len() > 0 { out.WriteString("\t") } + if len(text) > 30 { + text = append([]byte("T{\n"), text...) + text = append(text, []byte("\nT}")...) + } + if len(text) == 0 { + text = []byte{' '} + } out.Write(text) - out.WriteString("\t") } func (r *roffRenderer) Footnotes(out *bytes.Buffer, text func() bool) { @@ -196,7 +218,7 @@ func (r *roffRenderer) Link(out *bytes.Buffer, link []byte, title []byte, conten r.AutoLink(out, link, 0) } -func (r *roffRenderer) RawHtmlTag(out *bytes.Buffer, tag []byte) { +func (r *roffRenderer) RawHtmlTag(out *bytes.Buffer, tag []byte) { // nolint: golint out.Write(tag) } @@ -217,25 +239,6 @@ func (r *roffRenderer) Entity(out *bytes.Buffer, entity []byte) { out.WriteString(html.UnescapeString(string(entity))) } -func processFooterText(text []byte) []byte { - text = bytes.TrimPrefix(text, []byte("% ")) - newText := []byte{} - textArr := strings.Split(string(text), ") ") - - for i, w := range textArr { - if i == 0 { - w = strings.Replace(w, "(", "\" \"", 1) - w = fmt.Sprintf("\"%s\"", w) - } else { - w = fmt.Sprintf(" \"%s\"", w) - } - newText = append(newText, []byte(w)...) - } - newText = append(newText, []byte(" \"\"")...) - - return newText -} - func (r *roffRenderer) NormalText(out *bytes.Buffer, text []byte) { escapeSpecialChars(out, text) } From 0d9bd33babd1c138597b14c86e91882ae433426d Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Mon, 12 Feb 2018 12:43:24 -0800 Subject: [PATCH 2/2] man/docker-run.1.md: --restart, --ipc, --network options Describe the possible values for `--restart`, `--ipc`, and `--network` options. While at it, improve formatting for `--name` options arguments. Signed-off-by: Kir Kolyshkin --- man/docker-run.1.md | 55 +++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/man/docker-run.1.md b/man/docker-run.1.md index 66f482101cf5..0dfcae8ebc6e 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -342,9 +342,19 @@ redirection on the host system. It can only be used in conjunction with **--network** for user-defined networks **--ipc**="" - Default is to create a private IPC namespace (POSIX SysV IPC) for the container - 'container:': reuses another container shared memory, semaphores and message queues - 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. + Sets the IPC mode for the container. The following values are accepted: + +| Value | Description | +|:---------------------------|:----------------------------------------------------------------------------------| +| (empty) | Use daemon's default. | +| **none** | Own private IPC namespace, with /dev/shm not mounted. | +| **private** | Own private IPC namespace. | +| **shareable** | Own private IPC namespace, with a possibility to share it with other containers. | +| **container:**_name-or-ID_ | Join another ("shareable") container's IPC namespace. | +| **host** | Use the host system's IPC namespace. | + +If not specified, daemon default is used, which can either be **private** +or **shareable**, depending on the daemon version and configuration. **--isolation**="*default*" Isolation specifies the type of isolation technology used by containers. Note @@ -462,9 +472,12 @@ according to RFC4862. Assign a name to the container The operator can identify a container in three ways: - UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) - UUID short identifier (“f78375b1c487”) - Name (“jonah”) + +| Identifier type | Example value | +|:----------------------|:-------------------------------------------------------------------| +| UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" | +| UUID short identifier | "f78375b1c487" | +| Name | "evil_ptolemy" | The UUID identifiers come from the Docker daemon, and if a name is not assigned to the container with **--name** then the daemon will also generate a random @@ -473,12 +486,17 @@ other place you need to identify a container). This works for both background and foreground Docker containers. **--network**="*bridge*" - Set the Network mode for the container - 'bridge': create a network stack on the default Docker bridge - 'none': no networking - 'container:': reuse another container's network stack - 'host': use the Docker host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. - '|': connect to a user-defined network + Set the Network mode for the container. Supported values are: + +| Value | Description | +|:----------------------------|:-----------------------------------------------------------------------------------------| +| **none** | No networking in the container. | +| **bridge** | Connect the container to the default Docker bridge via veth interfaces. | +| **host** | Use the host's network stack inside the container. | +| **container:**_name_|_id_ | Use the network stack of another container, specified via its _name_ or _id_. | +| _network-name_|_network-id_ | Connects the container to a user created network (using `docker network create` command) | + +Default is **bridge**. **--network-alias**=[] Add network-scoped alias for the container @@ -549,8 +567,17 @@ outside of a container on the host. to write files anywhere. By specifying the `--read-only` flag the container will have its root filesystem mounted as read only prohibiting any writes. -**--restart**="*no*" - Restart policy to apply when a container exits (no, on-failure[:max-retry], always, unless-stopped). +**--restart**="" + Restart policy to apply when a container exits. Supported values are: + +| Policy | Result | +|:-------------------------------|:----------------------| +| **no** | Do not automatically restart the container when it exits. | +| **on-failure**[:_max-retries_] | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | +| **always** | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | +| **unless-stopped** | Always restart the container regardless of the exit status, but do not start it on daemon startup if the container has been put to a stopped state before. | + +Default is **no**. **--rm**=*true*|*false* Automatically remove the container when it exits. The default is *false*.