Re: [SLUG] Tools for documentation.

[Jeff Waugh <jdub@nospam.aphid.net>]

> > Rodos? Clarify please, Michael and I are up for a flame.
> 
> Don't let me hold you guys back. 
> 
> 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.


                     HTML  <---  DocBook  --->  PS/PDF
                     
                                    |
                                    |
                                    V

                                   RTF

DocBook is extraordinarily fast to work with - once you have a working
knowledge of the tags you need, it's lucid.

<sect1>
<title>Widgets</title>

<para>Widgets are really helpful, blah, blah, blah... [and so on]</para>

    <sect2>
    <title>The Big Widget</title>

    <para>Only very strong engineers should work with Big Widgets...</para>

    </sect2>

</sect1>

And so forth. All your really important words and features in your text you
markup to distinguish what they are. For instance:

<command>cp</command> <replaceable>source</replaceable>
<replaceable>destination</replaceable>

This means your processing software (say stylesheets like DSSSL) can make
them look they way you want. It also aids automation of your document in
other ways (searching, etc).

When it comes to images and other <sgmltag>MediaObjects</sgmltag> (that's
real DocBook by the way), you can define different sources for different
outputs. In your example, the jpegs could be used for just about any output,
whilst your xcircuits could be rendered to PS/EPS for print, and GIF or even
Flash for web. You just tell it what the source is, and its type, and your
processor does the rest.

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


Alright, you'd be nuts not to do this in DocBook. To begin with, a whole
swathe of the DocBook specification was based on man pages - read:

         http://www.docbook.org/tdg/html/ch02.html#MAKING-REFENTRY

So you can process these into real manpages at the flick of a wrist. Cool,
huh?

Um, do your README in vi. Like normal hackers do. I'm kidding - you can do
this in DocBook as well, but don't quote me when I say you can output to
plain text. DocBook wasn't designed to do README's, so you may find one of
the HTML/text tools floating around on Freshmeat useful - or you can always
copy out of Lynx (which is how I do stuff like that).


*Very* interested in Mike's talk - perhaps I should organise a DocBook/TeX
Religious Wars for that night? Hmm...

- Jeff


-- jdub@nospam.aphid.net ------------------------------------- jdub@nospam.linux.org.au --

   w: http://www.slug.org.au/
   i: 16341281 (jdub!)
   q: "In addition to these ample facilities, there exists a powerful
       configuration tool called gcc." - Elliot Hughes, author of lwm

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