Tutorial: Small formatting improvements

- Use inline literals for all code fragments and names.
- Add missing console code-blocks.
- Always use c++, not c as code language.

Help/guide/tutorial/A Basic Starting Point.rst

@@ -56,7 +56,7 @@ Using your favorite editor, create ``TutorialConfig.h.in`` in the source
 directory with the following contents:
 
 .. literalinclude:: Step2/TutorialConfig.h.in
-  :language: cmake
+  :language: c++
 
 When CMake configures this header file the values for
 ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be
@@ -89,9 +89,9 @@ We will need to explicitly state in the CMake code that it should use the
 correct flags. The easiest way to enable support for a specific C++ standard
 in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
 tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
-``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to
-True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call
-to ``add_executable``.
+``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`
+to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the
+call to ``add_executable``.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake

Help/guide/tutorial/Adding Export Configuration.rst

@@ -14,14 +14,14 @@ The first step is to update our :command:`install(TARGETS)` commands to not
 only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
 generates and installs a CMake file containing code to import all targets
 listed in the install command from the installation tree. So let's go ahead and
-explicitly ``EXPORT`` the MathFunctions library by updating the ``install``
+explicitly ``EXPORT`` the ``MathFunctions`` library by updating the ``install``
 command in ``MathFunctions/CMakeLists.txt`` to look like:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # install rules
 
-Now that we have MathFunctions being exported, we also need to explicitly
+Now that we have ``MathFunctions`` being exported, we also need to explicitly
 install the generated ``MathFunctionsTargets.cmake`` file. This is done by
 adding the following to the bottom of the top-level ``CMakeLists.txt``:
 
@@ -45,10 +45,10 @@ you will see that CMake will generate an error that looks like:
 What CMake is trying to say is that during generating the export information
 it will export a path that is intrinsically tied to the current machine and
 will not be valid on other machines. The solution to this is to update the
-MathFunctions :command:`target_include_directories` to understand that it needs
-different ``INTERFACE`` locations when being used from within the build
+``MathFunctions`` :command:`target_include_directories` to understand that it
+needs different ``INTERFACE`` locations when being used from within the build
 directory and from an install / package. This means converting the
-:command:`target_include_directories` call for MathFunctions to look like:
+:command:`target_include_directories` call for ``MathFunctions`` to look like:
 
 .. literalinclude:: Step12/MathFunctions/CMakeLists.txt
   :language: cmake

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -23,9 +23,9 @@ There are different types of
 Logical, Informational, and Output expressions.
 
 Logical expressions are used to create conditional output. The basic
-expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty
-string, and ``<1:...>`` results in the content of "...".  They can also be
-nested.
+expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the
+empty string, and ``<1:...>`` results in the content of ``...``.  They can also
+be nested.
 
 A common usage of
 :manual:`generator expressions <cmake-generator-expressions(7)>` is to
@@ -64,6 +64,5 @@ Looking at this we see that the warning flags are encapsulated inside a
 ``BUILD_INTERFACE`` condition. This is done so that consumers of our installed
 project will not inherit our warning flags.
 
-
 **Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
 a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.

Help/guide/tutorial/Adding Support for a Testing Dashboard.rst

@@ -37,10 +37,14 @@ executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project,
 but do not build it yet. Instead, change directory to the binary tree, and then
 run:
 
+.. code-block:: console
+
   ctest [-VV] -D Experimental
 
 Remember, for multi-config generators (e.g. Visual Studio), the configuration
-type must be specified::
+type must be specified:
+
+.. code-block:: console
 
   ctest [-VV] -C Debug -D Experimental
 

Help/guide/tutorial/Adding System Introspection.rst

@@ -11,8 +11,8 @@ If the platform has ``log`` and ``exp`` then we will use them to compute the
 square root in the ``mysqrt`` function. We first test for the availability of
 these functions using the :module:`CheckSymbolExists` module in
 ``MathFunctions/CMakeLists.txt``. On some platforms, we will need to link to
-the m library. If ``log`` and ``exp`` are not initially found, require the m
-library and try again.
+the ``m`` library. If ``log`` and ``exp`` are not initially found, require the
+``m`` library and try again.
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -47,4 +47,4 @@ Run the :manual:`cmake  <cmake(1)>` executable or the
 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool and run the Tutorial executable.
 
-Which function gives better results now, sqrt or mysqrt?
+Which function gives better results now, ``sqrt`` or ``mysqrt``?

Help/guide/tutorial/Adding Usage Requirements for a Library.rst

@@ -13,8 +13,8 @@ requirements are:
 
 Let's refactor our code from :guide:`tutorial/Adding a Library` to use the
 modern CMake approach of usage requirements. We first state that anybody
-linking to MathFunctions needs to include the current source directory,
-while MathFunctions itself doesn't. So this can become an ``INTERFACE``
+linking to ``MathFunctions`` needs to include the current source directory,
+while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE``
 usage requirement.
 
 Remember ``INTERFACE`` means things that consumers require but the producer
@@ -25,7 +25,7 @@ doesn't. Add the following lines to the end of
   :language: cmake
   :start-after: # to find MathFunctions.h
 
-Now that we've specified usage requirements for MathFunctions we can safely
+Now that we've specified usage requirements for ``MathFunctions`` we can safely
 remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
 ``CMakeLists.txt``, here:
 

Help/guide/tutorial/Adding a Custom Command and Generated File.rst

@@ -57,7 +57,7 @@ directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
   :end-before: # install rules
 
 Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
-``Table.h``. Next, we can rewrite the mysqrt function to use the table:
+``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table:
 
 .. literalinclude:: Step7/MathFunctions/mysqrt.cxx
   :language: c++
@@ -69,7 +69,7 @@ with your chosen build tool.
 
 When this project is built it will first build the ``MakeTable`` executable.
 It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will
-compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions
-library.
+compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the
+``MathFunctions`` library.
 
 Run the Tutorial executable and verify that it is using the table.

Help/guide/tutorial/Adding a Library.rst

@@ -41,7 +41,7 @@ last few lines of the top-level ``CMakeLists.txt`` file should now look like:
                                   "${PROJECT_SOURCE_DIR}/MathFunctions"
                                   )
 
-Now let us make the MathFunctions library optional. While for the tutorial
+Now let us make the ``MathFunctions`` library optional. While for the tutorial
 there really isn't any need to do so, for larger projects this is a common
 occurrence. The first step is to add an option to the top-level
 ``CMakeLists.txt`` file.
@@ -53,11 +53,11 @@ occurrence. The first step is to add an option to the top-level
 
 This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
 :manual:`ccmake <ccmake(1)>`
-with a default value of ON that can be changed by the user. This setting will
-be stored in the cache so that the user does not need to set the value each
-time they run CMake on a build directory.
+with a default value of ``ON`` that can be changed by the user. This setting
+will be stored in the cache so that the user does not need to set the value
+each time they run CMake on a build directory.
 
-The next change is to make building and linking the MathFunctions library
+The next change is to make building and linking the ``MathFunctions`` library
 conditional. To do this we change the end of the top-level ``CMakeLists.txt``
 file to look like the following:
 
@@ -92,7 +92,7 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
 ``TutorialConfig.h.in`` with the following line:
 
 .. literalinclude:: Step3/TutorialConfig.h.in
-  :language: c
+  :language: c++
   :lines: 4
 
 **Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
@@ -113,4 +113,4 @@ command-line, try:
 
 Rebuild and run the tutorial again.
 
-Which function gives better results, sqrt or mysqrt?
+Which function gives better results, ``sqrt`` or ``mysqrt``?

Help/guide/tutorial/Installing and Testing.rst

@@ -6,8 +6,8 @@ Now we can start adding install rules and testing support to our project.
 Install Rules
 -------------
 
-The install rules are fairly simple: for MathFunctions we want to install the
-library and header file and for the application we want to install the
+The install rules are fairly simple: for ``MathFunctions`` we want to install
+the library and header file and for the application we want to install the
 executable and configured header.
 
 So to the end of ``MathFunctions/CMakeLists.txt`` we add:

Help/guide/tutorial/Packaging Debug and Release.rst

@@ -28,7 +28,7 @@ And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
   :start-after: # add the executable
   :end-before: # add the binary tree to the search path for include files
 
-Let's also add version numbering to the MathFunctions library. In
+Let's also add version numbering to the ``MathFunctions`` library. In
 ``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and
 :prop_tgt:`SOVERSION` properties:
 

Help/guide/tutorial/Selecting Static or Shared Libraries.rst

@@ -8,12 +8,13 @@ and allow control over how libraries without an explicit type (``STATIC``,
 
 To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the
 top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows
-users to optionally select if the value should be ON or OFF.
+users to optionally select if the value should be ``ON`` or ``OFF``.
 
-Next we are going to refactor MathFunctions to become a real library that
+Next we are going to refactor ``MathFunctions`` to become a real library that
 encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
 code to do this logic. This will also mean that ``USE_MYMATH`` will not control
-building MathFunctions, but instead will control the behavior of this library.
+building ``MathFunctions``, but instead will control the behavior of this
+library.
 
 The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
@@ -22,7 +23,7 @@ The first step is to update the starting section of the top-level
   :language: cmake
   :end-before: # add the binary tree
 
-Now that we have made MathFunctions always be used, we will need to update
+Now that we have made ``MathFunctions`` always be used, we will need to update
 the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to
 create a SqrtLibrary that will conditionally be built and installed when
 ``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to
@@ -45,7 +46,7 @@ uses ``USE_MYMATH``:
 
 #. Always include ``MathFunctions.h``
 #. Always use ``mathfunctions::sqrt``
-#. Don't include cmath
+#. Don't include ``cmath``
 
 Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 
@@ -56,7 +57,7 @@ At this point, if you build everything, you may notice that linking fails
 as we are combining a static library without position independent code with a
 library that has position independent code. The solution to this is to
 explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
-SqrtLibrary to be True no matter the build type.
+SqrtLibrary to be ``True`` no matter the build type.
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
   :language: cmake