Re: [Firebird-docs] Fixing XML issues in docbook

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

Mark Rotteveel wrote:

[conversion DocBook -> asciidoc:]

> While working on this, I noticed that some documents apply weird tricks 
> to offset source listings. For example sometimes <programlisting> or 
> <screen> is wrapped in a <blockquote> so the code-block is offset from 
> the page margin, or they have a wide whitespace prefix so the code has 
> an offset inside the code-block. These seem to be tricks that might have 
> better been solved through styling.

As for the first category, you can achieve this by styling if you want
*all* instances of an element offset (or applied a certain makeup to)
in the same way, which is not always the case.

About extra spaces *within* a block element, this can be valid to
indent individual lines, e.g.:

  select this
  from that
    join yonder using (distance)
  where something < other_thing
    and everything > zilch
  order by num_entities
 
So I would leave those in, but replace spaces that push the block as a
whole by a styling rule (or wrap it in a blockquote ;-))

> When converting to asciidoc, such tricks result in markup that is less 
> than optimal (and the default styles will render it as a quote, which 
> this isn't).
>
> Are there objections if I 'normalize' this as well (no <blockquote>, and 
> no extra whitespace inside the <programlisting>)?

Is a blockquote (or its asciidoc equivalent) rendered with quote
characters around it by default? That's unwanted in most, if not all
cases where we used <blockquote>s. No objections from my side if you
change this to whatever you deem best, as long as in-block line
indentations are preserved (except where they make no sense at all,
but in those cases you should probably consult the author).

Cheers,
Paul Vinkenoog