Notes based on Thomas' email, and text tweaks.

Notes from Thomas Pöchtrager:
 * The *-g++-libc++ aliases use the Clang C++ library.
 * Don't use the Clang C++ library with GCC.
 * You can use an installed Clang, or build your own.
 * Same Clang serves both to compile OSXCross and as the cross-compiler.
 * INSTALLPREFIX is specifically for installing a (native!) clang.

Other tweaks to the text:
 * Broke some lines before 80 characters (found by lint check).
 * Removed some trailing spaces (found by lint check).
 * Put shell commands on their own, indendent lines.
 * Explain GCC_VERSION, ENABLE_FORTRAN, etc. explicitly.
 * Make each footnote its own paragraph, on a separate line.
 * Minor tweaks to wording for style & idiom.

README.md

@@ -2,7 +2,8 @@
 
 ### WHAT IS THE GOAL OF OSXCROSS? ###
 
-The goal of OSXCross is to provide a well working OS X cross toolchain for Linux, *BSD and Cygwin.
+The goal of OSXCross is to provide a well working OS X cross toolchain for
+Linux, *BSD, and Cygwin.
 
 ### HOW DOES IT WORK? ###
 
@@ -10,24 +11,28 @@ The goal of OSXCross is to provide a well working OS X cross toolchain for Linux
 and is now available on nearly every Linux distribution,
 so we just need a proper
 [port](https://github.com/tpoechtrager/cctools-port)
-of the [cctools](http://www.opensource.apple.com/tarballs/cctools) (ld, lipo, ...) and the OS X SDK.
+of the [cctools](http://www.opensource.apple.com/tarballs/cctools)
+(ld, lipo, ...) and the OS X SDK.
 
 If you want, then you can build an up-to-date vanilla GCC as well.
 
 ### WHAT CAN I BUILD WITH IT? ###
 
-Basically everything you can build on OS X with clang/gcc should build with this cross toolchain as well.
+Basically everything you can build on OS X with clang/gcc should build with
+this cross toolchain as well.
 
 ### PACKET MANAGERS ###
 
 OSXCross comes with a minimalistic MacPorts Packet Manager.
-Please see [README.MACPORTS](README.MACPORTS.md) for more.
+See [README.MACPORTS](README.MACPORTS.md) for more.
 
 ### INSTALLATION: ###
 
 *Windows/Cygwin users should follow [README.CYGWIN](README.CYGWIN.md).*
 
-Move your [packaged SDK](https://github.com/tpoechtrager/osxcross#packaging-the-sdk) to the tarballs/ directory.
+Move your
+[packaged SDK](https://github.com/tpoechtrager/osxcross#packaging-the-sdk)
+to the tarballs/ directory.
 
 Then ensure you have the following installed on your system:
 
@@ -45,39 +50,94 @@ Do not install libxar-dev on Ubuntu, it's a different package.
 \--
 You can run 'sudo tools/get\_dependencies.sh' to get these automatically.
 
-'[INSTALLPREFIX=...] ./build_clang.sh' can be used to build a recent clang version  
+##### Building Clang #####
-from source (requires gcc and g++).
 
-On debian like systems you can also use [llvm.org/apt](http://llvm.org/apt) to get a newer version of clang.  
+OSXCross uses `clang` as the default compiler for building its tools, and also
-But be careful, that repository is known to cause [troubles](https://github.com/tpoechtrager/osxcross/issues/16).  
+as a cross-compiler to create OSX binaries.
-\--
 
-Then run `[UNATTENDED=1] ./build.sh` to build the cross toolchain.  
+In `clang` there is no difference between cross-compilation and native
-(It will search 'tarballs' for your SDK and then build in its own directory.)
+compilation, so OSXCross can use a normal `clang` install for both.  You can
+use either a `clang` installation you already have, or build your own from
+source.
 
-**Do not forget** to add `<path>/target/bin` to your PATH variable.
+To build and install your own `clang` from a recent source tree, using `gcc`,
+run:
+
+```shell
+    ./build_clang.sh
+```
+
+This installs `clang` into `/usr/local`.  If you want to install somewhere
+else, set the `INSTALLPREFIX` variable.  For example:
+
+```shell
+    INSTALLPREFIX=/opt/clang ./build_clang.sh
+```
+
+On debian-like systems you can also use [llvm.org/apt](http://llvm.org/apt) to
+get a newer version of clang.
+But be careful, that repository is known to cause
+[troubles](https://github.com/tpoechtrager/osxcross/issues/16).
+
+
+##### Building OSXCross #####
+
+To build the cross toolchain (using `clang`), run:
+
+```shell
+    ./build.sh
+```
+
+Or, set variable `UNATTENDED` to `1` to skip the prompt and proceed straight to
+the build:
+
+```shell
+    UNATTENDED=1 ./build.sh
+```
+
+(This will search 'tarballs' for your SDK and then build in its own directory.)
+
+**Once this is done:** add `<path>/target/bin` to your PATH variable so that
+you can invoke the cross-compiler.
 
 That's it. See usage examples below.
 
 ##### Building GCC: #####
 
-If you want to build GCC as well, then you can do this by running:  
+If you also want to build GCC as a cross-compiler, you can do that by running:
-`[GCC_VERSION=5.2.0] [ENABLE_FORTRAN=1] ./build_gcc.sh`.  
+
+```shell
+    ./build_gcc.sh
+```
+
+The script lets you select a GCC version by setting the variable `GCC_VERSION`.
+ By default you get C and C++ compilers, but you can tell the script to build a
+Fortran compiler as well:
+
+```shell
+    GCC_VERSION=5.2.0 ENABLE_FORTRAN=1 ./build_gcc.sh
+```
 
 \[A gfortran usage example can be found [here](https://github.com/tpoechtrager/osxcross/issues/28#issuecomment-67047134)]
 
-But before you do this, make sure you have got the GCC build depedencies installed on your system.  
+Before you do this, make sure you have the GCC build depedencies installed on
+your system.
 
-On debian like systems you can run:
+On debian like systems you can install these using:
 
-`[sudo] apt-get install gcc g++ zlib1g-dev libmpc-dev libmpfr-dev libgmp-dev`  
+```shell
-
+    sudo apt-get install gcc g++ zlib1g-dev libmpc-dev libmpfr-dev libgmp-dev
-to install them.
+```
 
 ATTENTION:
 
-OSXCross links libgcc and libstdc++ statically by default (this affects `-foc-use-gcc-libstdc++` too).  
+OSXCross links libgcc and libstdc++ statically by default (this affects
-You can turn this behavior off with `OSXCROSS_GCC_NO_STATIC_RUNTIME=1` (env).
+`-foc-use-gcc-libstdc++` too).  You can turn this behavior off with
+`OSXCROSS_GCC_NO_STATIC_RUNTIME=1` (env).
+
+The build also creates aliases `*-g++-libc++` which link with the `clang`
+implementation of the C++ standard library instead of the GCC version.  Don't
+use these variants unless you know what you're doing.
 
 ### PACKAGING THE SDK: ###
 
@@ -90,10 +150,13 @@ You can turn this behavior off with `OSXCROSS_GCC_NO_STATIC_RUNTIME=1` (env).
 2. [Mount Xcode.dmg (Open With -> DiskImageMounter) \*\*\*]
 3. Run: `./tools/gen_sdk_package.sh` (from the OSXCross package)
 4. Copy the packaged SDK (\*.tar.\* or \*.pkg) on a USB Stick
-5. (On Linux/BSD) Copy or move the SDK into the tarballs/ directory of OSXCross
+5. (On Linux/BSD) Copy or move the SDK into the tarballs/ directory of
+   OSXCross.
 
 \*\* Xcode up to 7.3.x is known to work.
-\*\*\* If you get a dialog with a crossed circle, ignore it, you don't need to install Xcode.
+
+\*\*\* If you get a dialog with a crossed circle, ignore it.  You don't need
+to install Xcode.
 
 Step 1. and 2. can be skipped if you have Xcode installed.
 
@@ -123,23 +186,29 @@ Step 1. and 2. can be skipped if you have Xcode installed.
 
 ### USAGE EXAMPLES: ###
 
-##### Let's say you want to compile a file called test.cpp, then you can do this by running: #####
+##### Example.  To compile a file called test.cpp, you can run: #####
 
 * Clang:
 
-  * 32 bit:  `o32-clang++ test.cpp -O3 -o test`   OR   `i386-apple-darwinXX-clang++ test.cpp -O3 -o test`
+  * 32 bit: `o32-clang++ test.cpp -O3 -o test` OR
-  * 64 bit:  `o64-clang++ test.cpp -O3 -o test`   OR   `x86_64-apple-darwinXX-clang++ test.cpp -O3 -o test`
+    `i386-apple-darwinXX-clang++ test.cpp -O3 -o test`
+  * 64 bit: `o64-clang++ test.cpp -O3 -o test` OR
+    `x86_64-apple-darwinXX-clang++ test.cpp -O3 -o test`
 
 * GCC:
 
-  * 32 bit:  `o32-g++ test.cpp -O3 -o test`  OR   `i386-apple-darwinXX-g++ test.cpp -O3 -o test`
+  * 32 bit:  `o32-g++ test.cpp -O3 -o test` OR
-  * 64 bit:  `o64-g++ test.cpp -O3 -o test`   OR   `x86_64-apple-darwinXX-g++ test.cpp -O3 -o test`
+    `i386-apple-darwinXX-g++ test.cpp -O3 -o test`
+  * 64 bit:  `o64-g++ test.cpp -O3 -o test` OR
+    `x86_64-apple-darwinXX-g++ test.cpp -O3 -o test`
 
-XX= the target version, you can find it out by running  `osxcross-conf`  and then see `TARGET`.
+XX= the target version, you can find it out by running  `osxcross-conf` and
+then see `TARGET`.
 
-You can use the shortcut `o32-...` or `i386-apple-darwin...` what ever you like more.
+You can use the shortcuts `o32-...` for `i386-apple-darwin...`, depending on
+which you prefer.
 
-*I'll continue from now on with `o32-clang`, but remember,
+*I'll continue from here on with `o32-clang`, but remember,
  you can simply replace it with `o32-gcc` or `i386-apple-darwin...`.*
 
 ##### Building Makefile based projects: #####
@@ -156,7 +225,8 @@ Note: libc++ requires Mac OS X 10.7 or newer! If you really need C++11 for
 an older OS X version, then you can do the following:
 
 1. Build GCC so you have an up-to-date libstdc++
-2. Build your source code with GCC or `clang++-gstdc++` / `clang++ -foc-use-gcc-libstdc++`
+2. Build your source code with GCC or
+   `clang++-gstdc++` / `clang++ -foc-use-gcc-libstdc++`
 
 Usage Examples:
 
@@ -193,7 +263,8 @@ Usage Examples:
 * GCC:
   * build the 32 bit binary: `o32-g++ test.cpp -O3 -o test.i386`
   * build the 64 bit binary: `o64-g++ test.cpp -O3 -o test.x86_64`
-  * use lipo to generate the universal binary: `x86_64-apple darwinXX-lipo -create test.i386 test.x86_64 -output test`
+  * use lipo to generate the universal binary:
+    `x86_64-apple darwinXX-lipo -create test.i386 test.x86_64 -output test`
 
 ### DEPLOYMENT TARGET: ###
 
@@ -221,7 +292,9 @@ You will need gcc/g++/gcc-objc 4.7+.
 
 ### PROJECTS USING OSXCROSS: ###
 
-* [multiarch/crossbuild](https://github.com/multiarch/crossbuild): various cross-compilers (**Systems**: Linux, OS X, Windows, **Archs**: x86_64, i386, arm, ppc, mips) in Docker. OSXCross powers the Darwin builds.
+* [multiarch/crossbuild](https://github.com/multiarch/crossbuild): various
+  cross-compilers (**Systems**: Linux, OS X, Windows, **Archs**: x86\_64,
+  i386, arm, ppc, mips) in Docker. OSXCross powers the Darwin builds.
 * [Smartmontools](https://www.smartmontools.org)
 
 ### LICENSE: ####