fix some tutorial nits
authorCraig Dowell <craigdo@ee.washington.edu>
Wed, 25 Mar 2009 09:34:39 -0700
changeset 4295 6f7c05fd0f9b
parent 4294 ebb973fdb763
child 4296 0ef6dfed1dbd
fix some tutorial nits
doc/tutorial/building-topologies.texi
doc/tutorial/conceptual-overview.texi
doc/tutorial/getting-started.texi
doc/tutorial/tweaking.texi
--- a/doc/tutorial/building-topologies.texi	Tue Mar 24 17:53:30 2009 -0700
+++ b/doc/tutorial/building-topologies.texi	Wed Mar 25 09:34:39 2009 -0700
@@ -158,9 +158,9 @@
 number nodes you desire in the CSMA section minus one.
 
 The next bit of code should be quite familiar by now.  We instantiate a
-@code{PointToPointHelper} and set the associated default attributes so that
-we create a five megabit per second transmitter on devices created using the
-helper and a two millisecond delay on channels created by the helper.
+@code{PointToPointHelper} and set the associated default @code{Attributes} so
+that we create a five megabit per second transmitter on devices created using
+the helper and a two millisecond delay on channels created by the helper.
 
 @verbatim
   PointToPointHelper pointToPoint;
@@ -179,13 +179,13 @@
 channels, and the next lines introduce them.  The @code{CsmaHelper} works just
 like a @code{PointToPointHelper}, but it creates and connects CSMA devices and
 channels.  In the case of a CSMA device and channel pair, notice that the data
-rate is specified by a @emph{channel} attribute instead of a device attribute.
-This is because a real CSMA network does not allow one to mix, for example, 
-10Base-T and 100Base-T devices on a given channel.  We first set the data rate
-to 100 megabits per second, and then set the speed-of-light delay of the channel
-to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot over a 100
-meter segment).  Notice that you can set an attribute using its native data 
-type.
+rate is specified by a @emph{channel} @code{Attribute} instead of a device 
+@code{Attribute}.  This is because a real CSMA network does not allow one to mix,
+for example, 10Base-T and 100Base-T devices on a given channel.  We first set 
+the data rate to 100 megabits per second, and then set the speed-of-light delay
+of the channel to 6560 nano-seconds (arbitrarily chosen as 1 nanosecond per foot
+over a 100 meter segment).  Notice that you can set an @code{Attribute} using 
+its native data type.
 
 @verbatim
   CsmaHelper csma;
@@ -252,8 +252,8 @@
 point-to-point device.
 
 First, we set up the echo server.  We create a @code{UdpEchoServerHelper} and
-provide a required attribute value to the constructor which is the server port
-number.  Recall that this port can be changed later using the 
+provide a required @code{Attribute} value to the constructor which is the server
+port number.  Recall that this port can be changed later using the 
 @code{SetAttribute} method if desired, but we require it to be provided to
 the constructor.
 
@@ -276,7 +276,7 @@
 code.
 
 The client application is set up exactly as we did in the @code{first.cc}
-example script.  Again, we provide required attributes to the 
+example script.  Again, we provide required @code{Attributes} to the 
 @code{UdpEchoClientHelper} in the constructor (in this case the remote address
 and port).  We tell the client to send packets to the server we just installed
 on the last of the ``extra'' CSMA nodes.  We install the client on the 
@@ -780,8 +780,8 @@
 @end verbatim
 
 Next, we see an old friend.  We instantiate a @code{PointToPointHelper} and 
-set the associated default attributes so that we create a five megabit per 
-second transmitter on devices created using the helper and a two millisecond 
+set the associated default @code{Attributes} so that we create a five megabit 
+per second transmitter on devices created using the helper and a two millisecond 
 delay on channels created by the helper.  We then @code{Intall} the devices
 on the nodes and the channel between them.
 
@@ -809,8 +809,8 @@
 point-to-point device and a CSMA device.  We then create a number of ``extra''
 nodes that compose the remainder of the CSMA network.
 
