mirror of
https://git.rtems.org/rtems-source-builder
synced 2024-10-09 07:15:10 +08:00
135 lines
4.2 KiB
Plaintext
135 lines
4.2 KiB
Plaintext
Bugs in asciidoc latex backend
|
|
==============================
|
|
Geoff Eddy
|
|
|
|
Benjamin Klum was unable to maintain the LaTeX backend beyond version
|
|
8.2.7, and as a consequence the `latex.conf` file ceased to work with
|
|
`asciidoc` sometime after this. For version 8.4.3 I made some changes
|
|
to the file to get it working again. This document summarises the
|
|
remaining issues which I have found with generating LaTeX and thence
|
|
PDF output with `asciidoc`, which is done as follows:
|
|
|
|
- `asciidoc --backend=latex --unsafe FILE.txt`
|
|
- `latex FILE.tex`
|
|
- `kpdf FILE.pdf`
|
|
|
|
Many of these were found by processing the `asciidoc.txt` file and
|
|
comparing the HTML output with the PDF.
|
|
|
|
== Footnotes
|
|
|
|
Priority:: Low.
|
|
|
|
Problem:: References to footnotes, and a sensible value for the
|
|
`[footnoteref-inlinemacro]` section, don't seem to be possible.
|
|
|
|
Cause:: LaTeX doesn't support footnoting much beyond creating a
|
|
footnote at a certain point in text and displaying the footnote
|
|
itself.
|
|
|
|
Solution:: Unclear. How important or necessary is this, anyway?
|
|
|
|
== Spurious text at starts of paragraphs
|
|
|
|
Priority:: Medium
|
|
|
|
Problem:: It is necessary to insert spurious text in paragraphs.
|
|
|
|
Cause:: This `asciidoc` input:
|
|
+
|
|
-------------------------------------------------------------------
|
|
Text
|
|
-------------------------------------------------------------------
|
|
+
|
|
generates this LaTeX code:
|
|
+
|
|
\begin{lstlisting}
|
|
SPURIOUS TEXTText\end{lstlisting}
|
|
+
|
|
which should be:
|
|
+
|
|
\begin{lstlisting}[]
|
|
Text\end{lstlisting}
|
|
|
|
Solution:: Find out a way to generate the correct LaTeX output as
|
|
above. The obvious solution, as explained in `latet.conf`, doesn't
|
|
work.
|
|
|
|
== Tables
|
|
|
|
Priority:: Rather high.
|
|
|
|
Problem:: Not all of the table configuration options can be passed
|
|
through to the LaTeX backend. In particular, I've had to assume that
|
|
all tables will be fifteen or fewer left-justified columns wide.
|
|
|
|
Cause:: The table models in LaTeX and HTML are too dissimilar for one
|
|
`asciidoc` specification to generate valid output in both formats by
|
|
simple regexp replacement. Related to this is the unfortunate fact
|
|
that `<COLGROUP>` and related tags aren't a required part of HTML4,
|
|
and some broswers (at least Firefox and Konqueror) don't implement
|
|
them.
|
|
|
|
Solution:: Perhaps table processing could be handled by a Python
|
|
plugin, which would read in a table spec and generate the appropriate
|
|
text?
|
|
|
|
== Unicode escaping
|
|
|
|
Priority:: Rather high, to me at least.
|
|
|
|
Problem:: The commented-out section in `latex.conf`, if uncommented,
|
|
converts `π` to `\unichar{960}`, which then causes LaTeX to
|
|
complain that the resulting command is unavailable in encoding T1. The
|
|
more common non-ASCII characters, such as those in `félicité` and
|
|
`świeca`, are handled properly, but some - such as the IPA characters
|
|
in the `tipa` package - are not.
|
|
|
|
Cause:: The encodings in the LaTeX output are wrong.
|
|
|
|
Solution:: Correct the encodings.
|
|
|
|
== Text colours
|
|
|
|
Priority:: Probably low
|
|
|
|
Problem:: The text colour options are not processed by LaTeX; for
|
|
example `[#ff0000]#Red text#` is not rendered in red.
|
|
|
|
Cause:: LaTeX and HTML represent RGB triads differently: HTML is happy
|
|
with `#ff8000`, but LaTeX needs `[rgb]{1,0.5,0}`.
|
|
|
|
Solution:: Provide some sort of internal RGB conversion mechanism
|
|
which can convert RGB triads to different representations.
|
|
|
|
== Text sizes
|
|
|
|
Priority:: Probably low
|
|
|
|
Problem:: The text size options are not processed by LaTeX:
|
|
`[,,1]#text#` is rendered in the same size as normal text.
|
|
|
|
Cause:: HTML size tags - `h1` through `h7` - are directly derivable
|
|
from the size number, whereas LaTeX has a series of descriptive words
|
|
(`HUGE` through `normalsize` to `scriptsize`).
|
|
|
|
Solution:: Provide a way to treat the number as an index into an
|
|
array.
|
|
|
|
== Background colour in paragraphs
|
|
|
|
Priority:: Medium
|
|
|
|
Problem:: If the `backgroundcolor` attribute is specified in the
|
|
`lstset` command, all paragraphs are displayed as black rectangles by
|
|
`kpdf`, `xpdf`, and `evince`, although `kdvi` has no problems. I've
|
|
had to remove the attribute, and so paragraphs all appear on white
|
|
backgrounds. The PDF viewers also complain:
|
|
|
|
Error (NNNN): Unknown operator 'rgb'
|
|
|
|
Cause:: Apparently a known bug in the output of `pdflatex`. Not a bug
|
|
in `asciidoc`.
|
|
|
|
Solution:: Wait until this bug is fixed?
|