user: Remove nit-picky warnings.

34 files changed, 541 insertions, 313 deletions

diff --git a/user/bsps/bsps-powerpc.rst b/user/bsps/bsps-powerpc.rst
index 0ee51d1..365571f 100644
--- a/user/bsps/bsps-powerpc.rst
+++ b/user/bsps/bsps-powerpc.rst
@@ -94,7 +94,7 @@ Boot via U-Boot
 The application executable file (ELF file) must be converted to an U-Boot
 image.  Use the following commands:
 
-::
+.. code-block:: shell
 
     powerpc-rtems5-objcopy -O binary app.exe app.bin
     gzip -9 -f -c app.bin > app.bin.gz
@@ -102,7 +102,7 @@ image.  Use the following commands:
 
 Use the following U-Boot commands to boot an application via TFTP download:
 
-::
+.. code-block:: shell
 
     tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset
 
diff --git a/user/bsps/bsps-x86_64.rst b/user/bsps/bsps-x86_64.rst
index 3942307..c872734 100644
--- a/user/bsps/bsps-x86_64.rst
+++ b/user/bsps/bsps-x86_64.rst
@@ -49,7 +49,7 @@ Quick instructions (which may fall out of date) are:
 
 Then edit ``Conf/target.txt`` to set:
 
-::
+.. code-block:: ini
 
     ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
     TARGET                = DEBUG
@@ -67,7 +67,7 @@ You can find the ``OVMF.fd`` file like this as well in the edk2 directory:
 
     $ find . -name "*.fd"
     ./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.fd
-    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd <-- the file we're looking for
+    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd # the file we're looking for
     ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd
     ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd
 
@@ -84,12 +84,12 @@ replacing paths as appropriate.
 
 .. code-block:: shell
 
