--- a/README	Sun Nov 04 17:42:39 2018 +0000
+++ b/README	Sun Nov 04 19:24:46 2018 +0000
@@ -2,58 +2,31 @@
 tools in this package have been written to run on a Unix-based or Unix-like
 host system, such as a GNU/Linux PC or laptop, with the expectation that the
 user will compile them from the source using her regular system C compiler.
-See INSTALL for installation instructions.
-
-Most of these tools interface to and operate on Calypso-based GSM devices,
-while a few perform some ancillary functions.  Please see
-doc/Host-tools-overview for the listing of what tools are available and what
-they do.  These tools are built in the following source directories:
-
-ffstools	This directory subtree contains tools for "in vitro" analysis
-		of flash file system images read out of Calypso GSM devices,
-		as well as for analysis of some specific content from these
-		file systems.
-
-loadtools	fc-loadtool, fc-iram, fc-xram and fc-compalram form the part of
-		FC host tools called loadtools, which used to be its own
-		package.  In common with the rest of FC host tools, loadtools
-		run on a PC or whatever host system, but they also require two
-		target-side components called loadagent (for all targets) and
-		compalstage (for Compal phones only).  If you are working with
-		a packaged release of FC host tools, as opposed to a random
-		snapshot of the source tree, precompiled binaries for loadagent
-		and compalstage will be included in the target-bin directory.
-
-		fc-buzplay is also built in the loadtools suite because it uses
-		many of the same components.
-
-miscutil	A few miscellaneous utilities are built here.
+See INSTALL for installation instructions.  Most of these tools interface to
+and operate on Calypso-based GSM devices, while a few perform some ancillary
+functions.  Please see doc/Host-tools-overview for the listing of what tools
+are available and what they do.
 
-ringtools	Tools for working with ringtone melodies are built here.
-
-rvinterf	Everything dealing with the RVTMUX interface to running GSM
-		firmwares and everything based on the rvinterf framework is
-		built under rvinterf.
-
-		The tfc139 utility, which logically belongs with loadtools, is
-		built in the rvinterf subtree because it is built from mostly
-		the same source components as rvtdump and rvinterf.
-
-uptools		The User Phone Tools suite is built here - see
-		doc/User-phone-tools.
+The most commonly needed tool for flashing firmware images (fc-loadtool) and
+some of the more rarely needed tools (fc-xram, fc-iram when used with Mot C1xx
+phones, and fc-buzplay) have target-side components, i.e., a part of their
+functionality is implemented in Calypso ARM7 code pieces which these tools feed
+to the Calypso chip's boot ROM or to Mot/Compal's bootloader on Mot C1xx phones.
+The most important of these ARM7 code pieces is loadagent (implements flash
+reading and writing, hardware peeks and pokes, and the chain loading function
+for fc-xram) which is needed for all of our supported Calypso targets (it is
+also common to all of them, no variants), and the second most important piece
+is compalstage, which is needed for Compal (Mot C1xx) phones only.
 
-The 6 directories listed above plus the two common libraries librftab and
-libserial contain all of FC host tools; they are all you need in order to get a
-fully working installation of these tools if you are using the provided
-precompiled binaries for loadagent and compalstage.  However, if you would like
-to recompile these components from source, you will need the following
-additional stuff:
+If you are working with a packaged release of FC host tools, as opposed to a
+random snapshot of the source tree, precompiled binaries for loadagent and
+compalstage will be included in the target-bin directory, otherwise you will
+need to build them from source: the source for loadagent and compalstage (plus
+a few extra target utilities that are of interest only to developers) resides
+in target-utils, and you will first need to build and install a special ARM7
+gcc toolchain as explained in the INSTALL document.
 
-target-utils	The source for loadagent and compalstage lives here, along with
-		a few extra target utilities that are of interest only to
-		developers.
+There is a good amount of documentation included in the doc directory, and
+there is more documentation in our dedicated freecalypso-docs repository:
 
-toolchain	Scripts and patches for building the gcc+binutils toolchain
-		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband
-		processor.  You'll need to build and install this toolchain
-		first before you can build target-utils.
+https://bitbucket.org/falconian/freecalypso-docs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Source-dirs	Sun Nov 04 19:24:46 2018 +0000
@@ -0,0 +1,45 @@
+ffstools	This directory subtree was originally created to hold the source
+		for our TIFFS In Vitro Analyzer tool, but has since been
+		extended to contain various tools that perform static (or "in
+		vitro") transformations on various bits of data that go into
+		the flash file system on our FreeCalypso GSM devices or are
+		contained in other vendors' flash data structures.
+
+librftab	A library for reading and writing RF parameter tables in our
+		FreeCalypso ASCII format - see doc/RF_tables.
+
+libserial	All of our host programs that operate on serial ports (the way
+		in which we communicate with GSM device targets) go through
+		libserial, i.e., our serial port handling code has been factored
+		out into a common library.
+
+loadtools	fc-loadtool, fc-iram, fc-xram and fc-compalram form the part of
+		FC host tools called loadtools, which used to be its own
+		package.
+
+		fc-buzplay is also built in the loadtools suite because it uses
+		many of the same components.
+
+miscutil	A few miscellaneous utilities are built here.
+
+ringtools	Tools for working with ringtone melodies are built here.
+
+rvinterf	Everything dealing with the RVTMUX interface to running GSM
+		firmwares and everything based on the rvinterf framework is
+		built under rvinterf.
+
+		The tfc139 utility, which logically belongs with loadtools, is
+		built in the rvinterf subtree because it is built from mostly
+		the same source components as rvtdump and rvinterf.
+
+target-utils	The source for loadagent and compalstage lives here, along with
+		a few extra target utilities that are of interest only to
+		developers.
+
+toolchain	Scripts and patches for building the gcc+binutils toolchain
+		targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband
+		processor.  You'll need to build and install this toolchain
+		first before you can build target-utils.
+
+uptools		The User Phone Tools suite is built here - see
+		doc/User-phone-tools.