-We then instantiate a @code{CsmaHelper} and set its attributes as we did in
-the previous example.  We create a @code{NetDeviceContainer} to keep track of
+We then instantiate a @code{CsmaHelper} and set its @code{Attributes} as we did
+in the previous example.  We create a @code{NetDeviceContainer} to keep track of
 the created CSMA net devices and then we @code{Install} CSMA devices on the 
 selected nodes.
 
@@ -882,8 +882,8 @@
 layer implementation.  The particular kind of MAC layer is specified by
 @code{Attribute} as being of the "ns3::NqstaWifiMac" type.  This means that 
 the MAC will use a ``non-QoS station'' (nqsta) state machine.  Finally, the 
-``ActiveProbing'' attribute is set to false.  This means that probe requests
-will not be sent by MACs created by this helper.
+``ActiveProbing'' @code{Attribute} is set to false.  This means that probe
+requests will not be sent by MACs created by this helper.
 
 Once all the station-specific parameters are fully configured, both at the
 MAC and PHY layers, we can invoke our now-familiar @code{Install} method to 
@@ -908,11 +908,11 @@
 
 In this case, the @code{WifiHelper} is going to create MAC layers of the 
 ``ns3::NqapWifiMac'' (Non-Qos Access Point) type.  We set the 
-``BeaconGeneration'' attribute to true and also set an interval between 
+``BeaconGeneration'' @code{Attribute} to true and also set an interval between 
 beacons of 2.5 seconds.
 
 The next lines create the single AP which shares the same set of PHY-level
-attributes (and channel) as the stations:
+@code{Attributes} (and channel) as the stations:
 
 @verbatim
   NetDeviceContainer apDevices;
@@ -922,8 +922,8 @@
 Now, we are going to add mobility models.  We want the STA nodes to be mobile,
 wandering around inside a bounding box, and we want to make the AP node 
 stationary.  We use the @code{MobilityHelper} to make this easy for us.
-First, we instantiate a @code{MobilityHelper} object and set some attributes
-controlling the ``position allocator'' functionality.
+First, we instantiate a @code{MobilityHelper} object and set some 
+@code{Attributes} controlling the ``position allocator'' functionality.
 
 @verbatim
   MobilityHelper mobility;
@@ -1329,7 +1329,8 @@
 sources.''  You may find it interesting to try and hook some of these 
 traces yourself.  Additionally in the ``Modules'' documentation, there is
 a link to ``The list of all attributes.''  You can set the default value of 
-any of these attributes via the command line as we have previously discussed.
+any of these @code{Attributes} via the command line as we have previously 
+discussed.
 
 We have just scratched the surface of @command{ns-3} in this tutorial, but we 
 hope we have covered enough to get you started doing useful work.
--- a/doc/tutorial/conceptual-overview.texi	Tue Mar 24 17:53:30 2009 -0700
+++ b/doc/tutorial/conceptual-overview.texi	Wed Mar 25 09:34:39 2009 -0700
@@ -446,12 +446,12 @@
 If you look at the Doxygen for class @code{ns3::PointToPointNetDevice} and 
 find the documentation for the @code{GetTypeId} method, you will find a list
 of  @code{Attributes} defined for the device.  Among these is the ``DataRate''
-attribute.  Most user-visible @command{ns-3} objects have similar lists of 
-attributes.  We use this mechanism to easily configure simulations without
+@code{Attribute}.  Most user-visible @command{ns-3} objects have similar lists of 
+@code{Attributes}.  We use this mechanism to easily configure simulations without
 recompiling as you will see in a following section.
 
 Similar to the ``DataRate'' on the @code{PointToPointNetDevice} you will find a
-``Delay'' attribute associated with the @code{PointToPointChannel}.  The 
+``Delay'' @code{Attribute} associated with the @code{PointToPointChannel}.  The 
 final line,
 
 @verbatim