-   $ qemu-img create freebsd.img 8G
-   $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
-   $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
-   $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
-       -drive format=raw,file=freebsd.img \
-       -drive format=raw,file=$FREEBSD_MEMSTICK
+  $ qemu-img create freebsd.img 8G
+  $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
+  $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
+  $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
+      -drive format=raw,file=freebsd.img \
+      -drive format=raw,file=$FREEBSD_MEMSTICK
 
 The first time you do this, continue through and install FreeBSD. `FreeBSD's
 installation guide may prove useful
diff --git a/user/exe/debugging.rst b/user/exe/debugging.rst
index 67c4039..c10d6f6 100644
--- a/user/exe/debugging.rst
+++ b/user/exe/debugging.rst
@@ -91,7 +91,7 @@ the architecture and processor. Typical functions include:
 
 #. Break and watch points
 
-.. _fig-exe-debug-qemu:
+.. _fig-exe-debug-jtag:
 
 .. figure:: ../../images/user/exe-debug-jtag.png
    :width: 70%
diff --git a/user/exe/index.rst b/user/exe/index.rst
index 02dab19..3e9b571 100644
--- a/user/exe/index.rst
+++ b/user/exe/index.rst
@@ -14,8 +14,10 @@ execute it in a target. The section discusses how an application executable is
 created, what happens when an executable is loaded and run, debugging an
 execiutable, and creating and dynamically loading code.
 
-.. include:: executables.rst
-.. include:: execution.rst
-.. include:: initialization.rst
-.. include:: debugging.rst
-.. include:: loader.rst
+.. toctree::
+
+   executables
+   execution
+   initialization
+   debugging
+   loader
diff --git a/user/exe/initialization.rst b/user/exe/initialization.rst
index 4dbfa5c..eb96595 100644
--- a/user/exe/initialization.rst
+++ b/user/exe/initialization.rst
@@ -85,9 +85,11 @@ The RTEMS Tool ``rtems-exeinfo`` can provide some detail about the registered
 handlers. The following shows the initialization handlers for the *hello world*
 sample application in the RTEMS kernel's testsuite::
 
+.. code-block:: shell
+
  $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
  RTEMS Executable Info 5.5416cfa39dd6
-  rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
+ $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
  exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
 
  Compilation:
diff --git a/user/exe/loader.rst b/user/exe/loader.rst
index 77d7cda..485d691 100644
--- a/user/exe/loader.rst
+++ b/user/exe/loader.rst
@@ -146,6 +146,7 @@ follow.
 
 .. _dlopen:
 .. index:: dlopen
+
 ``void* dlopen(const char* path, int mode);``
   The ``dlopen()`` function makes the symbols (function identifiers and data
   object identifiers) in the executable object file specified by `file`
@@ -250,6 +251,7 @@ follow.
 
 .. _dlclose:
 .. index:: dlclose
+
 ``int dlclose(void* handle);``
   Releases a reference to the executable object file referenced by `handle`. If
   the reference count drops to ``0``, the executable object file's global symbol
@@ -262,6 +264,7 @@ follow.
 
 .. _dlsym:
 .. index:: dlsym
+
 ``void* dlsym(void* handle, const char* symbol);``
  The ``dlsym()`` function obtains the address of a symbol (a function identifier
  or a data object identifier) defined in the symbol table identified by the
@@ -288,6 +291,7 @@ follow.
 
 .. _dlinfo:
 .. index:: dlinfo
+
 ``int dlinfo(void* handle, int request, void* args);``
 
  The ``dlinfo()`` function provides information about dynamically loaded object.
@@ -303,6 +307,7 @@ follow.
 
 .. _dlerror:
 .. index:: dlerror
+
 ``const char *dlerror(void);``
  The ``dlerror()`` function returns a null-terminated character string (with no
  trailing ``<newline>``) that describes the last error that occurred during
@@ -690,29 +695,35 @@ used to allocate memory at an address must be used when making allocator
 calls. The ``rtems_rtl_alloc_tags`` are:
 
  .. index:: RTEMS_RTL_ALLOC_OBJECT
+
  ``RTEMS_RTL_ALLOC_OBJECT``
   Allocate a generic object. The link editor uses this memory for data
   structures it uses to manage the linking process and resident executable
   object files.
 
  .. index:: RTEMS_RTL_ALLOC_SYMBOL
+
  ``RTEMS_RTL_ALLOC_SYMBOL``
   Allocate memory to hold symbol data.
 
  .. index:: RTEMS_RTL_ALLOC_EXTERNAL
+
  ``RTEMS_RTL_ALLOC_EXTERNAL``
   Allocate memory for unresolved external symbols.
 
  .. index:: RTEMS_RTL_ALLOC_READ
+
  ``RTEMS_RTL_ALLOC_READ``
   Allocate memory for read-only data such as constants and exception tables.
 
  .. index:: RTEMS_RTL_ALLOC_READ_WRITE
+
  ``RTEMS_RTL_ALLOC_READ_WRITE``
   Allocate memory for read-write data such as a initialised, uninitialized and
   common variables.
 
  .. index:: RTEMS_RTL_ALLOC_READ_EXEC
+
  ``RTEMS_RTL_ALLOC_READ_EXEC``
   Allocate memory for code to be executed in. The address space is configure for
   read and execute.
@@ -724,21 +735,25 @@ The commands are used to control the action the allocator performs. The
 ``rtems_rtl_alloc_cmd`` are:
 
  .. index:: RTEMS_RTL_ALLOC_NEW
+
  ``RTEMS_RTL_ALLOC_NEW``
   Allocate memory of the ``tag`` type. Returns ``NULL`` if the allocation fails.
 
  .. index:: RTEMS_RTL_ALLOC_DEL
+
  ``RTEMS_RTL_ALLOC_DEL``
   Delete a previous allocation freeing the memory. The ``tag`` has to match
   address of the memory being deleted.
 
  .. index:: RTEMS_RTL_ALLOC_WR_ENABLE
+
  ``RTEMS_RTL_ALLOC_WR_ENABLE``
   Enable writes to a region of memory previously allocated. The ``tag`` has to
   match the address of the memory being write enabled. The link editor may call
   issue this command for memory that is already write enabled.
 
  .. index:: RTEMS_RTL_ALLOC_WR_DISABLE
+
  ``RTEMS_RTL_ALLOC_WR_DISABLE``
   Disable writes to a region of memory previously allocated. The ``tag`` has to
   match address of the memory being write disabled. The link editor may call
@@ -763,11 +778,13 @@ the function you need is:
 The arguments are:
 
 ``cmd``
- The command to action. See :ref:`_rtems_rtl_alloc_cmd`.
+ The command to action. See `rtems_rtl_alloc_cmd <rtems_rtl_alloc_cmd_>`_.
 
 ``tag``
- The type of memory the command is for. The ``tag`` must match the address for
- commands other than ``RTEMS_RTL_ALLOC_OBJECT``.
+
+ The type of memory the command is for. The ``tag`` must match the
+ address for commands other than ``RTEMS_RTL_ALLOC_OBJECT``.  See
+ `rtems_rtl_alloc_tags <rtems_rtl_alloc_tags_>`_.
 
 ``address``
  Pointer to the address. This is set of the ``RTEMS_RTL_ALLOC_OBJECT`` command
diff --git a/user/hosts/macos.rst b/user/hosts/macos.rst
index c68e627..d488f20 100644
--- a/user/hosts/macos.rst
+++ b/user/hosts/macos.rst
@@ -2,7 +2,7 @@
 
 .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
 
-.. _macos:
+.. _MacOS:
 
 Apple MacOS
 ===========
@@ -19,7 +19,6 @@ suitable.
 
 :ref:`QuickStartPrefixes` details using Prefixes to manage the installation.
 
-MacOS
 .. _Mavericks:
 
 Mavericks
@@ -43,5 +42,3 @@ Sierra
 ~~~~~~
 
 The RSB works on Sierra with the latest Xcode.
-
-
diff --git a/user/hosts/os.rst b/user/hosts/os.rst
index 98fa6af..d1f0834 100644
--- a/user/hosts/os.rst
+++ b/user/hosts/os.rst
@@ -38,7 +38,7 @@ proven over the years to be difficult to manage in production systems.
 
     The RSB assumes your host is set up and the needed packages are installed
     and configured to work. If your host has not been set up please refer to
-    :ref:`Hosts` and your host's section for packages you need to install.
+    section that covers your host's packages you need to install.
 
 .. topic:: Path to use when building applications:
 
@@ -80,4 +80,3 @@ proven over the years to be difficult to manage in production systems.
       $ git checkout -t origin/4.11
 
     Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
-
diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst
index 2a3e694..24930e7 100644
--- a/user/hosts/posix.rst
+++ b/user/hosts/posix.rst
@@ -53,27 +53,33 @@ been tested and report as working.
 ArchLinux
 ~~~~~~~~~
 
-The following packages are required on a fresh Archlinux 64bit installation::
+The following packages are required on a fresh Archlinux 64bit installation:
 
-    # pacman -S base-devel gdb xz unzip ncurses git zlib
+.. code-block:: shell
+
+  # pacman -S base-devel gdb xz unzip ncurses git zlib
 
 Archlinux, by default installs ``texinfo-5`` which is incompatible for building
 GCC 4.7 tree. You will have to obtain ``texinfo-legacy`` from ``AUR`` and
-provide a manual override::
+provide a manual override:
+
+.. code-block:: shell
 
-    # pacman -R texinfo
-    $ yaourt -S texinfo-legacy
-    # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
+  # pacman -R texinfo
+  $ yaourt -S texinfo-legacy
+  # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
 
 .. _CentOS:
 
 CentOS
 ~~~~~~
 
-The following packages are required on a minimal CentOS 6.3 64bit installation::
+The following packages are required on a minimal CentOS 6.3 64bit installation:
+
+.. code-block:: shell
 
-    # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
-    bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
+  # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
+  bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
 
 The minimal CentOS distribution is a specific DVD that installs a minimal
 system. If you use a full system some of these packages may have been
@@ -85,10 +91,12 @@ Fedora
 ~~~~~~
 
 The RTEMS Source Builder has been tested on Fedora 19 64bit with the following
-packages::
+packages:
 
-    # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
-         flex texinfo patch perl-Text-ParseWords zlib-devel
+.. code-block:: shell
+
+  # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
+       flex texinfo patch perl-Text-ParseWords zlib-devel
 
 .. _Raspbian:
 
@@ -96,10 +104,12 @@ Raspbian
 ~~~~~~~~
 
 The is the Debian distribution for the Raspberry Pi. The following packages are
-required::
+required:
+
+.. code-block:: shell
 
-    $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
-    texinfo unzip ncurses-dev python-dev git
+  $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
+  texinfo unzip ncurses-dev python-dev git
 
 It is recommended you get Model B of the Pi with 512M of memory and to mount a
 remote disk over the network. The tools can be built on the network disk with a
@@ -112,11 +122,13 @@ Ubuntu
 ~~~~~~
 
 The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes
-Xubuntu. A minimal installation was used and the following packages installed::
+Xubuntu. A minimal installation was used and the following packages installed:
+
+.. code-block:: shell
+
+  $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
+         flex libpython-dev git libncurses5-dev zlib1g-dev
 
-    $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
-           flex libpython-dev git libncurses5-dev zlib1g-dev
-    
 Note that in previous versions of Ubuntu, the package libpython-dev was
 python2.7-dev. The name of packages changes over time. You need the
 package with Python development libraries for C/C++ programs.
@@ -124,7 +136,7 @@ package with Python development libraries for C/C++ programs.
 It is likely necessary that you will have to enable the Ubuntu Source Repositories.
 Users have suggested the following web pages which have instructions:
 
-* https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872 
+* https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872
 * https://askubuntu.com/questions/496549/error-you-must-put-some-source-uris-in-your-sources-list
 
 .. _Linux Mint:
@@ -133,9 +145,11 @@ Linux Mint
 ~~~~~~~~~~
 
 zlib package is required on Linux Mint. It has a different name (other
-than the usual zlib-dev)::
+than the usual zlib-dev):
+
+.. code-block:: shell
 
-    # sudo apt-get install zlib1g-dev
+  # sudo apt-get install zlib1g-dev
 
 .. _openSUSE:
 
@@ -151,17 +165,21 @@ FreeBSD
 -------
 
 The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit
-version. You need to install some ports. They are::
+version. You need to install some ports. They are:
+
+.. code-block:: shell
 
-    # cd /usr/ports
-    # portinstall --batch lang/python27
+  # cd /usr/ports
+  # portinstall --batch lang/python27
 
 If you wish to build Windows (mingw32) tools please install the following
-ports::
+ports:
 
-    # cd /usr/ports
-    # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
-    # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
+.. code-block:: shell
+
+  # cd /usr/ports
+  # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
+  # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
 
 The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows
 QEMU.
@@ -175,11 +193,10 @@ NetBSD
 ------
 
 The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
-are::
-
-    # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
-    # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
-    # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
+are:
 
-.. _MacOS:
+.. code-block:: shell
 
+  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
+  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
+  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
diff --git a/user/hosts/windows.rst b/user/hosts/windows.rst
index bd63fb5..ffd70a0 100644
--- a/user/hosts/windows.rst
+++ b/user/hosts/windows.rst
@@ -38,7 +38,8 @@ overhead is only during the building of the tools and the RTEMS kernel
 and if you use a suitable build system that is native to Windows your
 application development should be similar to other operating systems.
 
-Building is known to work on `Windows 7 64bit Professional` and `Windows 10`.
+Building is known to work on `Windows 7 64bit Professional` and
+`Windows 10 64bit`.
 
 .. _windows-path-length:
 
@@ -222,49 +223,52 @@ result in Cygiwn binaries. With a Canadian cross-compile a Cygwin
 cross-compiler is built as well as the MinGW RTEMS cross-compiler. The Cygwin
 cross-compiler is required to build the C runtime for the RTEMS target because
 we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set
-is::
-
-    chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems
-    $ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
-    RTEMS Source Builder - Set Builder, v0.2
-    Build Set: 4.10/rtems-arm
-    config: expat-2.1.0-1.cfg
-    package: expat-2.1.0-x86_64-w64-mingw32-1
-    building: expat-2.1.0-x86_64-w64-mingw32-1
-    reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
-    config: tools/rtems-binutils-2.20.1-1.cfg
-    package: arm-rtems4.10-binutils-2.20.1-1   <1>
-    building: arm-rtems4.10-binutils-2.20.1-1
-    package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
-    building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
-    reporting: tools/rtems-binutils-2.20.1-1.cfg ->
-    arm-rtems4.10-binutils-2.20.1-1.html
-    config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
-    package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
-    building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
-    package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
-    building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
-    reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
-    arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
-    config: tools/rtems-gdb-7.3.1-1.cfg
-    package: arm-rtems4.10-gdb-7.3.1-1
-    building: arm-rtems4.10-gdb-7.3.1-1
-    reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
-    config: tools/rtems-kernel-4.10.2.cfg
-    package: arm-rtems4.10-kernel-4.10.2-1
-    building: arm-rtems4.10-kernel-4.10.2-1
-    reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
-    installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
-    installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
-    installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
-    installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
-    installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
-    cleaning: expat-2.1.0-x86_64-w64-mingw32-1
-    cleaning: arm-rtems4.10-binutils-2.20.1-1
-    cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
-    cleaning: arm-rtems4.10-gdb-7.3.1-1
-    cleaning: arm-rtems4.10-kernel-4.10.2-1
-    Build Set: Time 10:09:42.810547   <4>
+is:
+
+.. code-block:: shell
+
+  chris@cygwin ~/development/rtems/src/rtems-source-builder/rtems
+  $ ../source-builder/sb-set-builder --log=l-arm.txt \
+                --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
+  RTEMS Source Builder - Set Builder, v0.2
+  Build Set: 4.10/rtems-arm
+  config: expat-2.1.0-1.cfg
+  package: expat-2.1.0-x86_64-w64-mingw32-1
+  building: expat-2.1.0-x86_64-w64-mingw32-1
+  reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
+  config: tools/rtems-binutils-2.20.1-1.cfg
+  package: arm-rtems4.10-binutils-2.20.1-1   <1>
+  building: arm-rtems4.10-binutils-2.20.1-1
+  package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
+  building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
+  reporting: tools/rtems-binutils-2.20.1-1.cfg ->
+  arm-rtems4.10-binutils-2.20.1-1.html
+  config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
+  package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+  building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+  package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+  building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+  reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
+  arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
+  config: tools/rtems-gdb-7.3.1-1.cfg
+  package: arm-rtems4.10-gdb-7.3.1-1
+  building: arm-rtems4.10-gdb-7.3.1-1
+  reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
+  config: tools/rtems-kernel-4.10.2.cfg
+  package: arm-rtems4.10-kernel-4.10.2-1
+  building: arm-rtems4.10-kernel-4.10.2-1
+  reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
+  installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+  installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
+  installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+  installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+  installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
+  cleaning: expat-2.1.0-x86_64-w64-mingw32-1
+  cleaning: arm-rtems4.10-binutils-2.20.1-1
+  cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
+  cleaning: arm-rtems4.10-gdb-7.3.1-1
+  cleaning: arm-rtems4.10-kernel-4.10.2-1
+  Build Set: Time 10:09:42.810547   <4>
 
 .. topic:: Items:
 
@@ -289,4 +293,3 @@ is::
   cannot be avoided in all cases. Cygwin and it's fork MSYS are fantastic
   pieces of software in a difficult environment. I have found building a single
   tool tends to work, building all at once is harder.
-
diff --git a/user/installation/kernel.rst b/user/installation/kernel.rst
index 059b4c7..4978d41 100644
--- a/user/installation/kernel.rst
+++ b/user/installation/kernel.rst
@@ -250,9 +250,6 @@ the API headers and architecture specific libraries to a locaiton under the
 RTEMS. Do not mix versions of RTEMS under the same `prefix`. Make installs
 RTEMS with the following command:
 
-.. comment: CCJ - this code block for not parse and gives a warning in
-            index.rst.
-
 .. code-block:: shell
 
   $ make install
@@ -281,8 +278,8 @@ RTEMS with the following command:
   make[3]: Nothing to be done for 'install-data-am'.
   make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
   make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
-  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu
-   ......
+  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
+    ....
   make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
   make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
   make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32'
diff --git a/user/overview/index.rst b/user/overview/index.rst
index ef23d55..ee7c59b 100644
--- a/user/overview/index.rst
+++ b/user/overview/index.rst
@@ -5,6 +5,8 @@
 Introduction
 ************
 
+.. _Overview:
+
 Overview
 ========
 
diff --git a/user/rsb/bug-reporting.rst b/user/rsb/bug-reporting.rst
index b8fcc71..2adf90a 100644
--- a/user/rsb/bug-reporting.rst
+++ b/user/rsb/bug-reporting.rst
@@ -5,7 +5,7 @@
 .. _Bugs, Crashes, and Build Failures:
 
 Bugs, Crashes, and Build Failures
-=================================
+---------------------------------
 
 The RTEMS Source Builder is a Python program and every care is taken to test
 the code however bugs, crashes, and build failures can and do happen. If you
diff --git a/user/rsb/commands.rst b/user/rsb/commands.rst
index 214607c..80d74a5 100644
--- a/user/rsb/commands.rst
+++ b/user/rsb/commands.rst
@@ -3,12 +3,14 @@
 .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
 
 Commands
-========
+--------
 
 Checker (sb-check)
-------------------
+^^^^^^^^^^^^^^^^^^
 
-This commands checks your system is set up correctly. Most options are ignored::
+This commands checks your system is set up correctly. Most options are ignored:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-check --help
     sb-check: [options] [args]
@@ -47,10 +49,12 @@ This commands checks your system is set up correctly. Most options are ignored::
     Environment is ok
 
 Defaults (sb-defaults)
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 This commands outputs and the default macros for your when given no
-arguments. Most options are ignored::
+arguments. Most options are ignored:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-defaults --help
     sb-defaults: [options] [args]
@@ -86,9 +90,11 @@ arguments. Most options are ignored::
     --regression           : Set --no-install, --keep-going and --always-clean
 
 Set Builder (sb-set-builder)
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This command builds a set::
+This command builds a set:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --help
     RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
@@ -291,10 +297,12 @@ The ``arguments`` are a list of build sets to build.
   ``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically.
 
 Set Builder (sb-builder)
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 This command builds a configuration as described in a configuration
-file. Configuration files have the extension of ``.cfg``::
+file. Configuration files have the extension of ``.cfg``:
+
+.. code-block:: shell
 
     $ ./source-builder/sb-builder --help
     sb-builder: [options] [args]
diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst
index 141fd3b..85e3626 100644
--- a/user/rsb/configuration.rst
+++ b/user/rsb/configuration.rst
@@ -5,7 +5,7 @@
 .. _Configuration:
 
 Configuration
-=============
+-------------
 
 The RTEMS Source Builder has two types of configuration data:
 
@@ -23,9 +23,11 @@ private build configurations and if you run the RTEMS Source Builder command
 from that directory your configurations will be used.
 
 The configuration search path is a macro variable and is reference as
-``%{_configdir}``. It's default is defined as::
+``%{_configdir}``. It's default is defined as:
 
-    _configdir   : dir  optional<2>  %{_topdir}/config:%{_sbdir}/config <1>
+.. code-block:: spec
+
+    _configdir   : dir  optional  %{_topdir}/config:%{_sbdir}/config
 
 .. topic:: Items:
 
@@ -45,7 +47,7 @@ character. Anything after this character on the line is ignored. There is no
 block comment.
 
 Source and Patches
-------------------
+^^^^^^^^^^^^^^^^^^
 
 The RTEMS Source Builder provides a flexible way to manage source. Source and
 patches are declare in configurations file using the ``source`` and ``patch``
@@ -88,16 +90,16 @@ and start the build process again.
 The URL can contain macros. These are expanded before issuing the request to
 download the file. The standard GNU GCC compiler source URL is:
 
-.. code-block:: auto
+.. code-block:: spec
 
-    %source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
+    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
 
 .. topic:: Items:
 
-  1. The ``%source`` command's set command sets the source. The first is set
-     and following sets are ignored.
+  1. The ``%source`` command's ``set`` command sets the source. The
+     first is set and following sets are ignored.
 
-  2. The source is part of the ``gcc`` group.
+  2. The source package is part of the ``gcc`` group.
 
 The type of compression is automatically detected from the file extension. The
 supported compression formats are:
@@ -132,7 +134,7 @@ If the source URL references the GitHub API server https://api.github.com/ a
 tarball of the specified version is download. For example the URL for the
 STLINK project on GitHub and version is:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %define stlink_version 3494c11
     %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
@@ -168,7 +170,7 @@ from the options with ``=``. The options are:
 
 An example is:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
 
@@ -205,12 +207,12 @@ delimited by ``?`` and option arguments are delimited from the options with
 
 The following is an example of checking out from a CVS repository:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
 
 Macros and Defaults
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 The RTEMS Source Builder uses tables of *macros* read in when the tool
 runs. The initial global set of macros is called the *defaults*. These values
@@ -220,17 +222,23 @@ the build hosts.
 
 Build set and configuration files can define new values updating and extending
 the global macro table. For example builds are given a release number. This is
-typically a single number at the end of the package name. For example::
+typically a single number at the end of the package name. For example:
+
+.. code-block:: spec
 
     %define release 1
 
 Once defined if can be accessed in a build set or package configuration file
-with::
+with:
+
+.. code-block:: spec
 
     %{release}
 
 The ``sb-defaults`` command lists the defaults for your host. I will not include
-the output of this command because of its size::
+the output of this command because of its size:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-defaults
 
@@ -248,7 +256,9 @@ read from the defaults macro file called ``defaults.mc`` located in the top
 level RTEMS Source Builder command directory. User macros can be read in at
 start up by using the ``--macros`` command line option.
 
-The format for a macro in macro files is::
+The format for a macro in macro files is:
+
+.. code-block:: ini
 
   Name Type Attribute String
 
@@ -290,7 +300,9 @@ and the ``String`` field is a single or tripled multiline quoted string. The
 'String' can contain references to other macros. Macro that loop are not
 currently detected and will cause the tool to lock up.
 
-Maps are declared anywhere in the map using the map directive::
+Maps are declared anywhere in the map using the map directive:
+
+.. code-block:: ini
 
     # Comments
     [my-special-map] <1>
@@ -305,7 +317,9 @@ Maps are declared anywhere in the map using the map directive::
 
 Any macro defintions following a map declaration are placed in that map and the
 default map is ``global`` when loading a file. Maps are selected in
-configuration files by using the ``%select`` directive::
+configuration files by using the ``%select`` directive:
+
+.. code-block:: spec
 
     %select my-special-map
 
@@ -320,9 +334,11 @@ files need to add the ``%{_configdir}`` macro to the start of the file.
 
 Macro map files can include other macro map files using the ``%include``
 directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
-RTEMS from version control heads is::
+RTEMS from version control heads is:
+
+.. code-block:: spec
 
-    # <1>
+    #
     # Build all tool parts from version control head.
     #
     %include %{_configdir}/snapshots/binutils-head.mc
@@ -349,7 +365,7 @@ directory. You need to have the environment variable ``HOME`` defined for this
 work.
 
 Report Mailing
---------------
+^^^^^^^^^^^^^^
 
 The build reports can be mailed to a specific email address to logging and
 monitoring. Mailing requires a number of parameters to function. These are:
@@ -380,7 +396,9 @@ The ``from`` mail address is taken from:
 If you have configured an email and name in git it will be used used. If you do
 not a check is made for a ``.mailrc`` file. The environment variable ``MAILRC``
 is used if present else your home directory is check. If found the file is
-scanned for the ``from`` setting::
+scanned for the ``from`` setting:
+
+.. code-block:: shell
 
   set from="Foo Bar <foo@bar>"
 
@@ -392,20 +410,24 @@ default is ``localhost``. You can override the default with a personal
 or user macro file or via the command line option ``--smtp-host``.
 
 Build Set Files
----------------
+^^^^^^^^^^^^^^^
 
 Build set files lets you list the packages in the build set you are defining
 and have a file extension of ``.bset``. Build sets can define macro variables,
 inline include other files and reference other build set or package
 configuration files.
 
-Defining macros is performed with the ``%define`` macro::
+Defining macros is performed with the ``%define`` macro:
+
+.. code-block:: spec
 
     %define _target m32r-rtems4.11
 
 Inline including another file with the ``%include`` macro continues processing
 with the specified file returning to carry on from just after the include
-point::
+point:
+
+.. code-block:: spec
 
     %include rtems-4.11-base.bset
 
@@ -413,7 +435,9 @@ This includes the RTEMS 4.11 base set of defines and checks. The configuration
 paths as defined by ``_configdir`` are scanned. The file extension is optional.
 
 You reference build set or package configuration files by placing the file name
-on a single line::
+on a single line:
+
+.. code-block:: spec
 
     tools/rtems-binutils-2.22-1
 
@@ -425,7 +449,7 @@ package configuration the package is built with the package builder. This all
 happens once the build set file has finished being scanned.
 
 Configuration Control
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 The RTEMS Souce Builder is designed to fit within most verification and
 validation processes. All of the RTEMS Source Builder is source code. The
@@ -441,7 +465,9 @@ example the RTEMS configuration file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg``
 creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the
 Newlib version is 2.0.0, plus any RTEMS specific patches that related to this
 version. The configuration defines the version numbers of the various parts
-that make up this package::
+that make up this package:
+
+.. code-block:: spec
 
     %define gcc_version    4.7.2
     %define newlib_version 2.0.0
@@ -449,7 +475,9 @@ that make up this package::
     %define mpc_version    0.8.2
     %define gmp_version    5.0.5
 
-The package build options, if there are any are also defined::
+The package build options, if there are any are also defined:
+
+.. code-block:: spec
 
     %define with_threads 1
     %define with_plugin  0
@@ -457,11 +485,15 @@ The package build options, if there are any are also defined::
 
 The generic configuration may provide defaults in case options are not
 specified. The patches this specific version of the package requires can be
-included::
+included:
+
+.. code-block:: spec
 
     Patch0: gcc-4.7.2-rtems4.11-20121026.diff
 
-Finally including the GCC 4.7 configuration script::
+Finally including the GCC 4.7 configuration script:
+
+.. code-block:: spec
 
     %include %{_configdir}/gcc-4.7-1.cfg
 
@@ -476,7 +508,7 @@ the earlier revision number will not be effected by the change. This locks down
 a specific configuration over time.
 
 Personal Configurations
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 The RSB supports personal configurations. You can view the RTEMS support in the
 ``rtems`` directory as a private configuration tree that resides within the RSB
@@ -484,7 +516,9 @@ source. There is also the ``bare`` set of configurations. You can create your
 own configurations away from the RSB source tree yet use all that the RSB
 provides.
 
-To create a private configuration change to a suitable directory::
+To create a private configuration change to a suitable directory:
+
+.. code-block:: shell
 
     $ cd ~/work
     $ mkdir test
@@ -496,7 +530,7 @@ build set file. The section 'Adding New Configurations' details how to add a
 new confguration.
 
 New Configurations
-------------------
+^^^^^^^^^^^^^^^^^^
 
 This section describes how to add a new configuration to the RSB. We will add a
 configuration to build the Device Tree Compiler. The Device Tree Compiler or
@@ -558,7 +592,9 @@ release 1 of the package and the last ``1`` is the build configuration version.
 The file starts with some comments that detail the configuration. If there is
 anything unusual about the configuration it is a good idea to add something in
 the comments here. The comments are followed by a check for the release. In
-this case if a release is not provided a default of 1 is used::
+this case if a release is not provided a default of 1 is used:
+
+.. code-block:: spec
 
     #
     # DTC 1.x.x Version 1.
@@ -572,7 +608,9 @@ this case if a release is not provided a default of 1 is used::
 
 The next section defines some information about the package. It does not effect
 the build and is used to annotate the reports. It is recommended this
-information is kept updated and accurate::
+information is kept updated and accurate:
+
+.. code-block:: spec
 
     Name:      dtc-%{dtc_version}-%{_host}-%{release}
     Summary:   Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host}
@@ -586,7 +624,9 @@ single source package and it can be downloaded using the HTTP protocol. The RSB
 knows this is GZip'ped tar file. If more than one package is needed, add
 them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains
 examples of more than one source package as well as conditionally including
-source packages based on the outer configuration options::
+source packages based on the outer configuration options:
+
+.. code-block:: spec
 
     #
     # Source
@@ -618,7 +658,9 @@ unsure why something is being done a particular way.
 The preparation phase will often include source and patch setup commands. Outer
 layers can set the source package and add patches as needed while being able to
 use a common recipe for the build. Users can override the standard build and
-supply a custom patch for testing using the user macro command line interface::
+supply a custom patch for testing using the user macro command line interface:
+
+.. code-block:: spec
 
     #
     # Prepare the source code.
@@ -644,7 +686,9 @@ running ``make``. Note the use of the RSB macros for commands. In the case of
 systems we need to use the BSD make and not the GNU make.
 
 If your package requires a configuration stage you need to run this before the
-make stage. Again the GCC common configuration file provides a detailed example::
+make stage. Again the GCC common configuration file provides a detailed example:
+
+.. code-block:: spec
 
     %build
       build_top=$(pwd)
@@ -683,7 +727,9 @@ the RSB to vary specific commands based on the host. This can help on hosts
 like Windows where bugs can effect the standard commands such as ``rm``. There
 are many many macros to help you. You can find these listed in the
 ``defaults.mc`` file and in the trace output. If you are new to creating and
-editing configurations learning these can take a little time::
+editing configurations learning these can take a little time:
+
+.. code-block:: spec
 
     %install
       build_top=$(pwd)
@@ -701,7 +747,9 @@ for you.
 
 Once we have the configuration files we can execute the build using the
 ``sb-builder`` command. The command will perform the build and create a tar file
-in the ``tar`` directory::
+in the ``tar`` directory:
+
+.. code-block:: shell
 
     $  ../source-builder/sb-builder --prefix=/usr/local \
          --log=log_dtc devel/dtc-1.2.0
@@ -720,7 +768,9 @@ as binutils, GCC and GDB and a build set will build each of these packages and
 create a single build set tar file or install the tools on the host into the
 prefix path.
 
-The DTC build set file is called ``dtc.bset`` and contains::
+The DTC build set file is called ``dtc.bset`` and contains:
+
+.. code-block:: spec
 
     #
     # Build the DTC.
@@ -730,7 +780,9 @@ The DTC build set file is called ``dtc.bset`` and contains::
 
     devel/dtc-1.2.0.cfg
 
-To build this you can use something similar to::
+To build this you can use something similar to:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
        --trace --bset-tar-file --no-install dtc
@@ -772,7 +824,7 @@ and change directory into them and manually run commands until to figure what
 the package requires.
 
 Scripting
----------
+^^^^^^^^^
 
 Configuration files specify how to build a package. Configuration files are
 scripts and have a ``.cfg`` file extension. The script format is based loosely
@@ -923,23 +975,24 @@ The +%prep+ macro starts a block that continues until the next block macro. The
 *prep* or preparation block defines the setup of the package's source and is a
 mix of RTEMS Source Builder macros and shell scripting. The sequence is
 typically +%source+ macros for source, +%patch+ macros to patch the source
-mixed with some shell commands to correct any source issues::
+mixed with some shell commands to correct any source issues:
+
+.. code-block:: spec
 
-                  <1>                <2>      <3>
     %source setup gcc -q -c -T -n %{name}-%{version}
 
 .. topic:: Items:
 
-  1. The source group to set up.
+  1. The source group to set up is ``gcc``.
 
-  2. The source's name.
+  2. The source's name is the macro ``%{name}``.
 
-  3. The version of the source.
+  3. The version of the source is the macro ``%{version}``.
 
 The source set up are declared with the source ``set`` and ``add`` commands. For
 example:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
 
@@ -957,7 +1010,7 @@ example GNU's GCC was a few tar files for a while and it is now a single tar
 file. Support for multiple source files can be conditionally implemented with
 the following scripting:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
     %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2
@@ -966,7 +1019,7 @@ the following scripting:
 Separate modules use separate source groups. The GNU GCC compiler for RTEMS
 uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
     %source set newlib ftp://sourceware.org/pub/newlib/newlib-%{newlib_version}.tar.gz
@@ -976,7 +1029,7 @@ uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
 
 and set up with:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source setup gcc -q -n gcc-%{gcc_version}
     %source setup newlib -q -D -n newlib-%{newlib_version}
@@ -990,22 +1043,24 @@ applied using the +setup+ command. The +setup+ command takes the default patch
 option. You can provide options with each patch by adding them as arguments
 before the patch URL. Patches with no options uses the +setup+ default.
 
-.. code-block:: auto
+.. code-block:: spec
 
     %patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff
-    %patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
+    %patch add gdb -p0 %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
 
 .. topic:: Items:
 
-  1. This patch has a custom option.
+  1. This patch has the custom option of ``-p0``.
 
-To apply these patches::
+To apply these patches:
 
-    %patch setup gdb -p1 <1>
+.. code-block:: spec
+
+    %patch setup gdb -p1
 
 .. topic:: Items:
 
-  1. The default options.
+  1. The default options for ``gdb`` set up.
 
 .. _build:
 
@@ -1018,22 +1073,24 @@ package. It assumes all source code has been unpacked, patch and adjusted so
 the build will succeed.
 
 The following is an example take from the GitHub STLink project. The STLink is
-a JTAG debugging device for the ST ARM family of processors::
+a JTAG debugging device for the ST ARM family of processors:
+
+.. code-block:: spec
 
     %build
-      export PATH="%{_bindir}:${PATH}" <1>
+      export PATH="%{_bindir}:${PATH}"
 
-      cd texane-stlink-%{stlink_version} <2>
+      cd texane-stlink-%{stlink_version}
 
-      ./autogen.sh <3>
+      ./autogen.sh
 
     %if "%{_build}" != "%{_host}"
-      CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
+      CFLAGS_FOR_BUILD="-g -O2 -Wall" \
     %endif
-      CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
+      CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \
       CFLAGS="$SB_OPT_FLAGS" \
       LDFLAGS="-L $SB_TMPPREFIX/lib" \
-      ./configure \ <6>
+      ./configure \
         --build=%{_build} --host=%{_host} \
         --verbose \
         --prefix=%{_prefix} --bindir=%{_bindir} \
@@ -1041,36 +1098,41 @@ a JTAG debugging device for the ST ARM family of processors::
         --includedir=%{_includedir} --libdir=%{_libdir} \
         --mandir=%{_mandir} --infodir=%{_infodir}
 
-      %{__make} %{?_smp_mflags} all <7>
+      %{__make} %{?_smp_mflags} all
 
       cd ..
 
 .. topic:: Items:
 
-  1. Setup the PATH environment variable. This is not always needed.
+  1. Set up the PATH environment variable by setting the ``PATH`` environment
+     variable. This is not always needed.
 
-  2. This package builds in the source tree so enter it.
+  2. This package builds in the source tree
+     ``texane-stlink-%{stlink_version}`` so enter it before building.
 
   3. The package is actually checked directly out from the github project and
-     so it needs its autoconf and automake files generated.
+     so it needs its ``autoconf`` and ``automake`` files generated. Invoke the
+     provided script ``autogen.sh``
 
-  4. Flags for a cross-compiled build.
+  4. If the build machine and host are not the same the build is a
+     cross-compile. Update the flags for a cross-compiled build.
 
-  5. Various settings passed to configure to customise the build. In this
-     example an include path is being set to the install point of
-     ``libusb``. This package requires ``libusb`` is built before it.
+  5. The flags set in the environment before ``configure`` are various
+     settings that need to be passed to customise the build. In this example
+     an include path is being set to the install point of ``libusb``. This
+     package requires ``libusb`` is built before it.
 
   6. The ``configure`` command. The RTEMS Source Builder provides all the
      needed paths as macro variables. You just need to provide them to
      ``configure``.
 
-  7. Running make. Do not use ``make`` directly, use the RTEMS Source Builder's
-     defined value. This value is specific to the host. A large number of
-     packages need GNU make and on BSD systems this is ``gmake``. You can
-     optionally add the SMP flags if the packages build system can handle
-     parallel building with multiple jobs. The ``_smp_mflags`` value is
-     automatically setup for SMP hosts to match the number of cores the host
-     has.
+  7. Run ``make``. Do not use ``make`` directly, use the RTEMS Source
+     Builder's defined value. This value is specific to the host. A large
+     number of packages need GNU make and on BSD systems this is
+     ``gmake``. You can optionally add the SMP flags if the packages build
+     system can handle parallel building with multiple jobs. The
+     ``_smp_mflags`` value is automatically setup for SMP hosts to match the
+     number of cores the host has.
 
 %install
 ~~~~~~~~
@@ -1086,7 +1148,9 @@ the macro variable ``__tmpdir``. The RTEMS Source Builder sets up a shell
 environment variable called ``SB_BUILD_ROOT`` as the standard install point. Most
 packages support adding ``DESTDIR=`` to the ``make install`` command.
 
-Looking at the same example as in :ref:`build`::
+Looking at the same example as in :ref:`build`:
+
+.. code-block:: spec
 
     %install
       export PATH="%{_bindir}:${PATH}" <1>
@@ -1134,7 +1198,9 @@ configuration file that contains the ``%include`` macro.
 Including files allow a kind of configuration file reuse. The outer
 configuration files provide specific information such as package version
 numbers and patches and then include a generic configuration script which
-builds the package::
+builds the package:
+
+.. code-block:: spec
 
     %include %{_configdir}/gcc-4.7-1.cfg
 
@@ -1152,7 +1218,9 @@ with Newlib configuration the name is typically::
 
 The ``%summary`` is a brief description of the package. It is useful when
 reporting. This information is not capture in the package anywhere. For the GCC
-with Newlib configuration the summary is typically::
+with Newlib configuration the summary is typically:
+
+.. code-block:: spec
 
     Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
 
@@ -1161,7 +1229,9 @@ with Newlib configuration the summary is typically::
 
 The ``%release`` is a packaging number that allows revisions of a package to
 happen where no package versions change. This value typically increases when
-the configuration building the package changes::
+the configuration building the package changes:
+
+.. code-block:: spec
 
     %define release 1
 
@@ -1172,7 +1242,9 @@ The ``%version`` macro sets the version the package. If the package is a single
 component it tracks that component's version number. For example in the
 ``libusb`` configuration the ``%version`` is the same as ``%libusb_version``,
 however in a GCC with Newlib configuration there is no single version
-number. In this case the GCC version is used::
+number. In this case the GCC version is used:
+
+.. code-block:: spec
 
     Version: %{gcc_version}
 
@@ -1206,9 +1278,9 @@ source files to be set up. Subsequent ``set`` commands for the same source
 group are ignored. this lets you define the standard source files and override
 them for specific releases or snapshots. To set a source file group:
 
-.. code-block:: auto
+.. code-block:: spec
 
-    %source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
+    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
 
 .. topic:: Items:
 
@@ -1217,12 +1289,14 @@ them for specific releases or snapshots. To set a source file group:
 To add another source package to be installed into the same source tree you use
 the ``add`` command:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2
 
 The source ``setup`` command can only be issued in the ``%prep:`` section. The
-setup is::
+setup is:
+
+.. code-block:: spec
 
     %source gcc setup -q -T -D -n %{name}-%{version}
 
@@ -1269,25 +1343,29 @@ control applying a group of patches to a specific source tree.
 
 The ``__patchdir`` path is searched.
 
-To add a patch::
+To add a patch:
 
-    %patch add gcc <1>  gcc-4.7.2-rtems4.11-20121026.diff
-    %patch add gcc -p0 <2>  gcc-4.7.2-rtems4.11-20121101.diff
+.. code-block:: spec
+
+    %patch add gcc  gcc-4.7.2-rtems4.11-20121026.diff
+    %patch add gcc -p0  gcc-4.7.2-rtems4.11-20121101.diff
 
 .. topic:: Items:
 
   1. The patch group is ``gcc``.
 
-  2. Option for this specific patch.
+  2. Option ``-p0`` is this specific to this patch.
 
 Placing ``%patch setup`` in the ``%prep`` section will apply the groups
 patches::
 
-    %patch setup gcc <1>  -p1 <2>
+.. code-block:: spec
+
+    %patch setup gcc  -p1
 
-  1. The patch group.
+  1. The patch group is ``gcc``.
 
-  2. The default option used to apply the patch.
+  2. The default option used to apply the patch is ``-p1``.
 
 %hash
 ~~~~~
@@ -1303,7 +1381,9 @@ The basename of the file is used as the key for the hash.
 The hash algorthim can be ``md5``, ``sha1``, ``sha224``, ``sha256``,
 ``sha384``, and ``sha512`` and we typically use ``md5``.
 
-To add a hash::
+To add a hash:
+
+.. code-block:: spec
 
     %hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>
 
@@ -1351,7 +1431,9 @@ recorded in the build report so they can be traced.
 Configurations use different maps so macro overrides can target a specific
 package.
 
-The default map is ``global``::
+The default map is ``global``:
+
+.. code-block:: spec
 
     %select gcc-4.8-snapshot <1>
     %define one_plus_one 2 <2>
@@ -1367,7 +1449,9 @@ The default map is ``global``::
 ~~~~~~~
 
 The ``%define`` macro defines a new macro or updates an existing one. If no
-value is given it is assumed to be ``1``::
+value is given it is assumed to be ``1``:
+
+.. code-block:: spec
 
     %define foo bar
     %define one_plus_one 2
@@ -1392,7 +1476,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
 .. list-table::
 
   * - **%{}**
-    - Check the macro is set or *true*, ie non-zero::
+    - Check the macro is set or *true*, ie non-zero:
+
+      .. code-block:: spec
 
          %if ${foo}
           %warning The test passes, must not be empty or is non-zero
@@ -1401,7 +1487,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
          %endif
 
   * - **\!**
-    - The *not* operator inverts the test of the macro::
+    - The *not* operator inverts the test of the macro:
+
+      .. code-block:: spec
 
          %if ! ${foo}
           %warning The test passes, must be empty or zero
@@ -1410,7 +1498,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
          %endif
 
   * - **==**
-    - The left hand size must equal the right hand side. For example::
+    - The left hand size must equal the right hand side. For example:
+
+      .. code-block:: spec
 
          %define one 1
          %if ${one} == 1
@@ -1418,7 +1508,10 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
          %else
           %error The test fails
          %endif
-      You can also check to see if a macro is empty::
+
+      You can also check to see if a macro is empty:
+
+      .. code-block:: spec
 
          %if ${nothing} == %{nil}
           %warning The test passes
@@ -1426,7 +1519,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
           %error The test fails
 
   * - **!=**
-    - The left hand size does not equal the right hand side. For example::
+    - The left hand size does not equal the right hand side. For example:
+
+      .. code-block:: spec
 
          #
          # Check a value not being equal.
@@ -1465,7 +1560,9 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
 
 The ``%ifn`` macro inverts the normal ``%if`` logic. It avoids needing to provide
 empty *if* blocks followed by *else* blocks. It is useful when checking if a
-macro is defined::
+macro is defined:
+
+.. code-block:: spec
 
     %ifn %{defined foo}
      %define foo bar
diff --git a/user/rsb/cross-canadian-cross.rst b/user/rsb/cross-canadian-cross.rst
index 9c157b3..fc903e4 100644
--- a/user/rsb/cross-canadian-cross.rst
+++ b/user/rsb/cross-canadian-cross.rst
@@ -3,7 +3,7 @@
 .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
 
 Cross and Canadian Cross Building
-=================================
+---------------------------------
 
 Cross building and Canadian Cross building is the process of building on one
 machine an executable that runs on another machine. An example is building a
@@ -13,21 +13,23 @@ and Canadian cross building.
 This sections details how to the RSB to cross and Canadian cross build.
 
 Cross Building
---------------
+^^^^^^^^^^^^^^
 
 Cross building is where the _build_ machine and _host_ are different. The
 _build_ machine runs the RSB and the _host_ machine is where the output from
 the build runs. An example is building a package such as NTP for RTEMS on your
 development machine.
 
-To build the NTP package for RTEMS you enter the RSB command::
+To build the NTP package for RTEMS you enter the RSB command:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder \
        --log=log_ntp_arm.txt \
-       --prefix=$HOME/development/rtems/4.11 \  <1>
-       --host=arm-rtems4.11 \  <2>
+       --prefix=$HOME/development/rtems/5 \  <1>
+       --host=arm-rtems5 \  <2>
        --with-rtems-bsp=xilinx_zynq_zc706 \  <3>
-       4.11/net/ntp
+       5/net/ntp
 
 .. topic:: Items:
 
@@ -45,7 +47,7 @@ To build the NTP package for RTEMS you enter the RSB command::
   'bin' directory at the end of the path.
 
 Canadian Cross Building
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 A Canadian cross builds are where the **build**, **host** and **target**
 machines all differ. For example building an RTEMS compiler for an ARM
@@ -81,17 +83,21 @@ does not exist or you cannot access.
 
 To perform a cross build add ``--host=`` to the command line. For example
 to build a MinGW tool set on FreeBSD for Windows add ``--host=mingw32``
-if the cross compiler is ``mingw32-gcc``::
+if the cross compiler is ``mingw32-gcc``:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --host=mingw32 \
        --log=l-mingw32-4.11-sparc.txt \
-       --prefix=$HOME/development/rtems/4.11 \
-       4.11/rtems-sparc
+       --prefix=$HOME/development/rtems/5 \
+       5/rtems-sparc
 
 If you are on a Linux Fedora build host with the MinGW packages installed the
-command line is::
+command line is:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
        --log=l-mingw32-4.11-sparc.txt \
-       --prefix=$HOME/development/rtems/4.11 \
-       4.11/rtems-sparc
+       --prefix=$HOME/development/rtems/5 \
+       5/rtems-sparc
diff --git a/user/rsb/deployment.rst b/user/rsb/deployment.rst
index 3bb9e0a..c0cd1ce 100644
--- a/user/rsb/deployment.rst
+++ b/user/rsb/deployment.rst
@@ -5,7 +5,7 @@
 .. _RSBDeployment:
 
 Building and Deploying Tool Binaries
-====================================
+------------------------------------
 
 If you wish to create and distribute your build or you want to archive a build
 you can create a tar file. We term this deploying a build. This is a more
@@ -39,7 +39,9 @@ access only. To install a tar file you have downloaded into your new machine's
           $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
 
 A build set tar file is created by adding ``--bset-tar-file`` option to the
-``sb-set-builder`` command::
+``sb-set-builder`` command:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
              --prefix=$HOME/development/rtems/4.11 \
@@ -80,7 +82,9 @@ A build set tar file is created by adding ``--bset-tar-file`` option to the
 
 You can also suppress installing the files using the ``--no-install``
 option. This is useful if your prefix is not accessiable, for example when
-building Canadian cross compiled tool sets::
+building Canadian cross compiled tool sets:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
                 --prefix=$HOME/development/rtems/4.11 \
@@ -118,7 +122,9 @@ building Canadian cross compiled tool sets::
 
 A package tar file can be created by adding the ``--pkg-tar-files`` to the
 ``sb-set-builder`` command. This creates a tar file per package built in the
-build set::
+build set:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
             --prefix=$HOME/development/rtems/4.11 \
diff --git a/user/rsb/history.rst b/user/rsb/history.rst
index 2bb4324..d295e62 100644
--- a/user/rsb/history.rst
+++ b/user/rsb/history.rst
@@ -4,7 +4,7 @@
 
 
 History
-=======
+-------
 
 The RTEMS Source Builder is a stand alone tool based on another tool called the
 *SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010
diff --git a/user/rsb/index.rst b/user/rsb/index.rst
index 70f578e..d499800 100644
--- a/user/rsb/index.rst
+++ b/user/rsb/index.rst
@@ -7,7 +7,7 @@
 .. _RSB:
 
 RTEMS Source Builder
-====================
+********************
 
 The RTEMS Source Builder or RSB is a tool to build packages from source. It is
 used by the RTEMS project to build it's compilers and OS. The RSB helps
@@ -45,7 +45,7 @@ The RTEMS Source Builder has been tested on:
 
 .. topic:: Setting up your Host
 
-   :ref:`Hosts` details setting up hosts.
+   See :ref:`QuickStartHost` for details on setting up hosts.
 
 The RTEMS Source Builder has two types of configuration data. The first is the
 *build set*. A *build set* describes a collection of packages that define a set
@@ -62,7 +62,7 @@ The RTEMS Source Builder does not interact with any host package management
 systems. There is no automatic dependence checking between various packages you
 build or packages and software your host system you may have installed. We
 assume the build sets and configuration files you are using have been created
-by developers who do. Support is provided for package config or ``pkgconfg``
+by developers who do. Support is provided for package config or ``pkgconfig``
 type files so you can check and use standard libraries if present. If you have
 a problem please ask on our :r:list:`devel`.
 
@@ -82,8 +82,6 @@ configuration can read the remaining sections.
    Build Failures`.
 
 .. toctree::
