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