Merge pull request #15755 from edsantiago/docs_for_formats

[CI:DOCS] man pages: document some --format options

7 files changed, 144 insertions, 31 deletions

diff --git a/docs/source/markdown/podman-container-inspect.1.md b/docs/source/markdown/podman-container-inspect.1.md
index f92eea7bd..7157a3ec0 100644
--- a/docs/source/markdown/podman-container-inspect.1.md
+++ b/docs/source/markdown/podman-container-inspect.1.md
@@ -18,6 +18,50 @@ all results in a JSON array. If a format is specified, the given template will b
 Format the output using the given Go template.
 The keys of the returned JSON can be used as the values for the --format flag (see examples below).
 
+Valid placeholders for the Go template are listed below:
+
+| **Placeholder**      | **Description**                                    |
+| -----------------    | ------------------                                 |
+| .AppArmorProfile     | AppArmor profile (string)                          |
+| .Args                | Command-line arguments (array of strings)          |
+| .BoundingCaps        | Bounding capability set (array of strings)         |
+| .Config ...          | Structure with config info                         |
+| .ConmonPidFile       | Path to file containing conmon pid (string)        |
+| .Created             | Container creation time (string, ISO3601)          |
+| .Dependencies        | Dependencies (array of strings)                    |
+| .Driver              | Storage driver (string)                            |
+| .EffectiveCaps       | Effective capability set (array of strings)        |
+| .ExecIDs             | Exec IDs (array of strings)                        |
+| .GraphDriver ...     | Further details of graph driver (struct)           |
+| .HostConfig ...      | Host config details (struct)                       |
+| .HostnamePath        | Path to file containing hostname (string)          |
+| .HostsPath           | Path to container /etc/hosts file (string)         |
+| .ID                  | Container ID (full 64-char hash)                   |
+| .Image               | Container image ID (64-char hash)                  |
+| .ImageName           | Container image name (string)                      |
+| .IsInfra             | Is this an infra container? (string: true/false)   |
+| .IsService           | Is this a service container? (string: true/false)  |
+| .MountLabel          | SELinux label of mount (string)                    |
+| .Mounts              | Mounts (array of strings)                          |
+| .Name                | Container name (string)                            |
+| .Namespace           | Container namespace (string)                       |
+| .NetworkSettings ... | Network settings (struct)                          |
+| .OCIConfigPath       | Path to OCI config file (string)                   |
+| .OCIRuntime          | OCI runtime name (string)                          |
+| .Path                | Path to container command (string)                 |
+| .PidFile             | Path to file containing container PID (string)     |
+| .Pod                 | Parent pod (string)                                |
+| .ProcessLabel        | SELinux label of process (string)                  |
+| .ResolvConfPath      | Path to container's resolv.conf file (string)      |
+| .RestartCount        | Number of times container has been restarted (int) |
+| .Rootfs              | Container rootfs (string)                          |
+| .SizeRootFs          | Size of rootfs, in bytes [1]                       |
+| .SizeRw              | Size of upper (R/W) container layer, in bytes [1]  |
+| .State ...           | Container state info (struct)                      |
+| .StaticDir           | Path to container metadata dir (string)            |
+
+[1] This format specifier requires the **--size** option
+
 #### **--latest**, **-l**
 
 Instead of providing the container name or ID, use the last created container. If you use methods other than Podman
diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md
index b0e4d68c0..f892c2d7d 100644
--- a/docs/source/markdown/podman-info.1.md
+++ b/docs/source/markdown/podman-info.1.md
@@ -19,6 +19,16 @@ Displays information pertinent to the host, current storage stats, configured co
 
 Change output format to "json" or a Go template.
 
+| **Placeholder**     | **Info pertaining to ...**              |
+| ------------------- | --------------------------------------- |
+| .Host ...           | ...the host on which podman is running  |
+| .Plugins ...        | ...external plugins                     |
+| .Registries ...     | ...configured registries                |
+| .Store ...          | ...the storage driver and paths         |
+| .Version ...        | ...podman version                       |
+
+Each of the above branch out into further subfields, more than can
+reasonably be enumerated in this document.
 
 ## EXAMPLES
 
diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md
index e100256af..609cc47da 100644
--- a/docs/source/markdown/podman-pod-inspect.1.md
+++ b/docs/source/markdown/podman-pod-inspect.1.md
@@ -18,22 +18,42 @@ Change the default output format.  This can be of a supported type like 'json'
 or a Go template.
 Valid placeholders for the Go template are listed below:
 
