doc: Fix rst substituions and more

* Added rst_epilog in conf.py.in for substitutions

Signed-off-by: Enrico Joerns <e.joerns@tu-bs.de>

6 files changed, 163 insertions, 143 deletions

diff --git a/doc/conf.py.in b/doc/conf.py.in
index 40c688520..3e6b2b4fb 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -95,6 +95,27 @@ pygments_style = 'none'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+numfig = True
+
+rst_epilog = """
+.. |ptxdistPlatformDir| replace:: ``platform-versatilepb``
+.. |oselasTCNarch| replace:: arm
+.. |oselasTCNvariant| replace:: v4t
+.. |oselasTCNVendorVersion| replace:: 2014.12
+.. |oselasTCNVendorPatchLevel| replace:: .0
+.. |oselasTCNVendorptxdistversion| replace:: 2014.12.0
+.. |oselasToolchainName| replace:: arm-v4t-linux-gnueabi_gcc-4.8.2_glibc-2.18_binutils-2.24_kernel-3.12-sanitized
+.. |ptxdistBSPName| replace:: OSELAS.BSP-Pengutronix-Generic-2015.03.1
+.. |ptxdistCompilerName| replace:: arm-v4t-linux-gnueabi
+.. |ptxdistCompilerVersion| replace:: gcc-4.8.2-glibc-2.18-binutils-2.24-kernel-3.12-sanitized
+.. |ptxdistPlatformKernelRev| replace:: 3.19
+.. |ptxdistPlatformKernelRevNext| replace:: 4.0
+.. |ptxdistPlatformName| replace:: arm-qemu
+.. |ptxdistPlatformVariant| replace:: \ 
+.. |ptxdistPlatformCollection| replace:: \ 
+.. |ptxdistVendorVersion| replace:: 2015.03.0
+.. |package| replace:: <pagage>
+"""
 
 # -- Options for HTML output ----------------------------------------------
 
diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index 354358840..3b084fb7f 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -459,15 +459,15 @@ At this stage things can fail:
 
 -  The package depends on external components (libraries for example)
 
-| If the ``configure`` script is not cross compile aware, we are out of
-  luck. We must patch the source archive in this case to make it work.
-  Refer to section :ref:`configure_rebuild` on how to use
-  PTXdist’s features to simplify this task.
-| If the package depends on external components, these components might
-  be already part of PTXdist. In this case we just have to add this
-  dependency into the menu file and we are done. But if PTXdist cannot
-  fulfill this dependency, we also must add it as a separate package
-  first.
+If the ``configure`` script is not cross compile aware, we are out of
+luck. We must patch the source archive in this case to make it work.
+Refer to section :ref:`configure_rebuild` on how to use
+PTXdist’s features to simplify this task.
+If the package depends on external components, these components might
+be already part of PTXdist. In this case we just have to add this
+dependency into the menu file and we are done. But if PTXdist cannot
+fulfill this dependency, we also must add it as a separate package
+first.
 
 If the *prepare* stage has finished successfully, the next step is to
 compile the package.
@@ -630,15 +630,15 @@ After this command, the target’s root filesystem contains a file called
 ``/usr/bin/foo`` owned by root, its group is also root and everyone has
 execution permissions, but only the user root has write permissions.
 
-| One last task of this port is still open: A reasonable location for
-  the new menu entry in PTXdist’s menu hierarchy. PTXdist arranges its
-  menus on the meaning of each package. Is it a network related tool? Or
-  a scripting language? Or a graphical application?
-| Each of these global meanings have their own submenu, where we can add
-  our new entry to. We just have to edit the head of our new menu file
-  ``./rules/foo.in`` to add it to a specific global menu. If our new
-  package is a network related tool, the head of the menu file should
-  look like:
+One last task of this port is still open: A reasonable location for
+the new menu entry in PTXdist’s menu hierarchy. PTXdist arranges its
+menus on the meaning of each package. Is it a network related tool? Or
+a scripting language? Or a graphical application?
+Each of these global meanings have their own submenu, where we can add
+our new entry to. We just have to edit the head of our new menu file
+``./rules/foo.in`` to add it to a specific global menu. If our new
+package is a network related tool, the head of the menu file should
+look like:
 
 ::
 