-    :maxdepth: 5
-    :numbered:
 
     why-build-from-source.rst
     project-sets
diff --git a/user/rsb/project-sets.rst b/user/rsb/project-sets.rst
index cc63aaa..64a23d4 100644
--- a/user/rsb/project-sets.rst
+++ b/user/rsb/project-sets.rst
@@ -3,7 +3,7 @@
 .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
 
 Project Sets
-============
+------------
 
 The RTEMS Source Builder supports project configurations. Project
 configurations can be public or private and can be contained in the RTEMS
@@ -36,7 +36,7 @@ are implemented with the configuration scripts.  The best way to find what is
 available is to grep the configuration files for ``with`` and ``without``.
 
 Bare Metal
-----------
+^^^^^^^^^^
 
 The RSB contains a 'bare' configuration tree and you can use this to add
 packages you use on the hosts. For example 'qemu' is supported on a range of
@@ -47,8 +47,10 @@ and run on RTEMS.
 The **bare metal** support for GNU Tool chains. An example is the
 ``lang/gcc491`` build set. You need to provide a target via the command line
 ``--target`` option and this is in the standard 2 or 3 tuple form. For example
-for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf`, and for SPARC
-you would use `sparc-elf`::
+for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf``, and for SPARC
+you would use ``sparc-elf``:
+
+.. code-block:: shell
 
     $ cd rtems-source-builder/bare
     $ ../source-builder/sb-set-builder --log=log_arm_eabihf \
@@ -77,7 +79,7 @@ you would use `sparc-elf`::
     cleaning: arm-eabihf-gdb-7.7-1
 
 RTEMS
------
+^^^^^
 
 The RTEMS Configurations found in the ``rtems`` directory. The configurations
 are grouped by RTEMS version. In RTEMS the tools are specific to a specific
@@ -105,7 +107,9 @@ When building RTEMS within the RTEMS Source Builder it needs a suitable working
 prefix in order for them to work. The RTEMS Source Builder installs all
 packages only after they have been built so if you host does not have a
 recent enough version of ``autoconf`` and ``automake`` you first need to build them
-and install them then build your tool set. The commands are::
+and install them then build your tool set. The commands are:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
        --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
@@ -125,7 +129,9 @@ build fails a check.
 To build snapshots for testing purposes you use the available macro maps
 passing them on the command line using the ``--macros`` option. For RTEMS these
 are held in ``config/snapshots`` directory. The following builds *newlib* from
-CVS::
+CVS:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
        --prefix=$HOME/development/rtems/4.11 \
@@ -133,7 +139,9 @@ CVS::
        4.11/rtems-sparc
 
 and the following uses the version control heads for ``binutils``, ``gcc``,
-``newlib``, ``gdb`` and *RTEMS*::
+``newlib``, ``gdb`` and *RTEMS*:
+
+.. code-block:: shell
 
     $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
        --prefix=$HOME/development/rtems/4.11-head \
@@ -159,7 +167,7 @@ build sets:
   Attempt to build a C++ compiler.
 
 Patches
--------
+^^^^^^^
 
 Packages being built by the RSB need patches from time to time and the RSB
 supports patching upstream packages. The patches are held in a seperate
@@ -199,7 +207,9 @@ are provided the patch's setup default options are used.
 
 Patches can be declared in build set up files.
 
-This examples shows how to declare a patch for gdb in the ``lm32`` architecture::
+This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
+
+.. code-block:: spec
 
     %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
 
@@ -212,7 +222,9 @@ This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
   3. The patch's URL. It is downloaded from here.
 
 Patches require a checksum to avoid a warning. The ``%hash`` directive can be
-used to add a checksum for a patch that is used to verify the patch::
+used to add a checksum for a patch that is used to verify the patch:
+
+.. code-block:: spec
 
     %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
 
@@ -226,7 +238,9 @@ used to add a checksum for a patch that is used to verify the patch::
 
 The patches are applied when a patch ``setup`` command is issued in the
 ``%prep:`` section. All patches in the group are applied. To apply the GDB
-patch above use::
+patch above use:
+
+.. code-block:: spec
 
     %patch setup <1> gdb <2> -p1 <3>
 
@@ -251,7 +265,7 @@ it and add it to the RTEMS Tools git repository.  For example, to test a local
 patch for newlib, add the following two lines to the .cfg file in
 ``rtems/config/tools/`` that is included by the bset you use:
 
-.. code-block:: auto
+.. code-block:: spec
 
     %patch add newlib file://0001-this-is-a-newlib-patch.patch   <1>
     %hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>
diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst
index 82be4ff..c02153b 100644
--- a/user/rsb/third-party-packages.rst
+++ b/user/rsb/third-party-packages.rst
@@ -3,7 +3,7 @@
 .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
 
 RTEMS Third-Party Packages
-========================
+--------------------------
 
 This section describes how to build and add an RTEMS third-party package to the
 RSB.
@@ -21,7 +21,7 @@ in the RTEMS build system. If you have any issues with this support please ask
 on the RTEMS developers mailing list.
 
 Vertical Integration
---------------------
+^^^^^^^^^^^^^^^^^^^^
 
 The RSB supports horizontal integration with support for multiple
 architectures. Adding packages to the RSB as libraries is vertical
@@ -30,7 +30,7 @@ you build a compiler. The same can be done for third-party libraries, you can
 crate build sets that stack library dependences vertically to create a *stack*.
 
 Building
---------
+^^^^^^^^
 
 To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
 installed. The set builder command line requires you provide the tools path,
@@ -56,7 +56,7 @@ To build Net-SNMP the command is:
     Build Set: Time 0:01:10.651926
 
 Adding
-------
+^^^^^^
 
 Adding a package requires you first build it manually by downloading the source
 for the package and building it for RTEMS using the command line of a standard
@@ -114,7 +114,7 @@ A package requires 3 files to be created:
   specific parts. See :ref:`Configuration` for more details.
 
 BSP Support
------------
+^^^^^^^^^^^
 
 The RSB provides support to help build packages for RTEMS. RTEMS applications
 can be viewed as statically linked executables operating in a single address
@@ -135,7 +135,9 @@ RTEMS.
 The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
 support building third-party packages and you need to include this file in your
 RTEMS version specific configuration file. For example the Net-SNMP
-configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
+configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
+
+.. code-block:: spec
 
     #
     # NetSNMP 5.7.2.1
@@ -174,8 +176,8 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
 
   3. The Net-SNMP package's version.
 
-  4. Add specific CFLAGS to the build process. See the
-    ``net-snmp-5.7.2.1-1.cfg`` for details.
+  4. Add specific ``CFLAGS`` to the build process. See the
+     ``net-snmp-5.7.2.1-1.cfg`` for details.
 
   5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
 
@@ -184,7 +186,9 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
 The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
 sure standard command line options are provided. These include ``--host`` and
 ``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
-the ``${_prefix}`` is used::
+the ``${_prefix}`` is used:
+
+.. code-block:: spec
 
     %if %{_host} == %{nil} <1>
      %error No RTEMS target specified: --host=host
@@ -217,7 +221,9 @@ the ``${_prefix}`` is used::
 RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
 read and manage them even when there is no pkgconfig support installed on your
 build machine. Using this support we can obtain a BSP's configuration and set
-some standard macros variables (``rtems/config/rtems-bsp.cfg``)::
+some standard macros variables (``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
 
     %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
     %{pkgconfig crosscompile yes} <2>
@@ -246,7 +252,9 @@ The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses thes
 to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
 party library your host computer is the _build_ machine and RTEMS is the _host_
 machine therefore we set the ``host`` variables
-(``rtems/config/rtems-bsp.cfg``)::
+(``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
 
     %define host_cflags  %{rtems_bsp_cflags}
     %define host_ldflags %{rtems_bsp_ldflags}
@@ -257,7 +265,9 @@ package. Packages by default consider the ``_prefix`` the base and install
 various files under this tree. The package you are building is specific to a
 BSP and so needs to install into the specific BSP path under the
 ``_prefix``. This allows more than BSP build of this package to be install
-under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::
+under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
+
+.. code-block:: spec
 
     %define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
     %define _exec_prefix      %{rtems_bsp_prefix}
@@ -285,7 +295,9 @@ under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::
 
 When you configure a package you can reference these paths and the RSB will
 provide sensible default or in this case map them to the BSP
-(``source-builder/config/ntp-4-1.cfg``)::
+(``source-builder/config/ntp-4-1.cfg``):
+
+.. code-block:: spec
 
       ../${source_dir_ntp}/configure \ <1>
         --host=%{_host} \
@@ -306,7 +318,7 @@ provide sensible default or in this case map them to the BSP
   1. The configure command for NTP.
 
 RTEMS BSP Configuration
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 To build a package for RTEMS you need to build it with the matching BSP
 configuration. A BSP can be built with specific flags that require all code
diff --git a/user/rsb/why-build-from-source.rst b/user/rsb/why-build-from-source.rst
index d9cdcff..4f1615c 100644
--- a/user/rsb/why-build-from-source.rst
+++ b/user/rsb/why-build-from-source.rst
@@ -5,7 +5,7 @@
 .. _WhyBuildFromSource:
 
 Why Build from Source?
-======================
+----------------------
 
 The RTEMS Source Builder is not a replacement for the binary install systems
 you have with commercial operating systems or open source operating system
diff --git a/user/start/index.rst b/user/start/index.rst
index d5aa1be..d6333f3 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -13,8 +13,6 @@ Follow the sections of this chapter step by step to get started developing
 applications on top of RTEMS.
 
 .. toctree::
-    :maxdepth: 5
-    :numbered:
 
     host
     prefixes
diff --git a/user/testing/configuration.rst b/user/testing/configuration.rst
index e740af6..9c65506 100644
--- a/user/testing/configuration.rst
+++ b/user/testing/configuration.rst
@@ -57,6 +57,7 @@ The RTEMS Tester and RTEMS Run are primed using defaults from the file
 User configuration file.
 
 .. index:: BSP configuration, User configuration
+
 BSP and User Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -65,18 +66,21 @@ configuration file has to have an INI section that is the name of the BSP
 passed on the command line. The section has the following mandatory values:
 
 .. index:: bsp
+
 ``bsp``
   The name of the BSP. The BSP name is used to create a macro map to hold the
   BSP's configuration data. Typically this is the same as the BSP name used on
   the command line.
 
 .. index:: arch
+
 ``arch``
   The name of the BSP architecture. This is need for the GDB configuration
   scripts where the architecture specific GDB needs to run. It is mandatory so
   the *arch/bsp* standard RTEMS BSP string can be used.
 
 .. index:: tester
+
 ``tester``
   The tester or run configuration script. This is the name of the configuration
   script the RTEMS Tester or RTEMS Run executes as a back end. The ``tester``
@@ -87,18 +91,22 @@ Target commands support expansion of specific tags to provide a convenient way
 for users to customize a local test environment. The parameters expanded are:
 
 .. index:: @ARCH@
+
 ``@ARCH@``
   The BSP architecture.
 
 .. index:: @BSP@
+
 ``@BSP@``
   The BSP's name set by the ``bsp`` value.
 
 .. index:: @EXE@
+
 ``@EXE@``
   The executable name as an absolute path
 
 .. index:: @FEXE@
+
 ``@FEXE@``
   The filtered executable if a ``target_exe_filter`` is provided else the
   executable's file name.
@@ -107,6 +115,7 @@ The following are optional and depend on the back end being used and the local
 target hardware set up:
 
 .. index:: jobs
+
 ``jobs``
   The jobs value sets the number of jobs that can be run at once. This setting
   only effects the RTEMS Tester. The tester can run up to the ``jobs`` value of
@@ -116,12 +125,14 @@ target hardware set up:
   test timeouts may be recorded.
 
 .. index:: bsp_tty_dev
+
 ``bsp_tty_dev``
   The BSP's tty device. This can be a real device on the host machine the
   executable is being run from or it can be a telnet server and port defined
-  using the stand host format. See :ref:`tester-consoles` for details.
+  using the stand host format. See :ref:`TesterConsoles` for details.
 
 .. index:: target_pretest_command
+
 ``target_pretest_command``
   The pre-test command is a host shell command that is called before each test
   runs. It can be used to construct a suitable environment or image needed by a
@@ -129,12 +140,14 @@ target hardware set up:
   and the bootloader specific format is the output.
 
  .. index:: target_posttest_command
+
 ``target_posttest_command``
   The post-test command is a host shell command that is called after each test
   has finished. It can be used to destroy any environment or image created by
   the pre-test command.
 
 .. index:: target_exe_filter
+
 ``target_exe_filter``
   The target executable filter transforms the executable name into a filtered
   executable name. This filter lets the tester or run command track the name of
@@ -147,11 +160,13 @@ target hardware set up:
   is no need to escape the text in the second part, it is just plain test.
 
 .. index:: test_restarts
+
 ``test_restarts``
   The number of restarts before the test is considered ``invalid``. Currently
   not used.
 
 .. index:: target_reset_regex
+
 ``target_reset_regex``
   The target reset regular expression. This is a `Python regular expression
   <https://docs.python.org/2/library/re.html#regular-expression-syntax>`_ used
