doc: cleanup substitutions and use code sections

Now, that substitutions happen before the sphinx run, the '\ ' magic so
that the substitute patters are found, are no longer needed. And code
sections can now be used here. This is needed to break long lines for in
latex output.

Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

4 files changed, 60 insertions, 60 deletions

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index dfd2c040b..e89857549 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -67,7 +67,7 @@ package in question.
 
 One location is the project’s currently used platform directory. If the
 currently used platform is located in ``configs/``, PTXdist searches in
-./configs/\ |ptxdistPlatformName|\ /patches/<package name>
+./configs/|ptxdistPlatformName|/patches/<package name>
 
 If no patch series was found in the platform directory, the next
 location PTXdist it searches for a patch series is the main project
diff --git a/doc/environment.rst b/doc/environment.rst
index f840c9581..3362832ba 100644
--- a/doc/environment.rst
+++ b/doc/environment.rst
@@ -17,10 +17,10 @@ components which are available to the public).
 In order to build |ptxdistBSPName|, the following source archives have to be available
 on the development host:
 
- * ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2
- * |ptxdistBSPName|\ .tar.bz2
- * ptxdist-\ |oselasTCNVendorptxdistversion|\ .tar.bz2
- * OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ .tar.bz2
+ * ptxdist-|ptxdistVendorVersion|.tar.bz2
+ * |ptxdistBSPName|.tar.bz2
+ * ptxdist-|oselasTCNVendorptxdistversion|.tar.bz2
+ * OSELAS.Toolchain-|oselasTCNVendorVersion|.tar.bz2
 
 Main Parts of PTXdist
 ~~~~~~~~~~~~~~~~~~~~~
@@ -82,7 +82,7 @@ else.
 To install PTXdist, the archive Pengutronix provides has to be
 extracted:
 
-ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2
+ptxdist-|ptxdistVendorVersion|.tar.bz2
     The PTXdist software itself
 
 The PTXdist archive has to be extracted into some temporary directory in
@@ -98,16 +98,16 @@ to create it and change into it:
 
 Next step is to extract the archive:
 
-.. parsed-literal::
+::
 
-    $ tar -xjf ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2
+    $ tar -xjf ptxdist-|ptxdistVendorVersion|.tar.bz2
 
-If everything goes well, we now have a PTXdist-\ |ptxdistVendorVersion| directory, so we can
+If everything goes well, we now have a PTXdist-|ptxdistVendorVersion| directory, so we can
 change into it:
 
-.. parsed-literal::
+::
 
-    $ cd ptxdist-\ |ptxdistVendorVersion|
+    $ cd ptxdist-|ptxdistVendorVersion|
     $ ls -lF
     total 530
     -rw-r--r--   1 jb user  18446 Sep  9 15:59 COPYING
@@ -149,7 +149,7 @@ to be done now is to configure the packet:
 This will check your system for required components PTXdist relies on.
 If all required components are found the output ends with:
 
-.. parsed-literal::
+::
 
     [...]
     checking whether Python development files are present... yes
@@ -446,18 +446,18 @@ Install the binary OSELAS Toolchain
 Now everything is in place to install the binary OSELAS toolchain for
 the board support package:
 
-.. parsed-literal::
+::
 
-    $ apt-get install oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -<ptxdistCompilerVersion>
+    $ apt-get install oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-<ptxdistCompilerVersion>
 
 These package names are very long and hard to type without making typos.
 An easier way is to ask the package manager for available toolchains and
 just use the name by copy and paste it.
 
-.. parsed-literal::
+::
 
-    $ apt-cache search "oselas.toolchain-.*-\ |oselasTCNarch|\ .*\ |oselasTCNvariant|\ .*"
-    oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -<ptxdistCompilerVersion>
+    $ apt-cache search "oselas.toolchain-.*-|oselasTCNarch|.*|oselasTCNvariant|.*"
+    oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-<ptxdistCompilerVersion>
 
 The binary OSELAS Toolchain Package for non-Debian Distributions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -469,11 +469,11 @@ The related OSELAS toolchain package can be found here:
 
 Subpath is:
 
-| oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -\ |ptxdistCompilerVersion|\ /
+| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|/
 
 Package filename is:
 
-| oselas.toolchain-\ |oselasTCNVendorVersion|\ -\ |ptxdistCompilerName|\ -\ |ptxdistCompilerVersion|\ \*.deb
+| oselas.toolchain-|oselasTCNVendorVersion|-|ptxdistCompilerName|-|ptxdistCompilerVersion|\*.deb
 
 Package filenames for 32 bit host machines are ending on ``*_i386.deb``
 and for 64 bit host machines on ``*_amd64.deb``.
@@ -485,8 +485,8 @@ PTXdist handles toolchain building as a simple project, like all other
 projects, too. So we can download the OSELAS.Toolchain bundle and build
 the required toolchain for the OSELAS.BoardSupport() Package.
 
