Merge pull request containers#10601 from Procyhon/07062021_manpage

[CI:DOCS] UPDATE manpages with MANPAGE_SYNTAX

Makefile

@@ -437,7 +437,7 @@ $(MANPAGES): %: %.md .install.md2man docdir
          -e 's/\[\(podman[^]]*\)\]/\1/g' \
 		 -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \
          -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \
-         -e 's/\\$//  /g' $<  | \
+         -e 's/\\$$/  /g' $<  | \
 	$(GOMD2MAN) -in /dev/stdin -out $(subst source/markdown,build/man,$@)
 
 .PHONY: docdir

docs/MANPAGE_SYNTAX.md

@@ -4,7 +4,7 @@
 podman\-command - short description
 
 ## SYNOPSIS
-(Shows the command structure.)
+(Shows the command structure. If the command can be written in two different ways, both of them have to be shown.)
 
 **podman command** [*optional*] *mandatory value*
 
@@ -16,7 +16,7 @@ podman\-command - short description
 
 **podman subcommand command** [*optional*] *value1* | *value2*
 
-(If an optinal value follows a mandatory one.)
+(If an optional value follows a mandatory one.)
 
 **podman command** [*optional*] *value1* | *value2* [*optional*]
 
@@ -33,39 +33,39 @@ podman\-command - short description
 Example sentence: The command **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: You can 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.
+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`.
 
 ## 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: You can use **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)** for the problem.
+Example sentence: Use **[podman-generate-systemd --new](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 the remote client, the sentence about the default argument should the second to last sentence.
 
 
 #### **--version**, **-v**
 
-OPTIONS can be put after the command in two different ways. Eather 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.\
+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**.
 
 #### **--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 eqaul 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**. 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                                                                 |
 | ------------------ | --------------------------------------------------------------------------- |
@@ -102,6 +102,7 @@ All EXAMPLES are listed in this section. This section should be at the end of ea
 
 Description of the EXAMPLE
 ```
+### Example comment
 $ podman command
 
 $ podman command -o
@@ -111,9 +112,16 @@ $ cat $HOME/Dockerfile | podman command --option
 
 Description of the EXAMPLE two
 ```
-$ podman command --redhat
+# podman command --status=better
+```
+## SEE ALSO
+All commands, including commands with OPTIONS, and config-files mentioned in the manpage have to be listed here. Podman commands, including commands with OPTIONS, and config-files have to be linked. If a command is mentioned several times with different OPTIONS it just have to be linked once. All other commands, including commands with OPTIONS, and config-files just have to be mentioned. If a command is mentioned several times with different OPTIONS it just has to be linked once.
 
-$ podman command --redhat better
+Example:
+**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)**
 
-$ podman command --redhat=better
-```
+## HISTORY
+Normally, the dates of changes, the content of the changes and the person who provided them is listed here. Most manpages don't keep this record.
+
+Example:\
+December 2021, Originally compiled by Alexander Richter <[email protected]>

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

@@ -10,17 +10,16 @@ podman\-attach - Attach to a running container
 
 ## DESCRIPTION
 **podman attach** attaches to a running *container* using the *container's name* or *ID*, to either view its ongoing output or to control it interactively.\
-The *container* can detached from (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** option, or specifying it in the `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information.
+The *container* can detached from (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** OPTION, or specifying it in the `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information.
 
 ## 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`.
 
 #### **--latest**, **-l**
-
-Instead of providing the *container name* or *ID*, use the last created *container*. If you use methods other 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 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.*
 
 #### **--no-stdin**
 

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

@@ -23,7 +23,17 @@ Set the author for the committed image.
 #### **--change**, **-c**=*instruction*
 
 Apply the following possible instructions to the created image:
-**CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **ONBUILD** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR**
+
+- *CMD*
+- *ENTRYPOINT*
+- *ENV*
+- *EXPOSE*
+- *LABEL*
+- *ONBUILD*
+- *STOPSIGNAL*
+- *USER*
+- *VOLUME*
+- *WORKDIR*
 
 Can be set multiple times.
 

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

@@ -4,60 +4,60 @@
 podman\-completion - Generate shell completion scripts
 
 ## SYNOPSIS
-**podman completion** [*options*] *bash*|*zsh*|*fish*|*powershell*
+**podman completion** [*options*]   *bash* | *zsh* | *fish* | *powershell*
 
 ## DESCRIPTION
-The completion command generates shell completion scripts for a variety of shells. Supported shells are **bash**, **zsh**, **fish** and **powershell**.
+**podman completion** generates shell completion scripts for a variety of shells. Supported shells are *bash*, *zsh*, *fish* and *powershell*.
 
-These script are used by the shell to provide suggestions and complete commands when you are typing the command and press [TAB].
+These script are used by the shell to provide suggestions and complete commands when the command is typed and `[TAB]` is pressed.
 
 Usually these scripts are automatically installed via the package manager.
 
 ## OPTIONS
-#### **--file**, **-f**
+#### **--file**, **-f**=*file*
 
-Write the generated output to file.
+Write the generated output to a file.
 
 #### **--no-desc**
 
-Do not provide description in the completions.
+Do not provide description in the completions. The default is **false**.
 
 ## Installation
 
 ### BASH
-Make sure you have `bash-completion` installed on the system.
+`bash-completion` has to be installed on the system.
 
-To load the completion script into the current session run:
-`source <(podman completion bash)`
+To load the completion script into the current session run:\
+**source <(podman completion bash)**.
 
-To make it available for all bash sessions run:
-`podman completion bash -f /etc/bash_completion.d/podman`
+To make it available for all bash sessions run:\
+**podman completion -f /etc/bash_completion.d/podman bash**.
 
 
 ### ZSH
-If shell completion is not already enabled in the environment you will need to enable it. You can execute the following once:
-`echo "autoload -U compinit; compinit" >> ~/.zshrc`
+Shell completion needs to be already enabled in the environment. The following can be executed:\
+**echo "autoload -U compinit; compinit" >> ~/.zshrc**
 
-To make it available for all zsh sessions run:
-`podman completion zsh -f "${fpath[1]}/_podman"`
+To make it available for all zsh sessions run:\
+**podman completion -f "${fpath[1]}/_podman zsh"**
 
-Once you reload the shell the auto-completion should be working.
+Once the shell is reloaded the auto-completion should be working.
 
 
 ### FISH
 To load the completion script into the current session run:
-`podman completion fish | source`
+**podman completion fish | source**
 
 To make it available for all fish sessions run:
-`podman completion fish -f ~/.config/fish/completions/podman.fish`
+**podman completion -f ~/.config/fish/completions/podman.fish fish**
 
 ### POWERSHELL
 To load the completion script into the current session run:
-`podman.exe completion powershell | Out-String | Invoke-Expression`
+**podman.exe completion powershell | Out-String | Invoke-Expression**
 
 To make it available in all powershell sessions that a user has, write the
 completion output to a file and source that to the user's powershell profile.
-More information about profiles is available with `Get-Help about_Profiles`.
+More information about profiles is available with **Get-Help about_Profiles**.
 
 ## SEE ALSO
-[podman(1)](podman.1.md)
+**[podman(1)](podman.1.md)**, zsh(1), fish(1), powershell(1)