docs: improve man pages layout

Signed-off-by: Luca Di Maio <luca.dimaio1@gmail.com>
89luca89 · Jun 22, 2022 · 2a26ab6 · 2a26ab6
1 parent b91af1b
commit 2a26ab6
Show file tree

Hide file tree

Showing 10 changed files with 208 additions and 148 deletions.
diff --git a/docs/usage/distrobox-create.md b/docs/usage/distrobox-create.md
@@ -1,36 +1,19 @@
-<!-- markdownlint-disable MD010 -->
-# Create the distrobox
+<!-- markdownlint-disable MD010 MD036 -->
+# NAME
+
+	distrobox create
+	distrobox-create
+
+# DESCRIPTION
 
 distrobox-create takes care of creating the container with input name and image.
 The created container will be tightly integrated with the host, allowing sharing of
 the HOME directory of the user, external storage, external usb devices and
 graphical apps (X11/Wayland), and audio.
 
-Usage:
-
-	distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
-	distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
-	distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
-	distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
-	distrobox create --clone fedora-35 --name fedora-35-copy
-	distrobox create --image alpine my-alpine-container
-	distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
-	distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
-
-You can also use environment variables to specify container name, image and container manager:
-
-	DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
-
-Supported environment variables:
-
-	DBX_CONTAINER_ALWAYS_PULL
-	DBX_CONTAINER_CUSTOM_HOME
-	DBX_CONTAINER_IMAGE
-	DBX_CONTAINER_MANAGER
-	DBX_CONTAINER_NAME
-	DBX_NON_INTERACTIVE
+# SYNOPSIS
 
-Options:
+**distrobox create**
 
 	--image/-i:		image to use for the container	default: registry.fedoraproject.org/fedora-toolbox:36
 	--name/-n:		name for the distrobox		default: my-distrobox
@@ -53,13 +36,37 @@ Options:
 	--verbose/-v:		show more verbosity
 	--version/-V:		show version
 
-Compatibility:
+# COMPATIBILITY
 
 	for a list of compatible images and container managers, please consult the man page:
 		man distrobox
 		man distrobox-compatibility
 	or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
 
+# EXAMPLES
+
+	distrobox create --image alpine:latest --name test --init-hooks "touch /var/tmp/test1 && touch /var/tmp/test2"
+	distrobox create --image fedora:35 --name test --additional-flags "--env MY_VAR-value"
+	distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags "--pids-limit -1"
+	distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks "dnf config-manager --enable powertools && dnf -y install epel-release"
+	distrobox create --clone fedora-35 --name fedora-35-copy
+	distrobox create --image alpine my-alpine-container
+	distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
+	distrobox create --pull --image centos:stream9 --home ~/distrobox/centos9
+
+You can also use environment variables to specify container name, image and container manager:
+
+	DBX_CONTAINER_MANAGER="docker" DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
+
+Supported environment variables:
+
+	DBX_CONTAINER_ALWAYS_PULL
+	DBX_CONTAINER_CUSTOM_HOME
+	DBX_CONTAINER_IMAGE
+	DBX_CONTAINER_MANAGER
+	DBX_CONTAINER_NAME
+	DBX_NON_INTERACTIVE
+
 The `--additional-flags` or `-a` is useful to modify defaults in the container creations.
 For example:
 

diff --git a/docs/usage/distrobox-enter.md b/docs/usage/distrobox-enter.md
@@ -1,13 +1,34 @@
-<!-- markdownlint-disable MD010 -->
-# Enter the distrobox
+<!-- markdownlint-disable MD010 MD036 -->
+# NAME
+
+	distrobox enter
+	distrobox-enter
+
+# DESCRIPTION
 
 distrobox-enter takes care of entering the container with the name specified.
 Default command executed is your SHELL, but you can specify different shells or
 entire commands to execute.
 If using it inside a script, an application, or a service, you can specify the
 --headless mode to disable tty and interactivity.
 
-Usage:
+# SYNOPSIS
+
+**distrobox enter**
+
+	--name/-n:		name for the distrobox						default: my-distrobox
+	--/-e:			end arguments execute the rest as command to execute at login	default: bash -l
+	--no-tty/-T:		do not instantiate a tty
+	--no-workdir/-nw:		always start the container from container's home directory
+	--additional-flags/-a:	additional flags to pass to the container manager command
+	--help/-h:		show this message
+	--root/-r:		launch podman/docker with root privileges. Note that if you need root this is the preferred
+				way over "sudo distrobox"
+	--dry-run/-d:		only print the container manager command generated
+	--verbose/-v:		show more verbosity
+	--version/-V:		show version
+
+# EXAMPLES
 
 	distrobox-enter --name fedora-toolbox-35 -- bash -l
 	distrobox-enter my-alpine-container -- sh -l