-Building any toolchain of the OSELAS.Toolchain-\ |oselasTCNVendorVersion|  is
-tested with PTXdist-\ |oselasTCNVendorptxdistversion|.
+Building any toolchain of the OSELAS.Toolchain-|oselasTCNVendorVersion|  is
+tested with PTXdist-|oselasTCNVendorptxdistversion|.
 Pengutronix recommends to use this specific PTXdist to build the
 toolchain. So, it might be essential to install more than one PTXdist
 revision to build the toolchain and later on the Board Support Package
@@ -497,7 +497,7 @@ directory; all OSELAS.Toolchain projects that come with PTXdist are
 configured to use the standard installation paths mentioned below.
 
 All OSELAS.Toolchain projects install their result into
-/opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /.
+/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/.
 
 Usually the ``/opt`` directory is not world writeable. So in order to
 build our OSELAS.Toolchain into that directory we need to use a root
@@ -505,11 +505,11 @@ account to change the permissions. PTXdist detects this case and asks
 if we want to run ``sudo`` to do the job for us. Alternatively we can
 enter:
 
-.. parsed-literal::
+::
 
-   $ mkdir /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|
-   $ chown <username> /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|
-   $ chmod a+rwx /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|
+   $ mkdir /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|
+   $ chown <username> /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|
+   $ chmod a+rwx /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|
 
 We recommend to keep this installation path as PTXdist expects the
 toolchains at ``/opt``. Whenever we go to select a platform in a
@@ -534,7 +534,7 @@ compiler in question and start the build.
 
 The required compiler to build the board support package is
 
-|oselasToolchainName|\ .ptxconfig
+|oselasToolchainName|.ptxconfig
 
 .. important:: In order to build any of the OSELAS.Toolchains, the host must provide
   the tool *fakeroot*. Otherwise the
@@ -549,12 +549,12 @@ The required compiler to build the board support package is
 
 So the steps to build this toolchain are:
 
-.. parsed-literal::
+::
 
-    $ tar xf OSELAS.Toolchain-\ |oselasTCNVendorVersion|.tar.bz2
-    $ cd OSELAS.Toolchain-\ |oselasTCNVendorVersion|
-    $ ptxdist-\ |oselasTCNVendorptxdistversion| select ptxconfigs/\ |oselasToolchainName|\ .ptxconfig
-    $ ptxdist-\ |oselasTCNVendorptxdistversion| go
+    $ tar xf OSELAS.Toolchain-|oselasTCNVendorVersion|.tar.bz2
+    $ cd OSELAS.Toolchain-|oselasTCNVendorVersion|
+    $ ptxdist-|oselasTCNVendorptxdistversion| select ptxconfigs/|oselasToolchainName|.ptxconfig
+    $ ptxdist-|oselasTCNVendorptxdistversion| go
 
 At this stage we have to go to our boss and tell him that it’s probably
 time to go home for the day. Even on reasonably fast machines the time
@@ -607,10 +607,10 @@ new one.
 All toolchains will be installed side by side architecture dependent
 into directory
 
-| /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|/<architecture>
+| /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/<architecture>
 
 Different toolchains for the same architecture will be installed side by
 side version dependent into directory
 
-| /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|/<architecture>/<version>
+| /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/<architecture>/<version>
 
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index da2a3ff86..4201c945f 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -12,10 +12,10 @@ are changed.
 To get their content related to the current project, we can simply run
 a:
 
-.. parsed-literal::
+::
 
     $ ptxdist print PTXDIST_TOPDIR
-    /usr/local/lib/ptxdist-\ |release|
+    /usr/local/lib/ptxdist-|release|
 
 Replace the ``PTXDIST_TOPDIR`` with one of the other generic variables
 PTXdist provides.
diff --git a/doc/user_manual.rst b/doc/user_manual.rst
index f011edcd0..fe4ae1745 100644
--- a/doc/user_manual.rst
+++ b/doc/user_manual.rst
@@ -255,9 +255,9 @@ Extracting the Board Support Package
 In order to work with a PTXdist based project we have to extract the
 archive first.
 
-.. parsed-literal::
+::
 
-    $ tar -zxf |ptxdistBSPName|\ .tar.gz
+    $ tar -zxf |ptxdistBSPName|.tar.gz
     $ cd |ptxdistBSPName|
 
 PTXdist is project centric, so now after changing into the new directory
@@ -332,21 +332,21 @@ Selecting a Hardware Platform
 Before we can build this BSP, we need to select one of the possible
 platforms to build for. In this case we want to build for the :
 
-.. parsed-literal::
+::
 