@@ -161,6 +176,7 @@ target hardware set up:
   messages that indicate the boot process as failed.
 
 .. index:: target_start_regex
+
 ``target_start_regex``
 
   The target start regular expression. This is a Python regular expression to
@@ -169,6 +185,7 @@ target hardware set up:
   restart and ends the test with a suitable result.
 
 .. index:: target_on_command
+
 ``target_on_command``
   The target on command is a host shell command that is called before the first
   test. This command powers on a target. Targets should be left powered off
@@ -178,11 +195,13 @@ target hardware set up:
   command.
 
 .. index:: target_off_command
+
 ``target_off_command``
   The target off command is a host shell command that is called after the last
   test powering off the target.
 
 .. index:: target_reset_command
+
 ``target_reset_command``
   The target reset command is a host shell command that is called when the
   target needs to be reset. This command can power cycle the target or toggle a
diff --git a/user/testing/consoles.rst b/user/testing/consoles.rst
index ee5126a..28213c1 100644
--- a/user/testing/consoles.rst
+++ b/user/testing/consoles.rst
@@ -2,7 +2,7 @@
 
 .. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
 
-.. _tester-consoles:
+.. _TesterConsoles:
 
 Consoles
 --------
diff --git a/user/testing/gdb-jtag.rst b/user/testing/gdb-jtag.rst
index 0f91f52..83e950e 100644
--- a/user/testing/gdb-jtag.rst
+++ b/user/testing/gdb-jtag.rst
@@ -20,7 +20,7 @@ JTAG port of a target.
 
    RTEMS Tester using GDB and JTAG
 