@@ -25,20 +46,6 @@ Supported environment variables:
 	DBX_CONTAINER_MANAGER
 	DBX_SKIP_WORKDIR
 
-Options:
-
-	--name/-n:		name for the distrobox						default: my-distrobox
-	--/-e:			end arguments execute the rest as command to execute at login	default: bash -l
-	--no-tty/-T:		do not instantiate a tty
-	--no-workdir/-nw:		always start the container from container's home directory
-	--additional-flags/-a:	additional flags to pass to the container manager command
-	--help/-h:		show this message
-	--root/-r:		launch podman/docker with root privileges. Note that if you need root this is the preferred
-				way over "sudo distrobox"
-	--dry-run/-d:		only print the container manager command generated
-	--verbose/-v:		show more verbosity
-	--version/-V:		show version
-
 This is used to enter the distrobox itself. Personally, I just create multiple profiles in
 my `gnome-terminal` to have multiple distros accessible.
 

diff --git a/docs/usage/distrobox-export.md b/docs/usage/distrobox-export.md
@@ -1,53 +1,22 @@
-<!-- markdownlint-disable MD010 -->
-# Application and service exporting
+<!-- markdownlint-disable MD010 MD036 -->
 
-distrobox-export takes care of exporting an app a binary or a service from the container
-to the host.
-
-The exported app will be easily available in your normal launcher and it will
-automatically be launched from the container it is exported from.
-
-The exported services will be available in the host's user's systemd session, so
-
-	systemctl --user status exported_service_name
-
-will show the status of the service exported.
+# NAME
 
-The exported binaries will be exported in the "--export-path" of choice as a wrapper
-script that acts naturally both on the host and in the container.
-Note that "--export-path" is NOT OPTIONAL, you have to explicitly set it.
+	distrobox-export
 
-You can specify additional flags to add to the command, for example if you want
-to export an electron app, you could add the "--foreground" flag to the command:
+# DESCRIPTION
 
-	distrobox-export --app atom --extra-flags "--foreground"
-	distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"
-	distrobox-export --service syncthing --extra-flags "-allow-newer-config"
+**Application and service exporting**
 
-This works for services, binaries, and apps.
-Extra flags are only used then the exported app, binary, or service is used from
-the host, using them inside the container will not include them.
-
-The option "--delete" will un-export an app, binary, or service.
-
-	distrobox-export --app atom --delete
-	distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete
-	distrobox-export --service syncthing --delete
-	distrobox-export --service nginx --delete
-
-The option "--sudo" will launch the exported item as root inside the distrobox.
-
-Note you can use --app OR --bin OR --service but not together.
-
-	distrobox-export --service nginx --sudo
+distrobox-export takes care of exporting an app a binary or a service from the container
+to the host.
 
-Usage:
+The exported app will be easily available in your normal launcher and it will
+automatically be launched from the container it is exported from.
 
-	distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
-	distrobox-export --service syncthing [--extra-flags "flags"] [--delete] [--sudo]
-	distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
+# SYNOPSIS
 
-Options:
+**distrobox-export**
 
 	--app/-a:		name of the application to export
 	--bin/-b:		absolute path of the binary to export
@@ -65,15 +34,21 @@ Options:
 You may want to install graphical applications or user services in your distrobox.
 Using `distrobox-export` from **inside** the container will let you use them from the host itself.
 
-App export example:
+# EXAMPLES
+
+	distrobox-export --app mpv [--extra-flags "flags"] [--delete] [--sudo]
+	distrobox-export --service syncthing [--extra-flags "flags"] [--delete] [--sudo]
+	distrobox-export --bin /path/to/bin --export-path ~/.local/bin [--extra-flags "flags"] [--delete] [--sudo]
+
+**App export example**
 
 	distrobox-export --app abiword
 
 This tool will simply copy the original `.desktop` files along with needed icons,
 add the prefix `/usr/local/bin/distrobox-enter -n distrobox_name -e ...` to the commands to run, and
 save them in your home to be used directly from the host as a normal app.
 
-Service export example:
+**Service export example**
 
 	distrobox-export --service syncthing --extra-flags "--allow-newer-config"
 	distrobox-export --service nginx --sudo
@@ -83,7 +58,13 @@ For services, it will similarly export the systemd unit inside the container to
 `ExecStart ExecStartPre ExecStartPost ExecReload ExecStop ExecStopPost` with the
 `distrobox-enter` command prefix.
 
-Binary export example:
+The exported services will be available in the host's user's systemd session, so
+
+	systemctl --user status exported_service_name
+
+will show the status of the service exported.
+
+**Binary export example**
 
 	distrobox-export --bin /usr/bin/code --extra-flags "--foreground" --export-path $HOME/.local/bin
 
@@ -93,6 +74,42 @@ In the case of exporting binaries, you will have to specify **where** to export
 This can be handy with the use of `direnv` to have different versions of the same binary based on
 your `env` or project.
 
+The exported binaries will be exported in the "--export-path" of choice as a wrapper
+script that acts naturally both on the host and in the container.
+Note that "--export-path" is NOT OPTIONAL, you have to explicitly set it.
+
+**Additional flags**
+
+You can specify additional flags to add to the command, for example if you want
+to export an electron app, you could add the "--foreground" flag to the command:
+
+	distrobox-export --app atom --extra-flags "--foreground"
+	distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --extra-flags "-p"
+	distrobox-export --service syncthing --extra-flags "-allow-newer-config"
+
+This works for services, binaries, and apps.
+Extra flags are only used then the exported app, binary, or service is used from
+the host, using them inside the container will not include them.
+
+**Unexport**
+
+The option "--delete" will un-export an app, binary, or service.
+
+	distrobox-export --app atom --delete
+	distrobox-export --bin /usr/bin/vim --export-path ~/.local/bin --delete
+	distrobox-export --service syncthing --delete
+	distrobox-export --service nginx --delete
+
+**Run as root in the container**
+
+The option "--sudo" will launch the exported item as root inside the distrobox.
+
+**Notes**
+
+Note you can use --app OR --bin OR --service but not together.
+
+	distrobox-export --service nginx --sudo
+
 ![app-export](https://user-images.githubusercontent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)
 
 ![service-export](https://user-images.githubusercontent.com/598882/144294314-29a8921f-4511-453d-bf8e-d0d1e336db91.png)

diff --git a/docs/usage/distrobox-host-exec.md b/docs/usage/distrobox-host-exec.md
@@ -1,5 +1,9 @@
-<!-- markdownlint-disable MD010 -->
-# Host Command Execution
+<!-- markdownlint-disable MD010 MD036 -->
+# NAME
+
+	distrobox-host-exec
+
+# DESCRIPTION
 
 distrobox-host-exec lets one execute command on the host, while inside of a container.
 
@@ -8,21 +12,21 @@ most powerful and recommended method. If, instead, "flatpak-spawn" can't be foun
 still try to get the job done with "chroot" (but beware that not all commands/programs
 will work well in this mode).
 
+# SYNOPSIS
+
 Just pass to "distrobox-host-exec" any command and all its arguments, if any.
 
 	distrobox-host-exec [command [arguments]]
 
+	--help/-h:		show this message
+	--verbose/-v:		show more verbosity
+	--version/-V:		show version
+
 If no command is provided, it will execute "/bin/sh".
 
-Example usage:
+# EXAMPLES
 
 	distrobox-host-exec ls
 	distrobox-host-exec bash -l
 	distrobox-host-exec flatpak run org.mozilla.firefox
 	distrobox-host-exec podman ps -a
-
-Options:
-
-	--help/-h:		show this message
-	--verbose/-v:		show more verbosity
-	--version/-V:		show version
diff --git a/docs/usage/distrobox-init.md b/docs/usage/distrobox-init.md
@@ -1,22 +1,26 @@
-<!-- markdownlint-disable MD010 -->
-# Init the distrobox (not to be launched manually)
+<!-- markdownlint-disable MD010 MD036 -->
+# NAME
+
+	distrobox-init
+
+# DESCRIPTION
+
+**Init the distrobox (not to be launched manually)**
 
 distrobox-init is the entrypoint of a created distrobox.
 Note that this HAS to run from inside a distrobox, will not work if you run it
 from your host.
 
-This is not intended to be used manually, but instead used by distrobox-enter
-to set up the container's entrypoint.
+**This is not intended to be used manually, but instead used by distrobox-create
+to set up the container's entrypoint.**
 
 distrobox-init will take care of installing missing dependencies (eg. sudo), set
 up the user and groups, mount directories from the host to ensure the tight
 integration.
 
-Usage:
+# SYNOPSIS
 
-	distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
-
-Options:
+**distrobox-init**
 
 	--name/-n:		user name
 	--user/-u:		uid of the user
@@ -29,8 +33,6 @@ Options:
 	--version/-V:		show version
 	--:			end arguments execute the rest as command to execute during init
 
-This is used as entrypoint for the created container, it will take care of creating the users,
-setting up sudo, mountpoints, and exports.
+# EXAMPLES
 
-**You should not have to launch this manually**, this is used by `distrobox create` to set up
-container's entrypoint.
+	distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user