docs: sphinx: fix various errors

doc/tutorial/source/building-topologies.rst

@@ -61,13 +61,13 @@ three "extra" nodes as seen below:
 
 ::
 
-// Default Network Topology
-//
-//       10.1.1.0
-// n0 -------------- n1   n2   n3   n4
-//    point-to-point  |    |    |    |
-//                    ================
-//                      LAN 10.1.2.0
+  // Default Network Topology
+  //
+  //       10.1.1.0
+  // n0 -------------- n1   n2   n3   n4
+  //    point-to-point  |    |    |    |
+  //                    ================
+  //                      LAN 10.1.2.0
 
 Then the ns-3 namespace is ``used`` and a logging component is defined.
 This is all just as it was in ``first.cc``, so there is nothing new yet.
@@ -812,14 +812,14 @@ to the wifi module and the mobility module which we will discuss below.
 
 ::
 
-#include "ns3/core-module.h"
-#include "ns3/point-to-point-module.h"
-#include "ns3/network-module.h"
-#include "ns3/applications-module.h"
-#include "ns3/wifi-module.h"
-#include "ns3/mobility-module.h"
-#include "ns3/csma-module.h"
-#include "ns3/internet-module.h"
+  #include "ns3/core-module.h"
+  #include "ns3/point-to-point-module.h"
+  #include "ns3/network-module.h"
+  #include "ns3/applications-module.h"
+  #include "ns3/wifi-module.h"
+  #include "ns3/mobility-module.h"
+  #include "ns3/csma-module.h"
+  #include "ns3/internet-module.h"
 
 The network topology illustration follows:
 
@@ -1367,7 +1367,7 @@ case of the default number of CSMA and wireless nodes, this turns out to be
 node seven and the tracing namespace path to the mobility model would look
 like,
 
-::
+.. sourcecode:: text
 
   /NodeList/7/$ns3::MobilityModel/CourseChange
 
@@ -1513,39 +1513,32 @@ At the device layer, there are device specific queues:
 Changing from the defaults
 ++++++++++++++++++++++++++
 
-* The type of queue used by a NetDevice can be usually modified through the device helper:
+* The type of queue used by a NetDevice can be usually modified through the device helper::
 
-.. sourcecode:: cpp
+    NodeContainer nodes;
+    nodes.Create (2);
 
-  NodeContainer nodes;
-  nodes.Create (2);
+    PointToPointHelper p2p;
+    p2p.SetQueue ("ns3::DropTailQueue", "MaxSize", StringValue ("50p"));
 
-  PointToPointHelper p2p;
-  p2p.SetQueue ("ns3::DropTailQueue", "MaxSize", StringValue ("50p"));
-
-  NetDeviceContainer devices = p2p.Install (nodes);
+    NetDeviceContainer devices = p2p.Install (nodes);
 
 * The type of queue disc installed on a NetDevice can be modified through the
-  traffic control helper
-
-.. sourcecode:: cpp
+  traffic control helper::
 
-  InternetStackHelper stack;
-  stack.Install (nodes);
-
-  TrafficControlHelper tch;
-  tch.SetRootQueueDisc ("ns3::CoDelQueueDisc", "MaxSize", StringValue ("1000p"));
-  tch.Install (devices);
+    InternetStackHelper stack;
+    stack.Install (nodes);
 
-* BQL can be enabled on a device that supports it through the traffic control helper
+    TrafficControlHelper tch;
+    tch.SetRootQueueDisc ("ns3::CoDelQueueDisc", "MaxSize", StringValue ("1000p"));
+    tch.Install (devices);
 
-.. sourcecode:: cpp
-
-  InternetStackHelper stack;
-  stack.Install (nodes);
+* BQL can be enabled on a device that supports it through the traffic control helper::
 
-  TrafficControlHelper tch;
-  tch.SetRootQueueDisc ("ns3::CoDelQueueDisc", "MaxSize", StringValue ("1000p"));
-  tch.SetQueueLimits ("ns3::DynamicQueueLimits", "HoldTime", StringValue ("4ms"));
-  tch.Install (devices);
+    InternetStackHelper stack;
+    stack.Install (nodes);
 
+    TrafficControlHelper tch;
+    tch.SetRootQueueDisc ("ns3::CoDelQueueDisc", "MaxSize", StringValue ("1000p"));
+    tch.SetQueueLimits ("ns3::DynamicQueueLimits", "HoldTime", StringValue ("4ms"));
+    tch.Install (devices);

doc/tutorial/source/data-collection.rst

@@ -101,7 +101,7 @@ Now back to data collection.  In the ``examples/tutorial/`` directory,
 type the following command: ``diff -u sixth.cc seventh.cc``, and examine
 some of the new lines of this diff:
 
