Merge pull request #219 from thewtex/readme-order

README: Improve section order

README.rst

@@ -12,6 +12,7 @@ Features
 
 * Pre-built and configured toolchains for cross compiling.
 * Most images also contain an emulator for the target system.
+* Clean separation of build tools, source code, and build artifacts.
 * Commands in the container are run as the calling user, so that any created files have the expected ownership, (i.e. not root).
 * Make variables (`CC`, `LD` etc) are set to point to the appropriate tools in the container.
 * Recent `CMake <https://cmake.org>`_ and ninja are precompiled.
@@ -20,15 +21,61 @@ Features
 * Current directory is mounted as the container's workdir, ``/work``.
 * Works with the `Docker for Mac <https://docs.docker.com/docker-for-mac/>`_ and `Docker for Windows <https://docs.docker.com/docker-for-windows/>`_.
 
+Examples
+--------
 
-What is the difference between `dockcross` and `dockbuild` ?
+1. ``dockcross make``: Build the *Makefile* in the current directory.
-------------------------------------------------------------
+2. ``dockcross cmake -Bbuild -H. -GNinja``: Run CMake with a build directory
+   ``./build`` for a *CMakeLists.txt* file in the current directory and generate
+   ``ninja`` build configuration files.
+3. ``dockcross ninja -Cbuild``: Run ninja in the ``./build`` directory.
+4. ``dockcross bash -c '$CC test/C/hello.c -o hello'``: Build the *hello.c* file
+   with the compiler identified with the ``CC`` environmental variable in the
+   build environment.
+5. ``dockcross bash``: Run an interactive shell in the build environment.
 
-The key difference is that `dockbuild <https://github.com/dockbuild/dockbuild#readme>`_
+Note that commands are executed verbatim. If any shell processing for
-images use the same method to conveniently isolate the build environment as
+environment variable expansion or redirection is required, please use
-`dockcross <https://github.com/dockcross/dockcross#readme>`_ but they do **NOT** provide
+`bash -c 'command args...'`.
-a toolchain file.
 
+Installation
+------------
+
+This image does not need to be run manually. Instead, there is a helper script
+to execute build commands on source code existing on the local host filesystem. This
+script is bundled with the image.
+
+To install the helper script, run one of the images with no arguments, and
+redirect the output to a file::
+
+  docker run --rm CROSS_COMPILER_IMAGE_NAME > ./dockcross
+  chmod +x ./dockcross
+  mv ./dockcross ~/bin/
+
+Where `CROSS_COMPILER_IMAGE_NAME` is the name of the cross-compiler toolchain
+Docker instance, e.g. `dockcross/linux-armv7`.
+
+Only 64-bit x86_64 images are provided; a 64-bit x86_64 host system is required.
+
+Usage
+-----
+
+For the impatient, here's how to compile a hello world for armv7::
+
+  cd ~/src/dockcross
+  docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7
+  chmod +x ./dockcross-linux-armv7
+  ./dockcross-linux-armv7 bash -c '$CC test/C/hello.c -o hello_arm'
+
+Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** script on the commandline::
+
+  ./dockcross-linux-armv7 [command] [args...]
+
+The dockcross script will execute the given command-line inside the container,
+along with all arguments passed after the command. Commands that evaluate
+environmental variables in the image, like `$CC` above, should be executed in
+`bash -c`. The present working directory is mounted within the image, which
+can be used to make source code available in the Docker container.
 
 Cross compilers
 ---------------
@@ -164,44 +211,13 @@ dockcross/windows-x86
   |windows-x86-images| 32-bit Windows cross-compiler based on MXE/MinGW-w64.
 
 
-Installation
+Articles
-------------
+--------
 
-This image does not need to be run manually. Instead, there is a helper script
+- `dockcross: C++ Write Once, Run Anywhere
-to execute build commands on source code existing on the local host filesystem. This
+  <https://nbviewer.jupyter.org/format/slides/github/dockcross/cxx-write-once-run-anywhere/blob/master/dockcross_CXX_Write_Once_Run_Anywhere.ipynb#/>`_
-script is bundled with the image.
+- `Cross-compiling binaries for multiple architectures with Docker
-
+  <https://web.archive.org/web/20170912153531/http://blogs.nopcode.org/brainstorm/2016/07/26/cross-compiling-with-docker>`_
-To install the helper script, run one of the images with no arguments, and
-redirect the output to a file::
-
-  docker run --rm CROSS_COMPILER_IMAGE_NAME > ./dockcross
-  chmod +x ./dockcross
-  mv ./dockcross ~/bin/
-
-Where `CROSS_COMPILER_IMAGE_NAME` is the name of the cross-compiler toolchain
-Docker instance, e.g. `dockcross/linux-armv7`.
-
-Only 64-bit images are provided; a 64-bit host system is required.
-
-Usage
------
-
-For the impatient, here's how to compile a hello world for armv7::
-
-  cd ~/src/dockcross
-  docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7
-  chmod +x ./dockcross-linux-armv7
-  ./dockcross-linux-armv7 bash -c '$CC test/C/hello.c -o hello_arm'
-
-Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** script on the commandline::
-
-  ./dockcross-linux-armv7 [command] [args...]
-
-The dockcross script will execute the given command-line inside the container,
-along with all arguments passed after the command. Commands that evaluate
-environmental variables in the image, like `$CC` above, should be executed in
-`bash -c`. The present working directory is mounted within the image, which
-can be used to make source code available in the Docker container.
 
 
 Built-in update commands
@@ -285,23 +301,6 @@ For example, commands like ``git config --global advice.detachedHead false`` can
 be added to this script.
 
 
-Examples
---------
-
-1. ``dockcross make``: Build the *Makefile* in the current directory.
-2. ``dockcross cmake -Bbuild -H. -GNinja``: Run CMake with a build directory
-   ``./build`` for a *CMakeLists.txt* file in the current directory and generate
-   ``ninja`` build configuration files.
-3. ``dockcross ninja -Cbuild``: Run ninja in the ``./build`` directory.
-4. ``dockcross bash -c '$CC test/C/hello.c -o hello'``: Build the *hello.c* file
-   with the compiler identified with the ``CC`` environmental variable in the
-   build environment.
-5. ``dockcross bash``: Run an interactive shell in the build environment.
-
-Note that commands are executed verbatim. If any shell processing for
-environment variable expansion or redirection is required, please use
-`bash -c 'command args...'`.
-
 How to extend Dockcross images
 ------------------------------
 In order to extend Dockcross images with your own commands, one must:
@@ -324,13 +323,13 @@ And then in the shell::
   ./linux-armv7 bash							# Runs the helper script with the argument "bash", which starts an interactive container using your extended image.
 
 
-Articles
+What is the difference between `dockcross` and `dockbuild` ?
---------
+------------------------------------------------------------
 
-- `dockcross: C++ Write Once, Run Anywhere
+The key difference is that `dockbuild <https://github.com/dockbuild/dockbuild#readme>`_
-  <https://nbviewer.jupyter.org/format/slides/github/dockcross/cxx-write-once-run-anywhere/blob/master/dockcross_CXX_Write_Once_Run_Anywhere.ipynb#/>`_
+images use the same method to conveniently isolate the build environment as
-- `Cross-compiling binaries for multiple architectures with Docker
+`dockcross <https://github.com/dockcross/dockcross#readme>`_ but they do **NOT** provide
-  <https://web.archive.org/web/20170912153531/http://blogs.nopcode.org/brainstorm/2016/07/26/cross-compiling-with-docker>`_
+a toolchain file.
 
 
 ---