Re: [Firebird-docs] Hi

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

Hi Armando,

So you managed to subscribe after all? (I was just about to answer
your message in FFmembers when I saw this one appear).

> As you suggested, I subscribed to Firebird-docs. I'm willing to
> help, but I must admit this is an approach to writting that I never
> used before.

I was in the same situation when I joined the doc effort about 1,5
years ago. I'd never used DocBook and I really had to get used to it.
But I soon started to like it more and more.

> 1. Is there any global TOC so that we can pick up a subject from
> what is missing?

No, the TOC only contains the items that are really there. Anyway,
there have been some new developments during the last couple of days
that may lead to a change in our planning (certainly in mine):

- IBPhoenix are donating their QuickStart Guide to the project. This
  guide was already free, but (c) IBPhoenix. Author Helen Borrie is
  now writing an app to convert it to DocBook XML. Once that is done,
  we get the QSG in DocBook format and then it will be our job to
  update it to Firebird 1.5 and maintain it in the future. The
  QuickStart Guide is going to be part of the official Firebird
  release packages.

- Somewhere in the near future we'll also inherit the Using Firebird
  guide. This is a real monster so it'll give us a lot of work.

- IBPhoenix has an API Guide and an SQL Reference in the planning.
  These are *not* going to be free, but in light of our own situation
  (Michael Gloegl no time to work on SQL ref; myself barely started
  with API ref) it might be better to drop these items for now and
  work on other things: Reserved words list + Glossay, QuickStart
  Guide, Using Firebird... plus whatever other useful docs someone
  may come up with.


> 2. Would you agree if I tried to write a simple test text and send
> it to you or someone else just to check if I understood the way of
> working with docbook? (I never used it before).

Sure, you can send it to me. It doesn't even have to be a serious
Firebird-related text. Just try to use most of the basic elements:
chapter, sect1, sect2 (etc.), link, ulink, blockquote, emphasis,
filename, command, itemizedlist, orderedlist, variablelist,
programlisting, screen, note & friends, maybe a table... (see the
Docwriting Howto).

I do advise you to use XMLMind XML Editor, and then check the produced
DocBook source from time to time in a text editor (a disadvantage is
that you can't do that from within XXE). You can also write DocBook
XML directly in a text editor, but then you won't notice your mistakes
until you try to build a target.

Have you already checked out the existing docs from CVS? It may be
helpful to look at them as examples. The top document is
manual/src/docs/firebirddocs.xml, the individual docs are in
manual/src/docs/firebirddocs/*.xml


Greetings,
Paul Vinkenoog