Add manuals

https://github.com/debarshiray/toolbox/pull/66

doc/meson.build

@@ -0,0 +1,26 @@
+go_md2man_command = [
+  go_md2man,
+  '-in', '@INPUT@',
+  '-out', '@OUTPUT@',
+]
+
+manuals = [
+  'toolbox.1',
+  'toolbox-create.1',
+  'toolbox-enter.1',
+  'toolbox-list.1',
+]
+
+foreach manual: manuals
+  input = manual + '.md'
+  output = manual
+
+  custom_target(
+    output,
+    command: go_md2man_command,
+    input: input,
+    install: true,
+    install_dir: get_option('mandir'),
+    output: output,
+  )
+endforeach

doc/toolbox-create.1.md

@@ -0,0 +1,82 @@
+% toolbox-create(1)
+
+## NAME
+toolbox\-create - Create a new toolbox container
+
+## SYNOPSIS
+**toolbox create** [*--candidate-registry*]
+               [*--container NAME*]
+               [*--image NAME*]
+               [*--release RELEASE*]
+
+## DESCRIPTION
+
+Creates a new toolbox container. You can then use the `toolbox enter` command
+to interact with the container at any point.
+
+The toolbox container is an OCI container created from an OCI image. On Fedora
+the base image is known as `fedora-toolbox`. If the image is not present
+locally, then it is pulled from `registry.fedoraproject.org`. The base image is
+locally customized for the current user to create a second image, from which
+the container is finally created.
+
+Toolbox containers and images are tagged with the version of the OS that
+corresponds to the content inside them. The user-specific images and the
+toolbox containers are prefixed with the name of the base image and suffixed
+with the current user name.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--candidate-registry**
+
+Pull the base image from `candidate-registry.fedoraproject.org`. This is
+useful for testing newly built images before they have moved to the stable
+registry at `registry.fedoraproject.org`.
+
+**--container** NAME
+
+Assign a different NAME to the toolbox container. This is useful for creating
+multiple toolbox containers from the same base image, or for entirely
+customized containers from custom-built base images.
+
+**--image** NAME
+
+Change the NAME of the base image used to create the toolbox container. This
+is useful for creating containers from custom-built base images.
+
+**--release** RELEASE
+
+Create a toolbox container for a different operating system RELEASE than the
+host.
+
+## EXAMPLES
+
+### Create a toolbox container using the default image matching the host OS
+
+```
+$ toolbox create
+```
+
+### Create a toolbox container using the default image for Fedora 30
+
+```
+$ toolbox create --release f30
+```
+
+### Create a custom toolbox container from a custom image
+
+```
+$ toolbox create --container foo --image bar
+```
+
+### Create a toolbox using images from the unstable candidate registry
+
+```
+$ toolbox create --candidate-registry
+```
+
+## SEE ALSO
+
+`buildah(1)`, `podman(1)`

doc/toolbox-enter.1.md

@@ -0,0 +1,56 @@
+% toolbox-enter(1)
+
+## NAME
+toolbox\-enter - Enter an existing toolbox container for interactive use
+
+## SYNOPSIS
+**toolbox enter** [*--container NAME*] [*--release RELEASE*]
+
+## DESCRIPTION
+
+Spawns an interactive shell inside an existing toolbox container. The
+container should have been created using the `toolbox create` command.
+
+The toolbox container is an OCI container. On Fedora the toolbox containers are
+tagged with the version of the OS that corresponds to the content inside them.
+Their names are prefixed with the name of the base image and suffixed with the
+current user name.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--container** NAME
+
+Enter a toolbox container with the given NAME. This is useful when there are
+multiple toolbox containers created from the same base image, or entirely
+customized containers created from custom-built base images.
+
+**--release** RELEASE
+
+Enter a toolbox container for a different operating system RELEASE than the
+host.
+
+## EXAMPLES
+
+### Enter a toolbox container using the default image matching the host OS
+
+```
+$ toolbox enter
+```
+
+### Enter a toolbox container using the default image for Fedora 30
+
+```
+$ toolbox enter --release f30
+```
+
+### Enter a custom toolbox container using a custom image
+
+```
+$ toolbox enter --container foo
+```
+
+## SEE ALSO
+
+`buildah(1)`, `podman(1)`

doc/toolbox-list.1.md

@@ -0,0 +1,48 @@
+% toolbox-list(1)
+
+## NAME
+toolbox\-list - List existing toolbox containers and images
+
+## SYNOPSIS
+**toolbox list** [*--containers* | *-c*] [*--images* | *-i*]
+
+## DESCRIPTION
+
+Lists existing toolbox containers and images. These are OCI containers and
+images, which can be managed directly with tools like `buildah` and `podman`.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--containers, -c**
+
+List only toolbox containers, not images.
+
+**--images, -i**
+
+List only toolbox images, not containers.
+
+## EXAMPLES
+
+### List all existing toolbox containers and images
+
+```
+$ toolbox list
+```
+
+### List existing toolbox containers only
+
+```
+$ toolbox list --containers
+```
+
+### List existing toolbox images only
+
+```
+$ toolbox list --images
+```
+
+## SEE ALSO
+
+`buildah(1)`, `podman(1)`

doc/toolbox.1.md

@@ -0,0 +1,62 @@
+% toolbox(1)
+
+## NAME
+toolbox - Unprivileged development environment
+
+## SYNOPSIS
+**toolbox** [*--verbose* | *-v*] *COMMAND* [*ARGS*]
+
+## DESCRIPTION
+
+Toolbox is a tool that offers a familiar RPM based environment for developing
+and debugging software that runs fully unprivileged using Podman.
+
+The toolbox container is a fully *mutable* container; when you see
+`yum install ansible` for example, that's something you can do inside your
+toolbox container, without affecting the base operating system.
+
+This is particularly useful on OSTree based Fedora systems like Silverblue.
+The intention of these systems is to discourage installation of software on
+the host, and instead install software as (or in) containers.
+
+However this tool doesn't *require* using an OSTree based system — it works
+equally well if you're running e.g. existing Fedora Workstation or Server, and
+that's a useful way to incrementally adopt containerization.
+
+The toolbox environment is based on an OCI image. On Fedora this is the
+`fedora-toolbox` image. This image is then customized for the current user to
+create a toolbox container that seamlessly integrates with the rest of the
+operating system.
+
+## OPTIONS ##
+
+The following options are understood:
+
+**--help, -h**
+
+Print a synopsis of this manual and exit.
+
+**--verbose, -v**
+
+Print debug information. This includes messages coming from the standard error
+stream of internal commands.
+
+## COMMANDS
+
+Commands for working with toolbox containers and images:
+
+**toolbox-create(1)**
+
+Create a new toolbox container.
+
+**toolbox-enter(1)**
+
+Enter an existing toolbox container for interactive use.
+
+**toolbox-list(1)**
+
+List existing toolbox containers and images.
+
+## SEE ALSO
+
+`buildah(1)`, `podman(1)`

meson.build

@@ -5,7 +5,11 @@ project(
   meson_version: '>= 0.40.0',
 )
 
+go_md2man = find_program('go-md2man')
+
 install_data(
   'toolbox',
   install_dir: get_option('bindir'),
 )
+
+subdir('doc')