Re: [SLUG] Tools for documentation.

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

**********************************************************************
*                  This is an automated message.                     *
* This email message has been delayed due to a major system failure. *
*           We apologise for any inconvenience caused.               *
*             Please ignore any duplicate messages.                  *
**********************************************************************


Rodos wrote:
In reply to
> > > So we need to find out what Rodos wants to document...

> I am wanting to document a software project, but mainly the hardware and
> configuration site. I need to incorporate some schematic diagrams
> (xcircuit) and some pictures (jpeg). I need to be able to print the
> documentation and place it into an Intranet. I do not need to be able to
> colabourate with anyone else.

The LaTeX/noweb would handle the software docs well. To
incorporate xcircuit it depends on the format that xcircit
uses to store its files in. If its text files you can
include them directly in LaTeX or include them as
encapsulated postscript if xcircuit can export that. Did you
know that LaTeX can typeset electronic circuits? jpegs can
be converted to .eps files or you could just link to them
with a hyperlink. Then when converting from latex to HTML
the jpegs will link in fine. Otherwise eps files get turned
into gifs.   
xfig is good at mechanical drawing and can export straight
to LaTeX XYPic format or eps.
 
> But lets add another senario. Lets pretend I am writing some open source
> software and I am wanting to document it before I place it onto freshmeat.
> I am going to need stuff that people obviously expect. These would be a
> man(1) page, a README file and some details on how the software works,
> some examples etc. Lets call the last on the user docs or manual. Can any
> of these tools help me create these variety of documents. Not sure where
> this is leading, just throwing it out and seeing what comes back.

This is where noweb is useful. I'd better finish that talk.
In LaTeX you write the man pages and README (don't forget to
include the GNU copyleft file) and noweb will extract them
as separate files for a distribution with the code and HTML
docs. I would then just tarball then up for people to
download. You may wish to include the noweb source file or
not.

> P.S. As a lover of HTML I sometime get a little irked when everything
> for a package is in the HTML files (I know lynx index.html is easy).
> Sometimes I really want a .ps file I can print and read, but other times I
> quite like a terse readme file.

Thats where from LaTeX you make nice PostScript docs for
folks to download as well.
And DocBook would do that too.

I'd say either LaTeX/noweb combination or DocBook would
serve your purpose 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

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