Describe the documentation in the README

README.rst

@@ -5,6 +5,8 @@ triSYCL
   Not supported by GitHub :-(
   include:: doc/common-includes.rst
 
+.. section-numbering::
+
 .. highlight:: C++
 
 .. image:: https://travis-ci.org/triSYCL/triSYCL.svg?branch=master
@@ -81,15 +83,16 @@ For the SYCL_ ecosystem, look at http://sycl.tech
 
 
 Documentation
+-------------
 
 Some reasons to use SYCL
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Please see `about SYCL <doc/about-sycl.rst>`_
+Please see `about SYCL <doc/about-sycl.rst>`_
 
 
 Installation & testing
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 SYCL is a template library, so no real installation is required.
 
@@ -98,20 +101,43 @@ There are some examples you can build however.
 See `Testing <doc/testing.rst>`_
 
 
-OpenCL triSYCL code documentation
----------------------------------
+Architecture of triSYCL runtime and compiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The documentation of the triSYCL_ implementation itself can be found in
-http://xilinx.github.io/triSYCL/Doxygen/triSYCL/html and
-http://xilinx.github.io/triSYCL/Doxygen/triSYCL/triSYCL-implementation-refman.pdf
+`Architecture of triSYCL runtime and compiler <doc/architecture.rst>`_
+describes the code base with some high-level diagrams but also how to
+compile and use the device compiler on some Xilinx_ FPGA for example.
+
+
+CMake infrastructure
+~~~~~~~~~~~~~~~~~~~~
+
+Some details about CMake configuration and organization can be found
+in `CMake <doc/cmake.rst>`_
+
+
+Pre-processor macros used in triSYCL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, there are some macros used in triSYCL! Look at `Pre-processor
+macros used in triSYCL <doc/macros.rst>`_ to discover some of them.
 
 
 Possible futures
-----------------
+~~~~~~~~~~~~~~~~
 
 See `Possible futures <doc/possible-futures.rst>`_
 
 
+OpenCL triSYCL code documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The documentation of the triSYCL_ implementation itself can be found in
+http://xilinx.github.io/triSYCL/Doxygen/triSYCL/html and
+http://xilinx.github.io/triSYCL/Doxygen/triSYCL/triSYCL-implementation-refman.pdf
+
+
+
 News
 ----
 

doc/architecture.rst

@@ -235,7 +235,7 @@ package on Debian/Ubuntu.
 Using OpenCL PoCL on CPU
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The device compiler generates the kernels as SPIR-df (*de-facto*),
+The device compiler generates the kernels as SPIR-df (*de facto*),
 which is SPIR 2.0 encoded with LLVM IR of a more recent version than
 LLVM 3.4 expected by the SPIR specification. So a very modern SPIR
 consumer is required, such as a recent PoCL. It is not the version
@@ -328,7 +328,7 @@ The Clang/LLVM-based device compiler (bottom of `Figure 1`_) compiles
 the C++ SYCL code as for CPU only, but just keep the kernel part of
 the code and produce a simple portable intermediate representation
 (SPIR) of the kernels.  For now, since SPIR-V is not yet widely used,
-triSYCL uses SPIR-df *de-facto*, a non-conforming SPIR 2.0 encoded in
+triSYCL uses SPIR-df (*de facto*), a non-conforming SPIR 2.0 encoded in
 something newer than LLVM 3.4 IR.
 
 Then this SPIR-df output is optionally compiled by some vendor
@@ -556,10 +556,11 @@ of LLVM passes with:
   is the SYCL-specific pass generating the SPIR 2.0-style LLVM IR
   output. Since it generates LLVM IR with the version of the recent
   LLVM used, it is quite more modern that the official SPIR 2.0 based
-  on LLVM 3.4 IR. So it is a SPIR "de-facto", which is nevertheless
-  accepted by some tools. But by using a down-caster, it could
+  on LLVM 3.4 IR. So it is a SPIR-df (*de facto*)", which is nevertheless
+  accepted by some tools. But by using a bitcode down-caster, it could
   probably make some decent official SPIR 2.0 encoded in LLVM 3.4
-  IR). Or using a SPIR-V back-end could generate some SPIR-V code.
+  IR. Otherwise a SPIR-V back-end could generate some SPIR-V code from
+  this.
 
 
 Testing infrastructure