-The :ref:`fig-tester-gdb-jtag` figure shows the structure of RTEMS Testing
+The Figure :ref:`fig-tester-gdb-jtag` shows the structure of RTEMS Testing
 using GDB and JTAG. The executables are built and the ``rtems-test`` command is
 run from the top of the build directory. The RTEMS Tester executes the BSP
 architecture's GDB and expects the user to provide a ``gdb-script`` to connect
diff --git a/user/testing/index.rst b/user/testing/index.rst
index 7eefff1..a938af4 100644
--- a/user/testing/index.rst
+++ b/user/testing/index.rst
@@ -39,9 +39,11 @@ extend the RTEMS kernel's build time and use more disk space but it worth
 building and running them. The RTEMS test executables have the ``.exe`` file
 extension.
 
-.. include:: tests.rst
-.. include:: configuration.rst
-.. include:: consoles.rst
-.. include:: simulation.rst
-.. include:: gdb-jtag.rst
-.. include:: tftp.rst
+.. toctree::
+
+   tests
+   configuration
+   consoles
+   simulation
+   gdb-jtag
+   tftp
diff --git a/user/testing/tests.rst b/user/testing/tests.rst
index 37966c7..0b44d05 100644
--- a/user/testing/tests.rst
+++ b/user/testing/tests.rst
@@ -71,15 +71,18 @@ Test States
 The tests states are:
 
 .. index:: test state passed
