firebird-docs

[Firebird-docs] Which kind of docs?

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

Hello again,

Which kind of docs should we produce? Well, there doesn't have to be
consensus on that: everybody who is willing to spend unpaid time
writing docs, can - in principle at least - work on the document that
he/she finds important. Of course it would be nice to know from each
other what we are doing, especially when it comes to large documents
-- or else we might wind up with six Embedded SQL Guides.

Personally, I find it most important to produce a comprehensive core
documentation set, more or less like the PDF books that Borland ships
with InterBase. Such a set could (should?) contain:

- a DDL guide
- a DML guide
- an SQL reference
- an API guide
- a Programmer's Guide
- ...
- ...

For now, the free Borland IB6 beta docs are still very usable with
Firebird, provided you also have the Release Notes etc. that come with
the consecutive Firebird versions. But InterBase and Firebird _will_
diverge more and more, so in a couple of years' time this is really
going to be a problem.

Since I've been playing around with the API lately I would like to
start with an API Guide myself. But I realize that this is not the
most urgently needed guide, so I might be persuaded into writing
something else instead.


Important
=========
The Borland InterBase 6 Beta Docs are free in the sense that you don't
have to pay for them - but they *are* copyrighted. This implies that
it's perfectly OK to use all kinds of _INFORMATION_ we find in those
docs, but it's illegal to copy _TEXT_ (even portions) from them.
We'd better keep that in mind whilst writing our docs, or else!


I hope to hear more ideas from you all.

Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Which kind of docs?

[Thad H. <th...@mi...>]

Paul,

The vast majority of my work with Firebird (90+%) has been with embedded =
SQL=20
so that seems to be what I'm most qualified to write on.  I'm a bit unsur=
e of=20
some of the transaction handling but I might be able to blunder thru it. =
 And=20
I'm sure my boss and family will forgive my inattention. =20

What do you have as a formatting guide?  Is this all to be in MS Word, Op=
en=20
Office Writer, or some sort of XML tagging?  I would think the simpler th=
e=20
better till we're ready to go "final".

--Thad Humphries

On Saturday 19 July 2003 14:32, Paul Vinkenoog wrote:
> Hello again,
>=20
> Which kind of docs should we produce? Well, there doesn't have to be
> consensus on that: everybody who is willing to spend unpaid time
> writing docs, can - in principle at least - work on the document that
> he/she finds important. Of course it would be nice to know from each
> other what we are doing, especially when it comes to large documents
> -- or else we might wind up with six Embedded SQL Guides.
>=20
> Personally, I find it most important to produce a comprehensive core
> documentation set, more or less like the PDF books that Borland ships
> with InterBase. Such a set could (should?) contain:
>=20
> - a DDL guide
> - a DML guide
> - an SQL reference
> - an API guide
> - a Programmer's Guide
> - ...
> - ...
> ...

Re: [Firebird-docs] Which kind of docs?

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

Hi Thad,

> The vast majority of my work with Firebird (90+%) has been with
> embedded SQL so that seems to be what I'm most qualified to write
> on.

Sounds logical.

> I'm a bit unsure of some of the transaction handling but I might
> be able to blunder thru it. And I'm sure my boss and family will
> forgive my inattention.

Hmm... I wonder what Dr. Phil would have to say about this ;-)

> What do you have as a formatting guide? Is this all to be in MS
> Word, Open Office Writer, or some sort of XML tagging? I would think
> the simpler the better till we're ready to go "final".

The idea is to write the docs in XML, using the DocBook DTD. This way
we can produce different output formats (HTML, PDF, RTF, PS...) and
it's platform-independent - a good thing because Firebird runs on a
number of platforms.

If you read the webpage I mentioned a couple of days ago, and follow
some of the links, you'll find more about this, including some
guidelines written by David Jencks about tag choosing.

Myself, I don't really dig writing long documents in XML (or maybe I
should say: I don't know of a free or affordable editor that makes XML
writing a pleasure) but I agree it is the best choice because it's so
versatile and you keep the structure very manageable - *and* you can
finetune how the output is going to look like.

