hooks/docs: Add oci-hooks.5 and per-package man page building

This allows us to reference the hooks docs from podman(1) in a way
that will survive system installation.  The downside is that the
GitHub rendered pages become less usable, now that we can no longer
embed links as freely as we could before.

I've followed the "Sections within a manual page" suggestions from
[1].

locale(7) is [2], which is Linux-specific.  Even section numbering is
platform-dependent [3], so it's unlikely that these external man
references are particularly portable.  Platform packagers can adjust
our local references to match their target system, but that leaves the
GitHub rendering in an awkward place.  For now, I think a
Linux-centric GitHub rendering without clickable links may be the best
we can do without moving away from go-md2man.

As far as I can tell, there's not a nice way to get go-md2man to wrap
the links in SEE ALSO without sometimes hyphenating a URL (which makes
it harder for man-page readers to copy/paste those links into their
browser).

I've also fixed some "extention" -> "extension" typos.

[1]: http://man7.org/linux/man-pages/man7/man-pages.7.html
[2]: http://man7.org/linux/man-pages/man7/locale.7.html
[3]: https://en.wikipedia.org/wiki/Man_page#Manual_sections

Signed-off-by: W. Trevor King <wking@tremily.us>

Closes: #772
Approved by: mheon

3 files changed, 180 insertions, 160 deletions