+
 ``passed``
   The test start and end banners have been sent to the console.
 
 .. index:: test state failure
+
 ``failure``
   The test start banner has been sent to the console and no end banner has been
   seen when a target restart is detected.
 
 .. index:: test state expected-fail
+
 ``excepted-fail``
   The test is tagged as ``expected-fail`` in the RTEMS sources for this BSP and
   outputs the banner ``*** TEST STATE: EXPECTED_FAIL``. The test is known not
@@ -88,6 +91,7 @@ The tests states are:
   otherwise it is recorded as *expected-fail*.
 
 .. index:: test state indeterminate
+
 ``indeterminate``
   The test is tagged as ``indeterminate`` in the RTEMS sources for this BSP and
   outputs the banner ``*** TEST STATE: INDETERMINATE``. The test may or may not
@@ -95,12 +99,14 @@ The tests states are:
   the test run as far as it can and record the result as indeterminate.
 
 .. index:: test state user-input
+
 ``user-input``
   The test is tagged as ``user-input`` in the RTEMS sources and outputs the
   banner ``*** TEST STATE: USER_INPUT``. The RTEMS Tester will reset the target
   if the target's configuration provides a target reset command.
 
 .. index:: test state benchmark
+
 ``benchmark``
   The test is tagged as ``benchmark`` in the RTEMS sources and outputs the
   banner ``*** TEST STATE: BENCHMARK``. Benchmarks can take a while to run and
