Re: HTML+ for software documentation

nikos@cbl.leeds.ac.uk
Errors-To: listmaster@www0.cern.ch
Date: Wed, 4 May 1994 10:53:44 +0200
Errors-To: listmaster@www0.cern.ch
Message-id: <1083.9405040845@cblipca.cbl.leeds.ac.uk>
Errors-To: listmaster@www0.cern.ch
Reply-To: nikos@cbl.leeds.ac.uk
Originator: www-talk@info.cern.ch
Sender: www-talk@www0.cern.ch
Precedence: bulk
From: nikos@cbl.leeds.ac.uk
To: Multiple recipients of list <www-talk@www0.cern.ch>
Subject: Re: HTML+ for software documentation
X-Listprocessor-Version: 6.0c -- ListProcessor by Anastasios Kotsikonas


>To any HTML+ expert:
>
>        As a member of a computer satellite modeling team, I've been asked
>to investigate the feasibility of using NCSA Mosaic/HTML as a platform for
>writing hypertext software documentation.  Currently the team's leader and
>deputy leader are in a fierce debate arguing between Framemaker and LaTeX.
>Both, however, are interested in Mosaic and it's possible application to
>our work.
>
>        Before today, I would have said a large-scale documentation project
>would have been difficult using and HTML format due to restictions on image
>inlaying and the lack of a convenient equation editor. Recently (this
>morning), I've found mention of HTML+, as well as latex2html and WEBMAKER,
>converters that create HTML files from LaTeX and Framemaker.  I thought
>that perhaps these things might be the solution to our team's problem.


In the last few weeks two "literate programming" tools authors have 
announced that they support output both in LaTeX and in HTML 
(using latex2html) [A literate programming tool lets you mix 
program documentation with the actual code. The tool is responsible 
for separating the documentation (for human consumption) and the 
code (for the compiler)].

Although the paper-based documentation that comes out (LaTeX) is good,
there are still some problems with the HTML output especially
with large files. Have a look at
http://info.desy.de/user/projects/LitProg/HTML.html
for more information and links to examples.

But if you are thinking about software documentation which is written
and maintained separately from the code then either one of latex2html 
or webmaker should do - it should come down to what you are most
comfortable with...

[stuff deleted]

>        Thanks in advance for any help you can provide,
>
>          Tony Crider (http://sst.lanl.gov/~acrider)

Nikos.

--
Nikos Drakos			
Computer Based Learning Unit   	nikos@cbl.leeds.ac.uk
University of Leeds		http://cbl.leeds.ac.uk/nikos/personal.html