@@ -832,7 +832,7 @@ guess its settings we **must disable everything we do want**.
 
 Since every optional parameter adds four lines of code to the rule
 files, PTXdist provides some shortcuts to handle it. Refer to section
-[ref:sub:`p`\ aram\ :sub:`m`\ acros] for further details.
+:ref:`param_macros` for further details.
 
 With these special macros in use, the file content shown above looks
 much simpler:
diff --git a/doc/environment.rst b/doc/environment.rst
index b0db35c0b..913d7d389 100644
--- a/doc/environment.rst
+++ b/doc/environment.rst
@@ -137,14 +137,14 @@ Next step is to extract the archive:
 
 ::
 
-    $ tar -xjf ptxdist-\verbatimcmd\ptxdistVendorVersion{}.tar.bz2
+    $ tar -xjf ptxdist-\ |ptxdistVendorVersion|\ .tar.bz2
 
 If everything goes well, we now have a PTXdist- directory, so we can
 change into it:
 
 ::
 
-    $ cd ptxdist-\verbatimcmd\ptxdistVendorVersion
+    $ cd ptxdist-\ |ptxdistVendorVersion|
     $ ls -lF
     total 530
     -rw-r--r--   1 jb user  18446 Sep  9 15:59 COPYING
@@ -197,7 +197,7 @@ If all required components are found the output ends with:
     configure: creating ./config.status
     config.status: creating Makefile
 
-    ptxdist version \ptxdistVendorVersion configured.
+    ptxdist version |ptxdistVendorVersion| configured.
     Using '/usr/local' for installation prefix.
 
     Report bugs to ptxdist@pengutronix.de
@@ -419,7 +419,7 @@ If we want to check if our toolchain was built with the
 
 ::
 
-    $ mytoolchain-gcc -v 2\textgreater{}\&1 | grep with-sysroot
+    $ mytoolchain-gcc -v 2>&1 | grep with-sysroot
 
 If this command **does not** output anything, this toolchain was not
 built with the ``--with-sysroot`` option and cannot be used with
@@ -486,7 +486,7 @@ the board support package:
 
 ::
 
-    $ apt-get install oselas.toolchain-\oselasTCNVendorVersion \oselasTCNVendorPatchLevel -\ptxdistCompilerName-<ptxdistCompilerVersion>
+    $ apt-get install oselas.toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|\ -\ |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
@@ -494,8 +494,8 @@ just use the name by copy and paste it.
 
 ::
 
-    $ apt-cache search "oselas.toolchain-.*-\oselasTCNarch.*\oselasTCNvariant.*"
-    oselas.toolchain-\oselasTCNVendorVersion \oselasTCNVendorPatchLevel -\ptxdistCompilerName-<ptxdistCompilerVersion>
+    $ apt-cache search "oselas.toolchain-.*-\ |oselasTCNarch|\ .*\ |oselasTCNvariant|\ .*"
+    oselas.toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|\ -\ |ptxdistCompilerName|\ -<ptxdistCompilerVersion>
 
 The binary OSELAS Toolchain Package for non-Debian Distributions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -533,12 +533,13 @@ configured to use the standard installation paths mentioned below.
 All OSELAS.Toolchain projects install their result into
 ``/opt/OSELAS.Toolchain-/``.
 
-| 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
-  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:
-| ``mkdir /opt/OSELAS.Toolchain- chown <username> /opt/OSELAS.Toolchain- chmod a+rwx /opt/OSELAS.Toolchain-``.
+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
+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:
+
+``mkdir /opt/OSELAS.Toolchain- chown <username> /opt/OSELAS.Toolchain- chmod a+rwx /opt/OSELAS.Toolchain-``.
 
 We recommend to keep this installation path as PTXdist expects the
 toolchains at ``/opt``. Whenever we go to select a platform in a
