1 | Bugs in asciidoc latex backend |
---|
2 | ============================== |
---|
3 | Geoff Eddy |
---|
4 | |
---|
5 | Benjamin Klum was unable to maintain the LaTeX backend beyond version |
---|
6 | 8.2.7, and as a consequence the `latex.conf` file ceased to work with |
---|
7 | `asciidoc` sometime after this. For version 8.4.3 I made some changes |
---|
8 | to the file to get it working again. This document summarises the |
---|
9 | remaining issues which I have found with generating LaTeX and thence |
---|
10 | PDF output with `asciidoc`, which is done as follows: |
---|
11 | |
---|
12 | - `asciidoc --backend=latex --unsafe FILE.txt` |
---|
13 | - `latex FILE.tex` |
---|
14 | - `kpdf FILE.pdf` |
---|
15 | |
---|
16 | Many of these were found by processing the `asciidoc.txt` file and |
---|
17 | comparing the HTML output with the PDF. |
---|
18 | |
---|
19 | == Footnotes |
---|
20 | |
---|
21 | Priority:: Low. |
---|
22 | |
---|
23 | Problem:: References to footnotes, and a sensible value for the |
---|
24 | `[footnoteref-inlinemacro]` section, don't seem to be possible. |
---|
25 | |
---|
26 | Cause:: LaTeX doesn't support footnoting much beyond creating a |
---|
27 | footnote at a certain point in text and displaying the footnote |
---|
28 | itself. |
---|
29 | |
---|
30 | Solution:: Unclear. How important or necessary is this, anyway? |
---|
31 | |
---|
32 | == Spurious text at starts of paragraphs |
---|
33 | |
---|
34 | Priority:: Medium |
---|
35 | |
---|
36 | Problem:: It is necessary to insert spurious text in paragraphs. |
---|
37 | |
---|
38 | Cause:: This `asciidoc` input: |
---|
39 | + |
---|
40 | ------------------------------------------------------------------- |
---|
41 | Text |
---|
42 | ------------------------------------------------------------------- |
---|
43 | + |
---|
44 | generates this LaTeX code: |
---|
45 | + |
---|
46 | \begin{lstlisting} |
---|
47 | SPURIOUS TEXTText\end{lstlisting} |
---|
48 | + |
---|
49 | which should be: |
---|
50 | + |
---|
51 | \begin{lstlisting}[] |
---|
52 | Text\end{lstlisting} |
---|
53 | |
---|
54 | Solution:: Find out a way to generate the correct LaTeX output as |
---|
55 | above. The obvious solution, as explained in `latet.conf`, doesn't |
---|
56 | work. |
---|
57 | |
---|
58 | == Tables |
---|
59 | |
---|
60 | Priority:: Rather high. |
---|
61 | |
---|
62 | Problem:: Not all of the table configuration options can be passed |
---|
63 | through to the LaTeX backend. In particular, I've had to assume that |
---|
64 | all tables will be fifteen or fewer left-justified columns wide. |
---|
65 | |
---|
66 | Cause:: The table models in LaTeX and HTML are too dissimilar for one |
---|
67 | `asciidoc` specification to generate valid output in both formats by |
---|
68 | simple regexp replacement. Related to this is the unfortunate fact |
---|
69 | that `<COLGROUP>` and related tags aren't a required part of HTML4, |
---|
70 | and some broswers (at least Firefox and Konqueror) don't implement |
---|
71 | them. |
---|
72 | |
---|
73 | Solution:: Perhaps table processing could be handled by a Python |
---|
74 | plugin, which would read in a table spec and generate the appropriate |
---|
75 | text? |
---|
76 | |
---|
77 | == Unicode escaping |
---|
78 | |
---|
79 | Priority:: Rather high, to me at least. |
---|
80 | |
---|
81 | Problem:: The commented-out section in `latex.conf`, if uncommented, |
---|
82 | converts `π` to `\unichar{960}`, which then causes LaTeX to |
---|
83 | complain that the resulting command is unavailable in encoding T1. The |
---|
84 | more common non-ASCII characters, such as those in `félicité` and |
---|
85 | `Åwieca`, are handled properly, but some - such as the IPA characters |
---|
86 | in the `tipa` package - are not. |
---|
87 | |
---|
88 | Cause:: The encodings in the LaTeX output are wrong. |
---|
89 | |
---|
90 | Solution:: Correct the encodings. |
---|
91 | |
---|
92 | == Text colours |
---|
93 | |
---|
94 | Priority:: Probably low |
---|
95 | |
---|
96 | Problem:: The text colour options are not processed by LaTeX; for |
---|
97 | example `[#ff0000]#Red text#` is not rendered in red. |
---|
98 | |
---|
99 | Cause:: LaTeX and HTML represent RGB triads differently: HTML is happy |
---|
100 | with `#ff8000`, but LaTeX needs `[rgb]{1,0.5,0}`. |
---|
101 | |
---|
102 | Solution:: Provide some sort of internal RGB conversion mechanism |
---|
103 | which can convert RGB triads to different representations. |
---|
104 | |
---|
105 | == Text sizes |
---|
106 | |
---|
107 | Priority:: Probably low |
---|
108 | |
---|
109 | Problem:: The text size options are not processed by LaTeX: |
---|
110 | `[,,1]#text#` is rendered in the same size as normal text. |
---|
111 | |
---|
112 | Cause:: HTML size tags - `h1` through `h7` - are directly derivable |
---|
113 | from the size number, whereas LaTeX has a series of descriptive words |
---|
114 | (`HUGE` through `normalsize` to `scriptsize`). |
---|
115 | |
---|
116 | Solution:: Provide a way to treat the number as an index into an |
---|
117 | array. |
---|
118 | |
---|
119 | == Background colour in paragraphs |
---|
120 | |
---|
121 | Priority:: Medium |
---|
122 | |
---|
123 | Problem:: If the `backgroundcolor` attribute is specified in the |
---|
124 | `lstset` command, all paragraphs are displayed as black rectangles by |
---|
125 | `kpdf`, `xpdf`, and `evince`, although `kdvi` has no problems. I've |
---|
126 | had to remove the attribute, and so paragraphs all appear on white |
---|
127 | backgrounds. The PDF viewers also complain: |
---|
128 | |
---|
129 | Error (NNNN): Unknown operator 'rgb' |
---|
130 | |
---|
131 | Cause:: Apparently a known bug in the output of `pdflatex`. Not a bug |
---|
132 | in `asciidoc`. |
---|
133 | |
---|
134 | Solution:: Wait until this bug is fixed? |
---|