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
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
