Merge pull request #10676 from Procyhon/13062021_manpage

[CI:DOCS] UPDATE manpages with MANPAGE_SYNTAX

docs/MANPAGE_SYNTAX.md

@@ -4,7 +4,8 @@
 podman\-command - short description
 
 ## SYNOPSIS
-(Shows the command structure. If the command can be written in two different ways, both of them have to be shown.)
+(Shows the command structure. If the command can be written in two different ways, both of them have to be shown.\
+Many manpages include the OPTIONS **--all**, **-a** and/or **--latest**, **-l**. In this case there is no `container name` or `ID` needed after the initial command. Because most of the other OPTIONS still need the `container name` or ` ID`, it is defined that the *container* argument in the command should **not** be put in brackets. It should also be noted in the *IMPORTANT* section in the description of the OPTION with the following sentence: *IMPORTANT: This OPTION does not need a container name or ID as input argument.*.)
 
 **podman command** [*optional*] *mandatory value*
 
@@ -30,42 +31,54 @@ podman\-command - short description
 
 ## DESCRIPTION
 **podman command** is always the beginning of the DESCRIPTION section. Putting the command as the first part of the DESCRIPTION ensures uniformity. All commands mentioned in the text retain their appearance and form.\
-Example sentence: The command **podman command** is an example command.
+Example for the first sentence: **podman command** is an example command.
 
 Commands or files that are quoted from other podman manpages or podman repositories have to be linked to those. Non-podman commands are not to be linked.\
 Example sentence: Use **[podman-run](podman-run.1.md)** or **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for the problem.
 
-It should also be specified if the command can only be run as root. In addition, it should be described when a command, OPTION, or other content cannot be executed with the remote client or in combination with other commands, OPTIONS, or content. In this case, the following sentence is put at the end of a command, OPTION, or content: *IMPORTANT: This OPTION/command/other is not available with the command/OPTION/content/remote Podman client*. For a command, this should be done in the DESCRIPTION section. For the OPTIONS, it should be done in the DESCRIPTION of the specified OPTION. Do not use pronouns in the man pages, especially the word `you`.
+It should also be specified if the command can only be run as root. In addition, it should be described when a command, OPTION, or other content cannot be executed with the remote client or in combination with other commands, OPTIONS, or content. In this case, the following sentence is put at the end of a command, OPTION, or content: *IMPORTANT: This OPTION/command/other is not available with the command/OPTION/content/remote Podman client*. For a command, this should be done in the DESCRIPTION section. For the OPTIONS, it should be done in the DESCRIPTION of the specified OPTION.
+
+Do not use pronouns in the man pages, especially the word `you`.
+
+There should be **no** new line after H2-headers (`##`).
 
 ## OPTIONS
 All flags are referred to as OPTIONS. The term flags should not be used. All OPTIONS are listed in this section. OPTIONS that appear in descriptions of other OPTIONS and sections retain their appearance, for example: **--exit**.
 
 OPTIONS that are quoted from other podman manpages or podman repositories have to be linked to those.\