If you really really hate XML or it takes you too much time I suppose
you could choose another format - after all, an Embedded SQL Guide in
Word or HTML is better than no Embedded SQL Guide at all.

Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Which kind of docs?

[Helen B. <he...@tp...>]

At 01:30 PM 22/07/2003 +0200, Paul Vinkenoog wrote:

>Myself, I don't really dig writing long documents in XML (or maybe I
>should say: I don't know of a free or affordable editor that makes XML
>writing a pleasure) but I agree it is the best choice because it's so
>versatile and you keep the structure very manageable - *and* you can
>finetune how the output is going to look like.

http://www.cambridgedocs.com/

cheers,
Helen

Re: [Firebird-docs] Which kind of docs?

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

Hi Helen,

>> I don't really dig writing long documents in XML (or maybe I should
>> say: I don't know of a free or affordable editor that makes XML
>> writing a pleasure)

> http://www.cambridgedocs.com/

Thanks for the pointer, I've been playing with the Word2XML converter
a bit. It's very affordable, but unfortunately it only produces ppXML.
If you want DocBook, you have to use their xDoc converter which looks
very promising but is a tad on the expensive side at $ 2495...

Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Which kind of docs?

[Tilo M. <tm...@al...>]

Hi Paul, All,

> >> I don't really dig writing long documents in XML (or maybe I should
> >> say: I don't know of a free or affordable editor that makes XML
> >> writing a pleasure)
>
> > http://www.cambridgedocs.com/
>
> Thanks for the pointer, I've been playing with the Word2XML converter
> a bit. It's very affordable, but unfortunately it only produces ppXML.
> If you want DocBook, you have to use their xDoc converter which looks
> very promising but is a tad on the expensive side at $ 2495...

I don't think writing the docs in Word (or any other word processor) and
converting it afterwards to Docbook would be a good idea. Docbook separate
the text from the formatting instructions which means that you describe the
content and the formatting is later done by the stylesheets. This is the
main advantage of Docbook over any word processor and I think we should use
this advantage instead of only having Docbook as a container for dumb
text...

Regards,
Tilo

Re: [Firebird-docs] Which kind of docs?

[Tilo M. <tm...@al...>]

Hi,

"Paul Vinkenoog" <pa...@vi...> schrieb im Newsbeitrag
news:Pin...@s4......

[snip]

> Personally, I find it most important to produce a comprehensive core
> documentation set, more or less like the PDF books that Borland ships
> with InterBase. Such a set could (should?) contain:
>
> - a DDL guide
> - a DML guide
> - an SQL reference
> - an API guide
> - a Programmer's Guide
> - ...
> - ...

Why not take a look at PostgreSQL:
http://www.postgresql.org/docs/7.3/static/index.html
- A tutorial, great for newbies with databases in general and Firebird in
particular
- From the users point of view, DML, DDL
- From the admin point of view, setup, optimize, deploy
- Programmer Guide, API
- SQL Reference
- Developer Guide, also with infos for people willing to contribute to Fb

> For now, the free Borland IB6 beta docs are still very usable with
> Firebird, provided you also have the Release Notes etc. that come with
> the consecutive Firebird versions. But InterBase and Firebird _will_
> diverge more and more, so in a couple of years' time this is really
> going to be a problem.

Fully agreed.

> Since I've been playing around with the API lately I would like to
> start with an API Guide myself. But I realize that this is not the
> most urgently needed guide, so I might be persuaded into writing
> something else instead.

As I stated elsewhere, I will not have much spare time available for active
contribution but are willing to discuss things and help with the Docbook
setup itself.

> Important
> =========
> The Borland InterBase 6 Beta Docs are free in the sense that you don't
> have to pay for them - but they *are* copyrighted. This implies that
> it's perfectly OK to use all kinds of _INFORMATION_ we find in those
> docs, but it's illegal to copy _TEXT_ (even portions) from them.
> We'd better keep that in mind whilst writing our docs, or else!

Agreed.

> Greetings,
> Paul Vinkenoog

Regards,
Tilo