@@ -108,6 +114,7 @@ The tests states are:
   the target if the target's configuration provides a target reset command.
 
 .. index:: test state timeout
+
 ``timeout``
   The test start banner has been sent to the console and no end banner is seen
   within the *timeout* period and the target has not restart. A default
@@ -115,6 +122,7 @@ The tests states are:
   provide on the RTEMS Tester's command line using the ``--timeout`` option.
 
 .. index:: test state invalid
+
 ``invalid``
   The test did not output a start banner and the RTEMS Tester has detected the
   target has restarted. This means the executable did not load correctly, the
@@ -171,38 +179,45 @@ Test Builds
 The test reports the build of RTEMS being tested. The build are:
 
 .. index:: build default
+
 ``default``
   The build is the default. No RTEMS configure options have been used.
 
 .. index:: build posix
+
 ``posix``
   The build includes the POSIX API. The RTEMS configure option
   ``--enable-posix`` has been used. The ``cpuopts.h`` define ``RTEMS_POSIX``
   has defined and it true.
 
 .. index:: build smp
+
 ``smp``
   The build is an SMP kernel. The RTEMS configure option ``--enable-smp`` has
   been used.  The ``cpuopts.h`` define ``RTEMS_SMP`` has defined and it true.
 
 .. index:: build mp
