[CI:DOCS] Document --format for additional man pages #17766

rhatdan · 2023-03-13T20:37:51Z

Does this PR introduce a user-facing change?

Document --format in all man pages

Improves on #17472

rhatdan · 2023-03-13T21:13:28Z

@edsantiago What do I now need to do to clean this up?

edsantiago · 2023-03-13T21:23:02Z

@rhatdan first step is to put a space before all the dot-dot-dots:

-| .GraphDriver...      | Structure for the graph driver info                |
+| .GraphDriver ...     | Structure for the graph driver info                |

Next step is to document all the missing fields, basically, keep running hack/xref-helpmsgs-manpages until it exits zero. Like, add .HealthCheck ... to image-inspect, change .NameHistory to .NamesHistory (plural), and about 80 more.

edsantiago

This is great work, thank you! LGTM with a few questions and suggestions

edsantiago · 2023-03-14T12:30:33Z

docs/source/markdown/podman-image-inspect.1.md

+| .RepoDigests         | Repository digests for the image                   |
+| .RepoTags            | Repository tags for the image                      |
+| .RootFS ...          | Structure for the root file system info            |
+| .Size                | Size of image, in bytes [1]                        |


What does the [1] mean?

Cut and paste from somewhere else.

edsantiago · 2023-03-14T12:30:43Z

docs/source/markdown/podman-image-inspect.1.md

+| .Size                | Size of image, in bytes [1]                        |
+| .User                | Default user to execute the image as               |
+| .Version             | Image Version                                      |
+| .VirtualSize         | Virtual size of image, in bytes [1]                |


edsantiago · 2023-03-14T12:32:25Z

docs/source/markdown/podman-image-inspect.1.md

+| .Comment             | Image comment                                      |
+| .Config ...          | Structure with config info                         |
+| .Created             | Image creation time (string, ISO3601)              |
+| .Digest              | Image digest (sha256:+64-char hash)      	    |


There's a tab character in here.

I don't know if it's something in my emacs setup, or if it's automatic in emacs, but when I have my cursor inside MD tables and press the TAB key, emacs instantly aligns all the vertical bars. Really sweet. HTH.

Must be something in your emacs, would love to have that.

Must be this markdown-mode that I have installed (unfortunately, not in Fedora repos).

edsantiago · 2023-03-14T12:38:09Z

docs/source/markdown/podman-system-df.1.md

+| .Reclaimable              | Human reclaimable size of each Type |
+| .Size                     | Human size of each type             |
+| .Total                    | Total items for each type           |
+| .Type                     | Type of data                        |


"Human size" reads weirdly (to me). I like the parenthesized description you use elsewhere, would it make sense to write this table in that form?

.RawReclaimable | Reclaimable size (bytes) .Reclaimable | Reclaimable size (human-readable) ...

edsantiago · 2023-03-14T12:38:54Z

docs/source/markdown/podman-volume-inspect.1.md

+| .Mountpoint         | Source of volume mount point                 |
+| .Name               | Volume name                                  |
+| .NeedsChown         | Indicates whether volume needs to be chowned |
+| .NeedsCopyUp        | Indicates if volume needs to be copied up to |


Dangling "to"?

edsantiago · 2023-03-14T12:40:32Z

docs/source/markdown/podman-volume-ls.1.md.in

+| .Anonymous                | Indicates whether volume is anonymous        |
+| .CreatedAt                | Volume creation time                         |
+| .Driver                   | Volume driver                                |
+| .GID                      | GID to create volume with                    |


Maybe "GID of volume"? "to create with" seems more applicable to volume create than ls.

edsantiago · 2023-03-14T12:40:53Z

docs/source/markdown/podman-volume-ls.1.md.in

+| .Status                   | Status of the volume                         |
+| .StorageID                | StorageID of the volume                      |
+| .Timeout                  | Timeout of the volume                        |
+| .UID                      | UID to create volume with                    |


rhatdan · 2023-03-14T18:31:27Z

@containers/podman-maintainers PTAL
@Luap99 PTAL

edsantiago · 2023-03-14T19:58:16Z

LGTM

TomSweeneyRedHat · 2023-03-14T21:40:33Z

docs/source/markdown/podman-machine-inspect.1.md

+| .Name               | Name of the machine                                   |
+| .Resources ...      | Resources used by the machine                         |
+| .SSHConfig ...      | SSH configuration info for communitating with machine |
+| .State ...           | Machine state                                         |


Possible extra space here?

Before the first '|'

TomSweeneyRedHat · 2023-03-14T21:58:28Z

docs/source/markdown/podman-secret-ls.1.md.in

+Valid placeholders for the Go template are listed below:
+
+| **Placeholder**     | **Description**                     |
+| ------------------- | ----------------------------------- |


hmm, I thought this divider would have to line up with the below, but it seems to work OK as is. It would be nice to keep them consistent though.

TomSweeneyRedHat · 2023-03-14T22:00:39Z

docs/source/markdown/podman-volume-inspect.1.md

+| .Status             | Status of the volume                                   |
+| .StorageID          | StorageID of the volume                                |
+| .Timeout            | Timeout of the volume                                  |
+| .UID                | UID to create volume with                              |


and below you use UID of volume, that might be better.

TomSweeneyRedHat · 2023-03-14T22:02:03Z

docs/source/markdown/podman-volume-inspect.1.md