@@ -575,7 +576,7 @@ To select the correct one for our project we can follow the project
 specific documentation or, if we know what revision composition we need,
 we can find the correct configuration file in the following way.
 
-| For example this is one of the predefined toolchains:
+For example this is one of the predefined toolchains:
 
 **i586-unknown-linux-gnu\_gcc-4.7.2\_glibc-2.16.0\_binutils-2.22\_kernel-3.6-sanitized**
 
@@ -609,24 +610,23 @@ toolchain.
 
 The steps to do so are:
 
-In order to build any of the OSELAS.Toolchains, the host must provide
-the tool *fakeroot*. Otherwise the
-message\ ``bash: fakeroot: command not found`` will occur and the build
-stops.
+.. important:: In order to build any of the OSELAS.Toolchains, the host must provide
+  the tool *fakeroot*. Otherwise the
+  message\ ``bash: fakeroot: command not found`` will occur and the build
+  stops.
 
-Please ensure the ’current directory’ (the ``.`` entry) is not part of
-your PATH environment variable. PTXdist tries to sort out this entry,
-but might not be successful in doing so. Check by running
-``ptxdist print PATH`` if the output still contains any kind of ’current
-directory’ as a component. If yes, remove it first.
+.. important:: Please ensure the ’current directory’ (the ``.`` entry) is not part of
+  your PATH environment variable. PTXdist tries to sort out this entry,
+  but might not be successful in doing so. Check by running
+  ``ptxdist print PATH`` if the output still contains any kind of ’current
+  directory’ as a component. If yes, remove it first.
 
 ::
 
-    $ tar xf OSELAS.Toolchain-\verbatimcmd\oselasTCNVendorVersion{}\oselasTCNVendorPatchLevel.tar.bz2
-    $ cd OSELAS.Toolchain-\verbatimcmd\oselasTCNVendorVersion{}\oselasTCNVendorPatchLevel
-    $ ptxdist-\oselasTCNVendorptxdistversion{} select ptxconfigs/\verbatimcmd\ptxcr
-    	\verbatimcmd\oselasToolchainName.ptxconfig
-    $ ptxdist-\oselasTCNVendorptxdistversion{} go
+    $ tar xf OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|.tar.bz2
+    $ cd OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|
+    $ 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
diff --git a/doc/getting_help.rst b/doc/getting_help.rst
index bae89671a..c54b3b563 100644
--- a/doc/getting_help.rst
+++ b/doc/getting_help.rst
@@ -47,12 +47,12 @@ http://www.kroah.com/lkn/
 Chat/IRC
 --------
 
-**About PTXdist in particular**
+About PTXdist in particular
 
 **irc.freenode.net:6667**
 
-Create a connection to the **irc.freenode.net:6667** server and enter
-the chatroom **#ptxdist**. This is an English room to answer questions
+Create a connection to the ``irc.freenode.net:6667`` server and enter
+the chatroom ``#ptxdist``. This is an English room to answer questions
 about PTXdist. Best time to meet somebody there is at European daytime.
 
 Commercial Support
@@ -64,12 +64,12 @@ quotation for your special requirements.
 
 Contact us at:
 
-**Pengutronix
-Peiner Str. 6-8
-31137 Hildesheim
-Germany
-Phone: +49 - 51 21 / 20 69 17 - 0
-Fax: +49 - 51 21 / 20 69 17 - 55 55**
+| Pengutronix
+| Peiner Str. 6-8
+| 31137 Hildesheim
+| Germany
+| Phone: +49 - 51 21 / 20 69 17 - 0
+| Fax: +49 - 51 21 / 20 69 17 - 55 55
 
 or by electronic mail:
 
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index b296fbca4..cdb5ab136 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.
@@ -748,7 +748,7 @@ If the *get* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.get:
+    $(STATEDIR)/@package@.get:
     		@$(call targetinfo)
     		@$(call touch)
 
@@ -759,9 +759,9 @@ following rule must exist in this case:
 
 .. code-block:: make
 
-    $(|package|_SOURCE):
+    $(@package@_SOURCE):
     		@$(call targetinfo)
