Re: [Firebird-docs] Docs Built with Ventura

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

Hi Darcy,

> 1. The use of the <para> tag, especially when nested in
> <itemizedlist> - <listitem>, is causing some problems. The reason
> for this is that in Ventura you specify the relationship of the tag
> <itemizedlist><listitem><para> and then Ventura knows what 'Style'
> to apply to that section. The problem comes into play when Ventura
> doesn't recognize the 'tree structure', so it just applies the
> standard <para> tag. And in this case it should have bullet's.

But a standard <para> shouldn't have a bullet, should it? Is the
problem maybe that Ventura _does_ remember "we're inside a bulleted
list now" and then gives each paragraph a bullet just like Word does?
DocBook is like HTML in this respect: a listitem gets one bullet,
right at the start, no matter what happens inside.

What happens if you import an HTML file containing a structure like
this:

  <ul>
    <li>
      <p>First paragraph inside listitem</p>
      <p>Second paragraph inside listitem</p>
      <p>Third paragraph inside listitem</p>
    </li>
    <li>
      ...
    </li>
  </ul>

Do all the paragraphs get bullets too?

> In short to make it convenient we need to figure out a way for
> Ventura to recognize the nested tags without me building every
> possible relationship. This can even cause havoc in the Section tags
> <sect1> <sect2> etc. But luckily they only go to <sect5> so it's
> limited.  However, you can infinitely nest tags.
>
> Basically, should we use <simpara> for the simple paragraphs,

It wouldn't solve the problem, because there would still be a lot of
paras-in-listitems left that contain blockquotes, programlistings etc.
You can't use a <simpara> there. Also, many DocBook-aware XML editors
start a <para> when you hit Enter. The docwriter would have to
manually change that to <simpara> all the time (and then back to
<para> as soon as he includes a block element in the paragraph).

> or possible use and 'element' tag to identify nested tags?

What do you mean by that? In any case we can't invent new tags because
then the document isn't DocBook anymore. Editors will deem it invalid
and refuse to treat it as DocBook (you could still edit it as general
XML but then you lose all the DocBook validation). Processors will
break on it. So that's simply not an option.

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.

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

> 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. That's
not a good approach. One of the reasons DocBook was chosen is its
richness of structural and semantical tags. If you author a DocBook
doc, you should always use the best-fitting tag for the situation, AND
only choose tags on the basis of meaning. You should never try to
choose tags for presentational reasons, or because proprietary
application A or B can't deal with certain tags or combinations
thereof. As soon as you start doing that, you are working towards one
specific representation of the text (possibly harming other
renderings) and you make your document less valuable.

Try to look at it this way: the DocBook XML version *is* the document.
The HTML and PDF renderings are ways to look at it, they are a kind of
viewport. If we have a problem with the rendering, we must try to fix
the rendering, not change the document itself.

That said, you're still left with the problem. As an outsider to
Ventura I can't say if it can be fixed, and how. But:

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

  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.


Greetings,
Paul Vinkenoog