Re: [Firebird-docs] Docs Built with Ventura

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

Hi Darcy,

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

Do you have any suggestion how? Without breaking DocBook validity,
that is. The only possibility I see is to use the "role" attribute and
scan for that in your import definition. However, this would impose on
every docwriter the task to manually add this attribute whenever he or
she inserts a <para> in certain situations. I don't know if this will
work in practice.
On a more philosophical level, it does kind of "pollute" the source
document.

If we should take this route: what would you like to see in there, and
in which situation(s) exactly?

>> 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.

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. That's why we should be careful not to bend our
DocBook sources in order to satisfy one particular representation. If
already we succeeded (which is doubtful) we might wind up with less
clean DocBook sources and as a result get al kinds of other problems
later, e.g. when we start rendering to new formats like HTML Help, or
formats that don't even exist yet today.

Again, the problem you're facing right now is not in the DocBook
sources but in the rendering. So if possible, that's where we should
deal with it, not in the sources - because those are fine.


Now, about listing the tags and reporting the use of "new" tags: I
don't think we can ask that from the docwriters. They are supposed to
produce valid DocBook and apply the right tag for the situation. If
they would have to check the tags they use against an external list
and maintain a second list to report any tag you haven't taken care of
yet, things become pretty cumbersome.

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).


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.


Greetings,
Paul Vinkenoog