[Ns-developers] ns-3 manual format

[Bryan Ward]

I don't have much experience with latex2html, maybe I just don't know how to
customize it, but from what I have used it for, it turns out looking pretty
basic and primitive.  On the other hand, I have found that the documentation
generated by Sphinx is very professional looking.  I agree though that using
LaTeX gives you the nice capability to be able to easily copy/paste from
other LaTeX documents, and additionally, it is an environment that (I
assume) most people are going to familiar with.

On the side of sphinx, I think that it has several advantages.  The stuff it
generates by default looks a lot better.  The HTML/CSS it generates (e.g.
http://docs.python.org and http://www.eg.bucknell.edu/safe), is quite nice.
 It can integrate with your code documentation, so for example, you could
have links to methods in the API in the users manual.  It also can spit out
PDF files, so you can not only make nice looking webpages for your
documentation, but also professional looking PDF user manuals.  It does so
by converting the restructuredtext to LaTeX and then running pdflatex (or
equivalent) on it.  It has the capability to do all sorts of things with
figures and images too.

The one downside to Sphinx is that there is a little bit of a learning
curve.  Sometimes the syntax is a little bit funky.  But while yes, the
syntax may be a little bit funky, I don't think it would be that hard to
figure out.  I think that once there is a good body of restructuredtext,
that other authors will be able to figure out what they need to be doing by
example.

Bryan