firebird-docs

[Firebird-docs] Docs, create, I can

[Nigel W. <ni...@e-...>]

I'm interested in writing a few docs for Firebird, as I've been contributing
to FreeBSD forums (under the name of Squidge), and have found myself
enjoying it...

I don't know XML, DocBook, and can't run OpenOffice, but I can create a PDF
in an instant from a documentation engine.

Hopefully, it's a matter of, 'The more, The merrier?'

Are there areas that need urgent focus? I specialise in FreeBSD, PHP, and
Apache-based web-apps, powered by Firebird, so perhaps a few tutes in that
area, or is it saturated already?...


Nige.

Ps.
Pdf to date: http://oc.aims.net.au/fdp/dloads/
DocEngine: as above, but one dir back.

Re: [Firebird-docs] Docs, create, I can

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

Hello Nigel,

> I'm interested in writing a few docs for Firebird, as I've been
> contributing to FreeBSD forums (under the name of Squidge), and have
> found myself enjoying it...

Sounds good so far :-)

> I don't know XML, DocBook, and can't run OpenOffice,

OpenOffice is of no use to us, as it doesn't support DocBook. What you
need to know about DocBook in order to write Firebird docs can be
learned in less than an hour. I'm currently writing a Firebird
Docwriting Howto covering - among other things - how to write DocBook
XML. I expect it to be ready in less than a week.

> but I can create a PDF in an instant from a documentation engine.

I visited your pages, they look really good! And so does the PDF. Can
I ask what engine you use to generate it? It does a better job than
ours :-)

On thing though: the "Firebird Documentation Project" already exists,
as a subproject of the official Firebird Project at SourceForce. So if
you continue with yours as a separate project, I think you'd better
give it another name in order to avoid confusion.


> Hopefully, it's a matter of, 'The more, The merrier?'

Well, yes and no. The more good documentation, the better. But for the
project at SourceForge we
a) really want DocBook sources (if you can't produce that, someone
   else will have to convert it, which takes time), and
b) would like to coordinate things a bit so there's not too much overlap.
   Of course this doesn't mean that WE decide what YOU write about; just
   that the docwriters talk about what they would like to / are going to
   write about, so we can make the best possible use of our collective
   knowledge and skills.

If you want to keep your docs outside the SourceForge project, you can
basically do as you please, but even then it would be a good idea to
keep in touch with the other doccers to avoid duplication.


> Are there areas that need urgent focus? I specialise in FreeBSD,
> PHP, and Apache-based web-apps, powered by Firebird, so perhaps a
> few tutes in that area, or is it saturated already?...

Not that I know. *Certainly* not in the SourceForge project. To date,
we have very little: an introduction, an MS-SQL-To-Firebird Migration
Guide, a Docbuilding Howto, a second Howto in the making and that's
it. And I'll start documenting the Firebird API soon.

Now there's also a lot of free docs (and pointers to it) available at
ibphoenix.com. I suggest you have a look there to see if some of the
things you mentioned have already been taken care of, and then decide
on what to start with.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Docs, create, I can

[<Ste...@si...>]

Hi Paul,

>*Certainly* not in the SourceForge project. To date,
>we have very little: an introduction, an MS-SQL-To-Firebird Migration
>Guide,

I'm having a bad time finding the MS SQL to Firebird Migration doc on 
Sourceforge. Where is it?

I already have the migration doc from IBPhoenix:

        http://www.ibphoenix.com/a542.htm

and the one from Marcelo Lopez Ruiz:

        http://www.xlprueba.com.ar/ib/defaulthtml/ch01.html

I'm assuming neither of these are the Sourceforge doc. Or am I just not 
with it yet today?

Steve Miller
Language Software Development
SIL International

Re: [Firebird-docs] Docs, create, I can

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

Hi Steve,

