Re: Learnign DocBook

[Sean Wheller <sean enbaya co za>]

On Monday 07 June 2004 17:45, Telsa Gwynne wrote:
> 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).

I know what you mean. But I am assuming that people on this list are 
technically inclined in one way or the other. I guess the first step to 
learning Docbook would be first understand what XML is and the proceed to 
what is a DTD.

If that is to technical, then I suggest that people use a WYSIOO editor like 
XXE or Conglomerate. Frankly I don't think they help much as understanding 
the source is the key.

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

Yes looking at the source does give you an idea of what to do. It's the same 
with most languages, learning by example.

One tip is to download the Docbook TDG source from CVS there are also 
testdocs. These enable you to see examples in isolation.

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

Hmmm. Yes I guess that can be a problem, but the idea is to use the set of 
tags you need. There is no requirement to use all tags just because they are 
there. Since you and I may use the same tag for different purposes this could 
be confusing. In a collaborative environment we should have some agreement 
between ourselves as to which elements are used and which are not, and for 
what. This problem is discussed in TDG and I think is one of the reasons most 
people tend to swing toward sdocbook in the beginning.

Often you will find that projects do provide a guideline to element usage. I 
vaguely remember seeing something about this is in the GNOME documentation. I 
know that KDE has such a list of tags used by the project.

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

I guess it depends on how you read things. I thought that the intro material 
and docbook.org + wiki gave a very clear definition on what docbook is and 
for what purpose it can be applied. Looking at the DTD and XSD was also very  
helpful. When I took the docbook TDG and the testdocs the tagging made more 
sense. But then I already knew what XML, DTD, XSD, XSL etc mean and had 
worked with these on a daily basis. Perhaps a person coming from a more 
conventional WYSIWYG Word Processor would find it difficult to understand all 
the jargon. Then again a person with a background in publishing will identify 
that for the most part the docbook vocab is standard. The computer part of 
the lexicon can be confusing. I personally find that it this part of the 
vocab is limited and should be reviewed to include vocab that is more 
representative of the interface terms of today, but since I am not on TDBC I 
cant force this issue and hence just get along with what is.

I am however, very interested in your observation as I am currently writing a 
book about docbook and its application in technical publications and 
development environments. Perhaps you could share, in more detail, the exact 
problems you had "Getting Started". I am not certain that this is the forum 
for such dicussion, so please feel free to discuss off-list if required.
-- 
Sean Wheller