docs: more clarifications

docs/docker.rst

@@ -56,10 +56,10 @@ See the Docker documentation for
 Using the Docker image on the command line
 ==========================================
 
-**Unlike typical Docker containers**, in this mode we are using the
-OCRmyPDF Docker container is intended to be emphemeral – it runs for one
-OCR job and then terminates, just like a command line program. We are
-using Docker as a way of delivering an application, not a server.
+**Unlike typical Docker containers**, in this section the OCRmyPDF Docker
+container is emphemeral – it runs for one OCR job and terminates, just like a
+command line program. We are using Docker to deliver an application (as opposed
+to the more conventional case, where a Docker container runs as a server).
 
 To start a Docker container (instance of the image):
 
@@ -69,22 +69,21 @@ To start a Docker container (instance of the image):
    docker run --rm -i ocrmypdf (... all other arguments here...)
 
 For convenience, create a shell alias to hide the Docker command. It is
-easier to send the input file to file stdin and read the output from
-stdout – this avoids the occasionally messy permission issues with
-Docker entirely.
+easier to send the input file as stdin and read the output from
+stdout – **this avoids the messy permission issues with Docker entirely**.
 
 .. code-block:: bash
 
-   alias ocrmypdf='docker run --rm -i ocrmypdf'
-   ocrmypdf --version  # runs docker version
-   ocrmypdf <input.pdf >output.pdf
+   alias docker_ocrmypdf='docker run --rm -i ocrmypdf'
+   docker_ocrmypdf --version  # runs docker version
+   docker_ocrmypdf <input.pdf >output.pdf
 
 Or in the wonderful `fish shell <https://fishshell.com/>`__:
 
 .. code-block:: fish
 
-   alias ocrmypdf 'docker run --rm ocrmypdf'
-   funcsave ocrmypdf
+   alias docker_ocrmypdf 'docker run --rm ocrmypdf'
+   funcsave docker_ocrmypdf
 
 Alternately, you could mount the local current working directory as a
 Docker volume:
@@ -93,6 +92,9 @@ Docker volume:
 
    docker run --rm -v $(pwd):/data ocrmypdf /data/input.pdf /data/output.pdf
 
+(However, when done this way, ``output.pdf`` may be owned by the root
+user.)
+
 .. _docker-lang-packs:
 
 Adding languages to the Docker image

docs/installation.rst

@@ -311,17 +311,15 @@ Installing AUR packages as root is not allowed, so you must first `setup a
 non-root user
 <https://wiki.archlinux.org/index.php/Users_and_groups#User_management>`__ and
 `configure sudo <https://wiki.archlinux.org/index.php/Sudo#Configuration>`__.
-If you are using a VM image, such as `the official Vagrant image
-<https://app.vagrantup.com/archlinux/boxes/archlinux>`__, this may already be
-completed for you.
+The standard Docker image, ``archlinux/base:latest``, does **not** have a
+non-root user configured, so users of that image must follow these guides. If
+you are using a VM image, such as `the official Vagrant image
+<https://app.vagrantup.com/archlinux/boxes/archlinux>`__, this work may already
+be completed for you.
 
 Next you should install the `base-devel package group
 <https://www.archlinux.org/groups/x86_64/base-devel/>`__. This includes the
 standard tooling needed to build packages, such as a compiler and binary tools.
-`As noted in the Arch Wiki
-<https://wiki.archlinux.org/index.php/Makepkg#Usage>`__, "packages belonging to
-this group are not required to be listed as build-time dependencies
-(makedepends) in PKGBUILD files".
 
 .. code-block:: bash