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

[Mark R. <ma...@la...>]

On 28-04-2020 16:47, Paul Vinkenoog wrote:
> 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.

Differentiating between different offsets could probably be achieved by 
adding a role-attribute to the programlisting element (or possibly to 
the (grand)parent element), and defining specific styling for that role.

However, my focus is on transformations that might be easier to do now 
in the docbook sources, than cleaning them up later after conversion.

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

Yes, I'm not talking about indentation within the code, but about extra 
whitespace to offset the entire block of code (that is, each line has a 
prefix of at least <n> spaces).

Right now, for example the fblangref25 applies both tricks 
inconsistently (eg compare syntax of CREATE DATABASE vs ALTER DATABASE 
on 
https://firebirdsql.org/file/documentation/reference_manuals/fblangref25-en/html/fblangref25-ddl-db.html)

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

Blockquotes in asciidoc are - just like in docbook - for quotes, and the 
default styles will make clear it is a quote (but this can of course be 
tweaked). But avoiding these types of semantic issues is better.

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

Yes, my intention is to only remove the prefix spaces, not the 
significant indentation of code.

In any case, I'll probably leave fixing these kinds of issues to just 
before the final conversion of a document, to avoid having to tweak 
docbook styling as well just to preserve the current behavior.

Right now I'm experimenting with the conversion, and I still need to 
look at styling.

Mark
-- 
Mark Rotteveel