1 files changed, 134 insertions, 0 deletions
diff --git a/doc/asciidoc/examples/website/latex-bugs.txt b/doc/asciidoc/examples/website/latex-bugs.txt
new file mode 100644
index 0000000..d241cdb
--- /dev/null
+++ b/doc/asciidoc/examples/website/latex-bugs.txt
@@ -0,0 +1,134 @@
+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 `&#960;` 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?