Re: [SLUG] Tools for documentation.

[Michael Lake <Mike.Lake@nospam.uts.edu.au>]

Rodos wrote:
> 
> What tools do people use to create documentation?
What do you want to document?

> I want to use something that is open, and will not cause version problems
> in 10 years time (will Word 2010 read Word6 documents?).
> I had a quick look at DocBook and it scared me. I do what something that
> can create very nice paper output as well as an online version.
> Currently I am thinking LaTeX.
Yeah !!!!!

I am preparing a talk for SLUG on using noweb with LaTeX.
noweb is a literate programming tool that allows you to mix
documentation and code in the one file. Two commands
`notangle' and `noweave' are used to either extract your
code chunks from the main file and reassemble then into your
program or extract LaTeX documentation of your program. That
then gets turned into nice PostScript. noweb also uses
latex2html filters to create HTML documentation as well.

Your code can be in any language. Perl, sh, C, HTML or even
other documentation.
You can get away with learning just a dozen LaTeX commands
as documention can be done with very simple formating -
nothing fancy is needed so you don't need to learn any of
the hard stuff in LaTeX.

You can find an example at: 
http://www.science.uts.edu.au/~michael-lake/cavescript/
Follow "Documentation on-line, then either the DTD link or
the svx-XML link.
 
The direct URL to the latter is:
http://www.science.uts.edu.au/~michael-lake/cavescript/docs/svx-xml.html

That HTML doc was done in LaTeX. 
Advantages is that the text is still text. Even if you don't
have noweb and LaTeX in the future or have forgotten how to
use it you will still be able to read and follow your
documentation with any text viewer. 
And there are many latex to plain text strippers as well. 

Mike

-- 
--------------------------------------------------------------------
Michael Lake
University of Technology, Sydney
Email: mailto:Mike.Lake@nospam.uts.edu.au Ph: 02 9514 1724 Fx: 02
9514 1628 
URL: http://www.science.uts.edu.au/~michael-lake/
Linux enthusiast, active caver and interested in anything
technical.
--------------------------------------------------------------------
--
SLUG - Sydney Linux Users Group Mailing List - http://www.slug.org.au
To unsubscribe send email to slug-request@nospam.slug.org.au with
unsubscribe in the text