-    $ ptxdist platform configs/\ |ptxdistPlatformName|\ /platformconfig\ |ptxdistPlatformVariant|
+    $ ptxdist platform configs/|ptxdistPlatformName|/platformconfig|ptxdistPlatformVariant|
     info: selected platformconfig:
-          'configs/\ |ptxdistPlatformName|\ /platformconfig\ |ptxdistPlatformVariant|\ '
+          'configs/|ptxdistPlatformName|/platformconfig|ptxdistPlatformVariant|'
 
 .. note:: If you have installed the OSELAS.Toolchain() at its default
   location, PTXdist should already have detected the proper toolchain
   while selecting the platform. In this case it will output:
 
-.. parsed-literal::
+::
 
     found and using toolchain:
-    '/opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /\ |ptxdistCompilerName|\ /\
-    |ptxdistCompilerVersion|\ /bin'
+    '/opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/|ptxdistCompilerName|/\
+    |ptxdistCompilerVersion|/bin'
 
 If it fails you can continue to select the toolchain manually as
 mentioned in the next section. If this autodetection was successful, we
@@ -361,11 +361,11 @@ specific cases.
 
 To reduce the package count for the run:
 
-.. parsed-literal::
+::
 
-    $ ptxdist collection configs/\ |ptxdistPlatformCollection|
+    $ ptxdist collection configs/|ptxdistPlatformCollection|
     info: selected collectionconfig:
-          'configs/\ |ptxdistPlatformCollection|\ '
+          'configs/|ptxdistPlatformCollection|'
 
 Selecting a Toolchain
 ~~~~~~~~~~~~~~~~~~~~~
@@ -374,9 +374,9 @@ If not automatically detected, the last step in selecting various
 configurations is to select the toolchain to be used to build everything
 for the target.
 
-.. parsed-literal::
+::
 
-    $ ptxdist toolchain /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ /\ |ptxdistCompilerName|\ /\ |ptxdistCompilerVersion|\ /bin
+    $ ptxdist toolchain /opt/OSELAS.Toolchain-|oselasTCNVendorVersion|/|ptxdistCompilerName|/|ptxdistCompilerVersion|/bin
 
 Building the Root Filesystem Content
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -496,9 +496,9 @@ working QEMU on our development host.
 
 Simply run
 
-.. parsed-literal::
+::
 
-    $ ./configs/\ |ptxdistPlatformName|\ /run
+    $ ./configs/|ptxdistPlatformName|/run
 
 This will start QEMU in full system emulation mode and runs the
 previously built kernel which then uses the generated disk image to
@@ -673,10 +673,10 @@ To do so, we run:
 
 In this Kconfig dialogue we navigate to the entry:
 
-.. parsed-literal::
+::
 
     Linux kernel  --->
-        (\ |ptxdistPlatformKernelRev|\ ) kernel version
+        (|ptxdistPlatformKernelRev|) kernel version
 
 and replace the 3.19 value by the 4.0 value.
 
@@ -688,11 +688,11 @@ Now we can leave the menu and save the new settings.
 
 A Linux kernel needs a configuration for being built correctly. The
 project comes with a prepared configuration in the file
-configs/\ |ptxdistPlatformName|\ /kernelconfig-3.0 for the 3.0 kernel.
+configs/|ptxdistPlatformName|/kernelconfig-3.0 for the 3.0 kernel.
 
 It is always a good idea to start with a known-to-work kernel
 configuration. So, for this example, we are using a different
-known-to-work kernel configuration in the configs/\ |ptxdistPlatformName|\ /kernelconfig-3.7
+known-to-work kernel configuration in the configs/|ptxdistPlatformName|/kernelconfig-3.7
 file for our new 3.7 kernel.
 
 Adapting Linux Kernel Settings
@@ -736,10 +736,10 @@ When PTXdist has finished its job, the new bootable kernel can be found
 at ``images/linuximage``. To boot it again in the QEMU emulation, the
 hard disk image must be re-created with:
 
-.. parsed-literal::
+::
 
     $ ptxdist images
-    $ ./configs/\ |ptxdistPlatformName|\ /run
+    $ ./configs/|ptxdistPlatformName|/run
 
 The emulated system should now start with a 3.7 based kernel with USB
 support.
@@ -759,9 +759,9 @@ such packages.
 In this simple example, we want to add the missing ``head`` command to
 our target’s shell. Assuming we forgot to enable this command, we get:
 
-.. parsed-literal::
+::
 
-    $ ./configs/\ |ptxdistPlatformName|\ /run
+    $ ./configs/|ptxdistPlatformName|/run
 
     ptx login: root
     login[xxx]: root login on 'ttyS0'
@@ -799,7 +799,7 @@ change.
 And also once again, after finishing its job, the following commands let
 us test the new command:
 
-.. parsed-literal::
+::
 
     $ ptxdist images
     $ ./configs/|ptxdistPlatformName|/run