diff --git a/doc/tutorial/Makefile b/doc/tutorial/Makefile new file mode 100644 index 000000000..9fe17f20a --- /dev/null +++ b/doc/tutorial/Makefile @@ -0,0 +1,21 @@ +TEXI2HTML = texi2html +TEXI2PDF = texi2dvi --pdf +EPSTOPDF = epstopdf +TGIF = tgif +CSS = --css-include=tutorial.css + +TGIF_SOURCES = helpers.obj +TGIF_EPS = ${TGIF_SOURCES:.obj=.eps} + +all: images tutorial.html tutorial.pdf + +images: + cd figures/; $(TGIF) -print -png $(TGIF_SOURCES) + cd figures/; $(TGIF) -print -eps $(TGIF_SOURCES) + cd figures/; $(EPSTOPDF) $(TGIF_EPS) + +tutorial.html: + $(TEXI2HTML) ${CSS} tutorial.texi + +tutorial.pdf: + $(TEXI2PDF) tutorial.texi diff --git a/doc/tutorial/figures/README b/doc/tutorial/figures/README new file mode 100644 index 000000000..fe69d95cb --- /dev/null +++ b/doc/tutorial/figures/README @@ -0,0 +1,9 @@ +Please write image files in a vector graphics format, when possible, and +generate the .png and .pdf versions on the fly (see ../Makefile). + +Recommended tools are dia, tgif, and xfig. Store the .dia, .obj, or .fig +versions in mercurial, but not the .png or .pdfs. + +Note: tgif can convert from .obj to .pdf, but the pdf that results takes +up a whole page. Instead, we convert to an intermediate .eps step, and +then run epstopdf. diff --git a/doc/tutorial/figures/helpers.obj b/doc/tutorial/figures/helpers.obj new file mode 100644 index 000000000..22362079f --- /dev/null +++ b/doc/tutorial/figures/helpers.obj @@ -0,0 +1,115 @@ +%TGIF 4.1.43-QPL +state(0,37,100.000,0,0,0,32,1,9,1,1,0,0,1,2,1,0,'Courier',0,80640,0,2,0,10,0,0,1,1,0,16,0,0,1,1,1,1,1088,1408,1,0,2880,0). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +color_info(11,65535,0,[ + "magenta", 65535, 0, 65535, 65535, 0, 65535, 1, + "red", 65535, 0, 0, 65535, 0, 0, 1, + "green", 0, 65535, 0, 0, 65535, 0, 1, + "blue", 0, 0, 65535, 0, 0, 65535, 1, + "yellow", 65535, 65535, 0, 65535, 65535, 0, 1, + "pink", 65535, 49344, 52171, 65535, 49344, 52171, 1, + "cyan", 0, 65535, 65535, 0, 65535, 65535, 1, + "CadetBlue", 24415, 40606, 41120, 24415, 40606, 41120, 1, + "white", 65535, 65535, 65535, 65535, 65535, 65535, 1, + "black", 0, 0, 0, 0, 0, 0, 1, + "DarkSlateGray", 12079, 20303, 20303, 12079, 20303, 20303, 1 +]). +script_frac("0.6"). +fg_bg_colors('black','white'). +dont_reencode("FFDingbests:ZapfDingbats"). +page(1,"",1,''). +text('black',272,195,2,0,1,248,36,0,13,5,0,0,0,0,2,248,36,0,0,"",0,0,0,0,208,'',[ +minilines(248,36,0,0,0,0,0,[ +mini_line(200,13,5,0,0,0,[ +str_block(0,200,13,5,0,-8,0,0,0,[ +str_seg('black','Courier',0,80640,200,13,5,0,-8,0,0,0,0,0, + "low-level APIs (all src/ ")]) +]), +mini_line(248,13,5,0,0,0,[ +str_block(0,248,13,5,0,-2,0,0,0,[ +str_seg('black','Courier',0,80640,248,13,5,0,-2,0,0,0,0,0, + "directories except src/helper/)")]) +]) +])]). +rcbox('black','',96,240,384,288,5,1,1,0,16,2,0,0,0,0,'1',0,[ +]). +text('black',192,259,1,0,1,112,18,3,13,5,2,0,0,0,2,112,18,0,0,"",0,0,0,0,272,'',[ +minilines(112,18,0,0,0,0,0,[ +mini_line(112,13,5,0,0,0,[ +str_block(0,112,13,5,0,0,0,0,0,[ +str_seg('black','Courier',0,80640,112,13,5,0,0,0,0,0,0,0, + "ns-3 simulator")]) +]) +])]). +poly('black','',2,[ + 272,208,240,240],0,1,1,17,0,0,2,0,0,0,0,'1',0,0, + "0","",[ + 0,8,3,0,'8','3','0'],[0,8,3,0,'8','3','0'],[ +]). +poly('black','',2,[ + 240,176,240,240],1,1,1,18,0,0,0,0,0,0,0,'1',0,0, + "0","",[ + 0,8,3,0,'8','3','0'],[0,8,3,0,'8','3','0'],[ +]). +rcbox('black','',176,128,384,176,5,1,1,0,16,25,0,0,0,0,'1',0,[ +]). +text('black',192,131,2,0,1,120,36,26,13,5,2,0,0,0,2,120,36,0,0,"",0,0,0,0,144,'',[ +minilines(120,36,0,0,0,0,0,[ +mini_line(120,13,5,0,0,0,[ +str_block(0,120,13,5,0,-1,0,0,0,[ +str_seg('black','Courier',0,80640,120,13,5,0,-1,0,0,0,0,0, + "ns-3 helper API")]) +]), +mini_line(96,13,5,0,0,0,[ +str_block(0,96,13,5,0,-2,0,0,0,[ +str_seg('black','Courier',0,80640,96,13,5,0,-2,0,0,0,0,0, + "(src/helper)")]) +]) +])]). +rcbox('black','',96,16,384,64,0,1,1,0,16,32,0,0,0,0,'1',0,[ +]). +poly('black','',2,[ + 240,64,240,128],1,1,1,36,0,0,0,0,0,0,0,'1',0,0, + "0","",[ + 0,8,3,0,'8','3','0'],[0,8,3,0,'8','3','0'],[ +]). +text('black',272,83,2,0,1,200,36,40,13,5,0,0,0,0,2,200,36,0,0,"",0,0,0,0,96,'',[ +minilines(200,36,0,0,0,0,0,[ +mini_line(200,13,5,0,0,0,[ +str_block(0,200,13,5,0,-2,0,0,0,[ +str_seg('black','Courier',0,80640,200,13,5,0,-2,0,0,0,0,0, + "helper APIs (src/helper/)")]) +]), +mini_line(192,13,5,0,0,0,[ +str_block(0,192,13,5,0,-1,0,0,0,[ +str_seg('black','Courier',0,80640,192,13,5,0,-1,0,0,0,0,0, + "call into low-level APIs")]) +]) +])]). +poly('black','',2,[ + 272,96,240,128],0,1,1,41,0,0,2,0,0,0,0,'1',0,0, + "0","",[ + 0,8,3,0,'8','3','0'],[0,8,3,0,'8','3','0'],[ +]). +text('black',128,19,2,0,1,232,36,47,13,5,0,0,0,0,2,232,36,0,0,"",0,0,0,0,32,'',[ +minilines(232,36,0,0,0,0,0,[ +mini_line(224,13,5,0,0,0,[ +str_block(0,224,13,5,0,-2,0,0,0,[ +str_seg('black','Courier',0,80640,224,13,5,0,-2,0,0,0,0,0, + "ns-3 scripts (main programs)")]) +]), +mini_line(232,13,5,0,0,0,[ +str_block(0,232,13,5,0,-1,0,0,0,[ +str_seg('black','Courier',0,80640,232,13,5,0,-1,0,0,0,0,0, + "- may use either or both APIs")]) +]) +])]). +poly('black','',2,[ + 144,64,144,240],1,1,1,50,0,0,0,0,0,0,0,'1',0,0, + "0","",[ + 0,8,3,0,'8','3','0'],[0,8,3,0,'8','3','0'],[ +]). diff --git a/doc/tutorial/helpers.texi b/doc/tutorial/helpers.texi new file mode 100644 index 000000000..b64858173 --- /dev/null +++ b/doc/tutorial/helpers.texi @@ -0,0 +1,20 @@ +@node Helper Functions +@chapter Helper Functions +@anchor{chap:Helpers} +This chapter describes an intermediate API for the simulator; what we +call the "helper API". The helper API is implemented in +@code{src/helper/} directory; it depends on (and wraps) the low-level +API which is implemented everywhere else in @code{src/}. The following +figure shows this relationship. +@center @image{figures/helpers,,,,png} + +The use of the helper API is optional. It has two main goals: +@itemize @bullet +@item Provide "syntactic sugar" to wrap a number of related low-level +API calls together, that would normally be grouped together often, into +something that is more user-friendly. +@item Handle configuration of larger topological units (e.g., a set +of nodes or a set of nodes on a particular link) . +@end itemize + +(more to follow) diff --git a/doc/tutorial/output.texi b/doc/tutorial/output.texi index aa836b5cd..185608b42 100644 --- a/doc/tutorial/output.texi +++ b/doc/tutorial/output.texi @@ -457,9 +457,6 @@ wrapper, so you will not see the ARP exchanges that were logged when using the ASCII trace wrapper. You are encouraged to take a look at the contents of these pcap files using your favorite pcap software (or Wireshark). -@node Statistics -@section Statistics - @node Advanced Tracing @section Advanced Tracing diff --git a/doc/tutorial/statistics.texi b/doc/tutorial/statistics.texi new file mode 100644 index 000000000..094e91a4b --- /dev/null +++ b/doc/tutorial/statistics.texi @@ -0,0 +1,9 @@ +@node Statistics +@chapter Statistics +@anchor{chap:Statistics} + +ns-3 does not presently have support for statistics (automatically generated +statistical output). This is planned +for development later in 2008. If you are interested in contributing, +please see @uref{http://www.nsnam.org/wiki/index.php/Suggested_Projects,,our suggested projects page} or contact the ns-developers +list. diff --git a/doc/tutorial/tutorial.css b/doc/tutorial/tutorial.css new file mode 100644 index 000000000..a7586ac83 --- /dev/null +++ b/doc/tutorial/tutorial.css @@ -0,0 +1,156 @@ +body { + font-family: "Trebuchet MS", "Bitstream Vera Sans", verdana, lucida, arial, helvetica, sans-serif; + background: white; + color: black; + font-size: 11pt; +} + +h1, h2, h3, h4, h5, h6 { +# color: #990000; + color: #009999; +} + +pre { + font-size: 10pt; + background: #e0e0e0; + color: black; +} + +a:link, a:visited { + font-weight: normal; + text-decoration: none; + color: #0047b9; +} + +a:hover { + font-weight: normal; + text-decoration: underline; + color: #0047b9; +} + +img { + border: 0px; +} + +#main th { + font-size: 12pt; + background: #b0b0b0; +} + +.odd { + font-size: 12pt; + background: white; +} + +.even { + font-size: 12pt; + background: #e0e0e0; +} + +.answer { + font-size: large; + font-weight: bold; +} + +.answer p { + font-size: 12pt; + font-weight: normal; +} + +.answer ul { + font-size: 12pt; + font-weight: normal; +} + +#container { + position: absolute; + width: 100%; + height: 100%; + top: 0px; +} + +#feedback { + color: #b0b0b0; + font-size: 9pt; + font-style: italic; +} + +#header { + position: absolute; + margin: 0px; + top: 10px; + height:96px; + left: 175px; + right: 10em; + bottom: auto; + background: white; + clear: both; +} + +#middle { + position: absolute; + left: 0; + height: auto; + width: 100%; +} + +#main { + position: absolute; + top: 50px; + left: 175px; + right: 100px; + background: white; + padding: 0em 0em 0em 0em; +} + +#navbar { + position: absolute; + top: 75px; + left: 0em; + width: 146px; + padding: 0px; + margin: 0px; + font-size: 10pt; +} + +#navbar a:link, #navbar a:visited { + font-weight: normal; + text-decoration: none; + color: #0047b9; +} + +#navbar a:hover { + font-weight: normal; + text-decoration: underline; + color: #0047b9; +} + +#navbar dl { + width: 146px; + padding: 0; + margin: 0 0 10px 0px; + background: #99ffff url(images/box_bottom2.gif) no-repeat bottom left; +} + +#navbar dt { + padding: 6px 10px; + font-size: 100%; + font-weight: bold; + background: #009999; + margin: 0px; + border-bottom: 1px solid #fff; + color: white; + background: #009999 url(images/box_top2.gif) no-repeat top left; +} + +#navbar dd { + font-size: 100%; + margin: 0 0 0 0px; + padding: 6px 10px; + color: #0047b9; +} + +dd#selected { + background: #99ffff url(images/arrow.gif) no-repeat; + background-position: 4px 10px; +} diff --git a/doc/tutorial/tutorial.texi b/doc/tutorial/tutorial.texi index d71fe8cf3..737041b61 100644 --- a/doc/tutorial/tutorial.texi +++ b/doc/tutorial/tutorial.texi @@ -109,10 +109,12 @@ Part 5: Extending ns-3 @include introduction.texi @include log.texi @include attributes.texi +@include statistics.texi +@include helpers.texi @include callbacks.texi @include output.texi @include routing.texi -@include other.texi +@c @include other.texi @include troubleshoot.texi @printindex cp