From d5423b88a2ebb27a38d21e0a18ca0c6c713262bb Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Sun, 29 Jun 2008 14:20:40 -0700 Subject: [PATCH 1/4] Table of content fixes --- doc/tutorial/conceptual-overview.texi | 4 ++-- doc/tutorial/tutorial.texi | 13 +++++++++---- doc/tutorial/tweaking.texi | 14 +++++++------- 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/doc/tutorial/conceptual-overview.texi b/doc/tutorial/conceptual-overview.texi index 10130f322..cf88d60ce 100644 --- a/doc/tutorial/conceptual-overview.texi +++ b/doc/tutorial/conceptual-overview.texi @@ -11,7 +11,7 @@ @c ======================================================================== @c Some Conceptual Overview @c ======================================================================== -@node Conceptual Overveiw +@node Conceptual Overview @chapter Conceptual Overview @menu @@ -167,7 +167,7 @@ to compose those distinct operations into an easy to use model. @c A First ns-3 script @c ======================================================================== @node A First ns-3 Script -@chapter A First ns-3 script +@chapter A First ns-3 Script @cindex first script If you downloaded the system as was suggested above, you will have a release of ns-3 in a directory called @code{repos} under your home directory. Change diff --git a/doc/tutorial/tutorial.texi b/doc/tutorial/tutorial.texi index 8869fcab3..72daa948e 100644 --- a/doc/tutorial/tutorial.texi +++ b/doc/tutorial/tutorial.texi @@ -7,10 +7,11 @@ @ifinfo Primary documentation for the @command{ns-3} project is available in -three forms: +four forms: @itemize @bullet @item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}: Documentation of the public APIs of the simulator @item Tutorial (this document) +@item @uref{http://www.nsnam.org/docs/manual.html,,Reference Manual}: Reference Manual @item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki} @end itemize @@ -24,10 +25,11 @@ the document should be discussed on the ns-developers@@isi.edu mailing list. This is an @command{ns-3} tutorial. Primary documentation for the @command{ns-3} project is available in -three forms: +four forms: @itemize @bullet @item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}: Documentation of the public APIs of the simulator @item Tutorial (this document) +@item @uref{http://www.nsnam.org/docs/manual.html,,Reference Manual}: Reference Manual @item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki} @end itemize @@ -77,9 +79,12 @@ see @uref{http://www.nsnam.org/docs/tutorial.pdf}. @menu * Introduction:: -* Geting Started:: +* Browsing ns-3:: +* Resources:: +* Getting Started:: * Conceptual Overview:: -* Tweaking Ns-3:: +* A First ns-3 Script:: +* Tweaking ns-3:: * Building Topologies:: @end menu diff --git a/doc/tutorial/tweaking.texi b/doc/tutorial/tweaking.texi index 2bfb70505..b10702316 100644 --- a/doc/tutorial/tweaking.texi +++ b/doc/tutorial/tweaking.texi @@ -4,16 +4,16 @@ @c ======================================================================== @c ======================================================================== -@c PART: Tweaking Ns-3 +@c PART: Tweaking ns-3 @c ======================================================================== -@c The below chapters are under the major heading "Tweaking Ns-3" +@c The below chapters are under the major heading "Tweaking ns-3" @c This is similar to the Latex \part command @c @c ======================================================================== -@c Tweaking Ns-3 +@c Tweaking ns-3 @c ======================================================================== -@node Tweaking Ns-3 -@chapter Tweaking Ns-3 +@node Tweaking ns-3 +@chapter Tweaking ns-3 @menu * Using the Logging Module:: @@ -40,7 +40,7 @@ In other systems, warning messages may be output as well as more detailed informational messages. In some cases, logging facilities are used to output debug messages which can quickly turn the output into a blur. -Ns-3 takes the view that all of these verbosity levels are useful and se +ns-3 takes the view that all of these verbosity levels are useful and se provides a selectable, multi-level approach to message logging. Logging can be disabled completely, enabled on a component-by-component basis, enabled globally and has selectable verbosity levels. The ns-3 log module provides @@ -736,7 +736,7 @@ extending the tracing namespace and creating new tracing sources. @cindex tracing @cindex tracing|ASCII @subsection ASCII Tracing -Ns-3 provides an ASCII trace helper that is a wrapper around low-level +ns-3 provides an ASCII trace helper that is a wrapper around low-level tracing system. This helper lets you configure some useful and easily understood packet traces easily. The output of a trace of a simulation run is an ASCII file --- thus the name. For those familiar with @command{ns-2} From 133bf0b651c55ca0db6409fb237a10698a343225 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Sun, 29 Jun 2008 14:28:11 -0700 Subject: [PATCH 2/4] nits on Sections 1-4 --- doc/tutorial/getting-started.texi | 6 ++++++ doc/tutorial/introduction.texi | 17 ++++++----------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/doc/tutorial/getting-started.texi b/doc/tutorial/getting-started.texi index 17519e51c..646b7a20e 100644 --- a/doc/tutorial/getting-started.texi +++ b/doc/tutorial/getting-started.texi @@ -17,6 +17,9 @@ @menu * Downloading and Compiling ns-3:: +* Downloading:: +* Building and Testing:: +* Running a Script:: @end menu @c ======================================================================== @@ -40,6 +43,7 @@ We are going to assume that you have Mercurial and Waf installed and running on the target system as described in the Getting Started section of the ns-3 web site: @uref{http://www.nsnam.org/getting_started.html}. +@node Downloading @section Downloading @cindex tarball The ns-3 code is available in Mercurial repositories on the server @@ -107,6 +111,7 @@ look something like the following: You are now ready to build the ns-3 distribution. +@node Building and Testing @section Building and Testing @cindex Waf!build @cindex Waf!configure @@ -249,6 +254,7 @@ If a regression tests fails you will see a FAIL indication along with a pointer to the offending trace file and its associated reference trace file along with a suggestion on how to run diff in order to see what has gone awry. +@node Running a Script @section Running a Script @cindex Waf!run We typically run scripts under the control of Waf. This allows the build diff --git a/doc/tutorial/introduction.texi b/doc/tutorial/introduction.texi index f9233250b..4cdd7c5d5 100644 --- a/doc/tutorial/introduction.texi +++ b/doc/tutorial/introduction.texi @@ -24,14 +24,14 @@ The ns-3 simulator is a discrete-event network simulator targeted primarily for research and educational use. The @uref{http://www.nsnam.org,,ns-3 project}, -started in 2006, is an open-source project. The goal of the project is to -build a new network simulator primarily for research and educational use. +started in 2006, is an open-source project developing ns-3. -Primary documentation for the ns-3 project is available in three forms: +Primary documentation for the ns-3 project is available in four forms: @itemize @bullet @item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}: Documentation of the public APIs of the simulator @item Tutorial (this document) +@item @uref{http://www.nsnam.org/docs/manual.html,,Reference Manual}: Reference Manual @item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki} @end itemize @@ -96,7 +96,7 @@ page started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us}) @end itemize -If you are an ns user, please consider providing your feedback, bug fixes, or +If you are an ns-3 user, please consider providing your feedback, bug fixes, or code to the project. @node Tutorial Organization @@ -174,11 +174,6 @@ click on the @code{file} link, you will be sent to the source file for Example scripts are in the @code{examples} directory. The @code{examples} directory is a good place to start browsing the code. -For ns-2 users, who may be familiar with the @code{simple.tcl} example script -in the ns-2 documentation, an analogous script is found in -@code{examples/simple-point-to-point.cc} with a Python equivalent found -in @emph{(pending Python merge)}. - @node Doxygen @section Doxygen @@ -190,7 +185,7 @@ look. @section Other Documentation We provide a large amount of documentation regarding the various components -of ns-2 on our website. See: @uref{http://www.nsnam.org/documents.html}. +of ns-3 on our website. See: @uref{http://www.nsnam.org/documents.html}. @c ======================================================================== @c Resources @@ -284,7 +279,7 @@ only have to understand a tiny and intuitively obvious subset of Python in order to extend the system in most cases. For those interested in the gory details of Waf, the main web site can be -found at @uref{http://freehackers.org/\~tnagy/waf.html}. +found at @uref{http://freehackers.org/~tnagy/waf.html}. @node Environment Idioms Design Patterns @section Environment, Idioms, and Design Patterns From 45f203f09f475bd1d21426907f1c46288eefe4f6 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Sun, 29 Jun 2008 14:38:49 -0700 Subject: [PATCH 3/4] formatting nits on the Tweaking chapter --- doc/tutorial/tweaking.texi | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/tweaking.texi b/doc/tutorial/tweaking.texi index b10702316..eb2a5f6c8 100644 --- a/doc/tutorial/tweaking.texi +++ b/doc/tutorial/tweaking.texi @@ -32,7 +32,8 @@ We have already taken a brief look at the ns-3 logging module while going over the @code{first.cc} script. We will now take a closer look and see what kind of use-cases the logging subsystem was designed to cover. -@section Logging Overview +@node Logging Overview +@subsection Logging Overview Many large systems support some kind of message logging facility, and ns-3 is not an exception. In some cases, only error messages are logged to the ``operator console'' (which is typically @code{stderr} in Unix-based systems). @@ -83,7 +84,8 @@ Now that you have read the documentation in great detail, we can get some interesting information out of the @code{first.cc} example script you dropped in the scratch directory after the script walkthrough. -@section Enabling Logging Using the NS_LOG Environment Variable +@node Enabling Logging +@subsection Enabling Logging Using the NS_LOG Environment Variable @cindex NS_LOG First, let's use the NS_LOG environment variable to turn on some more logging in the @code{first.cc} script you have already built. Go ahead and run the @@ -323,7 +325,8 @@ transition into a debugger for fine-grained examination of the problem. This output can be especially useful when your script does something completely unexpected. -@section Adding Logging to your Code +@node Adding Logging to your Code +@subsection Adding Logging to your Code @cindex NS_LOG You can add new logging to your simulations by making calls to the log component via several macros. Let's do so in the @code{first.cc} script we @@ -390,7 +393,7 @@ with component name and simulation time. @node Using Command Line Arguments @section Using Command Line Arguments -@section Overriding Default Attributes +@subsection Overriding Default Attributes @cindex arguments|command line Another way you can change the way that ns-3 scripts behave without editing and building scripts is via @emph{command line arguments.} We provide a From c094200ef6c6fedda3729d47b22df7138f78f764 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Sun, 29 Jun 2008 20:48:18 -0700 Subject: [PATCH 4/4] a few section 8 nits --- doc/tutorial/building-topologies.texi | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/building-topologies.texi b/doc/tutorial/building-topologies.texi index 3f2763011..666e6dde5 100644 --- a/doc/tutorial/building-topologies.texi +++ b/doc/tutorial/building-topologies.texi @@ -16,8 +16,8 @@ @chapter Building Topologies @menu -* Building a Bus Network Topology -* Building a Wireless Network Topology +* Building a Bus Network Topology:: +* Building a Wireless Network Topology:: @end menu @c ======================================================================== @@ -565,8 +565,8 @@ rightmost CSMA device which is where the echo server resides. In this section we are going to further expand our knowledge of ns-3 network devices and channels to cover an example of a wireless network. Ns-3 provides a set of 802.11 models that attempt to provide an accurate MAC-level -implementation of the 802.11 specification a ``not-so-slow'' PHY-level model -of the 802.11a specification. +implementation of the 802.11 specification and a ``not-so-slow'' +PHY-level model of the 802.11a specification. Just as we have seen both point-to-point and CSMA topology helper objects when constructing point-to-point topologies, we will see equivalent @code{Wifi} @@ -748,7 +748,7 @@ management. Like many systems, ns-3 creates a base class called @code{Object} that provides our extensions ``for free'' to other classes that inherit from our @code{class Object}. -In the code snipped above, the right hand side of the expression is a +In the code snippet above, the right hand side of the expression is a call to a templated C++ function called @code{CreateObject}. The @emph{template parameter} inside the angle brackets basically tells the compiler what class it is we want to instantiate. Our system returns a