formatting cleanup

doc/manual/source/attributes.rst

@@ -686,12 +686,10 @@ and ::
 
     ./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml
     --ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge
-    @end example
-    @end smallformat
-    After running, you can open the csma-bridge-config.xml file and it will
-    display the configuration that was applied to your simulation; e.g.
-    @smallformat
-    @example
+
+After running, you can open the csma-bridge-config.xml file and it will
+display the configuration that was applied to your simulation; e.g.::
+
     <?xml version="1.0" encoding="UTF-8"?>
     <ns3>
      <default name="ns3::V4Ping::Remote" value="102.102.102.102"/>

doc/manual/source/csma.rst

@@ -96,7 +96,7 @@ PHY characteristics.
 The CsmaChannel has three states, ``IDLE``, ``TRANSMITTING`` and
 ``PROPAGATING``. These three states are "seen" instantaneously by all devices on
 the channel. By this we mean that if one device begins or ends a simulated
-transmission, all devices on the channel are @emph{immediately} aware of the
+transmission, all devices on the channel are *immediately* aware of the
 change in state. There is no time during which one device may see an ``IDLE``
 channel while another device physically further away in the collision domain may
 have begun transmitting with the associated signals not propagated down the

doc/manual/source/new-models.rst

@@ -514,7 +514,7 @@ The trivial base class ErrorModel does not do anything interesting, but it
 provides a useful base class interface (Corrupt () and Reset ()), forwarded to
 virtual functions that can be subclassed. Let's next consider what we call a
 BasicErrorModel which is based on the |ns2| ErrorModel class (in
-ns-2/queue/errmodel.@{cc,h@}).
+``ns-2/queue/errmodel.{cc,h}``).
 
 What properties do we want this to have, from a user interface perspective? We
 would like for the user to be able to trivially swap out the type of ErrorModel

doc/manual/source/organization.rst

@@ -4,8 +4,7 @@
 Organization
 ------------
 
-This manual is organized into several parts with several chapters per part.
-This chapter describes the overall software organization and the
+This chapter describes the overall |ns3| software organization and the
 corresponding organization of this manual.
 
 |ns3| is a discrete-event network simulator in which the simulation core
@@ -13,7 +12,7 @@ and models are implemented in C++. |ns3| is built as a library which may be
 statically or dynamically linked to a C++ main program that defines the
 simulation topology and starts the simulator. |ns3| also exports nearly all
 of its API to Python, allowing Python programs to import an "ns3" module in
-much the same way as in C++.  
+much the same way as the |ns3| library is linked by executables in C++.  
 
 .. _software-organization:
 
@@ -26,31 +25,36 @@ can be described by the diagram in :ref:`software-organization`. We will
 work our way from the bottom up; in general, modules only have dependencies
 on modules beneath them in the figure.
 
-We first describe Part 1 of the manual. The simulation core is implemented
+We first describe the core of the simulator; those components that are 
+common across all protocol, hardware, and environmental models. 
+The simulation core is implemented
 in ``src/core``, and the core is used to build the simulation engine
 ``src/simulator``. Packets are fundamental objects in a network simulator
-and are implemented in ``src/packet``. These three simulation modules by
+and are implemented in ``src/common``. These three simulation modules by
 themselves are intended to comprise a generic simulation core that can be
 used by different kinds of networks, not just Internet-based networks.  The
 above modules of |ns3| are independent of specific network and device
-models, which are covered in later parts of this manual.
+models, which are covered in subsequent parts of this manual.
 
-In addition to the above |ns3| core, we describe also in Part 1 two other
-modules that supplement the core C++-based API. |ns3| programs may access
+In addition to the above |ns3| core, we introduce, also in the initial 
+portion of the manual, two other modules that supplement the core C++-based 
+API.  |ns3| programs may access
 all of the API directly or may make use of a so-called *helper API* that
 provides convenient wrappers or encapsulation of low-level API calls. The
 fact that |ns3| programs can be written to two APIs (or a combination
-thereof) is a fundamental aspect of the simulator and is also covered in
-Part 1.  We also describe how Python is supported in |ns3| as the last
-chapter of Part 1. 
+thereof) is a fundamental aspect of the simulator.
+We also describe how Python is supported in |ns3| before moving onto
+specific models of relevance to network simulation.
 
 The remainder of the manual is focused on documenting the models and
