[Ns-developers] some ns-3 documentation proposals

[Tom Henderson]

Mathieu, a few more responses below:

Mathieu Lacage wrote:
> 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

I did some more poking around and came to similar conclusions:
- Doxygen is not going to produce very polished-looking PDF by default, 
although it can produce a readable PDF
- everything in the tutorial will end up in a single chapter
- the lack of control of ordering sections (which can be somewhat 
controlled on the HTML side) is troublesome.

And, as you point out, we could direct output to intermediate xml or 
perl files and do some processing there before running latex.

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

Good suggestion.

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

Agreed.  This can be worked around by enumerating explicitly selected 
files that are built into the printed manual, but it requires some care 
to maintain the Doxygen that way.

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

Agreed.  So how much do other people care about the printed output, for 
manual or tutorial or both?

One possible option at this point would be to:

- keep the tutorial in texinfo so that it can generate a clean PDF too, 
the rationale being that the tutorial is probably going to be its own 
set of standalone text files anyway and does not really benefit much 
from Doxygen other than being able to cross-link easily

- do not worry for now about building small latex manuals out of 
Doxygen; if users want to print things from the Doxygen, they can print 
sections from their browsers or extract the PDF pages they want from the 
larger PDF on their own.

Basically, this would be to do what I suggested a few weeks ago:
http://mailman.isi.edu/pipermail/ns-developers/2007-December/003581.html

I am not really motivated right now to build a custom latex output 
generator.

Tom