-		@$(call get, |package|)
+		@$(call get, @package@)
 
 extract Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -770,11 +770,11 @@ If the *extract* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.extract:
+    $(STATEDIR)/@package@.extract:
     		@$(call targetinfo)
-		@$(call clean, $(|package|_DIR))
-		@$(call extract, |package|)
-		@$(call patchin, |package|)
+		@$(call clean, $(@package@_DIR))
+		@$(call extract, @package@)
+		@$(call patchin, @package@)
     		@$(call touch)
 
 Which means a current existing directory of this package will be
@@ -787,59 +787,59 @@ prepare Stage Default Rule
 If the *prepare* stage is omitted, PTXdist runs a default stage rule
 depending on some variable settings.
 
-If the package’s rule file defines ``|package|_CONF_TOOL`` to ``NO``,
+If the package’s rule file defines ``@package@_CONF_TOOL`` to ``NO``,
 this stage is simply skipped.
 
-All rules files shall create the ``|package|_CONF_ENV`` variable and
+All rules files shall create the ``@package@_CONF_ENV`` variable and
 define it at least to ``$(CROSS_ENV)`` if the prepare stage is used.
 
-If the package’s rule file defines ``|package|_CONF_TOOL`` to
+If the package’s rule file defines ``@package@_CONF_TOOL`` to
 ``autoconf`` (``FOO_CONF_TOOL = autoconf`` for our *foo* example),
 PTXdist treats this package as an autotoolized package and runs:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.prepare:
+    $(STATEDIR)/@package@.prepare:
     		@$(call targetinfo)
-		@$(call clean, $(|package|_DIR)/config.cache)
-		@cd $(|package|_DIR)/$(|package|_SUBDIR) && \
-			$(|package|_PATH) $(|package|_CONF_ENV) \
-			./configure $(|package|_CONF_OPT)
+		@$(call clean, $(@package@_DIR)/config.cache)
+		@cd $(@package@_DIR)/$(@package@_SUBDIR) && \
+			$(@package@_PATH) $(@package@_CONF_ENV) \
+			./configure $(@package@_CONF_OPT)
     		@$(call touch)
 
-The ``|package|_CONF_OPT`` should at least be defined to
+The ``@package@_CONF_OPT`` should at least be defined to
 ``$(CROSS_AUTOCONF_USR)`` or ``$(CROSS_AUTOCONF_ROOT)``.
 
-If the package’s rule file defines ``|package|_CONF_TOOL`` to ``cmake``
+If the package’s rule file defines ``@package@_CONF_TOOL`` to ``cmake``
 (``FOO_CONF_TOOL = cmake`` for our *foo* example), PTXdist treats this
 package as a *cmake* based package and runs:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.prepare:
+    $(STATEDIR)/@package@.prepare:
     		@$(call targetinfo)
-		@cd $(|package|_DIR) && \
-			$(|package|_PATH) $(|package|_CONF_ENV) \
-			cmake $(|package|_CONF_OPT)
+		@cd $(@package@_DIR) && \
+			$(@package@_PATH) $(@package@_CONF_ENV) \
+			cmake $(@package@_CONF_OPT)
     		@$(call touch)
 
-The ``|package|_CONF_OPT`` should at least be defined to
+The ``@package@_CONF_OPT`` should at least be defined to
 ``$(CROSS_CMAKE_USR)`` or ``$(CROSS_CMAKE_ROOT)``.
 
-If the package’s rule file defines ``|package|_CONF_TOOL`` to ``qmake``
+If the package’s rule file defines ``@package@_CONF_TOOL`` to ``qmake``
 (``FOO_CONF_TOOL = qmake`` for our *foo* example), PTXdist treats this
 package as a *qmake* based package and runs:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.prepare:
+    $(STATEDIR)/@package@.prepare:
     		@$(call targetinfo)
