Bug 76

Summary:	new documentation templates needed
Product:	ns-3	Reporter:	Tom Henderson <tomh>
Component:	documentation	Assignee:	ns-bugs <ns-bugs>
Status:	RESOLVED FIXED
Severity:	normal
Priority:	P3
Version:	pre-release
Hardware:	All
OS:	All

Description Tom Henderson 2007-09-17 00:51:55 UTC

The current documentation system is based on Latex with perl-based pre-process and post-process script, and then relies on latex2html to generate HTML.  This system was inherited (and tweaked) from the ns-2 manual.

The goal is to write documentation that produces both clean looking PDF and clean, easily navigable web pages with hyperlinks and styles for pasting in code.

The current system is fragile in a number of ways, but the main problem is the HTML that is generated:
- images are not converted correctly when latex2html is run
- latex2html does not know how to handle many Latex environments and also specialized macros defined for ns-3
- specifying URLs that render correctly in both PDF and HTML is challenging, as witnessed by this example post from another forum:
http://www.tug.org/pipermail/latex2html/2002-September/002033.html

Two alternatives to consider are GNU Texinfo and Doxygen (using it more than just for APIs, such as Mathieu's tracing documentation).

Comment 1 Tom Henderson 2008-01-14 00:59:40 UTC

no longer using latex2html-- using Doxygen and Texinfo