--- a/doc/Compiling	Wed Oct 26 06:34:12 2016 +0000
+++ b/doc/Compiling	Wed Oct 26 07:35:42 2016 +0000
@@ -1,14 +1,43 @@
 Building and installing FreeCalypso host tools
 ==============================================
 
-In order to compile and install our host tools, just run 'make', then
-'make install' as root.
+Our FreeCalypso host tools are designed to be installed in the /opt/freecalypso
+directory hierarchy on your system.  The author of this software is very
+old-fashioned and refuses to use autotools (sorry, we aren't GNU), hence
+various hard-coded paths under /opt/freecalypso are sprinkled in bazillion
+places - thus changing this fixed install location is deemed to be impractical.
+
+In order to compile and install our host tools, follow these steps:
+
+1: Run 'make' as a regular user (not root) to compile the software.
+
+2: Decide if you prefer to have the /opt/freecalypso directory and everything
+   under it to be owned by root or by your non-root uid.
+
+If you prefer /opt/freecalypso to be root-owned:
+
+   3A: Run 'make install' as root; the install rule in the
+       Makefile will do mkdir -p /opt/freecalypso as its first step.
 
-The "standard" install directories are /usr/local/bin for binaries and
-/usr/local/share/freecalypso for helper files.  If you need to change these
-paths to something else, you'll need to edit a bunch of individual component
-Makefiles, and possibly also some source files like loadtools/defpath.c -
-sorry, FreeCalypso is not GNU and does not use autotools.
+   4A: You are done!
+
+If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
+
+   3A: Become root just to create the /opt/freecalypso directory and chown it
+       to your non-root uid.
+
+   4A: Run 'make install' as your regular uid; it should succeed because you
+       should have made yourself the owner of /opt/freecalypso with full write
+       permission in the previous step.
+
+   5A: You are done!
+
+The host tool binaries will be installed in /opt/freecalypso/bin; you can
+either add this directory to your PATH or make symlinks from /usr/bin or
+/usr/local/bin or wherever.
+
+Dependencies
+============
 
 All FreeCalypso host tools are written in plain C, and with the exception of one
 special hack-utility that has been excluded from the standard build set, they
@@ -57,10 +86,10 @@
 ======================
 
 Running 'make' in the target-utils tree with the ARM7 toolchain present in your
-PATH will result in compalstage and loadagent being built; these are the two
-components needed in order to use FreeCalypso loadtools.  Run 'make install' to
-install these target binaries in /usr/local/share/freecalypso, which is where
-loadtools will look for them.
+PATH will result in several target binaries being built, including compalstage
+and loadagent which are needed in order to use FreeCalypso loadtools.  Run
+'make install' to install these target binaries in /opt/freecalypso/target-bin,
+which is where loadtools will look for them.
 
-Run 'make all' in target-utils to build some other components that aren't
-really needed.
+Run 'make all' in target-utils to build some additional target code pieces that
+are needed only for development and only very rarely.