+     {
+          "Name": "myvol",
+          "Driver": "local",
+          "Mountpoint": "/home/dwalsh/.local/share/containers/storage/volumes/myvol/_data",


do you want to include /home/dwalsh here? I'd suggest something like /home/myusername

Ditto throughout

TomSweeneyRedHat · 2023-03-14T22:02:15Z

docs/source/markdown/podman-volume-inspect.1.md

+     {
+          "Name": "myvol",
+          "Driver": "local",
+          "Mountpoint": "/home/dwalsh/.local/share/containers/storage/volumes/myvol/_data",


ditto dwalsh

edsantiago · 2023-03-15T17:05:34Z

docs/source/markdown/podman-secret-ls.1.md.in

+Valid placeholders for the Go template are listed below:
+
+| **Placeholder**     | **Description**                                                        |
+| ------------------- | ------===================================----------------------------- |


EEK! Those equal signs make a complete mess of the table.

Dan, don't do stuff while running out to lunch.

edsantiago · 2023-03-15T17:35:01Z

docs/source/markdown/podman-secret-ls.1.md.in

+Valid placeholders for the Go template are listed below:
+
+| **Placeholder**          | **Description**                                                   |
+| =====------------------- | ----------------------------------------------------------------- |


aaaaaannd, you fixed one, but introduced equals in another.

Ninety-nine little bugs in the code
Ninety-nine little bugs
Fix one bug
commit & re-push
One hundred little bugs in the code

I wonder if Emacs is doing something strange here... Or just PEBCAK

edsantiago

Forcing a block to make sure nobody inadvertently merges this with the broken equals.

Signed-off-by: Daniel J Walsh <[email protected]>

openshift-ci · 2023-03-15T20:22:32Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: edsantiago, rhatdan

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [edsantiago,rhatdan]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

edsantiago · 2023-03-15T21:21:39Z

/lgtm

openshift-ci bot added release-note approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Mar 13, 2023

rhatdan force-pushed the man branch 4 times, most recently from 8ec004e to acec469 Compare March 13, 2023 20:45

rhatdan force-pushed the man branch from acec469 to a1523c5 Compare March 13, 2023 21:55

edsantiago reviewed Mar 14, 2023

View reviewed changes

rhatdan force-pushed the man branch from a1523c5 to d5af9c0 Compare March 14, 2023 18:27

TomSweeneyRedHat reviewed Mar 14, 2023

View reviewed changes

rhatdan force-pushed the man branch 3 times, most recently from 0d3e385 to 2004317 Compare March 15, 2023 16:08

edsantiago reviewed Mar 15, 2023

View reviewed changes

rhatdan force-pushed the man branch 2 times, most recently from 18efb3f to f3abb00 Compare March 15, 2023 17:25

edsantiago reviewed Mar 15, 2023

View reviewed changes

edsantiago suggested changes Mar 15, 2023

View reviewed changes

rhatdan added 4 commits March 15, 2023 16:15

Add format table to podman image inspect man page

5816118

Signed-off-by: Daniel J Walsh <[email protected]>

Add format to podman machine info

71bcd98

Signed-off-by: Daniel J Walsh <[email protected]>

Add format to podman system df

1c4bd4a

Signed-off-by: Daniel J Walsh <[email protected]>

Add format to podman secret ls

2555c80

Signed-off-by: Daniel J Walsh <[email protected]>

rhatdan added 3 commits March 15, 2023 16:15

Add format to podman volume inspect

b424f8f

Signed-off-by: Daniel J Walsh <[email protected]>

Add format to podman volume ls

87e93a7

Signed-off-by: Daniel J Walsh <[email protected]>

Add information for secret inspect

3a59af2

Signed-off-by: Daniel J Walsh <[email protected]>

rhatdan force-pushed the man branch from f3abb00 to 3a59af2 Compare March 15, 2023 20:16

edsantiago approved these changes Mar 15, 2023

View reviewed changes

openshift-ci bot assigned edsantiago Mar 15, 2023

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Mar 15, 2023

openshift-merge-robot merged commit 345aa34 into containers:main Mar 15, 2023

github-actions bot added the locked - please file new issue/PR Assist humans wanting to comment on an old issue or PR with locked comments. label Sep 6, 2023

github-actions bot locked as resolved and limited conversation to collaborators Sep 6, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CI:DOCS] Document --format for additional man pages #17766

[CI:DOCS] Document --format for additional man pages #17766

rhatdan commented Mar 13, 2023

rhatdan commented Mar 13, 2023

edsantiago commented Mar 13, 2023

edsantiago left a comment

edsantiago Mar 14, 2023

rhatdan Mar 14, 2023

edsantiago Mar 14, 2023

edsantiago Mar 14, 2023

rhatdan Mar 14, 2023

edsantiago Mar 14, 2023

edsantiago Mar 14, 2023

edsantiago Mar 14, 2023

edsantiago Mar 14, 2023

edsantiago Mar 14, 2023

rhatdan commented Mar 14, 2023

edsantiago commented Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

TomSweeneyRedHat Mar 14, 2023

edsantiago Mar 15, 2023

rhatdan Mar 15, 2023

edsantiago Mar 15, 2023

rhatdan Mar 15, 2023

edsantiago left a comment

openshift-ci bot commented Mar 15, 2023

edsantiago commented Mar 15, 2023

	\| .UID \| UID to create volume with \|
	\| .UID \| UID the volume was created with \|

[CI:DOCS] Document --format for additional man pages #17766

[CI:DOCS] Document --format for additional man pages #17766

Conversation

rhatdan commented Mar 13, 2023

Does this PR introduce a user-facing change?

rhatdan commented Mar 13, 2023

edsantiago commented Mar 13, 2023

edsantiago left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rhatdan commented Mar 14, 2023

edsantiago commented Mar 14, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

edsantiago left a comment

Choose a reason for hiding this comment

openshift-ci bot commented Mar 15, 2023

edsantiago commented Mar 15, 2023