build: doc'n support for --authfile flag (#219)

* add doc'n of SINGULARITY_AUTHFILE

* note abt relation btw (SINGULARITY_)DOCKER_xyz envvars and --authfile

* added mentioned of --authfile to "Authentication During a Build"

Author: preminger

singularity_and_docker.rst

@@ -614,9 +614,10 @@ ensure that the credentials needed to access the image are available to
 A build might be run as the ``root`` user, e.g. via ``sudo``, or under
 your own account with ``--fakeroot``.
 
-If you are running the build as ``root``, using ``sudo``, then any
-stored credentials or environment variables must be available to the
-``root`` user:
+If you are running the build as ``root``, using ``sudo``, then any stored
+credentials or environment variables must be available to the ``root`` user. You
+can make the credentials available to the ``root`` user in one of the following
+ways:
 
 -  Use the ``--docker-login`` flag for a one-time interactive login.
    I.E. run ``sudo singularity build --docker-login myimage.sif
@@ -634,6 +635,14 @@ stored credentials or environment variables must be available to the
 -  Use ``sudo docker login`` if ``docker`` is on your machine. This is
    separate from storing the credentials under your own account.
 
+-  Store the credentials in a custom file on your filesystem using the
+   ``registry login --authfile <path>`` subcommand, and then pass the same
+   ``--authfile <path>`` flag to the ``build`` command. Note, however, that this
+   will store the relevant credentials unencrypted in the specified file, so
+   appropriate care must be taken concerning the location, ownership, and
+   permissions of this file. See the :ref:`documentation of the --authfile flag
+   <sec:authfile>` for more information.
+
 If you are running the build under your account via the ``--fakeroot``
 feature you do not need to specially set credentials for the root user.