diff --git a/pkg/hooks/README.md b/pkg/hooks/README.md
index 86855e9f1..d68a2e0a7 100644
--- a/pkg/hooks/README.md
+++ b/pkg/hooks/README.md
@@ -11,170 +11,11 @@ For example the [oci-systemd-hook][] only executes if the command is `init` or `
 This means if we automatically enabled all hooks, every container would have to execute `oci-systemd-hook`, even if they don't run systemd inside of the container.
 Performance would also suffer if we exectuted each hook at each stage ([pre-start][], [post-start][], and [post-stop][]).
 
-## Notational Conventions
+The hooks configuration is documented in [`oci-hooks.5`][docs/oci-hooks.5.md].
 
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119].
-
-## JSON Definition
-
-This package reads all [JSON][] files (ending with a `.json` extention) from a series of hook directories.
-For both `crio` and `podman`, hooks are read from `/usr/share/containers/oci/hooks.d/*.json`.
-
-For `crio`, hook JSON is also read from `/etc/containers/oci/hooks.d/*.json`.
-If files of with the same name exist in both directories, the one in `/etc/containers/oci/hooks.d` takes precedence.
-
-Hooks MUST be injected in the JSON filename case- and width-insensitive collation order.
-Collation order depends on your locale, as set by [`LC_ALL`][LC_ALL], [`LC_COLLATE`][LC_COLLATE], or [`LANG`][LANG] (in order of decreasing precedence).
-For example, in the [POSIX locale][LC_COLLATE-POSIX], a matching hook defined in `01-my-hook.json` would be injected before matching hooks defined in `02-another-hook.json` and `01-UPPERCASE.json`.
-
-Each JSON file should contain an object with the following properties:
-
-### 1.0.0 Hook Schema
-
-* **`version`** (REQUIRED, string) Sets the hook-definition version.
-    For this schema version, the value MUST be 1.0.0.
-* **`hook`** (REQUIRED, object) The hook to inject, with the [hook-entry schema][spec-hooks] defined by the 1.0.1 OCI Runtime Specification.
-* **`when`** (REQUIRED, object) Conditions under which the hook is injected.
-    The following properties can be specified:
-
-    * **`always`** (OPTIONAL, boolean) If set `true`, this condition matches.
-    * **`annotations`** (OPTIONAL, object) If all `annotations` key/value pairs match a key/value pair from the [configured annotations][spec-annotations], this condition matches.
-        Both keys and values MUST be [POSIX extended regular expressions][POSIX-ERE].
-    * **`commands`** (OPTIONAL, array of strings) If the configured [`process.args[0]`][spec-process] matches an entry, this condition matches.
-        Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
-    * **`hasBindMounts`** (OPTIONAL, boolean) If `hasBindMounts` is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default), this condition matches.
-* **`stages`** (REQUIRED, array of strings) Stages when the hook MUST be injected.
-    Entries MUST be chosen from the 1.0.1 OCI Runtime Specification [hook stages][spec-hooks] or from extention stages supported by the package consumer.
-
-If *all* of the conditions set in `when` match, then the `hook` MUST be injected for the stages set in `stages`.
-
-#### Example
-
-The following configuration injects [`oci-systemd-hook`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:
-
-```console
-$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
-{
-  "version": "1.0.0",
-  "hook": {
-    "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
-  }
-  "when": {
-    "args": [".*/init$" , ".*/systemd$"],
-  },
-  "stages": ["prestart", "poststop"]
-}
-```
-
-The following example injects [`oci-umount --debug`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.
-
-```console
-$ cat /etc/containers/oci/hooks.d/oci-umount.json
-{
-  "version": "1.0.0",
-  "hook": {
-    "path": "/usr/libexec/oci/hooks.d/oci-umount",
-    "args": ["oci-umount", "--debug"],
-  }
-  "when": {
-    "hasBindMounts": true,
-  },
-  "stages": ["prestart"]
-}
-```
-
-The following example injects [`nvidia-container-runtime-hook prestart`][nvidia-container-runtime-hook] with particular environment variables in the [pre-start][] phase if the container is configured with an `annotations` entry whose key matches `^com\.example\.department$` and whose value matches `.*fluid-dynamics.*`.
-
-```console
-$ cat /etc/containers/oci/hooks.d/nvidia.json
-{
-  "hook": {
-    "path": "/usr/sbin/nvidia-container-runtime-hook",
-    "args": ["nvidia-container-runtime-hook", "prestart"],
-    "env": [
-      "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
-      "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
-    ]
-  },
-  "when": {
-    "annotations": {
-      "^com\.example\.department$": ".*fluid-dynamics$"
-    }
-  },
-  "stages": ["prestart"]
-}
-```
-
-### 0.1.0 Hook Schema
-
-Previous versions of CRI-O and libpod supported the 0.1.0 hook schema:
-
-* **`hook`** (REQUIRED, string) Sets [`path`][spec-hooks] in the injected hook.
-* **`arguments`** (OPTIONAL, array of strings) Additional arguments to pass to the hook.
-    The injected hook's [`args`][spec-hooks] is `hook` with `arguments` appended.
-* **`stages`** (REQUIRED, array of strings) Stages when the hook MUST be injected.
-    `stage` is an allowed synonym for this property, but you MUST NOT set both `stages` and `stage`.
-    Entries MUST be chosen from the 1.0.1 OCI Runtime Specification [hook stages][spec-hooks] or from extention stages supported by the package consumer.
-* **`cmds`** (OPTIONAL, array of strings) The hook MUST be injected if the configured [`process.args[0]`][spec-process] matches an entry.
-    `cmd` is an allowed synonym for this property, but you MUST NOT set both `cmds` and `cmd`.
-    Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
-* **`annotations`** (OPTIONAL, array of strings) The hook MUST be injected if an `annotations` entry matches a value from the [configured annotations][spec-annotations].
-    `annotation` is an allowed synonym for this property, but you MUST NOT set both `annotations` and `annotation`.
-    Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
-* **`hasbindmounts`** (OPTIONAL, boolean) The hook MUST be injected if `hasBindMounts` is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default).
-
-#### Example
-
-The following configuration injects [`oci-systemd-hook`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:
-
-```console
-$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
-{
-  "cmds": [".*/init$" , ".*/systemd$"],
-  "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
-  "stages": ["prestart", "poststop"]
-}
-```
-
-The following example injects [`oci-umount --debug`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.
-
-```console
-$ cat /etc/containers/oci/hooks.d/oci-umount.json
-{
-  "hook": "/usr/libexec/oci/hooks.d/oci-umount",
-  "arguments": ["--debug"],
-  "hasbindmounts": true,
-  "stages": ["prestart"]
-}
-```
-
-The following example injects [`nvidia-container-runtime-hook prestart`][nvidia-container-runtime-hook] in the [pre-start][] phase if the container is configured with an `annotations` entry whose value matches `.*fluid-dynamics.*`.
-
-```console
-$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
-{
-  "hook": "/usr/sbin/nvidia-container-runtime-hook",
-  "arguments": ["prestart"],
-  "annotations: [".*fluid-dynamics.*"],
-  "stages": ["prestart"]
-}
-```
-
-[JSON]: https://tools.ietf.org/html/rfc8259
-[LANG]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
-[LC_ALL]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
-[LC_COLLATE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_02
-[LC_COLLATE-POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_02_06
-[nvidia-container-runtime-hook]: https://github.com/NVIDIA/nvidia-container-runtime/tree/master/hook/nvidia-container-runtime-hook
 [oci-systemd-hook]: https://github.com/projectatomic/oci-systemd-hook
-[oci-umount]: https://github.com/projectatomic/oci-umount
-[POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
 [post-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststart
 [post-stop]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststop
 [pre-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#prestart
-[rfc2119]: http://tools.ietf.org/html/rfc2119
-[runc]: https://github.com/opencontainers/runc
 [runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/spec.md
-[spec-annotations]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#annotations
 [spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks
-[spec-process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process
diff --git a/pkg/hooks/docs/.gitignore b/pkg/hooks/docs/.gitignore
new file mode 100644
index 000000000..5d06cd466
--- /dev/null
+++ b/pkg/hooks/docs/.gitignore
@@ -0,0 +1 @@
+*.5
diff --git a/pkg/hooks/docs/oci-hooks.5.md b/pkg/hooks/docs/oci-hooks.5.md
new file mode 100644
index 000000000..73a9b0763
--- /dev/null
+++ b/pkg/hooks/docs/oci-hooks.5.md
@@ -0,0 +1,178 @@
+% oci-hooks(5) OCI Hooks Configuration
+% W. Trevor King
+% MAY 2018
+
+# NAME
+
+oci-hooks - OCI hooks configuration directories
+
+# SYNOPSIS
+
+`/usr/share/containers/oci/hooks.d/*.json`
+
+# DESCRIPTION
+
+Provides a way for users to configure the intended hooks for Open Container Initiative containers so they will only be executed for containers that need their functionality, and then only for the stages where they're needed.
+
+## Directories
+
+Hooks are configured with JSON files (ending with a `.json` extension) in a series of hook directories.
+The default directory is `/usr/share/containers/oci/hooks.d`, but tools consuming this format may change that default, include additional directories, or provide their callers with ways to adjust the configuration directories.
+
+Hooks are injected in the JSON filename case- and width-insensitive collation order.
+Collation order depends on your locale, as set by `LC_ALL`, `LC_COLLATE`, or `LANG` (in order of decreasing precedence).
+For more information, see `locale(7)`.
+For example, in the POSIX locale, a matching hook defined in `01-my-hook.json` would be injected before matching hooks defined in `02-another-hook.json` and `01-UPPERCASE.json`.
+
+Each JSON file should contain an object with one of the following schemas.
+
+## 1.0.0 Hook Schema
+
+`version` (required string)
+  Sets the hook-definition version.  For this schema version, the value be `1.0.0`.
+
+`hook` (required object)
+  The hook to inject, with the hook-entry schema defined by the 1.0.1 OCI Runtime Specification.
+
+`when` (required object)
+  Conditions under which the hook is injected.  The following properties can be specified, and at least one must be specified:
+
+  * `always` (optional boolean)
+      If set `true`, this condition matches.
+  * `annotations` (optional object)
+      If all `annotations` key/value pairs match a key/value pair from the configured annotations, this condition matches.
+      Both keys and values must be POSIX extended regular expressions.
+  * `commands` (optional array of strings)
+      If the configured `process.args[0]` matches an entry, this condition matches.
+      Entries must be POSIX extended regular expressions.
+  * `hasBindMounts` (optional boolean)
+      If `hasBindMounts` is true and the caller requested host-to-container bind mounts, this condition matches.
+
+`stages` (required array of strings)
+  Stages when the hook must be injected.  Entries must be chosen from the 1.0.1 OCI Runtime Specification hook stages or from extension stages supported by the package consumer.
+
+If *all* of the conditions set in `when` match, then the `hook` must be injected for the stages set in `stages`.
+
+## 0.1.0 Hook Schema
+
+`hook` (required string)
+  Sets `path` in the injected hook.
+
+`arguments` (optional array of strings)
+  Additional arguments to pass to the hook.  The injected hook's `args` is `hook` with `arguments` appended.
+
+`stages` (required array of strings)
+  Stages when the hook must be injected.  `stage` is an allowed synonym for this property, but you must not set both `stages` and `stage`.  Entries must be chosen from the 1.0.1 OCI Runtime Specification hook stages or from extension stages supported by the package consumer.
+
+`cmds` (optional array of strings)
+  The hook must be injected if the configured `process.args[0]` matches an entry.  `cmd` is an allowed synonym for this property, but you must not set both `cmds` and `cmd`.  Entries must be POSIX extended regular expressions.
+
+`annotations` (optional array of strings)
+  The hook must be injected if an `annotations` entry matches a value from the configured annotations.  `annotation` is an allowed synonym for this property, but you must not set both `annotations` and `annotation`.  Entries must be POSIX extended regular expressions.
+
+`hasbindmounts` (optional boolean)
+  The hook must be injected if `hasBindMounts` is true and the caller requested host-to-container bind mounts.
+
+# EXAMPLE
+
+## 1.0.0 Hook Schema
+
+The following configuration injects `oci-systemd-hook` in the pre-start and post-stop stages if `process.args[0]` ends with `/init` or `/systemd`:
+
+```console
+$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
+{
+  "version": "1.0.0",
+  "hook": {
+    "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
+  }
+  "when": {
+    "args": [".*/init$" , ".*/systemd$"],
+  },
+  "stages": ["prestart", "poststop"]
+}
+```
+
+The following example injects `oci-umount --debug` in the pre-start stage if the container is configured to bind-mount host directories into the container.
+
+```console
+$ cat /etc/containers/oci/hooks.d/oci-umount.json
+{
+  "version": "1.0.0",
+  "hook": {
+    "path": "/usr/libexec/oci/hooks.d/oci-umount",
+    "args": ["oci-umount", "--debug"],
+  }
+  "when": {
+    "hasBindMounts": true,
+  },
+  "stages": ["prestart"]
+}
+```
+
+The following example injects `nvidia-container-runtime-hook prestart` with particular environment variables in the pre-start stage if the container is configured with an `annotations` entry whose key matches `^com\.example\.department$` and whose value matches `.*fluid-dynamics.*`.
+
+```console
+$ cat /etc/containers/oci/hooks.d/nvidia.json
+{
+  "hook": {
+    "path": "/usr/sbin/nvidia-container-runtime-hook",
+    "args": ["nvidia-container-runtime-hook", "prestart"],
+    "env": [
+      "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
+      "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
+    ]
+  },
+  "when": {
+    "annotations": {
+      "^com\.example\.department$": ".*fluid-dynamics$"
+    }
+  },
+  "stages": ["prestart"]
+}
+```
+
+## 0.1.0 Hook Schema
+
+The following configuration injects `oci-systemd-hook` in the pre-start and post-stop stages if `process.args[0]` ends with `/init` or `/systemd`:
+
+```console
+$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
+{
+  "cmds": [".*/init$" , ".*/systemd$"],
+  "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
+  "stages": ["prestart", "poststop"]
+}
+```
+
+The following example injects `oci-umount --debug` in the pre-start stage if the container is configured to bind-mount host directories into the container.
+
+```console
+$ cat /etc/containers/oci/hooks.d/oci-umount.json
+{
+  "hook": "/usr/libexec/oci/hooks.d/oci-umount",
+  "arguments": ["--debug"],
+  "hasbindmounts": true,
+  "stages": ["prestart"]
+}
+```
+
+The following example injects `nvidia-container-runtime-hook prestart` in the pre-start stage if the container is configured with an `annotations` entry whose value matches `.*fluid-dynamics.*`.
+
+```console
+$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
+{
+  "hook": "/usr/sbin/nvidia-container-runtime-hook",
+  "arguments": ["prestart"],
+  "annotations: [".*fluid-dynamics.*"],
+  "stages": ["prestart"]
+}
+```
+
+# SEE ALSO
+
+`oci-systemd-hook(1)`, `oci-umount(1)`, `locale(7)`
+
+* [OCI Runtime Specification, 1.0.1, POSIX-platform hooks](https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks)
+* [OCI Runtime Specification, 1.0.1, process](https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process)
+* [POSIX extended regular expressions (EREs)](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)