gnu-social/vendor/zetacomponents/document/docs/conversion.txt
2021-07-16 19:44:40 +01:00

84 lines
2.6 KiB
Plaintext

====================
Document conversions
====================
This document aims to document a list of semantic markup elements, which can
not be converted into one or another markup language, so you have to expect
loss in the semantic document information during conversions.
Source RST
==========
Conversion loss, when the source is a RST document.
Docbook
-------
- Strong emphasis
There is no strong emphasis markup in Docbook, so we use <emphasis
role="strong"/> for this, while the role may be lost during further
conversions.
- Table colspan
Table colspan are available in Docbook, but the markup is rather unintuitive
and hard to read. These information may be lost during further conversions.
- Footnote enumeration
In docbook footnote do not have any user assigned enumeration, while in RST
there may be multiple footnotes with the same (labeled) user assigned
number. This information is completely lost during conversion.
- Substitutions
The substitution references are not preserved, but just substituted during
the conversion process. The information about the parts which were
substituted is completely lost.
- Line blocks / literal blocks
Line blocks and literal blocks are converted to <literalblock> elements,
only differing by the given class attribute.
- Bullet list tokens
The information which kind of bullet list token has been used is completely
omitted during the conversion.
XHTML
-----
- Headers
XHtml only allows a specification of header levels from 1 to 6. All headers
with a depth of ≥ 6 contain a class attribute specifying their real depth.
- Blockquote annotations
There is no XHtml element for blockquote annotations, so that they are
transformed to <div class="annotation"/> elements containing <cite>
elements, which may be considered as a citation source. This information may
be lost during further processing. The cite attribute of blockquotes only
accept URIs.
- Bullet list & ordered list types
XHtml strict does not allow to specify the type of bullet lists or ordered
lists, so that this information is lost during conversion.
- Footnotes
There is no dedicated XHtml element for footnotes, so that footnotes are
referenced inside the text by internal links with the class "footnote", and
the actual footnotes are added below the document in lists of the class
footnote with the proper reference targets.
- Line blocks
Line blocks are transformed into paragraphs, where the lines are seperated
by <br /> elements. This causes the right formatting, but may lose semantic
information.