-| **Placeholder**   | **Description**                                                               |
-| ----------------- | ----------------------------------------------------------------------------- |
-| .ID               | Pod   ID                                                                      |
-| .Name             | Pod   name                                                                    |
-| .State            | Pod   state                                                                   |
-| .Hostname         | Pod   hostname                                                                |
-| .Labels           | Pod   labels                                                                  |
-| .Created          | Time when the pod was created                                                 |
-| .CreateCgroup     | Whether cgroup was created                                                    |
-| .CgroupParent     | Pod   cgroup parent                                                           |
-| .CgroupPath       | Pod   cgroup path                                                             |
-| .CreateInfra      | Whether infrastructure created                                                |
-| .InfraContainerID | Pod   infrastructure ID                                                       |
-| .SharedNamespaces | Pod   shared namespaces                                                       |
-| .NumContainers    | Number of containers in the pod                                               |
-| .Containers       | Pod   containers                                                              |
+| **Placeholder**      | **Description**                             |
+|----------------------|---------------------------------------------|
+| .BlkioDeviceReadBps  | Block I/O Device Read, in bytes/sec         |
+| .BlkioDeviceWriteBps | Block I/O Device Read, in bytes/sec         |
+| .BlkioWeight         | Block I/O Weight                            |
+| .BlkioWeightDevice   | Block I/O Device Weight                     |
+| .CgroupParent        | Pod cgroup parent                           |
+| .CgroupPath          | Pod cgroup path                             |
+| .Containers          | Pod containers                              |
+| .CPUPeriod           | CPU period                                  |
+| .CPUQuota            | CPU quota                                   |
+| .CPUSetCPUs          | CPU Set CPUs                                |
+| .CPUSetMems          | CPU Set Mems                                |
+| .CPUShares           | CPU Shares                                  |
+| .CreateCgroup        | Whether cgroup was created                  |
+| .CreateCommand       | Create command                              |
+| .Created             | Time when the pod was created               |
+| .CreateInfra         | Whether infrastructure created              |
+| .Devices             | Devices                                     |
+| .ExitPolicy          | Exit policy                                 |
+| .Hostname            | Pod hostname                                |
+| .ID                  | Pod ID                                      |
+| .InfraConfig ...     | Infra config (contains further fields)      |
+| .InfraContainerID    | Pod infrastructure ID                       |
+| .InspectPodData ...  | Nested structure, for experts only          |
+| .Labels              | Pod labels                                  |
+| .MemoryLimit         | Memory limit, bytes                         |
+| .MemorySwap          | Memory swap limit, in bytes                 |
+| .Mounts              | Mounts                                      |
+| .Name                | Pod name                                    |
+| .Namespace           | Namespace                                   |
+| .NumContainers       | Number of containers in the pod             |
+| .SecurityOpts        | Security options                            |
+| .SharedNamespaces    | Pod shared namespaces                       |
+| .State               | Pod state                                   |
+| .VolumesFrom         | Volumes from                                |
 
 #### **--latest**, **-l**
 
diff --git a/docs/source/markdown/podman-pod-stats.1.md.in b/docs/source/markdown/podman-pod-stats.1.md.in
index 83a4b7a1e..4ecb30bdb 100644
--- a/docs/source/markdown/podman-pod-stats.1.md.in
+++ b/docs/source/markdown/podman-pod-stats.1.md.in
@@ -23,16 +23,16 @@ Valid placeholders for the Go template are listed below:
 
 | **Placeholder** | **Description**    |
 | --------------- | ------------------ |
-| .Pod            | Pod ID             |
+| .BlockIO        | Block IO           |
 | .CID            | Container ID       |
-| .Name           | Container Name     |
 | .CPU            | CPU percentage     |
+| .Mem            | Memory percentage  |
 | .MemUsage       | Memory usage       |
 | .MemUsageBytes  | Memory usage (IEC) |
-| .Mem            | Memory percentage  |
+| .Name           | Container Name     |
 | .NetIO          | Network IO         |
-| .BlockIO        | Block IO           |
 | .PIDS           | Number of PIDs     |
+| .Pod            | Pod ID             |
 
 When using a GO template, you may precede the format with `table` to print headers.
 
diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md
index 0e0d16120..77d9276bd 100644
--- a/docs/source/markdown/podman-secret-inspect.1.md
+++ b/docs/source/markdown/podman-secret-inspect.1.md
@@ -19,6 +19,17 @@ Secrets can be queried individually by providing their full name or a unique par
 
 Format secret output using Go template.
 
+| **Placeholder**          | **Description**                                                   |
+| ------------------------ | ----------------------------------------------------------------- |
+| .CreatedAt               | When secret was created (relative timestamp, human-readable)      |
+| .ID                      | ID of secret                                                      |
+| .Spec                    | Details of secret                                                 |
+| .Spec.Driver             | Driver info                                                       |
+| .Spec.Driver.Name        | Driver name (string)                                              |
+| .Spec.Driver.Options ... | Driver options (map of driver-specific options)                   |
+| .Spec.Name               | Name of secret                                                    |
+| .UpdatedAt               | When secret was last updated (relative timestamp, human-readable) |
+
 #### **--help**
 
 Print usage statement.
diff --git a/docs/source/markdown/podman-stats.1.md.in b/docs/source/markdown/podman-stats.1.md.in
index f06bd3fcc..a14bd81e6 100644
--- a/docs/source/markdown/podman-stats.1.md.in
+++ b/docs/source/markdown/podman-stats.1.md.in
@@ -30,17 +30,37 @@ Pretty-print container statistics to JSON or using a Go template
 
 Valid placeholders for the Go template are listed below:
 
-| **Placeholder** | **Description**    |
-| --------------- | ------------------ |
-| .ID             | Container ID       |
-| .Name           | Container Name     |
-| .CPUPerc        | CPU percentage     |
-| .MemUsage       | Memory usage       |
-| .MemUsageBytes  | Memory usage (IEC) |
-| .MemPerc        | Memory percentage  |
-| .NetIO          | Network IO         |
-| .BlockIO        | Block IO           |
-| .PIDS           | Number of PIDs     |
+| **Placeholder**     | **Description**                                  |
+|---------------------|--------------------------------------------------|
+| .AvgCPU             | Average CPU, full precision float                |
+| .AVGCPU             | Average CPU, formatted as a percent              |
+| .BlockInput         | Block Input                                      |
+| .BlockIO            | Block IO                                         |
+| .BlockOutput        | Block Output                                     |
+| .ContainerID        | Container ID, full (untruncated) hash            |
+| .ContainerStats ... | Nested structure, for experts only               |
+| .CPU                | Percent CPU, full precision float                |
+| .CPUNano            | CPU Usage, total, in nanoseconds                 |
+| .CPUPerc            | CPU percentage                                   |
+| .CPUSystemNano      | CPU Usage, kernel, in nanoseconds                |
+| .Duration           | Same as CPUNano                                  |
+| .ID                 | Container ID, truncated                          |
+| .MemLimit           | Memory limit, in bytes                           |
+| .MemPerc            | Memory percentage                                |
+| .MemUsage           | Memory usage                                     |
+| .MemUsageBytes      | Memory usage (IEC)                               |
+| .Name               | Container Name                                   |
+| .NetInput           | Network Input                                    |
+| .NetIO              | Network IO                                       |
+| .NetOutput          | Network Output                                   |
+| .PerCPU             | CPU time consumed by all tasks [1]               |
+| .PIDs               | Number of PIDs                                   |
+| .PIDS               | Number of PIDs (yes, we know it's a dup)         |
+| .SystemNano         | Current system datetime, nanoseconds since epoch |
+| .Up                 | Duration (CPUNano), in human-readable form       |
+| .UpTime             | Same as UpTime                                   |
+
+[1] Cgroups V1 only
 
 When using a GO template, you may precede the format with `table` to print headers.
 
diff --git a/docs/source/markdown/podman-version.1.md b/docs/source/markdown/podman-version.1.md
index 3062d10ab..93d4d54d5 100644
--- a/docs/source/markdown/podman-version.1.md
+++ b/docs/source/markdown/podman-version.1.md
@@ -16,6 +16,14 @@ OS, and Architecture.
 
 Change output format to "json" or a Go template.
 
+| **Placeholder**     | **Description**          |
+| ------------------- | ------------------------ |
+| .Client ...         | Version of local podman  |
+| .Server ...         | Version of remote podman |
+
+Each of the above fields branch deeper into further subfields
+such as .Version, .APIVersion, .GoVersion, and more.
+
 ## Example
 
 A sample output of the `version` command: