Re: [Firebird-docs] Docs Built with Ventura

[Darcy O'N. <ds...@sk...>]

Hello,

> Another consideration is that there's nothing wrong with the DocBook
> format as such. The problem you're facing now has to do with importing
> it into Ventura (which does support XML, but unfortunately not
> DocBook). So if the problem can be solved it has to be solved there,
> not by bending or breaking the DocBook standard.

I didn't mean to break the DocBook standard just identify certain <para> 
tags better.

>>Are we looking to be 100% compatible with DocBook?
> 
> It's not really a question of being "compatible" - our docs *are*
> DocBook docs. And the processing tools we use are based on that. It
> just so happens they do a poor job when it comes to PDF.

Actually the real documents are HTML, PDF and possible RTF. Nobody reads 
a DocBook XML file. The DocBook standard is only a 'means to an end', 
and a way to manage the information. The users of the Firebird database 
are expecting to read the documents in an easily recognizable and 
standard format i.e. Paper, PDF, HTML

The comment about being 100% compatible is better said as: can we 
reasonably be expected to support all the tags, from the start, in the 
DocBook standard when creating manuals if we want to develop quality 
manuals.

>>I'm thinking should we freeze the tags we use now, and then as
>>people have a need for more advanced stuff we add them as we go.
> 
> That would first require the generation of a list with all the tags we
> use now, and then ask people to avoid other tags if they can. 

Actually we don't want people to avoid tags, just tell us when they are 
going to use them, if they aren't on the current list, then I can add 
them to the mapping file and it will work fine. Without that notice the 
doc will publish fine but the section using the new tag won't look like 
the author intended.

  > - First realize it doesn't have to be solved in a week. If you see a
>   chance to develop a fix but it will take more time, by all means
>   take your time! If we can have these great-looking PDF versions in
>   half a year, without the errors they contain now: fine.
> 
> - Second: if it really can't be fixed, we could add a transformation
>   layer between the DocBook XML and Ventura. That is: we could develop
>   XSL stylesheets that convert the DocBook XML files to something
>   that's similar but with the "problem tags" removed or replaced by
>   other tags (which we could define ourselves). This layer wouldn't be
>   DocBook anymore; it would only be used for the Ventura import. Mind
>   you: this could take months too before it worked! But that's no
>   reason not to start with it if we can't fix it otherwise.

The best solution is to do a document release. i.e. freeze the document 
at a certain point, cut it and then process it with Ventura. Any errors 
can be hand edited. Now to most computer people automations is what they 
are used too, from a desktop publishers standpoint you have to manually 
go through each page and make the document perfect. If that means a few 
hours of hand editing for a better document then I'd prefer to do that. 
Spending days or hours making a 'transform layer' isn't worth it.

>   Before we do such a thing though, we could also have a look at
>   improving the current FO-producing stylesheets. After all, if we can
>   produce good and attractive PDF without Ventura, this would even be
>   better. But this too will take a lot of time I'm afraid.

That's the current benefit of Ventura in that it is designed to publish 
books and make them look good without a lot of time. I suspect that if 
we get the XML import at 90 to 95% the other stuff can be hand edited to 
make the document perfect.

Darcy O'Neil