[Ns-developers] some ns-3 documentation proposals

[Tom Henderson]

Based on Mathieu's suggestion to use Doxygen for all of the ns-3 
documentation (including the tutorial), I did a bit of prototyping in 
the tomh/ns-3-dev-doxygen repository, and have built some html and 
posted it at
http://www.nsnam.org/temp/doxygen-proposal/

Overall, I think it is promising.  Here is what I've found.

To recap, we want to build an ns-3 manual and ns-3 tutorial with the 
following properties.
1.  be able to generate clean looking HTML
2.  be able to generate clean looking PDF
3.  handle hyperlinks correctly without too much syntactical cruft
4.  handle embedded images cleanly (PNG for web, eps for PDF version)
5.  source text is version controlled

Mathieu proposed to use Doxygen for both of these documents, in addition 
to the current use of Doxygen for API documentation.

As I see it, the pros for using Doxygen for everything include:
- everything is hyperlinked together, internally consistent
- documentation is stored with the source code
- the web output looks really nice; Doxygen shines at this.
- it does handle hyperlinks and images nicely

You can see from the above link that I created two "Related Pages" with 
Doxygen's subpaging facility, to handle the tutorial and a second 
(proposed) HOWTOs document, separately from the core modules.

As for the ns-3 manual, it seems that the Doxygen way to handle this is 
to make each "chapter" a separate module, and to organize the modules 
with a file that serves as an outline for all of these modules.  I 
created this file as doc/modules, and you can see how the present module 
documentation could be organized by selecting the Modules tab.  This 
seems a reasonable approach to building a manual for web browsing at 
least; more on the PDF below.

As for the tutorial, I converted a few snippets to see what it would 
look like, and to solicit more comments before going further.  See the 
Related Pages tab.  I also started a HOWTO document as a Related Page. 
I agree with Mathieu's previous observation that converting from texinfo 
to doxygen format is not a big deal.

In summary, I think that this fully Doxygen approach might be a nice one 
to adopt.  I did not try to convert the tutorial completely; I just did 
a few snippets to see what it would look like, and to solicit feedback.

The open questions I still have are the following:

1.  generating small PDFs of subsets of the material, such as 
ns-3-tutorial alone, or parts of the ns-3-manual.  Right now, the PDF 
generated by straightforward application of "./waf --doxygen" and latex 
runs at 484 pages.  A lot of that is obviously raw API documentation and 
graphviz.

(note:  I do not see much reason to worry about generating subsets of 
the HTML, though).

For building the ns-3 manual PDF, I do not know how to unobtrusively get 
Doxygen to pull out only the "Detailed Description" or any other 
subsection, however.  There probably is a way to explicitly tag 
sections, but it still wasn't clear how to do that.

For building the tutorial PDF, I think it might suffice to remove the 
src/ directory from the list of sources when building it.  This could be 
done by the build system.

2.  should we store .png and .eps figures as version controlled figures, 
or just store the vector graphics source and pre-process them during the 
build process to generate the png and eps?

I think that if we go down the path of storing the documentation with 
the mainline code, we should try hard to generate the figures on the fly 
from xfig, tgif, or dia source.  I would like to avoid that the doc/ 
directory swells in size.


Any further comments or suggestions?  I'd like to try to resolve this 
issue in the coming week so that we can settle on a format for the tutorial.

Tom