[Ns-developers] some ns-3 documentation proposals

[Mathieu Lacage]

hi tom,

I spent a while looking at your doxygen source and experimented a bit
locally. Comments below.

On Sun, 2007-12-30 at 21:32 -0800, Tom Henderson wrote:

> 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.

One of the problems with this approach (and with doxygen in general) is
that it is impossible to specify the order in which the groups are going
to appear in the final latex output. i.e., if the 'wifi tutorial' is
parsed before the 'tutorial introduction', it will be output first. 

Another problem with doxygen is that the latex output cannot contain any
chapter beyond the predefined chapters. i.e., the 'pages' and 'groups'
you define are converted to sections within the two 'Related Pages' and
'Groups' chapters which is most likely not what you want in a serious
manual.

So, I don't see many options here if you really care about good-looking
pdf output:
  - use the doxygen xml output to generate ourselves our own latex
output with a small python script. This is not especially hard but it
will take some work
  - a potentially simpler approach would be to use the perlmod output of
doxygen to generate our own latex.
  - do not use doxygen


> 
> 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.

I think that the html output you linked to looks ok. The source, on the
other hand, could be made to look nicer:
1) we should agree on a consistent extension naming scheme for files
which contain only doxygen documentation: .h or .txt ?
2) the content itself should be marked using the /*! */ syntax:
/*!
Random text

*/

This saves you the pain to have to insert a leading * at the start of
each line for such lengthy text-only files.

> 
> 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.

The only way that I know of to control the latex output is to limit the
number of files parsed by doxygen which makes it somewhat hard to pick
the subsets you are interested in.

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

ok.

> 
> 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.

I do not know of any way to control the latex output like that beyond
writing our own latex output generator on top of doxygen's xml or
perlmod output.

> 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.

It would be nice to keep a single vector source for all images unless
they are naturally pixel-based, of course.

Conclusion:
  - the html output is really nice.
  - the latex output is going to require some more work.

regards,
Mathieu