1
=======================
3
=======================
5
:Author: Engelbert Gruber
6
:Contact: grubert@users.sourceforge.net
7
:Revision: $Revision: 1.32 $
8
:Date: $Date: 2004/05/09 15:49:30 $
9
:Copyright: This document has been placed in the public domain.
17
Producing LaTeX code from reST input could be done in at least two ways:
19
a. Transform the internal markup into corresponding LaTeX markup e.g.
20
a section title would be written as ```\section{this section ...}``.
21
b. Using LaTeX as a typesetting system to produce desired paperwork
22
without caring about loosing document structure information.
24
The former might be preferable, but limits to LaTeXs capabilities, so
25
in reality it is a mix. The reality is that LaTeX has a titlepage with
26
title, author and date, by default only title is used. Author and date
27
are shown in the docutils docinfo table and set to blank for LaTeX.
28
To get author and date set by LaTeX specify option "use-LaTeX-docinfo".
33
Configuration can be done in two ways (again):
35
1. Options to the docutils tool: e.g. language selection.
36
2. Options to LaTeX via the stylesheet file.
38
The generated LaTeX documents should be kept processable by a standard
39
LaTeX installation (if such a thing exists), therefore the document
40
contains default settings. To allow *overwriting defaults* the stylesheet
43
Run ``rst2latex.py --help`` to see the command-line options, or have look in
47
===================== ================================================
48
Setting/Config Entry Description
49
===================== ================================================
50
papersize Default: a4paper. Paper geometry can be changed
51
using ``\geometry{xxx}`` entries.
55
* a4paper, b3paper, letterpaper, executivepaper,
57
* landscape, portrait, twoside.
59
and a ton of other option setting margins.
63
\geometry{a5paper,landscape}
64
--------------------- ------------------------------------------------
65
paragraph indent By default LaTeX indents the forst line in a
66
paragraph. The following lines set indentation
67
to zero but add a vertical space between
70
\setlength{\parindent}{0pt}
71
\setlength{\parskip}{6pt plus 2pt minus 1pt}
72
--------------------- ------------------------------------------------
73
admonitionwidth The width for admonitions.
74
Default: 0.9*textwidth, this can be changed
77
\setlength{\admonitionwidth}{0.7\textwidth}
78
--------------------- ------------------------------------------------
79
docinfowidth The width for the docinfo table.
80
Default: 0.9*textwidth, changed to e.g.::
82
\setlength{\docinfowidth}{0.7\textwidth}
83
--------------------- ------------------------------------------------
84
rubric style The header contains the definition of a new
85
LaTeX command rubric. Inserting::
87
\renewcommand{\rubric}[1]{\subsection*{
88
~\hfill {\color{red} #1} \hfill ~}}
90
sets rubric to subsection style in red.
92
Default: subsection style italic.
93
--------------------- ------------------------------------------------
94
font selection see below
95
===================== ================================================
100
* Selection of LaTeX fontsize.
101
* Assumed reST linelength for table width setting.
106
When generating pdf-files from LaTeX, use the pdflatex command, the files
107
are a lot smaller if postscript fonts are used. To do so put
108
``\usepackage{times}`` into the stylesheet.
110
It is said that the typewriter font in computer modern font, the default
111
LaTeX font package, is too heavy compared to the others. There is a package
112
or some commands too fix this, which i currently cannot find.
114
Some people diagnose a similar unbalance for the postscript fonts, the
115
package to fix this is ``\usepackage{pslatex}``.
116
pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
121
A table of figures can be generated by a command directly to LaTeX::
127
LaTeX also has a command ``\listoftables``.
132
If section numbering and LaTeX table of contents is used LaTeX and
133
docutils will number sections. To switch off displaying of LaTeX's
134
numbers one has to add following lines to the stylesheet ::
136
% no section number display
138
\def\@seccntformat#1{}
141
\renewcommand{\numberline}[1]{}
144
Commands directly to LaTeX
145
==========================
147
By means of the reST-raw directive one can give commands directly to
148
LaTeX, e.g. forcing a page break::
155
Or setting formulas in LaTeX::
159
$$x^3 + 3x^2a + 3xa^2 + a^3,$$
162
Or making a colorbox: If someone wants to get a red background for a textblock,
163
she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
164
reStructuredText do something like this::
167
Nobody expects the spanish inquisition.
170
.. |begincolorbox| raw:: LaTeX
174
\\parbox{0.985\\linewidth}{
176
.. |endcolorbox| raw:: LaTeX
185
Currently maketitle only shows the title and subtitle, date and author are shown
186
in the docinfo table.
188
To change the titlepage layout, e.g. see fancyhdr, one must redefine the
189
maketitle command in the stylesheet::
191
\renewcommand{\maketitle}{
194
\textsf{TITLE \@title} \\
200
``\@title`` contains the title.
205
Open to be fixed or open to discussion.
210
Does not work, or only in verbatim or verb.
215
:Tablewidth: reST-documents line length is assumed to be 80 characters. The
216
tablewidth is set relative to this value. If someone produces
217
documents with line length of 132 this will fail.
219
Table width is tried to fit in page even if it is wider than
220
the assumed linewidth, still assumed linewidth is a hook.
222
* In tools.txt the option tables right column, there should be some more spacing
223
between the description and the next paragraph "Default:".
225
Paragraph separation in tables is hairy.
226
see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
228
- The strut solution did not work.
229
- setting extrarowheight added ad top of row not between paragraphs in
230
a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
231
- baselineskip/stretch does not help.
232
* Should there be two hlines after table head and on table end ?
233
* Table: multicol cells are always {l}.
234
* Table heads and footer for longtable (firstpage lastpage ..).
235
* Longtable does not work with multirow
236
* Tabularx says "do not use any multicolmn which spans any X column.
237
maybe use ltxtable instead of tabularx (Longtable combined with tabularx).
238
but ltxtable disables longtable's multicolumn.
239
* Table cells with multirow and multicolumn
244
* The underscore ``_`` does not work in literal-blocks, has different width.
247
- Escape it ``{\_}`` to narrow
248
- Underline a blank ``\underline{ }`` to low, as in windows-xp.
249
- Subscript a hyphen ``$_{\tt-}$`` too wide and thin
250
- ``$_{-}$`` the same.
252
* recongize LaTeX and replace by ``\LaTeX``.
253
* Support embed-stylesheet.
254
* the ^-sign is problematic: using mathmode wedge is usually the wrong font.
256
* Maybe add end of line after term in definition list. see
257
http://roundup.sf.net/doc-0.5/features.pdf
258
* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
259
* center subsection{Abstract} gives a LaTeX error here.
260
``! LaTeX Error: Something's wrong--perhaps a missing \item.``
261
Committed a HACK: centering by hfill.
262
* Document errors are also too silent.
263
* Use optionlist for docinfo, the table does only work for single page.
264
* Consider peter funk's hooks for TeXpert:
266
* Define his own document preamble (including the choice to
267
choose his own documentclass. That would make the ``--documentclass``
268
option superfluous). I suggest to call this option ``--preamble``
269
* Use two additional hooks to put additional stuff just behind the
270
``\begin{document}`` and just before the ``\end{document}`` macros.
271
Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
272
``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
273
for larger documents.
275
* Hyphens: co-developers should be co--developers ?
276
* The indentional problematic error in test.txt is not referring anywhere.
277
* Footnotes are not all on the same page (as in tools/test.txt) and do not link back
279
* No link to system errors.
280
* Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt
281
2.14 directives directives
282
* Meta keywords into pdf ?
283
* Pagestyle headings does not work, when sections are starred.
284
* For additional docinfo items: the field_body is inserted as text, i.e. no
286
* Multiple author entries in docinfo (same thing as in html).
287
* pslatex has not textbackslash ind bold ?
288
* make use (but test against pslatex) ::
290
\textbackslash \backslash \
294
\textasciicircum \hat ^
295
\textasciitilde \tilde ~
296
\textbullet \bullet gef�llter Kreis auf halber H�he
297
\textperiodcentered \cdot �
298
\textvisiblespace (n.v.) sichtbares Leerzeichen
added
removed
docs/latex.txt
