Re: [Firebird-docs] A how-to on writing Firebird docs?

[Paul V. <pa...@vi...>]

Hi Mauricio,

> Just to get a better understanding... Why *do* you want the help to
> be a docbook xml?  Please, I don't have any specific objections, but
> all the steps involved in the discussion list seem to make for a lot
> of trouble for anyone participating in the effort.  Please, bear in
> mind that I'm not criticizing, and that I have no other suggestion
> at the moment, but I would like to understand the "whys" in order to
> decide if I should/could think of someway to contribute.

I've also received this mail privately and replied (as you know of
course). Now I see that you posted it to the list too, but it took a
couple of days to show up - I think SF has a random delay function
built in somewhere in the mailing list chain :-)

Anyway, since the question is now on the list, I'll post my answer
here too, because other people may have the same question. It's been
answered before, but the archives are not always accessible - the
interface at SF is a bit awkward, often slow and I think also
incomplete; and the NNTP mirror at news.atkin.com has problems
regularly (right now it's down). So here goes:


> Just to get a better understanding... Why *do* you want the help to
> be a docbook xml?

Because with DocBook XML, you mark up the _structure_ of a text and
the _meaning_ of its elements: you tag things as chapters, sections,
subsections, titles, warnings, code snippets, filenames, tips, user
commands, etc.  etc...  There is no "pollution" by presentational
markup like in HTML, RTF, Word and other formats.

This results in a very clean and structured source text which is easy
to maintain, totally platform-independent *and* presentation-
independent,

From this DocBook XML source, we can then (automatically) build HTML,
PDF and other output for the readers. Stylesheets (which we can change
if we want to) control how the structural markup is translated to a
certain presentation.

> Please, I don't have any specific objections, but all the steps
> involved in the discussion list seem to make for a lot of trouble
> for anyone participating in the effort.

I'm afraid you are right :-(

It takes time to get familiar with DocBook XML. Ten months ago I'd
never heard of it - I learned using it because I wanted to help
produce Firebird documentation. But now that I know it, I find it even
easier to write then HTML or Word or whatever, precisely because I
never have to worry about the layout while I'm writing!

If I write a text in Word, I have to think about if I want section
titles bold or not - or perhaps in a nice color? - and then I have to
remember my decision so I don't do it another way ten pages further
down. And how do I make up a code snippet? And a command line? And a
warning? And... and... aaaargh!

But even if I *do* make some great rules for all these elements, and I
*do* apply them consequently throughout the text, the resulting
document will still suffer from these drawbacks:

- The information itself as to whether something is a code snippet, a
  warning, or a filename, is not included in the document - because
  I've already translated that info to makeup: font types, colors etc.

- I only have a Word text now. How to convert to PDF and HTML? Yes, I
  know: the latest Word versions do that, but you can't really control
  _how_ they do it.

If I write DocBook XML on the other hand, I rarely have to think about
which tags to use, because In DocBook you tag a command as <command>,
a filename as <filename>, a code snippet as <programlisting>, etc...
Easy!

Also, if everybody produces DocBook XML, we can have one common output
style (defined by the stylesheets). If we'd all produce HTML it would
be very difficult (and very frustrating for the docwriters) to have a
common style.


But - having said all that - if someone wants to help and he REALLY
has a big problem with DocBook XML, he can write in another format
too. But I hope everybody will at least give DocBook a good try before
they decide not to use it.


I hope I can finish the first - draft - Howto this week; it's about
how to download the manual module and build the docs. A second Howto
(hopefully within three weeks) will be on how to write docs in DocBook
XML format.


Greetings!
Paul Vinkenoog

 - no docs today, my mind has gone away -