-supporting capabilities.  Part 2 focuses on two fundamental objects in
+supporting capabilities.  The next part focuses on two fundamental objects in
 |ns3|:  the ``Node`` and ``NetDevice``. Two special NetDevice types are
 designed to support network emulation use cases, and emulation is described
-in Part 3. Part 4 is devoted to Internet-related models, including the
-sockets API used by Internet applications. Part 5 covers applications, and
-Part 6 describes additional support for simulation, such as animators.
+next.  The following chapter is devoted to Internet-related models, 
+including the
+sockets API used by Internet applications. The next chapter covers 
+applications, and the following chapter describes additional support for 
+simulation, such as animators and statistics.
 
 The project maintains a separate manual devoted to testing and validation
 of |ns3| code (see the `ns-3 Testing and Validation manual

doc/manual/source/packets.rst

@@ -134,7 +134,7 @@ virtual methods listed below:
 
 Basically, the first three functions are used to serialize and deserialize
 protocol control information to/from a Buffer. For example, one may define
-@code{class TCPHeader : public Header}. The TCPHeader object will typically
+``class TCPHeader : public Header``. The TCPHeader object will typically
 consist of some private data (like a sequence number) and public interface
 access functions (such as checking the bounds of an input). But the underlying
 representation of the TCPHeader in a Packet Buffer is 20 serialized bytes (plus

doc/manual/source/realtime.rst

@@ -73,8 +73,8 @@ Implementation
 
 The implementation is contained in the following files:
 
-* ``src/simulator/realtime-simulator-impl.@{cc,h@}``
-* ``src/simulator/wall-clock-synchronizer.@{cc,h@}``
+* ``src/simulator/realtime-simulator-impl.{cc,h}``
+* ``src/simulator/wall-clock-synchronizer.{cc,h}``
 
 In order to create a realtime scheduler, to a first approximation you just want
 to cause simulation time jumps to consume real time. We propose doing this using

doc/manual/source/tcp.rst

@@ -15,7 +15,7 @@ user code can swap out implementations with minimal changes to the scripts.
 There are two important abstract base classes:
 
 * class :cpp:class:`TcpSocket`:  This is defined in
-  ``src/node/tcp-socket.@{cc,h@}``. This class exists for hosting TcpSocket
+  ``src/node/tcp-socket.{cc,h}``. This class exists for hosting TcpSocket
   attributes that can be reused across different implementations. For instance,
   ``TcpSocket::SetInitialCwnd()`` can be used for any of the implementations
   that derive from class :cpp:class:`TcpSocket`.

doc/manual/source/wifi.rst

@@ -312,14 +312,14 @@ successfully received or not: a random number is drawn from a uniform
 distribution and is compared against the probability of error.
 
 To evaluate the probability of error, we start from the piecewise linear 
-functions shown in Figure @ref{fig:snir} and calculate the 
+functions shown in Figure :ref:`snir` and calculate the 
 SNIR function. 
 
 .. _snir:
 
 .. figure:: figures/snir.*
    
-   SNIR function over time.
+   *SNIR function over time.*
 
 From the SNIR function we can derive bit error rates for BPSK and QAM
 modulations.  Then, for each interval l where BER is constant, we define the

doc/manual/source/wimax.rst

@@ -239,7 +239,8 @@ appropriate WiMAX connection. Class :cpp:class:`IpcsClassifier` and class
 :cpp:class:`IpcsClassifierRecord` implement the classifier module for both SS
 and BS
  
-@subsection MAC Common Part Sublayer
+MAC Common Part Sublayer
+++++++++++++++++++++++++
  
 The MAC Common Part Sublayer (CPS) is the main sublayer of the IEEE 802.16 MAC
 and performs the fundamental functions of the MAC. The module implements the