-		@cd $(|package|_DIR) && \
-			$(|package|_PATH) $(|package|_CONF_ENV) \
-			qmake $(|package|_CONF_OPT)
+		@cd $(@package@_DIR) && \
+			$(@package@_PATH) $(@package@_CONF_ENV) \
+			qmake $(@package@_CONF_OPT)
     		@$(call touch)
 
-The ``|package|_CONF_OPT`` should at least be defined to
+The ``@package@_CONF_OPT`` should at least be defined to
 ``$(CROSS_QMAKE_OPT)``.
 
 compile Stage Default Rule
@@ -849,24 +849,24 @@ If the *compile* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.compile:
+    $(STATEDIR)/@package@.compile:
     		@$(call targetinfo)
-		@cd $(|package|_DIR) && \
-			$(|package|_PATH) $(|package|_MAKE_ENV) \
-			$(MAKE) $(|package|_MAKE_OPT) $(|package|_MAKE_PAR)
+		@cd $(@package@_DIR) && \
+			$(@package@_PATH) $(@package@_MAKE_ENV) \
+			$(MAKE) $(@package@_MAKE_OPT) $(@package@_MAKE_PAR)
     		@$(call touch)
 
-If the ``|package|_MAKE_ENV`` is not defined, it defaults to
+If the ``@package@_MAKE_ENV`` is not defined, it defaults to
 ``$(CROSS_ENV)``. If some additional variables should be added to the
-``|package|_MAKE_ENV``, always begin with the ``$(CROSS_ENV)`` and then
+``@package@_MAKE_ENV``, always begin with the ``$(CROSS_ENV)`` and then
 add the additional variables.
 
-If the ``|package|_MAKE_OPT`` is intended for additional parameters to
+If the ``@package@_MAKE_OPT`` is intended for additional parameters to
 be forwarded to ``make`` or to overwrite some settings from the
-``|package|_MAKE_ENV``. If not defined in the rule file it defaults to
+``@package@_MAKE_ENV``. If not defined in the rule file it defaults to
 an empty string.
 
-Note: ``|package|_MAKE_PAR`` can be defined to ``YES`` or ``NO`` to
+Note: ``@package@_MAKE_PAR`` can be defined to ``YES`` or ``NO`` to
 control if the package can be built in parallel.
 
 install Stage Default Rule
@@ -876,14 +876,14 @@ If the *install* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.install:
+    $(STATEDIR)/@package@.install:
     		@$(call targetinfo)
-		@cd $(|package|_DIR) && \
-			$(|package|_PATH) $(|package|_MAKE_ENV) \
-			$(MAKE) $(|package|_INSTALL_OPT)
+		@cd $(@package@_DIR) && \
+			$(@package@_PATH) $(@package@_MAKE_ENV) \
+			$(MAKE) $(@package@_INSTALL_OPT)
     		@$(call touch)
 
-Note: ``|package|_INSTALL_OPT`` is always defined to ``install`` if not
+Note: ``@package@_INSTALL_OPT`` is always defined to ``install`` if not
 otherwise specified. This value can be replaced by a package’s rule file
 definition.
 
@@ -904,7 +904,7 @@ be provided:
 
 .. code-block:: make
 
-    $(STATEDIR)/|package|.<stage_to_skip>:
+    $(STATEDIR)/@package@.<stage_to_skip>:
     		@$(call targetinfo)
     		@$(call touch)
 
diff --git a/doc/user_manual.rst b/doc/user_manual.rst
index 3d5ef074b..087ed085f 100644
--- a/doc/user_manual.rst
+++ b/doc/user_manual.rst
@@ -140,7 +140,7 @@ command:
 
 ::
 
-    $ ptxdist <parameter>
+    $ ptxdist |parameter|
 
 To run different functions, this command must be extended by parameters
 to define the function we want to run.
@@ -253,10 +253,10 @@ 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
-    $ cd <ptxdistBSPName>
+    $ tar -zxf |ptxdistBSPName|\ .tar.gz
+    $ cd |ptxdistBSPName|
 
 PTXdist is project centric, so now after changing into the new directory
 we have access to all valid components.
@@ -330,27 +330,27 @@ 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:
+.. 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><oselasTCNVendorPatchLevel>/<ptxdistCompilerName>/<ptxcr>
-         <ptxdistCompilerVersion>/bin'
+    '/opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|\ /\ |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
 can omit the steps of the section and continue to build the BSP.
 
-In the unified , one included platform can use more userland features
+In the unified, one included platform can use more userland features
 than another. For example platforms with graphic features will also
 build graphic support, but platforms sans display do not need it. To
 speed up compilation for specific platforms PTXdist provides
@@ -359,11 +359,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
 ~~~~~~~~~~~~~~~~~~~~~
@@ -372,10 +372,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 \oselasTCNVendorPatchLevel/<ptxdistCompilerName>/\ptxcr
-          <ptxdistCompilerVersion>/bin
+    $ ptxdist toolchain /opt/OSELAS.Toolchain-\ |oselasTCNVendorVersion|\ |oselasTCNVendorPatchLevel|\ /\ |ptxdistCompilerName|\ /\ |ptxdistCompilerVersion|\ /bin
 
 Building the Root Filesystem Content
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -400,40 +399,40 @@ What we Got Now
 After building the project, we find even more sub directories in our
 project.
 
-**|ptxdistPlatformDir|build-cross**
+|ptxdistPlatformDir|\ ``/build-cross``
     Contains all packages sources compiled to run on the host and handle
     target architecture dependend things.
 
-**|ptxdistPlatformDir|build-host**
+|ptxdistPlatformDir|\ ``/build-host``
     Contains all packages sources compiled to run on the host and handle
     architecture independend things.
 
-**|ptxdistPlatformDir|build-target**
+|ptxdistPlatformDir|\ ``/build-target``
     Contains all package sources compiled for the target architecure.
 
-**|ptxdistPlatformDir|images**
+|ptxdistPlatformDir|\ ``/images``
     Generated files for the target can be found here: Kernel image and
     root filesystem image.
 
-**|ptxdistPlatformDir|packages**
+|ptxdistPlatformDir|\ ``/packages``
     Location for alle individual packages in ipk format.
 
-**|ptxdistPlatformDir|sysroot-target**
+|ptxdistPlatformDir|\ ``/sysroot-target``
     Contains everything target architecture dependend (libraries, header
     files and so on).
 
-**|ptxdistPlatformDir|sysroot-cross**
+|ptxdistPlatformDir|\ ``/sysroot-cross``
     Contains everything that is host specific but must handle target
     architecture data.
 
-**|ptxdistPlatformDir|sysroot-host**
+|ptxdistPlatformDir|\ ``/sysroot-host``
     Contains everything that is only host specific.
 
-**|ptxdistPlatformDir|root**
+|ptxdistPlatformDir|\ ``/root``
     Target’s root filesystem image. This directory can be mounted as
     an NFS root for example.
 
-**|ptxdistPlatformDir|root-debug**
+|ptxdistPlatformDir|\ ``/root-debug``
     Target’s root filesystem image. The difference to ``root/`` is,
     all programs and libraries in this directory still have their
     debug information present. This directory is intended to be used
@@ -441,7 +440,7 @@ project.
     should setup your debugger with
     ``set solib-absolute-prefix </path/to/workspace>/root-debug``
 
-**|ptxdistPlatformDir|state**
+|ptxdistPlatformDir|\ ``/state``
     Building every package is divided onto stages. And stages of one
     package can depend on stages of other packages. In order to handle
     this correctly, this directory contains timestamp files about
@@ -449,7 +448,7 @@ project.
 
 This are the generated files:
 
-**|ptxdistPlatformDir|logfile**
+|ptxdistPlatformDir|\ ``/logfile``
     Every run of PTXdist will add its output to this file. If something
     fails, this file can help to find the cause.
 
@@ -495,9 +494,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
@@ -672,10 +671,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.
 
@@ -759,10 +758,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.
@@ -782,9 +781,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'
@@ -822,10 +821,10 @@ 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
+    $ ./configs/|ptxdistPlatformName|/run
 
 Log in on the emulated system and simply check with a: