Correct my misunderstanding and add documentation that would have helped past me

I did not see the "Can I use repo2docker to bootstrap my own
Dockerfile?" FAQ the first time through. I've linked it from the part
that I _did_ see so hopefully the next person through (maybe me in 6
months) won't have the same misunderstanding!

docs/source/config_files.rst

@@ -240,14 +240,13 @@ In the majority of cases, providing your own Dockerfile is not necessary as the
 images provide core functionality, compact image sizes, and efficient builds. We recommend
 trying the other configuration files before deciding to use your own Dockerfile.
 
-With Dockerfiles, a regular Docker build will be performed.
+Try the ``--appendix`` :ref:`CLI flag <usage-cli>` as a last resort. If you
+still can't achieve your goals, you should create a Dockerfile from scratch to
+define your image.
 
 .. note::
-    If a Dockerfile is present, all other configuration files will be ignored.
-
-If you're working on an existing project and need the `Dockerfile` escape
-hatch, you can :ref:`view the generated Dockerfile
-<usage-debugging-with-debug-and-no-build>`.
+   With Dockerfiles, a regular Docker build will be performed. All other
+   configuration files will be ignored.
 
 See the `Advanced Binder Documentation <https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html>`_ for
 best-practices with Dockerfiles.

docs/source/faq.rst

@@ -115,6 +115,9 @@ flag for each variable that you want to define.
 
 For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...``
 
+
+.. _faq-dockerfile-bootstrap:
+
 Can I use repo2docker to bootstrap my own Dockerfile?
 -----------------------------------------------------
 
@@ -189,3 +192,33 @@ tool called `source2image <https://github.com/openshift/source-to-image/>`_.
 This is an excellent open tool for containerization, but we
 ultimately decided that it did not fit the use-case we wanted to address. For more information,
 `here <https://github.com/yuvipanda/words/blob/fd096dd49d87e624acd8bdf6d13c0cecb930bb3f/content/post/why-not-s2i.md>`_ is a short blog post about the decision and the reasoning behind it.
+
+
+Where are my ``man`` pages?
+---------------------------
+
+The base image used by ``repo2docker`` is `Minimal Ubuntu
+<https://wiki.ubuntu.com/Minimal>`_ version 18. In Minimal Ubuntu, ``man``
+pages are disabled to reduce image size. If your use case is interactive
+computing or education, you may want to re-enable ``man`` pages. To do this,
+use the ``--appendix`` :ref:`CLI flag <usage-cli>` to pass in additional
+``Dockerfile`` instructions, for example:
+
+.. code-block:: dockerfile
+
+   # Re-enable man pages disabled in Ubuntu 18 minimal image
+   # https://wiki.ubuntu.com/Minimal
+   USER root
+   RUN yes | unminimize
+   # NOTE: $NB_PYTHON_PREFIX is the same as $CONDA_PREFIX at run-time.
+   # $CONDA_PREFIX isn't available in this context.
+   # NOTE: Prepending ensures a working path; if $MANPATH was previously empty,
+   # the trailing colon ensures that system paths are searched.
+   ENV MANPATH="${NB_PYTHON_PREFIX}/share/man:${MANPATH}"
+   RUN mandb
+
+   # Revert to default user
+   USER ${NB_USER}
+
+This appendix can be used by, for example, writing it to a file named
+``appendix`` and executing ``repo2docker --appendix "$(cat appendix)" .``.

docs/source/usage.rst

@@ -111,6 +111,11 @@ by ``repo2docker`` to see how to configure the build process.
 Debugging repo2docker with ``--debug`` and ``--no-build``
 =========================================================
 
+.. warning::
+
+   This feature is *not* for bootstrapping a custom Dockerfile. Please see the
+   :ref:`relevant FAQ entry <faq-dockerfile-bootstrap>`.
+
 To debug the docker image being built, pass the ``--debug`` parameter:
 
 .. code-block:: bash
@@ -128,12 +133,8 @@ be used by docker directly.
 
    jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
 
-.. warning::
-
-   ``repo2docker --no-build --debug . > Dockerfile`` will create an empty
-   Dockerfile. Please use ``repo2docker --no-build --debug . > tmp_Dockerfile
-   && mv tmp_Dockerfile Dockerfile`` instead!
 
+.. _usage-cli:
 
 Command line API
 ================