Re: Learnign DocBook

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Mon, Jun 07, 2004 at 05:09:03PM +0200 or thereabouts, Sean Wheller wrote:
> On Monday 07 June 2004 13:59, Muthiah Annamalai wrote:
> > How do I learn Doc book ?
> 
> May I suggest starting with http://www.docbook.org
> Subscribe to the docbook mailing lists

To be honest, I didn't find those too helpful when I started.
That was some time ago, though, so things may have changed.

But looking at the hundreds of tags is off-putting in the
extreme. It is likely that at first you won't need all of
them. I can't think of many short documents which will 
require lots of <guimenuthingy> (for referring to the UI)
_and_ <structwotsit>s, <returnvalue> and <void> (for talking
about the kernel or something).

> Then get yourself an XML editor I suggest one that gives you access to the 
> source xml view. The Oxygen XML Editor is a good tool http://
> www.oxygenxml.com

I shall investigate that one. At the moment, I generally just
write in a plain text editor. Which is certainly do-able, but
not necessarily the most fun to start with.

What I did (a lot) when learning DocBook was to start with
other people's documents which were already valid, and tweak
them: remove all the content and leave just the tags, and
fill my idea of content in, and so on. And then venture a 
new <para> or -- gosh -- a new <sect2> or something, and 
stare miserable at jade output when it then broke :) 

And that exposed me to a manageable (just about) set of
tags until I got used to what DocBook was. So subsequently,
when I needed to mark up something about the kernel, all 
I had to do was to think "I bet there's a tag for this" and
head to the index of the printed version of the DocBook book
every so often.

(Incidentally, I find that book a splendid reference, but
I didn't find it so good for learning "what is a docbook" :))

Also, I sat around on the #docs channel on irc.gnome.org a
lot, and chatted to a friend a bit further ahead than me on
another network. IRC is good for quick explanations. Sometimes.

Telsa