+
 ``mp``
   The build is an MP kernel. The RTEMS configure option
   ``--enable-multiprocessing`` has been used.  The ``cpuopts.h`` define
   ``RTEMS_MULTIPROCESSING`` has defined and it true.
 
 .. index:: build paravirt
+
 ``paravirt``
   The build is a paravirtualization kernel. The ``cpuopts.h`` define
   ``RTEMS_PARAVIRT`` has defined and it true.
 
 .. index:: build debug
+
 ``debug``
   The build includes kernel debugging support. The RTEMS configure option
   ``--enable-debug`` has been used. The ``cpuopts.h`` define ``RTEMS_DEBUG``
   has defined and it true.
 
 .. index:: build profiling
+
 ``profiling``
   The build include profiling support. The RTEMS configure option
   ``--enable-profiling`` has been used. The ``cpuopts.h`` define
diff --git a/user/testing/tftp.rst b/user/testing/tftp.rst
index 1d01673..54b744a 100644
--- a/user/testing/tftp.rst
+++ b/user/testing/tftp.rst
@@ -22,9 +22,10 @@ U-Boot script.
 
    RTEMS Tester using TFTP and U-Boot.
 
-The :ref:`fig-tester-tftp-u-boot` figure shows the structure and control flow
-of the RTEMS Tester using TFTP and U-boot. The executables are built and the
-``rtems-test`` command is run from the top of the build directory.
+The Figure :ref:`fig-tester-tftp-u-boot` figure shows the structure and
+control flow of the RTEMS Tester using TFTP and U-boot. The executables are
+built and the ``rtems-test`` command is run from the top of the build
+directory.
 
 This test mode can only support a single test job running at once. You cannot
 add more test target hardware and run the tests in parallel.
@@ -45,7 +46,7 @@ The RTEMS Tester TFTP and U-Boot method of testing requires:
 
 #. Console interface cable that matches your target's console UART interface.
 
-#. Telnet terminal server. See :ref:`tester-consoles`.
+#. Telnet terminal server. See :ref:`TesterConsoles`.
 
 The network power or IO switch is a device that can control power or an IO pin
 over a network connection using a script-able protocol such as Telnet or
@@ -58,7 +59,9 @@ Obtain a working image of the U-Boot boot loader for your target. We suggest
 you follow the instructions for you target.
 
 Configure U-Boot to network boot using the TFTP protocol. This is U-Boot script
-for a Zedboard::
+for a Zedboard:
+
+.. code-block:: shell
 
   loadaddr=0x02000000
   uenvcmd=echo Booting RTEMS Zed from net; set autoload no; dhcp; set serverip 10.10.5.2; tftpboot zed/rtems.img; bootm; reset;
@@ -86,7 +89,9 @@ The BSP's configuration file must contain the standard fields:
 - ``jobs`` - Must be set to ``1``.
 - ``tester`` - Set to ``%{_rtscripts}/tftp.cfg``
 
-For example the Zedboard's configuration is::
+For example the Zedboard's configuration is:
+
+.. code-block:: ini
 
   [xilinx_zynq_zedboard]
   bsp    = xilinx_zynq_zedboard
@@ -159,14 +164,18 @@ substituted. The parameters are:
 substituted
 
 Some of these field are normally provided by a user's configuration. To do this
-use::
+use:
+
+.. code-block:: shell
 
   requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command
 
 The ``requires`` value requires the user provide these settings in their
 configuration file.
 
-The Zedboard's configuration file is::
+The Zedboard's configuration file is:
+
+.. code-block:: ini
 
   [xilinx_zynq_zedboard]
   bsp                = xilinx_zynq_zedboard
@@ -186,7 +195,9 @@ happen if U-Boot cannot detect the PHY device. It also checks if too many DHCP
 requests happen and finally a check is made for any timeouts reported by
 U-Boot.
 
-An example of a user configuration for the Zedboard is::
+An example of a user configuration for the Zedboard is:
+
+.. code-block:: ini
 
   [xilinx_zynq_zedboard]
   bsp_tty_dev            = selserver:12345
diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst
index fab8bed..d04b8a4 100644
--- a/user/tracing/captureengine.rst
+++ b/user/tracing/captureengine.rst
@@ -98,7 +98,7 @@ traces the context switches between these tasks. ``cwceil`` and ``cwfloor`` are
 set to a narrow range of task priorities to avoid creating noise from a large
 number of context switches between tasks we are not interested in.
 
-.. code:: shell
+.. code-block:: shell
 
   *** BEGIN OF TEST CAPTURE ENGINE ***
   *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst
index d847533..c44daff 100644
--- a/user/tracing/examples.rst
+++ b/user/tracing/examples.rst
@@ -46,7 +46,7 @@ has been stored) run the following commands to generate traces:
 
 BSP is configured with the following command -
 
-.. code:: shell
+.. code-block:: shell
 
   ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
   --enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx
@@ -58,7 +58,7 @@ following commands according to your installation. Also confirm the path of the
 fileio's executable and object files in the last line of the command according
 to your installation.
 
-.. code:: shell
+.. code-block:: shell
 
   sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
   -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
@@ -72,7 +72,7 @@ the application. The link command follows the escape sequence "--". "-C" option
 denotes the name of the user configuration file and "-W" specifies the name of
 the wrapper c file.
 
-.. code:: shell
+.. code-block:: shell
 
   rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
   -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \
@@ -88,13 +88,13 @@ display the contents of the trace buffer and save the buffer to disk in the form
 of binary files. Use `rtrace -l` to list the availalble options for commands
 with `rtrace`.
 
-.. code:: shell
+.. code-block:: shell
 
   sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe
 
 The output from the above commands will be as follows:
 
-.. code:: shell
+.. code-block:: shell
 
   *** BEGIN OF TEST FILE I/O ***
   *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8
diff --git a/user/tracing/introduction.rst b/user/tracing/introduction.rst
index d6f249f..a2e635d 100644
--- a/user/tracing/introduction.rst
+++ b/user/tracing/introduction.rst
@@ -2,7 +2,7 @@
 
 .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
 
-.. _introduction:
+.. _IntroductionToTracing:
 
 Introduction to Tracing
 ***********************
diff --git a/user/tracing/tracelinker.rst b/user/tracing/tracelinker.rst
index 8aad20f..b1e60fd 100644
--- a/user/tracing/tracelinker.rst
+++ b/user/tracing/tracelinker.rst
@@ -92,7 +92,7 @@ used to include other INI files using the include key name. This is shown in the
 following example where the values indicate rtems and rtld-base configuration
 files:
 
-.. code-block:: shell
+.. code-block:: ini
 
   include = rtems.ini, rtld-base.ini
 
@@ -100,7 +100,7 @@ The trace linker also uses values in keys to specify other sections. In this
 example the functions name lists `test-trace-funcs` and that section contains a
 headers key that further references a section called `test-headers`:
 
-.. code-block:: shell
+.. code-block:: ini
 
   functions = test-trace-funcs, rtems-api
 
@@ -143,7 +143,7 @@ following keys:
 The tracer section of the file:`test-trace.ini` is shown below with explanatory
 comments.
 
-.. code-block:: shell
+.. code-block:: ini
 
   ;
   ; RTEMS Trace Linker Test Configuration.
@@ -212,7 +212,7 @@ general options section can contain following sets of keys:
 The options section of the file: `test-trace.ini` uses two of the aforementioned
 keys as shown below:
 
-.. code-block:: shell
+.. code-block:: ini
 
   ;
   ; Options can be defined here or on the command line.
@@ -250,7 +250,7 @@ The trace section of the file: `test-trace.ini` is shown below. A trace section
 can reference other trace sections of a specific type. This allows a trace
 sections to build on other trace sections.
 
-.. code:: shell
+.. code-block:: ini
 
   ; User application trace example.
   ;
@@ -421,7 +421,7 @@ The file: `test-trace.ini` specifies ``printf-generator`` as its generator. This
 section can be found in the file: `rtld-print.ini` in the rtems-tools directory
 and is shown below:
 
-.. code:: shell
+.. code:: ini
 
   ;
   ; A printf generator prints to stdout the trace functions.
diff --git a/user/wscript b/user/wscript
index 4063cd4..8dcbfcd 100644
--- a/user/wscript
+++ b/user/wscript
@@ -1,7 +1,13 @@
 from common.waf import cmd_configure as configure
-from common.waf import cmd_build as build
+from common.waf import cmd_build as doc_build
 from common.waf import cmd_options as options
 from common.waf import spell
 from common.waf import cmd_spell
 from common.waf import linkcheck
 from common.waf import cmd_linkcheck
+
+def build(ctx):
+    sources = {
+        'exclude' : ['apps/index.rst']
+    }
+    doc_build(ctx, sources = sources)