Re: [Firebird-docs] Docs Built with Ventura

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

Hello,

>If we should take this route: what would you like to see in there, and
>in which situation(s) exactly?
>  
>
Not sure yet, we have lots of time to figure this out so I'll just keep 
hacking away with the XML Map and see if I can get a reasonable solution.

>
>True, but the HTML, PDF, etc. are also (maybe even more so) "only" a
>means to an end: our goal is to produce documentation and make it
>accessible for the users. The output formats are not goals in
>themselves, they are means to let the user access the information in a
>practical and user-friendly way. In ten years there may be totally
>different output formats, but the DocBook sources will still be valid
>because they don't contain presentational markup - only structured
>informational content. 
>
We're pretty much on the same page here, DocBook manages the 
'information', but the end users require an accessible document. Without 
informed end users there really isn't a project. Since I started using 
Firebird the only docs available we're from Interbase, since we are 
moving away from Interbase it's going to get harder and harder for 
people to migrate from other databases.

Think of it this way: the most poorly managed document system that still 
produces readable documents is better than the best managed document 
system that produces broken and non-user friendly document. Having spent 
years working at one of the worlds largest oil companies I can tell you 
that most of the documents were poorly managed (i.e. Excel = database, 
Word = desktop publishing system, Document Control System - None, Format 
Standard = Microsoft) but very accessible to the end user. Because the 
dumbest people could access the documents, the company was very successful.

>There's a better way to do this: I could write a small program that
>reads any XML file, extracts the tags, and looks them up in a list of
>known tags. Any tags not in the list are reported so you can deal with
>them. This is faster (apart from writing the prog once) and more
>reliable than having everybody doing it manually. If this would be of
>help to you, I could write such a program in 1 - 3 weeks (depending on
>how busy I am with other things).
>  
>
The Ventura XML map actually creates a list of used tags, it would be 
easier for me to use diff to see which new tags were added during a 
'release' period. We should probably concentrate on documenting Firebird 
as opposed to building the perfect doc system, even though that in 
itself is a worthy cause.

>Am I right in saying that the real problem is not in the tags (because
>we can deal with those one by one) but in the nesting? Is Ventura not
>aware of the nesting? That's the impression I get right now.
>  
>
I agree that for the most part the DocBook standard is good, but even 
the in the DocBook guide it clearly states in the <para> description 
that 'Some processing systems may find the presence of block elements in 
a paragraph difficult to handle. - and - There is no easy answer to this 
problem." No single solution is perfect and over time this will get 
better, so for now we'll see what we can do.

Darcy O'Neil