@@ -487,8 +487,9 @@
 two for a point-to-point link) a @code{PointToPointNetDevice} is created and 
 saved in the device container.  A @code{PointToPointChannel} is created and 
 the two @code{PointToPointNetDevices} are attached.  When objects are created
-by the @code{PointToPointHelper}, the attributes previously set in the helper
-are used to initialize the corresponding attributes in the created objects.
+by the @code{PointToPointHelper}, the @code{Attributes} previously set in the 
+helper are used to initialize the corresponding @code{Attributes} in the 
+created objects.
 
 After executing the @code{pointToPoint.Install (nodes)} call we will have
 two nodes, each with an installed point-to-point net device and a 
@@ -575,13 +576,13 @@
 The first line of code in the above snippet declares the 
 @code{UdpEchoServerHelper}.  As usual, this isn't the application itself, it
 is an object used to help us create the actual applications.  One of our 
-conventions is to place required attributes in the helper constructor.  In this
-case, the helper can't do anything useful unless it is provided with a port
-number that the client also knows about.  Rather than just picking one and
-hoping it all works out, we require the port number as a parameter to the 
+conventions is to place required @code{Attributes} in the helper constructor.
+In this case, the helper can't do anything useful unless it is provided with
+a port number that the client also knows about.  Rather than just picking one 
+and hoping it all works out, we require the port number as a parameter to the 
 constructor.  The constructor, in turn, simply does a @code{SetAttribute}
-with the passed value.  You can, if desired, set the ``Port'' attribute to
-another value later.
+with the passed value.  You can, if desired, set the ``Port'' @code{Attribute}
+to another value later.
 
 Similar to many other helper objects, the @code{UdpEchoServerHelper} object 
 has an @code{Install} method.  It is the execution of this method that actually
@@ -634,12 +635,12 @@
     clientApps.Stop (Seconds (10.0));
 @end verbatim
 
-For the echo client, however, we need to set five different attributes.  The 
-first two attributes are set during construction of the 
+For the echo client, however, we need to set five different @code{Attributes}.
+The first two @code{Attributes} are set during construction of the 
 @code{UdpEchoClientHelper}.  We pass parameters that are used (internally to
-the helper) to set the ``RemoteAddress'' and ``RemotePort'' attributes in
-accordance with our convention to make required attributes parameters in the 
-helper constructors.  
+the helper) to set the ``RemoteAddress'' and ``RemotePort'' @code{Attributes}
+in accordance with our convention to make required @code{Attributes} parameters
+in the helper constructors.  
 
 Recall that we used an @code{Ipv4InterfaceContainer} to keep track of the IP 
 addresses we assigned to our devices.  The zeroth interface in the 
@@ -651,12 +652,12 @@
 to be  the IP address assigned to the node on which the server resides.  We 
 also tell it to arrange to send packets to port nine.
 
-The ``MaxPackets'' attribute tells the client the maximum number of packets 
-we allow it to send during the simulation.  The ``Interval'' attribute tells
-the client how long to wait between packets, and the ``PacketSize'' attribute
-tells the client how large its packet payloads should be.  With this 
-particular combination of attributes, we are telling the client to send one 
-1024-byte packet.
+The ``MaxPackets'' @code{Attribute} tells the client the maximum number of 
+packets we allow it to send during the simulation.  The ``Interval'' 
+@code{Attribute} tells the client how long to wait between packets, and the
+``PacketSize'' @code{Attribute} tells the client how large its packet payloads
+should be.  With this particular combination of @code{Attributes}, we are 
+telling the client to send one 1024-byte packet.
 
 Just as in the case of the echo server, we tell the echo client to @code{Start}
 and @code{Stop}, but here we start the client one second after the server is
--- a/doc/tutorial/getting-started.texi	Tue Mar 24 17:53:30 2009 -0700
+++ b/doc/tutorial/getting-started.texi	Wed Mar 25 09:34:39 2009 -0700
@@ -411,7 +411,7 @@
 feature was not enabled.  There is a feature to use sudo to set the suid bit of
 certain programs.  This was not enabled by default.
 
