Cleanup manpage formatting

Also address most troff issues. Not all of them are easy, in particular those
manpages with long urls and examples that include digests are difficult to
render in traditional manpages.

Add troff renderering to the Manpage to surface those troff issues more easily

Signed-off-by: Reinhard Tartler <siretart@tauware.de>

Author: siretart

common/docs/Containerfile.5.md

@@ -117,23 +117,23 @@ Current supported mount TYPES are bind, cache, secret and tmpfs.
 
        Common Options:
 
-	      · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
+	      * src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
 
-	      · dst, destination, target: mount destination spec.
+	      * dst, destination, target: mount destination spec.
 
-	      · ro, read-only: true (default) or false.
+	      * ro, read-only: true (default) or false.
 
        Options specific to bind:
 
-	      · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
+	      * bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
 
-	      . bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.
+	      * bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.
 
-	      · from: stage or image name for the root of the source. Defaults to the build context.
+	      * from: stage or image name for the root of the source. Defaults to the build context.
 
-	      · relabel=shared, z: Relabels src content with a shared label.
+	      * relabel=shared, z: Relabels src content with a shared label.
 
-	      . relabel=private, Z: Relabels src content with a private label.
+	      * relabel=private, Z: Relabels src content with a private label.
 
 	      Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz.
 
@@ -143,31 +143,31 @@ Current supported mount TYPES are bind, cache, secret and tmpfs.
 
 	      Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container.
 
-	      · rw, read-write: allows writes on the mount.
+	      * rw, read-write: allows writes on the mount.
 
        Options specific to tmpfs:
 
-	      · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
+	      * tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
 
-	      · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
+	      * tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
 
-	      · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
+	      * tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
 
 	Options specific to cache:
 
-	      · id: Create a separate cache directory for a particular id.
+	      * id: Create a separate cache directory for a particular id.
 
-	      · mode: File mode for new cache directory in octal. Default 0755.
+	      * mode: File mode for new cache directory in octal. Default 0755.
 
-	      · ro, readonly: read only cache if set.
+	      * ro, readonly: read only cache if set.
 
-	      · uid: uid for cache directory.
+	      * uid: uid for cache directory.
 
-	      · gid: gid for cache directory.
+	      * gid: gid for cache directory.
 
-	      · from: stage name for the root of the source. Defaults to host cache directory.
+	      * from: stage name for the root of the source. Defaults to host cache directory.
 
-	      · rw, read-write: allows writes on the mount.
+	      * rw, read-write: allows writes on the mount.
 
 **RUN --network**
 

common/docs/Makefile

@@ -7,6 +7,7 @@ docs: $(patsubst %.md,%,$(wildcard *.md))
 
 %.5:  %.5.md
 	$(GOMD2MAN) -in $^ -out $@
+	groff -Tascii $@ > /dev/null
 
 .PHONY: install
 install:

common/docs/containerignore.5.md

@@ -6,23 +6,27 @@
 
 # INTRODUCTION
 
-Before container engines build an image, they look for a file named .containerignore or .dockerignore in the root
-context directory. If one of these file exists, the CLI modifies the context to exclude files and
-directories that match patterns specified in the file. This avoids adding them to images using the ADD or COPY
-instruction.
-
-The CLI interprets the .containerignore or .dockerignore file as a newline-separated list of patterns similar to
-the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the
-working and the root directory. For example, the patterns /foo/bar and foo/bar both exclude a file or directory
-named bar in the foo subdirectory of PATH or in the root of the git repository located at URL. Neither excludes
+Before container engines build an image, they look for a file named
+`.containerignore` or `.dockerignore` in the root context directory. If one of
+these file exists, the CLI modifies the context to exclude files and
+directories that match patterns specified in the file. This avoids adding them
+to images using the ADD or COPY instruction.
+
+The CLI interprets the `.containerignore` or `.dockerignore` file as a
+newline-separated list of patterns similar to the file globs of Unix
+shells. For the purposes of matching, the root of the context is considered to
+be both the working and the root directory. For example, the patterns `/foo/bar`
+and `foo/bar` both exclude a file or directory named bar in the foo subdirectory
+of PATH or in the root of the git repository located at URL. Neither excludes
 anything else.
 