> I already have the migration doc from IBPhoenix:
>
>         http://www.ibphoenix.com/a542.htm
>
> and the one from Marcelo Lopez Ruiz:
>
>         http://www.xlprueba.com.ar/ib/defaulthtml/ch01.html
>
> I'm assuming neither of these are the Sourceforge doc. Or am I just
> not with it yet today?

At SF, we have the one from Marcelo, but for the moment only as a
DocBook XML source. If you want to build it you'd have to checkout the
manual module. But since you already have it...

This situation is going to change in the near future; we'll place the
finished docs as PDF and/or HTML in the files section. But first I
would like to finish the Docwriting Howto and improve the PDF output
if possible. It really doesn't look good.


Greetings,
Paul Vinkenoog

RE: [Firebird-docs] Docs, create, I can

[Nigel W. <ni...@e-...>]

Hi Paul,

> I visited your pages, they look really good! And so does the PDF. Can
> I ask what engine you use to generate it? It does a better job than
> ours :-)
> 

I wrote the engine myself. It's fully PHP and Firebird powered, and a cron
job to create the PDF every 5 minutes.
Doc Writers need only register on the site, and start producing articles.
Moderators decide when the article is ready for inclusion in the book.

It's probably an ideal system for multiple doc writers to prepare their
articles, and get them included in the final documentation...(I dunno)

> On thing though: the "Firebird Documentation Project" already exists,
> as a subproject of the official Firebird Project at SourceForce. So if
> you continue with yours as a separate project, I think you'd better
> give it another name in order to avoid confusion.
> 

Already changed. It's now called 'Firebird Pocketbook'. PDF should have
caught up by the time you get this email...

> 
> > Hopefully, it's a matter of, 'The more, The merrier?'
> 
> Well, yes and no. The more good documentation, the better. But for the
> project at SourceForge we
> a) really want DocBook sources (if you can't produce that, someone
>    else will have to convert it, which takes time), and

I'm presuming this is so you can quickly convert from XML markup, into
HTML/PDF in a snap. This system uses simple tags for bolds/underlines/code
snippets, etc, and generates HTML/PDF for you instantly. Perhaps I can make
your life easier.
Or perhaps I can add a DocBook output filter...

> b) would like to coordinate things a bit so there's not too 
> much overlap.
>    Of course this doesn't mean that WE decide what YOU write 
> about; just
>    that the docwriters talk about what they would like to / 
> are going to
>    write about, so we can make the best possible use of our collective
>    knowledge and skills.

Unfortunately my skills include:
Bare-iron installs(framework in pocketbook)
Securing databases(framework in pocketbook)
Theories of database design
Tables/triggs/st.procs/ref.integ/exceptions (no views yet - haven't had a
need yet)
PHP based apps, both web and command-line

> Not that I know. *Certainly* not in the SourceForge project. To date,
> we have very little: an introduction, an MS-SQL-To-Firebird Migration
> Guide, a Docbuilding Howto, a second Howto in the making and that's
> it. And I'll start documenting the Firebird API soon.
> 
> Now there's also a lot of free docs (and pointers to it) available at
> ibphoenix.com. I suggest you have a look there to see if some of the
> things you mentioned have already been taken care of, and then decide
> on what to start with.
> 
I wouldn't mind wrapping many of these how-to's and docs into one
pocketbook. Any problems here?
(References would be listed, or course)

Nige.

RE: [Firebird-docs] Docs, create, I can

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

Hi Nigel,

>> I visited your pages, they look really good! And so does the
>> PDF. Can I ask what engine you use to generate it? It does a better
>> job than ours :-)

> I wrote the engine myself. It's fully PHP and Firebird powered, and
> a cron job to create the PDF every 5 minutes.

But did you also write the part that does the actual PDF rendering?


>> Well, yes and no. The more good documentation, the better. But for
>> the project at SourceForge we
>> a) really want DocBook sources

> I'm presuming this is so you can quickly convert from XML markup,
> into HTML/PDF in a snap.