-Now go ahead and switch back to the debug build:
+Now go ahead and switch back to the debug build.
 
 @verbatim
   ./waf -d debug configure
@@ -424,6 +424,26 @@
   ./waf
 @end verbatim
 
+Some waf commands are meaningful during the build phase and some commands are valid
+in the configuration phase.  For example, if you wanted to use the emulation 
+features of @command{ns-3} you might want to enable setting the suid bit using
+sudo.  This is a configuration command, and so you could have run the following
+command
+
+@verbatim
+  ./waf -d debug --enable-sudo configure
+@end verbatim
+
+If you had done this, waf would have run sudo to change the socket creator 
+programs to run as root.  There are many other configure- and build-time options
+available in waf.  To explore these options, type:
+
+@verbatim
+  ./waf -- help
+@end verbatim
+
+We'll use some of the testing-related commands in the next section.
+
 Okay, sorry, I made you build the @command{ns-3} part of the system twice,
 but now you know how to change the configuration and build optimized code.
 
@@ -518,7 +538,7 @@
 
 @verbatim
   cd build/debug/regression/traces/second.ref
-  tcpdump -nn -tt -r second-1-1.pcap
+  tcpdump -nn -tt -r second-2-0.pcap
 @end verbatim
 
 The output should be clear to anyone who is familiar with tcpdump or net
--- a/doc/tutorial/tweaking.texi	Tue Mar 24 17:53:30 2009 -0700
+++ b/doc/tutorial/tweaking.texi	Wed Mar 25 09:34:39 2009 -0700
@@ -93,7 +93,7 @@
 
 @verbatim
   ./waf --run scratch/myfirst
-@end verbtim
+@end verbatim
 
 You should see the now familiar output of the first @command{ns-3} example
 program
@@ -438,10 +438,10 @@
 @end verbatim
 
 This simple two line snippet is actually very useful by itself.  It opens the
-door to the @command{ns-3} global variable and attribute systems.  Go ahead 
-and add that two lines of code to the @code{scratch/first.cc} script at the 
-start of @code{main}.  Go ahead and build the script and run it, but ask the script 
-for help in the following way,
+door to the @command{ns-3} global variable and @code{Attribute} systems.  Go 
+ahead and add that two lines of code to the @code{scratch/first.cc} script at
+the start of @code{main}.  Go ahead and build the script and run it, but ask 
+the script for help in the following way,
 
 @verbatim
   ./waf --run "scratch/myfirst --PrintHelp"
@@ -464,7 +464,7 @@
 @end verbatim
 
 Let's focus on the @code{--PrintAttributes} option.  We have already hinted
-at the @command{ns-3} attribute system while walking through the 
+at the @command{ns-3} @code{Attribute} system while walking through the 
 @code{first.cc} script.  We looked at the following lines of code,
 
 @verbatim
@@ -475,17 +475,17 @@
 
 and mentioned that @code{DataRate} was actually an @code{Attribute} of the 
 @code{PointToPointNetDevice}.  Let's use the command line argument parser
-to take a look at the attributes of the PointToPointNetDevice.  The help
+to take a look at the @code{Attributes} of the PointToPointNetDevice.  The help
 listing says that we should provide a @code{TypeId}.  This corresponds to the
-class name of the class to which the attributes belong.  In this case it will
-be @code{ns3::PointToPointNetDevice}.  Let's go ahead and type in,
+class name of the class to which the @code{Attributes} belong.  In this case it
+will be @code{ns3::PointToPointNetDevice}.  Let's go ahead and type in,
 
 @verbatim
   ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointNetDevice"
 @end verbatim
 