-If a line in .containerignore or .dockerignore file starts with # in column 1, then this line is considered as a
-comment and is ignored before interpreted by the CLI.
+If a line in `.containerignore` or `.dockerignore` file starts with `#` in
+column 1, then this line is considered as a comment and is ignored before
+interpreted by the CLI.
 
 # EXAMPLES
 
-Here is an example .containerignore file:
+Here is an example `.containerignore` file:
 
 ```
 # comment
@@ -33,6 +37,7 @@ temp?
 
 This file causes the following build behavior:
 Rule 	Behavior
+
 ```
 # comment 	Ignored.
 */temp* 	Exclude files and directories whose names start with temp in any immediate subdirectory of the root.
@@ -41,22 +46,33 @@ For example, the plain file /somedir/temporary.txt is excluded, as is the direct
 root. For example, /somedir/subdir/temporary.txt is excluded.
 temp? 	Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded.
 ```
-Matching is done using Go’s filepath.Match rules. A preprocessing step removes leading and trailing whitespace and
-eliminates . and .. elements using Go’s filepath.Clean. Lines that are blank after preprocessing are ignored.
 
-Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string ** that matches any number of
-directories (including zero). For example, **/*.go will exclude all files that end with .go that are found in all
-directories, including the root of the build context.
+Matching is done using the golang `path/filepath` package.
+
+Match rules:
+ * A preprocessing step removes leading and trailing whitespace and eliminates
+   . and .. elements using the golang `path/filepath` package.
+ * Lines that are blank after preprocessing are ignored.
+
+Beyond the `filepath.Match` rules, Docker also supports a special wildcard
+string `**` that matches any number of directories (including zero). For
+example, `**/*.go` will exclude all files that end with `.go` that are found in
+all directories, including the root of the build context.
+
+Lines starting with `!` (exclamation mark) can be used to make exceptions to
+exclusions. The following is an example .containerignore file that uses this
+mechanism:
 
-Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism:
 ```
 *.md
 !README.md
 ```
 All markdown files except README.md are excluded from the context.
 
-The placement of ! exception rules influences the behavior: the last line of the .containerignore that matches a
-particular file determines whether it is included or excluded. Consider the following example:
+The placement of `!` exception rules influences the behavior: the last line of
+the `.containerignore` that matches a particular file determines whether it is
+included or excluded. Consider the following example:
+
 ```
 *.md
 !README*.md
@@ -65,20 +81,24 @@ README-secret.md
 No markdown files are included in the context except README files other than README-secret.md.
 
 Now consider this example:
+
 ```
 *.md
 README-secret.md
 !README*.md
 ```
-All of the README files are included. The middle line has no effect because !README*.md matches README-secret.md and
-comes last.
 
-You can even use the .containerignore file to exclude the Containerfile or Dockerfile and .containerignore files.
-These files are still sent to the daemon because it needs them to do its job. But the ADD and COPY instructions do
-not copy them to the image.
+All of the README files are included. The middle line has no effect because
+`!README*.md` matches `README-secret.md` and comes last.
+
+You can even use the .containerignore file to exclude the `Containerfile` or
+`Dockerfile` and `.containerignore` files.  These files are still sent to the
+daemon because it needs them to do its job. But the `ADD` and `COPY` instructions
+do not copy them to the image.
 
-Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve
-this, specify * as the first pattern, followed by one or more ! exception patterns.
+Finally, you may want to specify which files to include in the context, rather
+than which to exclude. To achieve this, specify `*` as the first pattern,
+followed by one or more `!` exception patterns.
 
 ## SEE ALSO
 buildah-build(1), podman-build(1), docker-build(1)