Not only that. Also important is that it's an open standard,
platform-independent, and especially that it's completely
makeup-free. DocBook elements (there are hundreds, of which we
actively use a few dozens) are all about structure and semantics,
never about layout or makeup. This makes it ideal for storing
technical documentary content. The makeup of the rendered documents
is controlled through stylesheets.

> This system uses simple tags for bolds/underlines/code snippets,
> etc, and generates HTML/PDF for you instantly. Perhaps I can make
> your life easier.

Your system will certainly be easier to use, but it doesn't have the
richness of DocBook, _and_ it includes makeup codes. Please don't take
this as criticism: like I said, I thought the output looked great.

DocBook is not really hard to learn, but for some people it could be
an obstacle just high enough to keep them from contributing at all.
For these people your setup could be a godsend.

> Or perhaps I can add a DocBook output filter...

Yes, but it would only output very poor DocBook. For it would have to
drop all the bold, italics etc. stuff (since that doesn't exist in
DocBook) and it would not know where and how to apply other DocBook
tags such as <database>, <filename>, <literal>, <blockquote>,
<example>, <bookinfo>, etc. etc., and there's also the question of
assigning IDs to elements (often necessary in DocBook for
cross-referencing).

So this output would then have to be edited by someone who's
knowledgeable about DocBook and about the subject matter, possibly in
cooperation with the original author. Of course that's still
better than not having the doc at all... but I really do hope people
will want to invest a little time to learn DocBook. The Docwriting
Howto will include all you need to know to get started, and I think
you can master the DocBook part in less than an hour - not to learn it
by heart, but to read and understand it, and to get started with the
docwriting. But maybe that's overoptimistic; I'm really interested to
know what people think of it once they read it.

> Unfortunately my skills include:
> Bare-iron installs(framework in pocketbook)
> Securing databases(framework in pocketbook)
> Theories of database design
> Tables/triggs/st.procs/ref.integ/exceptions (no views yet - haven't
> had a need yet)
> PHP based apps, both web and command-line

What do you mean: unfortunately? I think you could make some nice
Firebird-related docs with this knowledge :-)

> I wouldn't mind wrapping many of these how-to's and docs into one
> pocketbook. Any problems here?
> (References would be listed, or course)

That would require the permission of each individual author, unless
they explicitly state in their documents that it's OK to republish
them in another format.

Can you have more than one pocketbook at your site? I sure hope so
because to cram all the docs together in one giant PDF is not exactly
ideal...


OK, signing off now... tired...

Paul Vinkenoog

RE: [Firebird-docs] Docs, create, I can

[Nigel W. <ni...@e-...>]

> But did you also write the part that does the actual PDF rendering?

Ah heck no, that's "htmldoc", a tool for turning all sorts of docs into all
sorts of other docs

> DocBook elements (there are hundreds, of which we
> actively use a few dozens) are all about structure and semantics,
> never about layout or makeup. This makes it ideal for storing
> technical documentary content. The makeup of the rendered documents
> is controlled through stylesheets.

Groovy!
 
> Your system will certainly be easier to use, but it doesn't have the
> richness of DocBook, _and_ it includes makeup codes. Please don't take
> this as criticism: like I said, I thought the output looked great.
> 
> DocBook is not really hard to learn, but for some people it could be
> an obstacle just high enough to keep them from contributing at all.
> For these people your setup could be a godsend.

Well, it's there if people want to have a go. Just register, create,
preview, and submit to a section for moderation...;-)

 
> The Docwriting
> Howto will include all you need to know to get started, and I think
> you can master the DocBook part in less than an hour - not to learn it
> by heart, but to read and understand it, and to get started with the
> docwriting. But maybe that's overoptimistic; I'm really interested to
> know what people think of it once they read it.

I shall peruse it when it's available! ;-)

> Can you have more than one pocketbook at your site? I sure hope so
> because to cram all the docs together in one giant PDF is not exactly
> ideal...

I would imagine so. The P133 has 40MB ram, so it should do it just fine.
I could quickly break out each section into it's own pocketbook - rough, but
a start.

Have a good night's sleep!

N.