-The system will print out all of the attributes of this kind of net device.
-Among the attributes you will see listed is,
+The system will print out all of the @code{Attributes} of this kind of net device.
+Among the @code{Attributes} you will see listed is,
 
 @verbatim
   --ns3::PointToPointNetDevice::DataRate=[32768bps]:
@@ -493,7 +493,7 @@
 @end verbatim
 
 This is the default value that will be used when a @code{PointToPointNetDevice}
-is created in the system.  We overrode this default with the attribute
+is created in the system.  We overrode this default with the @code{Attribute}
 setting in the @code{PointToPointHelper} above.  Let's use the default values 
 for the point-to-point devices and channels by deleting the 
 @code{SetDeviceAttribute} call and the @code{SetChannelAttribute} call from 
@@ -558,7 +558,7 @@
   ./waf --run "scratch/myfirst --ns3::PointToPointNetDevice::DataRate=5Mbps"
 @end verbatim
 
-This will set the default value of the @code{DataRate} attribute back to 
+This will set the default value of the @code{DataRate} @code{Attribute} back to 
 five megabits per second.  Are you surprised by the result?  It turns out that
 in order to get the original behavior of the script back, we will have to set 
 the speed-of-light delay of the channel as well.  We can ask the command line 
@@ -569,7 +569,7 @@
   ./waf --run "scratch/myfirst --PrintAttributes=ns3::PointToPointChannel"
 @end verbatim
 
-We discover the @code{Delay} attribute of the channel is set in the following
+We discover the @code{Delay} @code{Attribute} of the channel is set in the following
 way:
 
 @verbatim
@@ -603,12 +603,12 @@
 @end verbatim
 
 Note that the packet is again received by the server at 2.00369 seconds.  We 
-could actually set any of the attributes used in the script in this way.  In
-particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} 
+could actually set any of the @code{Attributes} used in the script in this way.
+In particular we could set the @code{UdpEchoClient Attribute MaxPackets} 
 to some other value than one.
 
 How would you go about that?  Give it a try.  Remember you have to comment 
-out the place we override the default attribute in the script.  Then you 
+out the place we override the default @code{Attribute} in the script.  Then you 
 have to rebuild the script using the default.  You will also have to find the
 syntax for actually setting the new default atribute value using the command
 line help facility.  Once you have this figured out you should be able to
@@ -649,11 +649,11 @@
 @end verbatim
 
 Scroll down to the point in the script where we set the @code{MaxPackets}
-attribute and change it so that it is set to the variable @code{nPackets}
+@code{Attribute} and change it so that it is set to the variable @code{nPackets}
 instead of the constant @code{1} as is shown below.
 
 @verbatim
-  echoClient.SetAppAttribute ("MaxPackets", UintegerValue (nPackets));
+  echoClient.SetAttribute ("MaxPackets", UintegerValue (nPackets));
 @end verbatim
 
 Now if you run the script and provide the @code{--PrintHelp} argument, you 
@@ -708,11 +708,11 @@
 You have now echoed two packets.
 
 You can see that if you are an @command{ns-3} user, you can use the command 
-line argument system to control global values and attributes.  If you are a 
-model author, you can add new attributes to your Objects and they will 
-automatically be available for setting by your users through the command line
-system.  If you are a script author, you can add new variables to your scripts
-and hook them into the command line system quite painlessly.
+line argument system to control global values and @code{Attributes}.  If you are
+a model author, you can add new @code{Attributes} to your @code{Objects} and 
+they will automatically be available for setting by your users through the
+command line system.  If you are a script author, you can add new variables to 
+your scripts and hook them into the command line system quite painlessly.
 
 @c ========================================================================
 @c Using the Tracing System
@@ -927,7 +927,7 @@
 @verbatim
   00 r 
   01 2.25732 
-  02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/Rx 
+  02 /NodeList/1/DeviceList/0/$ns3::PointToPointNetDevice/MacRx 
   03 ns3::PppHeader (
   04   Point-to-Point Protocol: IP (0x0021)) 
   05   ns3::Ipv4Header (