5
5
:Author: Engelbert Gruber
6
6
:Contact: grubert@users.sourceforge.net
7
:Revision: $Revision: 3415 $
8
:Date: $Date: 2005-06-01 02:56:39 +0200 (Wed, 01 Jun 2005) $
7
:Revision: $Revision: 5575 $
8
:Date: $Date: 2008-06-23 11:33:43 +0200 (Mon, 23 Jun 2008) $
9
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".
17
Producing LaTeX code from reST input can be done in at least two ways:
19
a. Transform the internal markup into corresponding LaTeX markup.
20
For example, a section title would be written with the LaTeX section
21
command: ``\section{this section title}``.
23
This can be constrained by the LaTeX document class
24
and may require hacking around bugs/features in LaTeX,
25
but it produces a readable LaTeX file.
27
If you prefer this approach, try ``rst2latex``.
29
b. Use LaTeX as a typesetting system to produce the desired document structure
30
without bothering with the usual LaTeX idioms for representing
31
document structure information.
33
This is not constrained by a particular LaTeX document class
34
and therefore requires hacking around bugs/features in LaTeX.
35
But it produces a hard to read LaTeX file.
37
``rst2newlatex`` adds a lot of LaTeX macros and uses LaTeX as a typesetter
38
without caring about producing readable LaTeX files.
33
Configuration can be done in two ways (again):
44
Configuration can be done in two ways:
35
46
1. Options to the docutils tool: e.g. language selection.
36
2. Options to LaTeX via the stylesheet file.
47
2. Options to LaTeX via a stylesheet file.
38
49
The generated LaTeX documents should be kept processable by a standard
39
50
LaTeX installation (if such a thing exists), therefore the document
63
74
\geometry{a5paper,landscape}
64
75
--------------------- ------------------------------------------------
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
76
paragraph indent The default LaTeX behavior in most document classes
77
is the following: indent the first line in
78
a paragraph unless it is the first line of
79
a chapter, section, subsection, or
82
This is configurable. For example, you could
83
use the following lines to set paragraph
84
indentation to zero but add a vertical space
70
87
\setlength{\parindent}{0pt}
71
88
\setlength{\parskip}{6pt plus 2pt minus 1pt}
111
128
for bigger linespacing.
112
129
--------------------- ------------------------------------------------
130
use verbatim when When possibile, use verbatim for literal-blocks.
131
possible Compatibility alias for "--literal-env=verbatim".
133
A literal-block element, when processed by a
134
docutils-writer might have it's origin in a
135
markup with "::" syntax or a
136
".. parsed-literal::" directive.
138
A LaTeX verbatim environment is only useable if
139
there are no elements contained in the
141
--------------------- ------------------------------------------------
113
142
font selection see below
114
143
===================== ================================================
148
LaTeX offers three ways
151
Generates a PDF document directly from the LaTeX file. As always one
152
might need to call it twice (thrice) to get internal references correct.
155
Use ``latex`` to generate a dvi file and ``dvipdfm`` to produce a pdf file.
156
If you will take this approach, specify ``documentoptions=dvipdfm``.
159
Produce a dvi file with ``latex``, postscript with ``dvips`` and pdf with
162
see next section for font selection.
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
205
The generated LaTeX documents are in the input encoding per default.
207
* If the source document is in utf-8 encoding (or
208
``--output-encoding=utf-8`` is set), LaTeX needs unicode support
209
(the ``ucs`` package). If this is not available, specify
210
a different output-encoding, e.g. ``latin1``.
212
* If LaTeX issues a Warning about unloaded/known characters adding ::
167
214
\PreloadUnicodePage{n}
169
where *n* is the unicode pagenumber, might help.
171
.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
216
where *n* is the unicode pagenumber, might help.
218
.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
220
* Unicode box drawing characters
222
- generate LaTeX code with ``--output-encoding=utf-8:strict``.
224
- In the latex file, edit the preamble to load "ucs" with "postscript"
225
option and also load the pstricks package::
227
\usepackage{shortvrb}
229
+ \usepackage[postscript]{ucs}
230
+ \usepackage{pstricks}
231
\usepackage[utf8x]{inputenc}
233
- Convert to PDF with ``latex``, ``dvips``, and ``ps2pdf``.
176
238
A table of figures can be generated by a command directly to LaTeX::
184
246
Section numbering
185
247
-----------------
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]{}
249
The options ``--section-numbering`` and ``--use-latex-toc``, both
250
influence section numbering.
252
* If ``--use-latex-toc`` is specified the latex-writer generates
253
LaTeX output, so that LaTeX generates a table of contents and
254
generates section numbers. Usually one does not want to have
255
section numbers generated by docutils in this case, therefore
256
``--no-section-numbering`` should be specified.
258
The advantage is that LaTeX does put page numbers into the
259
table of contents, but the section depth is limited by the
260
used LaTeX-documentclass, usually to three levels.
262
* If section numbering and LaTeX table of contents is used LaTeX and
263
docutils will number sections. To switch off displaying of LaTeX's
264
numbers one has to add following lines to the stylesheet ::
266
% no section number display
268
\def\@seccntformat#1{}
271
\renewcommand{\numberline}[1]{}
273
This enables to have the same section numbers as in other docutils-
274
writers and page numbers in the table of contents.
199
276
Number pages by chapter
200
277
-----------------------
222
299
If pdf-image inclusion in pdf files fails, specify
223
300
``--graphicx-option=pdftex`` or ``--graphicx-option=auto``.
302
Wrapping text around images requires the wrapfig package.
226
304
Commands directly to LaTeX
227
305
==========================
229
307
By means of the reST-raw directive one can give commands directly to
230
308
LaTeX, e.g. forcing a page break::
237
315
Or setting formulas in LaTeX::
241
319
$$x^3 + 3x^2a + 3xa^2 + a^3,$$
249
327
Nobody expects the spanish inquisition.
252
.. |begincolorbox| raw:: LaTeX
330
.. |begincolorbox| raw:: latex
256
334
\\parbox{0.985\\linewidth}{
258
.. |endcolorbox| raw:: LaTeX
336
.. |endcolorbox| raw:: latex
335
420
uses raggedright.
336
421
- Ragged right fails on followup paragraphs as the vertical space would be
423
* Use tabularx column type ``X`` and let latex decide width.
424
* csv-tables do not have a colwidth.
342
430
* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
431
* If default table-style is not booktabs, but the document contains a table
432
with class booktabs, one has to add the latex package booktabs. That means
435
\usepackage{booktabs}
437
into your latex-style.
347
442
* Selection of LaTeX fontsize configurable.
348
443
* Assumed reST linelength for table width setting configurable.
349
444
* literal-block indentation configurable.
350
* recongize LaTeX and replace by ``\LaTeX``.
445
* recognize LaTeX and replace by ``\LaTeX``.
351
446
* Support embed-stylesheet.
352
447
* Sidebar handling.
353
* Maybe add end of line after term in definition list. see
354
http://roundup.sf.net/doc-0.5/features.pdf
355
448
* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
356
449
* center subsection{Abstract} gives a LaTeX error here.
357
450
``! LaTeX Error: Something's wrong--perhaps a missing \item.``
376
469
* No link to system errors.
377
470
* Hyperlinks are not hyphenated; this leads to bad spacing. See
378
471
docs/user/rst/demo.txt 2.14 directives.
379
* Meta keywords into pdf ?
472
* Meta keywords into PDF ?
380
473
* Pagestyle headings does not work, when sections are starred.
381
474
* For additional docinfo items: the field_body is inserted as text, i.e. no
added
removed
docs/user/latex.txt