-Example sentence: Use **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)** for the problem.
+Example sentence: Use **[podman-generate-systemd --new](./source/markdown/podman-generate-systemd.1.md#--new)** for the problem.
+
+ Each OPTION should be explained to the fullest extent below the OPTION itself. Each OPTION is behind an H4-header (`####`). If the OPTION has a default argument, it has to be explained in the description of the OPTION. If the OPTION is also not available with a command/OPTION/content/remote Podman client, the sentence about the default argument should the second to last sentence. The sentence about the default argument should be in a new line as well as the *IMPORTANT* sentence.
+
+ All OPTIONS are to be sorted in alphabetical order.
 
- Each OPTION should be explained to the fullest extent below the OPTION itself. Each OPTION is behind an H4-header (`####`). If the OPTION has a default argument, it has to be explained in the description of the OPTION. If the OPTION is also not available with the remote client, the sentence about the default argument should the second to last sentence.
+ Tables should be used when there is a different definition for different arguments and these have to be explained. This is shown with the OPTION **--test**.\
+ Lists should be used when arguments are used that do not need a definition for each argument and a single description explains them. An example is shown with **[podman-commit --change](./source/markdown/podman-commit.1.md#--change--cinstruction)**
 
 
 #### **--version**, **-v**
 
-OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front.\
-Example: The default is **false**. *IMPORTANT: This OPTION is not available with the remote Podman client*.
+OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If the arguments behind the OPTION are boolean, it is not shown behind the OPTION itself. The default boolean argument is shown in the same way normal default arguments are displayed.\
+Example: The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client.*
 
 #### **--exit**
 
 An example of an OPTION that has only one possible structure. Thus, it cannot be executed by the extension **-e**.
 
 #### **--answer**=, **-a**=**active** | *disable*
 
-The "answer" OPTION above is an example of an OPTION that accepts two possible arguments as inputs. If there is a default argument that is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used it must include an argument afterwards. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them. The default value is shown as **active**.
+The **--answer** OPTION above is an example of an OPTION that accepts two possible arguments as inputs. If there is a default argument that is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used it must include an argument afterwards. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them.\
+The default value is shown as **active**.
 
 #### **--status**=**good** | *better* | *best*
 
-This is an example of three arguments following an OPTION. If the number of arguments is greater than three, the arguments are **not** listed after the equal sign. The arguments have to be shown in a table like in **--test**=**_test_**, regardless of the number of arguments. The default value is shown as **good**.
+This is an example of three arguments following an OPTION. If the number of arguments is greater than three, the arguments are **not** listed after the equal sign. The arguments have to be shown in a table like in **--test**=**_test_**. This form should also be used if the understanding of the content is in danger of becoming incomprehensible. An example for this is **[podman-container-prune --filters](./source/markdown/podman-container-prune.1.md#--filterfilters)**.\
+The default value is shown as **good**.
 
 #### **--test**=**test**
 
-OPTIONS that are followed by an equal sign include an argument after the equal sign in **bold**. If there is a default argument, that is used if the OPTION is not specified in the command, the argument after the equal sign is displayed in **bold**. All arguments must be listed and explained in the text below the OPTION.
+OPTIONS that are followed by an equal sign include an argument after the equal sign in **bold** or *italic*. If there is a default argument, that is used if the OPTION is not specified in the command, the argument after the equal sign is displayed in **bold**. All arguments must be listed and explained in the text below the OPTION.
 
 | Argument           | Description                                                                 |
 | ------------------ | --------------------------------------------------------------------------- |
@@ -75,8 +88,8 @@ OPTIONS that are followed by an equal sign include an argument after the equal s
 | *example four*     | Example: Can be combined with **--exit**.                                   |
 | *example five*     | The fifth description                                                       |
 
-The table shows an example for a listing of arguments. The contents in the table should be aligned left. If the content in the table conflicts with this, it can be aligned in a way that supports the understanding of the content. If there is a default argument, it **must** listed as the first entry in the table. The default value is shown as **example one**.
-
+The table shows an example for a listing of arguments. The contents in the table should be aligned left. If the content in the table conflicts with this, it can be aligned in a way that supports the understanding of the content. If there is a default argument, it **must** listed as the first entry in the table.\
+The default value is shown as **example one**.
 
 If the number of arguments is smaller than four they have to be listed behind the OPTION as seen in the OPTION **--status**.
 
@@ -104,9 +117,7 @@ Description of the EXAMPLE
 ```
 ### Example comment
 $ podman command
-
 $ podman command -o
-
 $ cat $HOME/Dockerfile | podman command --option
 ```
 
@@ -125,3 +136,5 @@ Normally, the dates of changes, the content of the changes and the person who pr
 
 Example:\
 December 2021, Originally compiled by Alexander Richter <[email protected]>
+
+`A new line is needed of the end of every manpage.`

docs/source/markdown/podman-attach.1.md

@@ -15,22 +15,25 @@ The *container* can detached from (and leave it running) using a configurable ke
 ## OPTIONS
 #### **--detach-keys**=**sequence**
 
-Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is `ctrl-p,ctrl-q`.
+Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature.\
+The default is `ctrl-p,ctrl-q`.
 
 #### **--latest**, **-l**
-Instead of providing the *container name* or *ID*, use the last created *container*. If other methods are used than Podman to run containers such as `CRI-O`, the last started *container* could be from either of those methods. The default is **false**.\
-*IMPORTANT: This OPTION is not available with the remote Podman client.*
+
+Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.*
 
 #### **--no-stdin**
 
 Do not attach STDIN. The default is **false**.
 
 #### **--sig-proxy**
 
-Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**.
+Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.\
+The default is **true**.
 
 ## EXAMPLES
-
 Attach to a container called "foobar".
 ```
 $ podman attach foobar

docs/source/markdown/podman-auto-update.1.md

@@ -9,8 +9,7 @@ podman\-auto-update - Auto update containers according to their auto-update poli
 ## DESCRIPTION
 **podman auto-update** looks up containers with a specified `io.containers.autoupdate` label (i.e., the auto-update policy).
 
-If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated.
-The label `image` is an alternative to `registry` maintained for backwards compatibility.
+If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility.
 An image is considered updated if the digest in the local storage is different than the one of the remote image.
 If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container.
 
@@ -35,7 +34,6 @@ Systemd units that start and stop a container cannot run a new image.
 Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer.  The timer can be altered for custom time-based updates if desired.  The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**.
 
 ## OPTIONS
-
 #### **--authfile**=*path*
 
 Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**.
@@ -44,7 +42,6 @@ If the authorization state is not found there, `$HOME/.docker/config.json` is ch
 Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**.
 
 ## EXAMPLES
-
 Autoupdate with registry policy
 
 ```

docs/source/markdown/podman-commit.1.md

@@ -15,7 +15,6 @@ If `image` does not begin with a registry name component, `localhost` will be ad
 If `image` is not provided, the values for the `REPOSITORY` and `TAG` values of the created image will each be set to `<none>`.
 
 ## OPTIONS
-
 #### **--author**, **-a**=*author*
 
 Set the author for the committed image.
@@ -39,15 +38,17 @@ Can be set multiple times.
 
 #### **--format**, **-f** =**oci** | *docker*
 
-Set the format of the image manifest and metadata.  The currently supported formats are **oci** and *docker*. The default is **oci**.
+Set the format of the image manifest and metadata.  The currently supported formats are **oci** and *docker*.\
+The default is **oci**.
 
 #### **--iidfile**=*ImageIDfile*
 
 Write the image ID to the file.
 
 #### **--include-volumes**
 
-Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands. The default is **false**.
+Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands.\
+The default is **false**.
 
 #### **--message**, **-m**=*message*
 
@@ -56,14 +57,15 @@ Set commit message for committed image.\
 
 #### **--pause**, **-p**
 
-Pause the container when creating an image. The default is **false**.
+Pause the container when creating an image.\
+The default is **false**.
 
 #### **--quiet**, **-q**
 
-Suppresses output. The default is **false**.
+Suppresses output.\
+The default is **false**.
 
 ## EXAMPLES
-
 Create image from container with entrypoint and label
 ```
 $ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change "LABEL blue=image" reverent_golick image-committed

docs/source/markdown/podman-completion.1.md

@@ -20,7 +20,8 @@ Write the generated output to a file.
 
 #### **--no-desc**
 
-Do not provide description in the completions. The default is **false**.
+Do not provide description in the completions.\
+The default is **false**.
 
 ## Installation