-::
+.. sourcecode:: diff
 
   +  std::string probeType;
   +  std::string tracePath;
@@ -222,7 +222,7 @@ The PNG image title states that this plot is a plot of
 "Packet Byte Count vs. Time", and that it is plotting the probed data
 corresponding to the trace source path:
 
-::
+.. sourcecode:: text
 
   /NodeList/*/$ns3::Ipv6L3Protocol/Tx
 

doc/tutorial/source/getting-started.rst

@@ -100,9 +100,7 @@ get a copy of a release by typing the following into your Linux shell
   $ tar xjf ns-allinone-3.28.tar.bz2
 
 If you change into the directory ``ns-allinone-3.28`` you should see a
-number of files and directories:
-
-::
+number of files and directories::
 
   $ ls
   bake      constants.py   ns-3.28                            README
@@ -138,9 +136,7 @@ following into your Linux shell (assuming you have installed Mercurial)::
   $ hg clone http://code.nsnam.org/bake
 
 As the hg (Mercurial) command executes, you should see something like the 
-following displayed,
-
-::
+following displayed::
 
   ...
   destination directory: bake
@@ -198,9 +194,7 @@ by referencing the binary, but if one chooses to run bake from
 outside of the directory it was downloaded into, it is advisable
 to put bake into your path, such as follows (Linux bash shell example).
 First, change into the 'bake' directory, and then set the following
-environment variables
-
-::
+environment variables::
 
   $ export BAKE_HOME=`pwd`
   $ export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin
@@ -220,9 +214,7 @@ various components.  Type::
 
   $ ./bake.py check
 
-You should see something like the following,
-
-::
+You should see something like the following::
 
    > Python - OK
    > GNU C++ compiler - OK
@@ -315,7 +307,7 @@ You will see lots of typical compiler output messages displayed as the build
 script builds the various pieces you downloaded.  Eventually you should see the
 following::
 
-   Waf: Leaving directory `/path/to/workspace/ns-allinone-3.28/ns-3.28/build'
+   Waf: Leaving directory '/path/to/workspace/ns-allinone-3.28/ns-3.28/build'
    'build' finished successfully (6m25.032s)
   
    Modules built:
@@ -361,19 +353,15 @@ that a compiler warning will cause the build to fail.
 
 For instance, ns-3.28 was released prior to Fedora 28, which included
 a new major version of gcc (gcc-8).  Building ns-3.28 or older releases
-on Fedora 28, when Gtk2+ is installed, will result in an error such as:
-
-::
+on Fedora 28, when Gtk2+ is installed, will result in an error such as::
 
   /usr/include/gtk-2.0/gtk/gtkfilechooserbutton.h:59:8: error: unnecessary parentheses in declaration of ‘__gtk_reserved1’ [-Werror=parentheses]
    void (*__gtk_reserved1);
 
 In releases starting with ns-3.28.1, an option is available in Waf to work
 around these issues.  The option disables the inclusion of the '-Werror' 
 flag to g++ and clang++.  The option is '--disable-werror' and must be
-used at configure time; e.g.:
-
-::
+used at configure time; e.g.::
 
   ./waf configure --disable-werror --enable-examples --enable-tests
 
@@ -560,15 +548,13 @@ A command exists for checking which profile is currently active
 for an already configured project::
 
   $ ./waf --check-profile
-  Waf: Entering directory \`/path/to/ns-3-allinone/ns-3.28/build'
+  Waf: Entering directory \`/path/to/ns-3-allinone/ns-3.28/build\'
   Build profile: debug
 
 The build.py script discussed above supports also the ``--enable-examples``
 and ``enable-tests`` arguments, but in general, does not directly support
 other waf options; for example, this will not work:
 
-::
-
   $ ./build.py --disable-python
 
 will result in
@@ -578,9 +564,7 @@ will result in
   build.py: error: no such option: --disable-python
 
 However, the special operator ``--`` can be used to pass additional
-options through to waf, so instead of the above, the following will work:
-
-::
+options through to waf, so instead of the above, the following will work::
 
   $ ./build.py -- --disable-python   
 
@@ -738,9 +722,7 @@ environment.  So when installing libraries to the system, it is good
 practice to check that the intended libraries are being used.
 
 Users may choose to install to a different prefix by passing the ``--prefix``
-option at configure time, such as:
-
-::
+option at configure time, such as::
 
   ./waf configure --prefix=/opt/local
 

doc/tutorial/source/tracing.rst

@@ -672,7 +672,9 @@ interest was the code that provided the Config path.  Therefore, the
 be the only Callback called.
 
 The final piece of the puzzle is the "context".  Recall that we saw an
-output looking something like the following from ``third.cc``::
+output looking something like the following from ``third.cc``:
+
+.. sourcecode:: text
 
   /NodeList/7/$ns3::MobilityModel/CourseChange x = 7.27897, y =
   2.22677
@@ -2739,11 +2741,11 @@ but to summarize ...
     helper.EnableAscii ("prefix", "client/eth0");
     helper.EnableAscii ("prefix", "server/eth0");
 
-    This would result in two files named ``prefix-client-eth0.tr`` and
-    ``prefix-server-eth0.tr`` with traces for each device in the
-    respective trace file.  Since all of the ``EnableAscii`` functions
-    are overloaded to take a stream wrapper, you can use that form as
-    well::
+  This would result in two files named ``prefix-client-eth0.tr`` and
+  ``prefix-server-eth0.tr`` with traces for each device in the
+  respective trace file.  Since all of the ``EnableAscii`` functions
+  are overloaded to take a stream wrapper, you can use that form as
+  well::
 
     Names::Add ("client" ...);
     Names::Add ("client/eth0" ...);
@@ -2773,10 +2775,10 @@ but to summarize ...
     ...
     helper.EnableAscii ("prefix", d);
 
-    This would result in a number of ASCII trace files being created,
-    each of which follows the ``<prefix>-<node id>-<device id>.tr``
-    convention.
-
+  This would result in a number of ASCII trace files being created,
+  each of which follows the ``<prefix>-<node id>-<device id>.tr``
+  convention.
+  
   Combining all of the traces into a single file is accomplished
   similarly to the examples above::
 

src/applications/doc/applications.rst

@@ -108,12 +108,14 @@ In summary, the application works as follows.
 4. The parsing takes a short time (randomly determined) to determine the
    number of *embedded objects* (also randomly determined) in the web page. 
    Number of embedded object is illustrated in :ref:`fig-http-num-of-embedded-objects`.
-    - If at least one embedded object is determined, the application requests
-      the first embedded object from the server. The request for the next
-      embedded object follows after the previous embedded object has been
-      completely received.
-    - If there is no more embedded object to request, the application enters
-      the *reading time*.
+
+    * If at least one embedded object is determined, the application requests
+       the first embedded object from the server. The request for the next
+       embedded object follows after the previous embedded object has been
+       completely received.
+    * If there is no more embedded object to request, the application enters
+       the *reading time*.
+
 5. Reading time is a long delay (again, randomly determined) where the
    application does not induce any network traffic, thus simulating the user
    reading the downloaded web page.

src/traffic-control/doc/prio.rst

@@ -37,9 +37,7 @@ Examples
 ========
 
 An example of how to configure PrioQueueDisc with custom child queue discs and priomap
-is provided by `queue-discs-benchmark.cc` located in ``examples/traffic-control``:
-
-.. sourcecode:: cpp
+is provided by `queue-discs-benchmark.cc` located in ``examples/traffic-control``::
 
   TrafficControlHelper tch;
   uint16_t handle = tch.SetRootQueueDisc ("ns3::PrioQueueDisc", "Priomap", StringValue ("0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1"));
@@ -63,14 +61,14 @@ ii) packets are dequeued in the correct order.
 
 The test suite can be run using the following commands:
 
-::
+.. sourcecode:: bash
 
   $ ./waf configure --enable-examples --enable-tests
   $ ./waf build
   $ ./test.py -s prio-queue-disc
 
 or
 
-::
+.. sourcecode:: bash
 
   $ NS_LOG="PrioQueueDisc" ./waf --run "test-runner --suite=prio-queue-disc"

src/traffic-control/doc/tbf.rst

@@ -81,7 +81,7 @@ References
 
 .. [Ref1] A. Kuznetsov and D. Torokhov; Linux Cross Reference Source Code; Available online at `<http://lxr.free-electrons.com/source/net/sched/sch_tbf.c>`_.
 
-.. [Ref2] J. Vehent; Journey to the Center of the Linux Kernel: Traffic Control, Shaping and QoS; Available online at `<http://wiki.linuxwall.info/doku.php/en:resources:dossiers:networking:traffic_control#tbf\_-_token_bucket_filter>`_.
+.. [Ref2] J. Vehent; Journey to the Center of the Linux Kernel: Traffic Control, Shaping and QoS; Available online at `<http://wiki.linuxwall.info/doku.php/en:resources:dossiers:networking:traffic_control#tbf_-_token_bucket_filter>`_.
 
 .. [Ref3] Practical IP Network QoS: TBF queuing discipline; Available online at `<http://web.opalsoft.net/qos/default.php?p=ds-24>`_.