1
================================
2
Generating LaTeX with Docutils
3
================================
5
:Author: Engelbert Gruber
6
:Contact: grubert@users.sourceforge.net
7
:Revision: $Revision: 3415 $
8
:Date: $Date: 2005-06-01 02:56:39 +0200 (Wed, 01 Jun 2005) $
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
Configuration Issue 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
line spacing Is done with package *setspace*, which gives
95
singlespace, onehalfspace and doublespace
96
commands. To get documentwide double spacing,
97
add this to your stylesheet ::
106
And yet another, add ``doublesp`` to the
107
documentoptions and e.g. ::
111
for bigger linespacing.
112
--------------------- ------------------------------------------------
113
font selection see below
114
===================== ================================================
120
When generating pdf-files from LaTeX, use the pdflatex command, the files
121
are a lot smaller if postscript fonts are used. This *was* fixed by putting
122
``\usepackage{times}`` into the stylesheet.
124
It is said that the typewriter font in computer modern font, the default
125
LaTeX font package, is too heavy compared to the others. There is a package
126
or some commands too fix this, which i currently cannot find.
128
Some people diagnose a similar unbalance for the postscript fonts, the
129
package to fix this is ``\usepackage{pslatex}``.
130
pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
132
As ``times`` does not use the appropriate mathematical fonts and ``pslatex``
133
does not work with T1 encodings one should use::
135
\usepackage{mathptmx}
136
\usepackage[scaled=.90]{helvet}
139
*font encoding* can be selected with option "font-encoding". Default
140
uses package "ae" for old style font encoding use "OT1".
145
The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to
146
10000 almost prevents hyphenation. As this produces lines with more spcea
147
between words one should increase LaTeX's ``\tolerance`` for this.
157
The generated LaTeX documents are in latin1 encoding per default, if unicode
158
characters are required one must set ``--output-encoding=utf-8`` install
159
`LaTeX unicode`_ support and add::
162
\usepackage[utf8]{inputenc}
164
to the stylesheet. If LaTeX issues a Warning about unloaded/known characters
167
\PreloadUnicodePage{n}
169
where *n* is the unicode pagenumber, might help.
171
.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
176
A table of figures can be generated by a command directly to LaTeX::
182
LaTeX also has a command ``\listoftables``.
187
If section numbering and LaTeX table of contents is used LaTeX and
188
docutils will number sections. To switch off displaying of LaTeX's
189
numbers one has to add following lines to the stylesheet ::
191
% no section number display
193
\def\@seccntformat#1{}
196
\renewcommand{\numberline}[1]{}
199
Number pages by chapter
200
-----------------------
202
This can be accomplished with ::
206
From the documentation
208
Basic operation of the package is to redefine ``\thepage`` to be
209
``\thechapter-\arabic{page}``, and to cause the page number to be reset
210
(to 1) at the start of each chapter. So the pages of chapter 3 will
211
be numbered 3-1, 3-2, ..., and the pages of appendix B will be
212
numbered B-1, B-2, ...
214
See documentation for details and other possibilities.
219
Images are included in LaTeX by the graphicx package. The supported
220
image formats depend on the used driver (dvi, dvips, pdftex, ...).
222
If pdf-image inclusion in pdf files fails, specify
223
``--graphicx-option=pdftex`` or ``--graphicx-option=auto``.
226
Commands directly to LaTeX
227
==========================
229
By means of the reST-raw directive one can give commands directly to
230
LaTeX, e.g. forcing a page break::
237
Or setting formulas in LaTeX::
241
$$x^3 + 3x^2a + 3xa^2 + a^3,$$
244
Or making a colorbox: If someone wants to get a red background for a textblock,
245
she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
246
reStructuredText do something like this::
249
Nobody expects the spanish inquisition.
252
.. |begincolorbox| raw:: LaTeX
256
\\parbox{0.985\\linewidth}{
258
.. |endcolorbox| raw:: LaTeX
267
Currently maketitle only shows the title and subtitle, date and author are shown
268
in the docinfo table.
270
To change the titlepage layout, e.g. see fancyhdr, one must redefine the
271
maketitle command in the stylesheet::
273
\renewcommand{\maketitle}{
276
\textsf{TITLE \@title} \\
282
``\@title`` contains the title.
287
Open to be fixed or open to discussion.
289
footnotes and citations
290
-----------------------
292
Initially both were implemented using figures, because hyperlinking back
293
and forth seemed to be impossible. Later images were put into figures.
295
This results in footnotes images and figures possibly being mixed at page
298
* Use LaTeX footnotes and citations for printing or more complex layout.
299
* Footnotes and citations done with figures might excell in hyperlink
302
If ``use-latex-citations`` is used a bibliography is inserted right at
303
the end of the document. *This should be customizable*.
308
:Tablewidth: reST-documents line length is assumed to be 80 characters. The
309
tablewidth is set relative to this value. If someone produces
310
documents with line length of 132 this will fail.
312
Table width is tried to fit in page even if it is wider than
313
the assumed linewidth, still assumed linewidth is a hook.
315
* In tools.txt the option tables right column, there should be some more spacing
316
between the description and the next paragraph "Default:".
318
Paragraph separation in tables is hairy.
319
see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
321
- The strut solution did not work.
322
- setting extrarowheight added ad top of row not between paragraphs in
323
a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
324
- baselineskip/stretch does not help.
325
* Should there be two hlines after table head and on table end ?
326
* Table: multicol cells are always {l}.
327
* The contents of a rowspan cell do not influence table height.
328
(Maybe if we put a tabular inside ?)
329
* Table heads and footer for longtable (firstpage lastpage ..).
330
* Table cells with multirow and multicolumn
331
* literal-blocks in table cells:
333
- If verbatim or flushleft is used one gets vertical space above and below.
334
- This is bad for the topmost paragraph in a cell, therefore the writer
336
- Ragged right fails on followup paragraphs as the vertical space would be
342
* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
347
* Selection of LaTeX fontsize configurable.
348
* Assumed reST linelength for table width setting configurable.
349
* literal-block indentation configurable.
350
* recongize LaTeX and replace by ``\LaTeX``.
351
* Support embed-stylesheet.
353
* Maybe add end of line after term in definition list. see
354
http://roundup.sf.net/doc-0.5/features.pdf
355
* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
356
* center subsection{Abstract} gives a LaTeX error here.
357
``! LaTeX Error: Something's wrong--perhaps a missing \item.``
358
Committed a HACK: centering by hfill.
359
* Document errors are also too silent.
360
* Use optionlist for docinfo, the table does only work for single page.
361
* Consider peter funk's hooks for TeXpert:
363
* Define his own document preamble (including the choice to
364
choose his own documentclass. That would make the ``--documentclass``
365
option superfluous). I suggest to call this option ``--preamble``
366
* Use two additional hooks to put additional stuff just behind the
367
``\begin{document}`` and just before the ``\end{document}`` macros.
368
Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
369
``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
370
for larger documents.
372
* The indentional problematic error in docs/user/rst/demo.txt is not
374
* Footnotes are not all on the same page (as in
375
docs/user/rst/demo.txt) and do not link back and forth.
376
* No link to system errors.
377
* Hyperlinks are not hyphenated; this leads to bad spacing. See
378
docs/user/rst/demo.txt 2.14 directives.
379
* Meta keywords into pdf ?
380
* Pagestyle headings does not work, when sections are starred.
381
* For additional docinfo items: the field_body is inserted as text, i.e. no
383
* Multiple author entries in docinfo (same thing as in html).
384
* keep literal-blocks together on a page, avoid pagebreaks.
386
failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
added
removed
docs/user/latex.txt
