1================================ 2 Generating LaTeX with Docutils 3================================ 4 5:Author: Engelbert Gruber, Guenter Milde 6:Contact: docutils-develop@lists.sourceforge.net 7:Revision: $Revision: 8625 $ 8:Date: $Date: 2021-02-19 00:09:23 +0100 (Fr, 19. Feb 2021) $ 9:Copyright: This document has been placed in the public domain. 10:Abstract: This document covers topics specific to Docutils' LaTeX_ export. 11 12.. contents:: 13.. sectnum:: 14 15 16LaTeX 17===== 18 19LaTeX__, is a document preparation system for high-quality typesetting. It 20is most often used for medium-to-large technical or scientific documents but 21it can be used for almost any form of publishing. There exists a wide 22selecton of `LaTeX Documentation on the net`_ and `books on LaTeX and 23related topics`_. For an introduction to LaTeX see, e.g., `LaTeX2e for 24authors`_. 25 26__ http://www.latex-project.org/ 27.. _LaTeX2e for authors: 28 http://www.latex-project.org/guides/usrguide.pdf 29.. _LaTeX Documentation on the net: 30 http://www.latex-project.org/guides/ 31.. _books on LaTeX and related topics: 32 http://www.latex-project.org/guides/books.html 33 34 35.. _LaTeX packages: 36 37LaTeX document classes and packages 38----------------------------------- 39 40Unlike HTML with CSS, LaTeX uses one common language for markup and style 41definitions. Separation of content and style is realized by collecting style 42definitions in LaTeX classes and packages, or the 43`document preamble <LaTeX preamble_>`_. 44 45LaTeX document classes and packages (similar to Python modules or C 46libraries) provide means to extend or modify the LaTeX language by 47redefining macros or providing new ones. 48 49Using the `document class`_ and `style sheet`_ configuration options, you 50can select from a *huge* selection of classes and packages (standard as well 51as user contributed) coming with your TeX distribution or available at 52CTAN_ as well as custom style sheets. 53 54.. _CTAN: http://www.ctan.org 55 56 57Docutils specific LaTeX macros 58------------------------------ 59 60Some Docutils objects have no LaTeX counterpart, they will be typeset 61using a Docutils specific LaTeX *macro* (command, environment, or 62length) to allow customization. By convention, special macros use the 63prefix ``\DU``\ [#]_. 64 65The `docutils.sty`_ LaTeX package providing required definitions is 66part of Docutils ≥ 0.17 and available on CTAN since 2020-09-04. 67The generated LaTeX documents should be kept processable by a standard LaTeX 68installation. Therefore fallback definitions are included after the `custom 69style sheets`_, if a macro is required in the document and 70the `stylesheet`_ setting does not include "docutils". 71 72* Custom `style sheets`_ can define alternative implementations with 73 ``\newcommand``, ``\newenvironment``, and ``\newlength`` followed by 74 ``\setlength``. 75 76* Definitions with `raw LaTeX`_ are part of the document body. Use 77 ``\def``, ``\renewcommand`` or ``\renewenvironment``, and ``\setlength``. 78 79See the test output standalone_rst_latex.tex_ for an example of the fallback 80definitions and their use in the document. 81 82.. [#] DU for Documentation Utilities = Docutils 83 84.. _docutils.sty: https://ctan.org/pkg/docutils 85 86 87 88Length units 89------------ 90 91LaTeX supports all `length units`_ defined for Docutils plus the 92following less common units: 93 94:pt: typewriter's (or LaTeX) point (1 pt = 1/72.27 in) 95:dd: didôt (1 dd = 1238/1157 pt) 96:cc: cîcero (1 cc = 12 dd) 97:sp: scaled point (1sp = 1/65536pt) 98 99.. attention:: Different definitions of the unit "pt"! 100 101 * In Docutils (as well as CSS) the unit symbol "pt" denotes the 102 `Postscript point` or `DTP point`. 103 104 * LaTeX uses "pt" for the `LaTeX point`, which is unknown to Docutils and 105 0.3 % smaller. 106 107 * The `DTP point` is available in LaTeX as "bp" (big point): 108 109 1 pt = 1/72.25 in < 1 bp = 1/72 in 110 111 Lengths specified in the document with unit "pt" will be given the 112 unit "bp" in the LaTeX source. 113 114 In `raw LaTeX`_ and `custom style sheets`_, the `DTP point` must be 115 specified as "bp", while "pt" is interpreted as `LaTeX point`. 116 117The default length unit (added by Docutils to length specifications 118without unit) is the "DTP point". 119 120.. _length units: ../ref/rst/restructuredtext.html#length-units 121 122 123PDF generation 124============== 125 126In most cases, LaTeX code is not the desired end-format of the document. 127LaTeX offers many ways to generate PDF documents from the LaTeX 128source, including: 129 130_`pdflatex` 131 Generates a PDF document directly from the LaTeX file. 132 Export your document with the _`LaTeX2e writer` (writer 133 name "``latex``", frontend tool rst2latex.py_). 134 135_`xelatex` or _`lualatex` 136 The `XeTeX`_ and LuaTeX_ engines work with input files in UTF-8 encoding 137 and system fonts. Export your document with the _`XeTeX writer` (writer 138 name "``xetex``", frontend tool rst2xetex.py_). 139 140You may need to call latex two or three times to get internal references 141correct. 142 143.. _documentoptions: config.html#documentoptions 144.. _xetex: http://tug.org/xetex/ 145.. _luatex: http://luatex.org/ 146.. _rst2latex.py: tools.html#rst2latex-py 147.. _rst2xetex.py: tools.html#rst2xetex-py 148 149_`rubber` 150 The Rubber__ wrapper for LaTeX and friends can be used to automatically 151 run all programs the required number of times and delete "spurious" files. 152 This includes processing bibliographic references or indices, as well as 153 compilation or conversion of figures. 154 155__ https://gitlab.com/latex-rubber/rubber/ 156 157 158Configuration 159============= 160 161.. contents:: :local: 162 163.. _option: 164 165Options/Settings 166---------------- 167 168Options can be specified as 169 170* command-line options, or 171 172* configuration settings. 173 174Run ``rst2latex.py --help`` to get a list of available options; 175see `Docutils Configuration`_ for details. 176 177.. _Docutils Configuration: 178 config.html 179 180Classes 181------- 182 183The `"classes" attribute`_ is one of the common attributes, shared by all 184Docutils elements. 185In HTML, the common use is to provide selection criteria for style rules in 186CSS stylesheets. As there is no comparable framework for LaTeX, Docutils 187emulates some of this behaviour via `Docutils specific LaTeX macros`_. 188Due to LaTeX limitations, class arguments are ignored for 189some elements (e.g. a rubric_). 190 191*Inline elements* 192 are handled via the ``\DUrole{}`` macro that calls the optional styling 193 command ``\DUrole«classargument»`` with one argument (the role content). 194 See `custom interpreted text roles`_. 195 196*Block level elements* 197 are wrapped in "class environments": 198 ``\begin{DUclass}`` calls the optional styling command 199 ``\DUCLASS«classargument»{}``, ``\end{DUclass}`` tries 200 ``\endDUCLASS«classargument»``. 201 202Customization is done by defining matching macros or environments. 203 204Example 1: 205 Use small caps font inside elements with class value "custom". 206 207 *Inline elements* 208 The LaTeX function ``\textsc`` sets the argument in small caps:: 209 210 \newcommand{\DUrolecustom}[1]{\textsc{#1}} 211 212 *Block-level elements* 213 The LaTeX directive (macro without argument) ``\scshape`` switches to 214 the small caps font. Its effect is confined to the wrapper ``DUclass`` 215 environment:: 216 217 \newcommand*{\DUCLASScustom}{\scshape} 218 219Example 2: 220 It is even possible to locally redefine other LaTeX macros, e.g. to 221 turn bullet lists with class value "enumerateitems" into enumerated 222 lists:: 223 224 \newcommand*{\DUCLASSenumerateitems}{% 225 \renewenvironment{itemize}{\begin{enumerate}}% 226 {\end{enumerate}}% 227 } 228 229.. rubric:: Notes 230 231* Class arguments may contain numbers and hyphens, which need special 232 treatment in LaTeX command names (see `class directive`_). The commands 233 ``\csname`` and ``\endcsname`` or the special command ``\@namedef`` can 234 help with the definition of corresponding macros or environments, e.g.:: 235 236 \expandafter\newcommand\csname gg1\endcsname{Definition of gg1.} 237 238 or :: 239 240 \makeatletter 241 \@namedef{DUadmonitionadmonition-test}{…} 242 \makeatother 243 244* Elements can have multiple class arguments. In contrast to HTML/CSS, the 245 order of the class arguments cannot be ignored in LaTeX 246 247* Class handling differs for some elements and class values: 248 249 * Class argument values starting with ``align-`` are transformed to 250 "align" argument values. Class argument values starting with 251 ``language-`` set the elements language property. 252 253 * The table element recognizes some special class values. See section 254 table_. 255 256 * For "historical reasons", the special macros ``\DUadmonition`` and 257 ``\DUtitle`` are written with a comma separated list of class values as 258 optional argument if the legacy-class-functions_ setting is True. 259 260 See the sections on admonitions_ and titles_ for customization examples. 261 262.. _"classes" attribute: ../ref/doctree.html#classes 263.. _legacy-class-functions: config.html#legacy-class-functions 264 265LaTeX code 266---------- 267 268Custom LaTeX code can be placed in `style sheets`_, the 269`LaTeX preamble`_, the document body (`raw LaTeX`_), or custom templates_. 270 271The functional tests that come with Docutils, can serve as example. 272 273input: 274 standalone_rst_latex.txt_ (includes files from `tests/functional/input/data`_) 275expected output: 276 standalone_rst_latex.tex_ 277 278.. _standalone_rst_latex.txt: 279 https://sf.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/standalone_rst_latex.txt 280.. _tests/functional/input/data: 281 https://sf.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/data 282.. _standalone_rst_latex.tex: 283 https://sf.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/standalone_rst_latex.tex?format=raw 284 285 286.. _style sheet: 287.. _custom style sheets: 288 289Style sheets 290```````````` 291 292A common way of LaTeX customization is the preparation of custom style 293sheets, either as simple files with LaTeX code snippets or as home-made 294`LaTeX packages`_ (see the clsguide_ for an introduction on LaTeX 295package writing). 296 297Options: 298 stylesheet_ 299 300 It is possible to specify multiple style sheets and mix `LaTeX 301 packages`_ with custom style sheets. 302 303You cannot specify package options with the stylesheet_ setting. If 304you need to pass options to the package, use the ``\usepackage`` 305command in the `LaTeX preamble`_ or a custom style sheet. 306 307Example 1: 308 Select Latin Modern fonts with the `lmodern` package:: 309 310 --stylesheet=lmodern 311 312Example 2: 313 Use the `preamble.tex` home-made custom style sheet together with 314 the package `kerkis` (Bookman fonts):: 315 316 --stylesheet=kerkis,preamble.tex 317 318Example 3: 319 Select Palatino fonts with old-style numbers and true small-caps 320 with the LaTeX command :: 321 322 \usepackage[osf,sc]{mathpazo} 323 324 in the `LaTeX preamble`_ or `custom style sheets`_. 325 326Stylesheet Repository 327 There is a `repository of user-contributed style sheets`_ in the 328 Docutils Sandbox_. 329 330.. _clsguide: 331 http://mirrors.ctan.org/macros/latex/base/clsguide.pdf 332.. _stylesheet: 333 config.html#stylesheet-latex-writers 334.. _embed-stylesheet: 335 config.html#embed-stylesheet-latex-writers 336.. _repository of user-contributed style sheets: 337 ../../../sandbox/stylesheets/ 338.. _sandbox: ../../../sandbox/ 339 340 341LaTeX preamble 342`````````````` 343 344Configuration by LaTeX code in the document preamble is also possible 345without a separate stylesheet. This way, packages can be loaded with 346options or commands re-defined without the need to create a separate 347file (new in Docutils 0.7). 348 349Option: 350 latex-preamble_ 351 352Default: 353 used for `font setup`_ 354 355Example: 356 To use the better looking ``txtt`` font for monospaced text define the 357 latex-preamble_ setting in a configuration file:: 358 359 latex-preamble: \renewcommand{\ttdefault}{txtt} 360 \usepackage{mathptmx} % Times 361 \usepackage[scaled=.92]{helvet} % Helvetica 362 363.. _latex-preamble: 364 config.html#latex-preamble 365.. _PDF standard fonts: 366 http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts 367.. _Linux Libertine: 368 http://www.linuxlibertine.org/index.php?id=1&L=1 369 370 371Templates 372````````` 373 374Some customizations require commands at places other than the insertion 375point of stylesheets or depend on the deletion/replacement of parts of the 376document. This can be done via a custom template. See the `publisher 377documentation`_ for a description of the document parts available in a 378template file. 379 380Option: 381 template_ 382 383In addition to the 'default.tex' template, the latex writer directory 384contains the alternatives 'titlepage.tex' (separete title page) and 385'titlingpage.tex'" (separate title page with the `memoir`_ 386`document class`_). 387 388Example: 389 Print a title page including docinfo, dedication, and abstract:: 390 391 --template=titlepage.tex 392 393.. _publisher documentation: ../api/publisher.html 394.. _template: config.html#template-latex-writers 395 396Raw LaTeX 397````````` 398 399By means of the `raw directive`_ or a derived `custom role`_, one can 400give commands directly to LaTeX. These can be both, styling as well as 401printing commands. 402 403Example: 404 Math formula:: 405 406 .. raw:: latex 407 408 \[x^3 + 3x^2a + 3xa^2 + a^3,\] 409 410 (Drawback: the formula will be invisible in other output formats. Better 411 use the `math directive`_) 412 413Most LaTeX code examples also work as raw LaTeX inside the document. 414An exception are commands that need to be given in the document 415preamble (e.g. package loading with ``\usepackage``, which can be 416achieved with the ``--style-sheet`` or ``--latex-preamble`` command 417line options instead). Remember to use *re-defining* commands for 418customizing `Docutils specific LaTeX macros`_ with raw LaTeX. 419 420Example: 421 Define the transition command as page break:: 422 423 .. raw:: latex 424 425 \renewcommand*{\DUtransition}{\pagebreak[4]} 426 427See also: 428 * Defining a macro for a `custom role`_. 429 * Forcing `page breaks`_. 430 431.. _raw directive: 432 ../ref/rst/directives.html#raw 433.. _math directive: 434 ../ref/rst/directives.html#math 435 436 437 438How to configure the ... 439======================== 440 441admonitions 442----------- 443 444Admonitions__ are specially marked "topics" that can appear anywhere an 445ordinary body element can. 446 447__ ../ref/rst/directives.html#admonitions 448 449Command: 450 ``\DUadmonition`` (with legacy-class-functions_) 451 452Environment: 453 ``DUadmonition`` (with new-class-functions_) 454 455 .. _new-class-functions: legacy-class-functions_ 456 457Default: 458 Typeset in a frame (90 % of text width). 459 460The admonition title is typeset with the ``\DUtitle`` command (see `titles`_). 461 462Example 1: 463 A lighter layout without the frame:: 464 465 \newcommand{\DUadmonition}[2][class-arg]{% 466 % try \DUadmonition#1{#2}: 467 \ifcsname DUadmonition#1\endcsname% 468 \csname DUadmonition#1\endcsname{#2}% 469 \else 470 \begin{quote} 471 #2 472 \end{quote} 473 \fi 474 } 475 476 rsp with new-class-functions_:: 477 478 \newenvironment{DUadmonition}% 479 {\begin{quote}} 480 {\end{quote}} 481 482 483Example 2: 484 Print admonitions in the margin:: 485 486 \newcommand{\DUadmonition}[2][class-arg]{\marginpar{#2}} 487 488 Make sure there is enough space to fit the note. 489 See also the marginnote_ package. 490 491Example 3: 492 Use the ``.. note::`` admonition for a margin note:: 493 494 \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}} 495 496 rsp with new-class-functions_ we re-define the environment in the 497 class-wrapper:: 498 499 \newcommand{\DUCLASSnote}{% 500 \renewcommand{\DUadmonition}{\marginpar} 501 502 Make sure there is enough space to fit the note. 503 504 505.. _marginnote: 506 http://ctan.org/pkg/marginnote 507 http://ctan.org/pkg/marginnote 508 509 510.. _custom role: 511 512custom interpreted text roles 513----------------------------- 514 515The rst `role directive`_ allows defining custom `text roles`_ that mark 516parts of inline text (spans) with class arguments (see section classes_). 517 518Commands: 519 ``\DUrole``: dispatcher command 520 521 ``\DUrole«classargument»``: optional styling command with 1 argument (the 522 role content). 523 524Default: 525 The default definition of ``\DUrole{«classargument»}{}`` calls the macro 526 named ``\DUrole«classargument»{}`` if it is defined and silently ignores 527 this class argument if not. 528 529Example 1: 530 Typeset text in small caps:: 531 532 .. role:: smallcaps 533 534 :smallcaps:`Fourier` transformation 535 536 This is transformed to the LaTeX code:: 537 538 \DUrole{smallcaps}{Fourier} transformation 539 540 The definition :: 541 542 \newcommand{\DUrolesmallcaps}{\textsc} 543 544 as `raw LaTeX`_ or in the custom `style sheet`_ will give the expected 545 result (if the text font_ supports small caps). 546 547Example 2: 548 Subscript text in normal size and *italic* shape:: 549 550 .. role:: sub(subscript) 551 552 As "sub" inherits from the standard "subscript" role, the LaTeX macro 553 only needs to set the size and shape:: 554 555 \newcommand{\DUrolesub}{\normalsize\itshape} 556 557Example 3: 558 A role with several classes and a converted class name:: 559 560 .. role:: custom4 561 :class: argI argII arg_3 562 563 is translated to the nested commands:: 564 565 \DUrole{argi}{\DUrole{argii}{\DUrole{arg-3}{<content>}}} 566 567 With the definitions:: 568 569 \newcommand{\DUroleargi}[1]{\textsc} 570 \newcommand{\DUroleargii}[1]{{\large #1}} 571 \makeatletter 572 \@namedef{DUrolearg-3}{\textbf} 573 \makeatother 574 575 in a `style sheet`_\ [#]_ or as `raw LaTeX`_ in the document source, 576 text styled with ``:custom4:`large bold small-caps``` will be typeset 577 accordingly. 578 579.. [#] Leave out the ``\makeatletter`` - ``\makeatother`` pair if the style 580 sheet is a LaTeX package (``*.sty``). 581 582.. _role directive: 583 ../ref/rst/directives.html#role 584 585.. _text roles: 586 ../ref/rst/roles.html 587 588.. _class directive: 589 ../ref/rst/directives.html#class 590 591definition lists 592---------------- 593 594ReStructuredText `definition lists`__ correspond to HTML ``<dl>`` list 595objects. 596 597Environment: 598 ``description``: LaTeX standard environment 599 600Command: 601 ``\descriptionlabel``: styling macro for the description term 602 603Default: 604 bold label text, hanging indent 605 606Example: 607 A non-bold label can be achieved with:: 608 609 \renewcommand\descriptionlabel[1]{\hspace\labelsep \normalfont #1} 610 611__ ../ref/rst/restructuredtext.html#definition-lists 612 613 614document class 615-------------- 616 617There are hundreds of LaTeX document classes installed by modern 618LaTeX distributions, provided by publishers, or available at CTAN_. 619 620Popular document classes: 621 * article, report, book: standard document classes 622 * scrartcl, scrrprt, scrbook: KOMA-script_ classes 623 * memoir_: highly configurable class for larger documents 624 625Option: 626 documentclass_ 627 628.. _KOMA-script: 629 http://ctan.org/pkg/koma-script 630.. _memoir: 631 http://ctan.org/pkg/memoir 632.. _documentclass: 633 config.html#documentclass 634 635 636document info 637------------- 638 639Content of the `bibliographic fields`__ at the top of a document. 640By default, docinfo items are typeset as a table. 641 642Options: 643 use-latex-docinfo_, use-latex-abstract_ 644 645Length: 646 ``\DUdocinfowidth``: the width for the `docinfo` table. 647 648Default: 649 90 % of text width: ``0.9\textwidth`` 650 651Example: 652 set to 70 % of text width:: 653 654 \newlength{\DUdocinfowidth} 655 \setlength{\DUdocinfowidth}{0.7\textwidth} 656 657__ ../ref/rst/restructuredtext.html#bibliographic-fields 658 659.. _use-latex-docinfo: 660 config.html#use-latex-docinfo 661.. _use-latex-abstract: 662 config.html#use-latex-abstract 663 664 665document title 666-------------- 667 668A lone top-level section title is (usually) transformed to the document title 669(see `section structure`_). 670 671The format of the document title is defined by the `document class`_. The 672"article" document class uses an in-page title and the "report" and "book" 673classes write a separate title page. See the `TeX FAQ`_ on how to customize 674the `style of document titles`_. 675 676The default title page shows only title and subtitle, date and author 677are shown in the `document info`_ table. 678 679Options: 680 use-latex-docinfo_ 681 682 ``--template=titlepage.tex`` Put docinfo and abstract into the title page. 683 A separate title page is used also with the "abstract" document class. 684 685.. _section structure: rst/quickref.html#section-structure 686.. _TeX FAQ: http://www.tex.ac.uk/faq 687.. _style of document titles: 688 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=titlsty 689 690 691field lists 692----------- 693 694`Field lists`__ may be used as generic two-column table constructs in 695documents. 696 697Environment: 698 ``DUfieldlist`` 699 700Default: 701 Indented description list. 702 703Example: 704 Use a description list customized with enumitem_:: 705 706 \usepackage{enumitem} 707 \newenvironment{DUfieldlist}% 708 {\description[font=,style=sameline,leftmargin=8em]} 709 {\enddescription} 710 } 711 712 The `KOMA-script`_ classes provide a similar environment under the name 713 `labeling`. 714 715.. _enumitem: 716 http://ctan.org/pkg/enumitem 717 718__ ../ref/rst/restructuredtext.html#field-lists 719 720 721figure and table captions 722------------------------- 723 724The caption_ package provides many ways to customise the captions in 725floating environments like figure and table. 726 727The chngcntr_ package helps to configure the numbering of figure and table 728caption numberings. 729 730Some document classes (e.g. KOMA-script_) provide additional configuration. 731Also see the related `LaTeX FAQ entry`__ 732 733Example 734 :: 735 736 \usepackage{caption} 737 \captionsetup{justification=raggedleft,singlelinecheck=false} 738 739.. _caption: 740 http://ctan.org/pkg/caption 741.. _chngcntr: 742 http://ctan.org/pkg/chngcntr 743__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos 744 745 746figure placement 747---------------- 748 749Figures_ might be typeset at the place of definition (default) or "float" 750to a suitable place at the top or bottom of a page. This is implemented 751using the float_ package. 752 753Command: 754 ``\floatplacement`` 755 756The placement setting is valid from the point of definition until the next 757``\floatplacement`` command or the end of the document. See float.pdf_ for 758details. 759 760Default: 761 ``\floatplacement{figure}{H}`` (here definitely). This corresponds most 762 closely to the source and HTML placement (principle of least surprise). 763 764Example 1: 765 In a custom `style sheet`_, set the default to let LaTeX find a suitable 766 place for figure floats:: 767 768 \usepackage{float} 769 \floatplacement{figure}{htbp} % here, top, bottom, extra-page 770 771Example 2: 772 To move all following figures to the top or bottom of the page write in 773 the document source:: 774 775 .. raw:: latex 776 777 \floatplacement{figure}{tb} 778 779.. _figures: ../ref/rst/directives.html#figure 780.. _float: 781 http://ctan.org/pkg/float 782.. _float.pdf: 783 http://mirrors.ctan.org/macros/latex/contrib/float/float.pdf 784 785.. _font setup: 786 787font 788---- 789 790The selected text font influences the *look*, the *feel*, 791and the *readability* of the document (cf. 792http://www.csarven.ca/web-typography). 793Selecting a suitable font also solves the problem with `bad looking 794PDF output`_. 795 796Font selection is one of the main differences between LaTeX and XeTeX/LuaTeX: 797 798LaTeX 799 cannot use the fonts of the operating system directly but needs 800 specially installed fonts with additional supporting files. 801 802XeTeX/LuaTeX 803 can use system fonts and provides access to the full feature set of 804 modern OpenType_ fonts. 805 806.. _OpenType: http://en.wikipedia.org/wiki/OpenType 807 808The default font setup is done in the latex-preamble_: 809 810LaTeX 811 `PDF standard fonts`_ (Times, Helvetica, Courier) 812 813XeTeX/LuaTeX 814 `Linux Libertine`_, a free, high quality alternative to Times with a 815 wide coverage of glyphs, styles, and OpenType features. 816 817 Despite its name, Linux Libertine can be used on any operating 818 system that can handle OpenType fonts. 819 820Alternative fonts can be selected by 821 822LaTeX 823 a) specifying the corresponding LaTeX package(s) as argument to the 824 stylesheet_ option_ or with the ``\usepackage`` LaTeX command. 825 826 * packages can be combined, 827 * passing options to a package is only possible in a `style sheet`_ 828 or the `LaTeX preamble`_. 829 830 b) changing the font-default macros ``\rmdefault``, ``\sfdefault`` 831 and/or ``\ttdefault`` in a custom `style sheet`_, the `LaTeX 832 preamble`_ or `raw LaTeX`_. 833 834 Example 1: 835 Use `Latin Modern`_. `LaTeX code`_:: 836 837 \usepackage{lmodern} 838 839 Command line argument:: 840 841 --stylesheet=lmodern 842 843 Example 2: 844 The _`Times/Helvetica/Courier` `PDF standard fonts`_ are 845 selected by the LaTeX code [#]_:: 846 847 \usepackage{mathptmx} % Times for serif and math 848 \usepackage[scaled=.90]{helvet} % downscaled Helvetica for sans serif 849 \usepackage{courier} % Courier for teletype (mono-space) 850 851 Since Docutils 0.7, this is the default value of the 852 `latex-preamble`_ option. 853 854 .. [#] When generating PDF-files from LaTeX, the `PDF standard 855 fonts`_ do not need to be embedded in the document. While this 856 results in smaller files, the actually used fonts on screen and in 857 print might differ! (For details see, e.g., the testflow_ package 858 documentation.) 859 860 861 Example 3: 862 Use the teletype font from the txfonts_ package. As there is no 863 package for this, we re-define the font macro with the `LaTeX code`_:: 864 865 \renewcommand{\ttdefault}{txtt} 866 867 868XeTeX/LuaTeX 869 using the macros of the fontspec_ package. Use some font-viewer or 870 -manager (e.g. fontmatrix_) to find out the correct names of the 871 fonts on your system. 872 873 Example: 874 DejaVu_, very wide coverage, screen optimized. As this font 875 runs wide, add ``DIV=10`` to the `documentoptions`_:: 876 877 \setmainfont{DejaVu Serif} 878 \setsansfont{DejaVu Sans} 879 \setmonofont[HyphenChar=None]{DejaVu Sans Mono} 880 881.. _fontspec: http://ctan.org/pkg/fontspec 882.. _fontmatrix: http://fontmatrix.net/ 883.. _DejaVu: http://dejavu-fonts.org/ 884.. _documentoptions: config.html#documentoptions 885 886choice of suitable fonts 887```````````````````````` 888 889High quality free fonts suitable for use with XeTeX/LuaTeX are, e.g., listed 890at `Good Libre Fonts`_, `25 Best Free Quality Fonts`_ and the update 891`19 More Free Quality Fonts`_. 892 893The `LaTeX Font Catalogue`_ provides information and examples for a wide 894range of fonts available for use with LaTeX. Here is just a selection: 895 896a) The `Latin Modern`_ (LM) fonts are extended outline versions of the 897 standard TeX font Computer Modern (CM). 898 899 +1 simple invocation: ``--stylesheet=lmodern`` 900 901 +1 keeps the traditional TeX "look and feel": 902 903 +1 generally accepted as high quality CM replacement, 904 +1 comprehensive math support, 905 +1 including optical sizes, 906 +1 compatible with extensions made to match CM, 907 -1 modern types are hard to read at low (screen) resolutions. 908 909 -1 not part of a minimal standard TeX installation 910 911b) CM-Super_ is another outline CM replacement. 912 913 +1 simple invocation: modern LaTeX distributions use CM-Super 914 automatically instead of CM if it is installed. 915 916 -1 said to be of inferior quality compared to LM. 917 918 -1 not part of a minimal standard TeX installation, 919 bigger download size than Latin Modern (64 MB). 920 921c) `Bera`_ (Bitstream Vera) 922 923 +1 simple invocation: ``--stylesheet=bera`` 924 925 +1 optimized for on-screen viewing with goot hinting 926 927 -1 not part of a minimal standard TeX installation 928 929d) PSNFSS_ Postscript fonts 930 931 +1 part of every standard TeX installation 932 933 +1 smaller PDF/Postscript document size if standard fonts are not 934 embedded 935 936 -1 restricted set of glyphs in the free versions [#]_ 937 938 -1 different fonts for roman, sans-serif and typewriter fonts. 939 940 -1 invocation somewhat more complex, as several packages are 941 required for a complete font set, sometimes including package 942 options. 943 944 Roman (serif) PSNFSS fonts: 945 946 Bookman 947 good legibility but very wide. 948 949 Charter 950 bread-and-butter type optimized for printing on low-resolution 951 printers 952 953 New Century Schoolbook 954 good legibility but very wide. 955 956 Palatino 957 +1 recommended by font experts 958 +1 good LaTeX support including matching math fonts, small caps, 959 old-style figures 960 -1 bad rendering in xpdf viewer (auto-hinting leads to different 961 x-hight for different characters at some magnifications) 962 (this is fixed in recent versions). 963 964 Times 965 +1 the serif `PDF Standard Font`_, 966 -1 overused and quite narrow (devised for multi-column layouts). 967 968 Utopia 969 recommended by font experts 970 971 972 .. table:: Font packages for standard Postscript fonts 973 (cf. `Using common Postscript fonts with LaTeX`_) 974 975 ========= ============ ============= ============= ========= 976 Package Roman Sans Serif Typewriter Math 977 ========= ============ ============= ============= ========= 978 (none) CM Roman CM Sans Serif CM Typewriter CM Math 979 980 mathpazo Palatino Palatino 981 982 mathptmx Times Times 983 984 helvet Helvetica 985 986 avant Avant Garde 987 988 courier Courier 989 990 chancery Zapf 991 Chancery 992 993 bookman Bookman Avant Garde Courier 994 995 newcent New Century Avant Garde Courier 996 Schoolbook 997 998 charter Charter 999 1000 utopia Utopia 1001 1002 fourier Utopia Fourier 1003 ========= ============ ============= ============= ========= 1004 1005.. [#] Extended versions of the standard Postscript fonts including 1006 accented chars, as well as real small-caps 1007 and old-style numbers are available with the `TeX Gyre`_ bundle 1008 which is part of, e.g., `TeX Live`_. 1009 1010 1011.. _LaTeX Font Catalogue: 1012 http://www.tug.dk/FontCatalogue/ 1013.. _Latin Modern: 1014 http://ctan.org/pkg/lm 1015.. _CM-Super: 1016 http://ctan.org/pkg/cm-super 1017.. _bera: 1018 http://ctan.org/pkg/bera 1019.. _TeX Gyre: http://www.gust.org.pl/projects/e-foundry/tex-gyre 1020.. _PSNFSS: 1021 http://ctan.org/pkg/psnfss 1022.. _Using common PostScript fonts with LaTeX: 1023 http://mirrors.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf 1024.. _TeX Live: http://tug.org/texlive/ 1025.. _txfonts: 1026 http://ctan.org/pkg/txfonts 1027.. _PDF Standard Font: 1028 http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts 1029.. _testflow: 1030 http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/testflow.html 1031.. _Good Libre Fonts: 1032 http://typophile.com/node/18207 1033.. _25 Best Free Quality Fonts: 1034 http://www.alvit.de/blog/article/20-best-license-free-official-fonts 1035.. _19 More Free Quality Fonts: 1036 http://www.smashingmagazine.com/2006/10/11/17-more-free-quality-fonts/ 1037 1038 1039font encoding 1040------------- 1041 1042LaTeX font encodings are described in detail in the encguide_ which is 1043part of the LaTeX base documentation. 1044 1045Option: 1046 font-encoding_ 1047 1048Default: 1049 "T1" 1050 1051Example 1: 1052 Use the (obsolete) LaTeX default encoding "OT1":: 1053 1054 --font-encoding=OT1 1055 1056 or (without loading the fontenc_ package):: 1057 1058 --font-encoding="" 1059 1060 This will improve the look on screen with the default Computer Modern 1061 fonts at the expense of problems with `search and text extraction`_ 1062 The recommended way is to select a T1-encoded "Type 1" (vector) 1063 font, for example `Latin Modern`_ 1064 1065Example 2: 1066 Support for characters in the Unicode blocks Latin, Latin-1 Supplement, 1067 and Greek together with a T1-encoded "Type 1" (vector) font, for example 1068 `Latin Modern`_:: 1069 1070 --font-encoding=LGR,T1 --stylesheet=lmodern 1071 1072.. _encguide: 1073 http://mirrors.ctan.org/macros/latex/base/encguide.pdf 1074.. _font-encoding: 1075 config.html#font-encoding 1076.. _fontenc: 1077 http://ctan.org/pkg/fontenc 1078 1079 1080font size 1081--------- 1082 1083Add font size in points to the document options, e.g. 1084``--documentoptions=12``, use e.g. the document classes provided by 1085extsizes_ for values other than [10,11,12]. 1086 1087.. _extsizes: 1088 http://ctan.org/pkg/extsizes 1089 1090 1091footnotes 1092--------- 1093 1094By default, footnotes are set with Docutils-specific wrappers around 1095the standard ``\footnotemark`` and ``\footnotetext`` commands. You 1096can configure the footnote layout similar to standard LaTeX footnotes 1097in a custom `style sheet`_ or the `LaTeX preamble`_. 1098 1099Further configuration is possible by alternative definitions of 1100``\DUfootnotemark`` and ``\DUfootnotetext`` 1101 1102Example 1: 1103 Set footnote text with a hanging indent. 1104 1105 * This is the default with KOMA-script_ classes, e.g:: 1106 1107 --documentclass=scrartcl 1108 1109 (for further configuration, see the `KOMA-script Guide`_), 1110 1111 * with package footmisc_:: 1112 1113 \usepackage[hang]{footmisc} 1114 \setlength{\footnotemargin}{0em} 1115 1116 (play with the ``\footnotemargin`` setting), 1117 1118 * redefine ``\DUfootnotetext`` inserting `\hangindent`:: 1119 1120 \newcommand{\DUfootnotetext}[4]{% 1121 \begingroup% 1122 \renewcommand{\thefootnote}{% 1123 \protect\raisebox{1em}{\protect\hypertarget{#1}{}}% 1124 \protect\hyperlink{#2}{#3}}% 1125 \footnotetext{\hangindent=2em #4}% 1126 \endgroup% 1127 } 1128 1129 (adapt the ``\hangindent`` value). 1130 1131Example 2: 1132 Footnote marks in normal font size, not superscript:: 1133 1134 \usepackage{scrextend} % not required with KOMA-script document classes 1135 \deffootnote{1em}{1em}{\thefootnotemark\ } 1136 1137 (See the `KOMA-script Guide`_ for details and other options.) 1138 1139Example 3: 1140 Place the footnote text where it appears in the source document (instead 1141 of at the page bottom). This can be used to get the effect of endnotes 1142 (needs the hanging_ package):: 1143 1144 \usepackage{hanging} 1145 \newcommand{\DUfootnotetext}[4]{% 1146 \par\noindent\raisebox{1em}{\hypertarget{#1}{}}% 1147 \hyperlink{#2}{#3}% 1148 \hangpara{\parindent}{1}#4% 1149 } 1150 1151.. _footmisc: 1152 http://ctan.org/pkg/footmisc 1153.. _hanging: 1154 http://ctan.org/pkg/hanging 1155 1156 1157hyphenation 1158----------- 1159 1160The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to 116110000 almost prevents hyphenation. As this produces lines with more space 1162between words one should increase Latex's ``\tolerance`` for this. 1163 1164Example: 1165 :: 1166 1167 \hyphenpenalty=5000 1168 \tolerance=1000 1169 1170 1171hyperlinks 1172---------- 1173 1174Options: 1175 hyperlink-color_, hyperref-options_ 1176 1177Hyperlinks are realized using the hyperref_ package. As it re-defines many 1178standard LaTeX macros, this package is loaded last, *after* the style 1179sheets. 1180 1181However, you can load hyperref before a package that requires its 1182presence in a `style sheet`_ or the `LaTeX preamble`_ (see example 1183below). This will ignore options set with hyperlink-color_ and 1184hyperref-options_. 1185 1186URLs are typeset with the "url" package (loaded implicitely by "hyperref"). 1187The font of URLs can be defined with the ``\urlstyle`` command. Valid 1188arguments are 1189 1190:same: normal text font, Docutils default, 1191:tt: teletype (monospaced), LaTeX default, 1192:rm: roman, 1193:sf: sans serif 1194 1195Example: 1196 Custom loading of the hyperref package also switches to 1197 the LaTeX default (monospaced fonts for URLs). Reset to use the text 1198 font:: 1199 1200 \usepackage[unicode,colorlinks=true,linkcolor=green]{hyperref} 1201 \urlstyle{same} 1202 1203See also `non-breaking hyperlinks`_. 1204 1205.. _hyperlink-color: 1206 config.html#hyperlink-color 1207.. _hyperref-options: 1208 config.html#hyperref-options 1209 1210 1211disable hyperlinks 1212`````````````````` 1213 1214To suppress the hyper-linking completely (e.g. for printing or to 1215avoid clashes with other packages), set hyperref-options_ to "draft" 1216or load the "nohyperref" package that comes with the "hyperref" 1217bundle. 1218 1219Option: 1220 ``--hyperref-options=draft`` 1221 1222`LaTeX code`_:: 1223 1224 \usepackage{nohyperref,url} 1225 \urlstyle{same} 1226 1227.. _hyperref: 1228 http://ctan.org/pkg/hyperref 1229 1230line blocks 1231----------- 1232 1233In `line blocks`__, newlines and leading whitespace are respected. 1234 1235Environment: 1236 ``DUlineblock``: special list environment for line blocks 1237 1238Length: 1239 ``\DUlineblockindent``: indentation of indented lineblock parts. 1240 1241Default: 1242 2.5 times the font hight: ``2.5em`` 1243 1244Example: 1245 set to the paragraph indentation:: 1246 1247 \newlength{\DUlineblockindent} 1248 \setlength{\DUlineblockindent}{\parindent} 1249 1250__ ../ref/rst/restructuredtext.html#line-blocks 1251 1252 1253line spacing 1254------------ 1255 1256Commands: 1257 ``\linespread``: for small adjustments 1258 1259 ``\singlespacing``, ``\onehalfspacing``, and ``\doublespacing``: from 1260 package `setspace` 1261 1262Example 1: 1263 Get document wide double spacing:: 1264 1265 \usepackage{setspace} 1266 \doublespacing 1267 1268Example 2: 1269 Increase line spacing by five percent for better readability:: 1270 1271 \linespread{1.05} 1272 1273 1274literal blocks 1275-------------- 1276 1277No markup processing is done within a `literal block`__. It is left as-is, 1278and is typically rendered in a monospaced typeface 1279 1280Option: 1281 literal-block-env_ 1282 1283Example: 1284 1285 ``--literal-block-env=lstlisting`` 1286 1287 The ``lstlisting`` environment is highly configurable (as documented in 1288 listings.pdf_) and provides syntax highlight for many programming languages, 1289 for instance :: 1290 1291 \renewcommand{\ttdefault}{txtt} 1292 \lstset{language=Python, morekeywords=[1]{yield}} 1293 \lstloadlanguages{Python} 1294 \lstset{ 1295 basicstyle=\ttfamily, 1296 keywordstyle=\bfseries, 1297 commentstyle=\rmfamily\itshape, 1298 stringstyle=\slshape, 1299 } 1300 \lstset{showstringspaces=false} 1301 \lstset{columns=fullflexible, 1302 basewidth={0.5em,0.4em}} 1303 1304 and to get LaTeX syntax highlight for a code block with "listings":: 1305 1306 \lstloadlanguages{[LaTeX]TeX} % comma separated list of languages 1307 \newcommand{\DUCLASSlatex}{\lstset{language=[LaTeX]TeX}} 1308 1309 The indentation of literal blocks can be reset with :: 1310 1311 \lstset{resetmargins=true} 1312 1313 and/or configured with e. g.:: 1314 1315 \lstset{xleftmargin=-2em} 1316 1317__ ../ref/rst/restructuredtext.html#literal-blocks 1318.. _literal-block-env: 1319 config.html#literal-block-env 1320.. _listings.pdf: 1321 http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf 1322 1323 1324lists 1325----- 1326 1327Remove extra vertical whitespace between items of bullet lists and 1328enumerated lists. 1329 1330Example: 1331 Pass the class argument "compact" to the list:: 1332 1333 .. class:: compact 1334 1335 * first item 1336 * second item 1337 1338 The following lines for the `LaTeX preamble`_ use the enumitem_ package to 1339 remove spacing from all lists with class argument "compact":: 1340 1341 \usepackage{enumitem} 1342 \newcommand*{\DUCLASScompact}{\setlist{noitemsep}} 1343 1344 1345list of figures/tables 1346---------------------- 1347 1348Docutils does not support lists of figures or tables. 1349 1350However, with LaTeX, they can be generated using `raw LaTeX`_ in the 1351document source. 1352 1353Commands: 1354 ``\listoffigures``: a list of figures 1355 1356 ``\listoftables``: a list of tables 1357 1358Example: 1359 :: 1360 1361 .. raw:: latex 1362 1363 \listoffigures 1364 1365 1366option list 1367----------- 1368 1369`Option lists`__ are two-column lists of command-line options and 1370descriptions, documenting a program's options. 1371 1372Environment: 1373 ``DUoptionlist``: environment for option lists, 1374 1375Command: 1376 ``\DUoptionlistlabel``: set appearance of the options 1377 1378Example: 1379 set command options with a bold monospace font:: 1380 1381 \newcommand{\DUoptionlistlabel}{\texttt{\textbf{#1}} \hfill} 1382 1383__ ../ref/rst/restructuredtext.html#option-lists 1384 1385 1386page breaks 1387----------- 1388 1389* Page breaks before top-level sections are the default with a 1390 documentclass that provides "chapters", e.g. "book", "memoir" or 1391 "scrbook". 1392 1393* Redefining the \section or \section* command in a 1394 style sheet is possible too. 1395 1396* `Raw LaTeX`_ or a `custom role`_ can be used. 1397 1398* The transition element can be re-defined to produce a page break, 1399 1400Commands 1401 ``\newpage``: hard pagebreak at exactly this position 1402 1403 ``\pagebreak[2]``: recommended page break after line end (precedence 1...4) 1404 1405Example: 1406 Define the transition command as page break with the `LaTeX code`_:: 1407 1408 \newcommand*{\DUtransition}{\pagebreak[4]} 1409 1410 (use ``\renewcommand`` with `raw LaTeX`_). 1411 1412page layout 1413----------- 1414 1415By default, paper size and margin settings are determined by the document 1416class. 1417 1418The following packages help to configure the page layout: 1419 1420a) The `typearea`_ package (part of the `KOMA-script`_ bundle) calculates a 1421 *good* page layout (based on rules and recommendations of typography 1422 experts). 1423 1424 See the `KOMA-Script Guide`_ for details on what is a *good* layout and 1425 how this is achieved. 1426 1427b) The `geometry`_ package is recommended if you have to follow guidelines 1428 with fixed values for the margins. 1429 For details see the `geometry manual`_. 1430 1431Example 1: 1432 Let `typearea` determine the type area with ``DIV=calc`` in the 1433 documentoptions:: 1434 1435 --documentoptions='a4paper,DIV=calc' 1436 1437 The ``DIV`` option can also be specified, like ``DIV=10``. It defines how 1438 "crowded" a page will be: larger values mean larger text area (at the 1439 expense of readability). 1440 1441Example 2: 1442 `LaTeX code`_ to set margins with the geometry_ package:: 1443 1444 \usepackage{geometry} 1445 \geometry{hmargin={3cm,0.8in},height=8in} 1446 \geometry{height=10in}. 1447 1448.. _typearea: 1449 http://ctan.org/pkg/typearea 1450.. _KOMA-Script Guide: 1451 http://mirrors.ctan.org/macros/latex/contrib/koma-script/doc/scrguien.pdf 1452.. _geometry: 1453 http://ctan.org/pkg/geometry 1454.. _geometry manual: 1455 http://mirrors.ctan.org/macros/latex/contrib/geometry/geometry.pdf 1456 1457 1458page headers and footers 1459------------------------ 1460 1461With the fancyhdr_ package or the `KOMA-script`_ classes, you can define 1462custom page head- and foot-lines. 1463 1464The `"header" and "footer" directives`_ save their content in the macros 1465``\DUheader`` rsp. ``\DUfooter``. The macros can be used in LaTeX code and 1466will be replaced by LaTeX with the content of the directives. 1467 1468Example: 1469 `LaTeX code`_ to place left-aligned "header" and "footer" on every 1470 page with fancyhdr_:: 1471 1472 \usepackage{fancyhdr} 1473 \fancyhead[L]{\DUheader} 1474 \fancyfoot{} % reset 1475 \fancyfoot[L]{\DUfooter} 1476 \pagestyle{fancy} 1477 1478 1479.. _fancyhdr: http://www.ctan.org/pkg/fancyhdr 1480.. _"header" and "footer" directives: ../ref/rst/directives.html#header 1481 1482 1483page numbering 1484-------------- 1485 1486Example: 1487 Number pages by chapter (using the chappg_ package):: 1488 1489 \usepackage{chappg} 1490 1491 See the `chappg documentation`_ for details. 1492 1493.. _chappg: 1494 http://ctan.org/pkg/chappg 1495.. _chappg documentation: 1496 http://mirrors.ctan.org/macros/latex/contrib/chappg/chappg.pdf 1497 1498 1499paper size 1500---------- 1501 1502Paper geometry can be changed using ``--documentoptions`` or with the 1503`geometry`_ package. 1504 1505`LaTeX code`_:: 1506 1507 \usepackage{geometry} 1508 \geometry{OPTIONLIST} 1509 1510Default: 1511 a4paper 1512 1513Some possibilities: 1514 1515* a4paper, b3paper, letterpaper, executivepaper, legalpaper 1516* landscape, portrait, twoside. 1517 1518Example: 1519 Choose A5 pager in landscape orientation with command line argument:: 1520 1521 --documentoptions=a5paper,landscape 1522 1523 The same with LaTeX commands in the `style sheet`_:: 1524 1525 \usepackage{geometry} 1526 \geometry{a5paper,landscape} 1527 1528 For details see the `geometry manual`_. 1529 1530paragraph indent 1531---------------- 1532 1533Default (in most document classes): 1534 Indent the first line in a paragraph unless it is the first line of a 1535 chapter, section, subsection, or subsubsection. 1536 1537Example 1: 1538 To set paragraph indentation to zero but add a vertical space between 1539 load the `parskip` package with the command line argument:: 1540 1541 --stylesheet=parskip 1542 1543 or in a custom `style sheet`_ with:: 1544 1545 \usepackage{parskip} 1546 1547Example 2: 1548 To suppress the indentation of a specific paragraph, you may give it the 1549 class "noindent" with, e.g. :: 1550 1551 .. class:: noindent 1552 1553 This paragraph should not be indented. 1554 1555 and define the `custom role`_ command:: 1556 1557 \newcommand{\DUrolenoindent}[1]{\noindent #1} 1558 1559rubric 1560------ 1561 1562A rubric__ is like an informal heading that doesn't correspond to the 1563document's structure. 1564 1565Command: 1566 ``\DUrubric`` 1567 1568Default: 1569 subsubsection style (unnumbered), italic 1570 1571Example1: 1572 Set centred and red:: 1573 1574 \newcommand*{\DUrubric}[1]{% 1575 \subsubsection*{\centerline{\color{red}#1}}} 1576 1577.. note:: 1578 Class attribute values are ignored because the "classes_ wrapper" 1579 interferes with LaTeX's formatting (spacing/indendation) of text following 1580 a section heading. Consider using a `topic element`_ or a container_. 1581 1582__ ../ref/rst/directives.html#rubric 1583.. _container: ../ref/rst/directives.html#container 1584 1585section headings 1586---------------- 1587 1588Options: documentclass_, use-part-section_ 1589 1590Section headings are converted into LaTeX macros according to their level, 1591the document class and the value of the use-part-section_ setting: 1592 1593===== ============= ================== ============= ============== 1594Level article article with part book [#]_ book with part 1595===== ============= ================== ============= ============== 1596 1 section part chapter part 1597 2 subsection section section chapter 1598 3 subsubsection subsection subsection section 1599 4 paragraph subsubsection subsubsection subsection 1600 5 subparagraph paragraph paragraph subsubsection 1601 6 DUtitle subparagraph subparagraph paragraph 1602 7 DUtitle DUtitle DUtitle subparagraph 1603===== ============= ================== ============= ============== 1604 1605 1606.. [#] One of the document classes 'book', 'memoir', 'report 'scrbook', 1607 or 'scrreprt'. 1608 1609.. _use-part-section: config.html#use-part-section 1610 1611section numbering 1612----------------- 1613 1614Sections are numbered if there is a `sectnum directive`_ in the document. 1615 1616Option: sectnum_xform_ 1617 ``--section-numbering``, ``--no-section-numbering`` 1618 1619If sectnum_xform_ is False, section numbers are generated by LaTeX. In this 1620case the "prefix" and "suffix" arguments of the `sectnum directive`_ are 1621ignored. The section number style is determined by the `document class`_ 1622and can be configured in a LaTeX `style sheet`_, e.g.:: 1623 1624 \setcounter{secnumdepth}{5} 1625 1626.. note:: The LaTeX name is 'secnumdepth' (whithout 't'). 1627 1628.. _sectnum directive: ../ref/rst/directives.html#sectnum 1629.. _sectnum_xform: config.html#sectnum-xform 1630 1631 1632sidebar 1633------- 1634 1635Sidebars__ are like miniature, parallel documents that occur inside other 1636documents, providing related or reference material. They can be likened to 1637super-footnotes; their content is outside of the flow of the document's main 1638text. 1639 1640Command: 1641 ``DUsidebar`` 1642 1643Default: 1644 Box with grey background. 1645 1646Example: 1647 Use margin notes:: 1648 1649 \newcommand{\DUsidebar}[1]{\marginpar{\flushleft #1}} 1650 1651 * Make sure the margin is wide enough to hold the note. 1652 * This fails with some constructs inside the `side bar` and where 1653 \marginpar cannot be used, e.g., inside floats, footnotes, or in frames 1654 made with the framed package (see marginnote_). 1655 1656__ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar 1657 1658size of a pixel 1659--------------- 1660 1661The *physical size* of a pixel depends on the resolution of the output 1662device and is usually specified in *dots per inch* (DPI). 1663 1664The *length unit* "px" is defined by the output format. For LaTeX, it is 1665`defined in pdfTeX and LuaTeX`__ (the `xetex` writer emulates this 1666definition). 1667 1668Default: 1669 72 DPI, i.e. 1 px = 1/72 in. [#]_ 1670 1671Example: 1672 Set the value to match the CSS definition 1673 with the `LaTeX code`_:: 1674 1675 \pdfpxdimen=1in 1676 \divide\pdfpxdimen by 96 % 1/96 inch 1677 1678.. [#] The `CSS length unit ``px```_ defaults to 1/96 inch. 1679 1680__ http://tex.stackexchange.com/questions/41370/ 1681 what-are-the-possible-dimensions-sizes-units-latex-understands 1682.. _CSS length unit ``px``: http://www.w3.org/TR/css-values-3/#px 1683.. _reference pixel: http://www.w3.org/TR/css-values-3/#reference-pixel 1684 1685table 1686----- 1687 1688A pre-configured table style can be globally selected via the table-style_ 1689setting or set for individual tables via a `class directive`_ or the class 1690option of the `table directive`_. 1691 1692.. _table-style: config.html#table-style-latex-writers 1693.. _table directive: ../ref/rst/directives.html#table 1694 1695topic element 1696------------- 1697 1698A topic_ is like a block quote with a title, or a self-contained section 1699with no subsections. Topics and rubrics can be used at places where a 1700`section title`_ is not allowed (e.g. inside a directive). 1701 1702Example: 1703 Use a standard paragraph for a topic:: 1704 1705 \newcommand{\DUCLASStopic}{% 1706 \renewenvironment{quote}{}{}% 1707 } 1708 1709.. _topic: ../ref/rst/directives.html#topic 1710.. _section title: ../ref/rst/restructuredtext.html#sections 1711 1712 1713titles 1714------ 1715 1716The titles of admonitions_, sidebar_, and `topic element`_ are defined with 1717the ``\DUtitle`` command that also takes a "class" argument. 1718 1719Example 1: 1720 a centered and somewhat larger title for topcis:: 1721 1722 \newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1} 1723 1724Example 2: 1725 a right-pointing hand as title for the "attention" directive:: 1726 1727 \usepackage{pifont} 1728 \newcommand{\DUtitleattention}[1]{\ding{43}} 1729 1730 The title argument is "swallowed" by the command. 1731 To have both, hand and title use:: 1732 1733 \usepackage{pifont} 1734 \newcommand{\DUtitleattention}[1]{\ding{43} #1} 1735 1736 1737table of contents 1738----------------- 1739 1740A `contents directive`_ is replaced by a table of contents (ToC). 1741 1742Option: use-latex-toc_ 1743 ``--use-latex-toc``, ``--use-docutils-toc`` 1744 1745With use-latex-toc (default since release 0.6): 1746 1747* The ToC is generated by LaTeX (via the ``\tableofcontents`` command). 1748 1749 The layout depends on the choosen document class and can be configured in 1750 a custom `style sheet`_ (see e.g. the `KOMA-Script Guide`_ for the 1751 `KOMA-script`_ classes). 1752 1753* The depth of the ToC and PDF-bookmarks can be configured 1754 1755 + with the "depth" argument of the `contents directive`_, or 1756 1757 + in a style sheet with e.g. ``\setcounter{tocdepth}{5}``. 1758 1759* Local ToCs are done with the minitoc_ package. See the `minitoc 1760 documentation`_ for the numerous configuration options. 1761 1762.. note:: 1763 Minitoc supports local ToCs only at "part" and top section level 1764 ("chapter" or "section"). Local `contents` directives at lower levels 1765 are ignored (a warning is issued). 1766 1767 This is an intended feature of the minitoc_ package. If you really 1768 require local ToCs at lower level, turn off the use-latex-toc_ option. 1769 1770.. _use-latex-toc: config.html#use-latex-toc 1771.. _contents directive: ../ref/rst/directives.html#contents 1772.. _minitoc: 1773 http://ctan.org/pkg/minitoc 1774.. _minitoc documentation: 1775 http://mirrors.ctan.org/macros/latex/contrib/minitoc/minitoc.pdf 1776 1777 1778title reference role 1779-------------------- 1780 1781`Title reference`_ is the default `default role`_ for `interpreted text`_. 1782 1783Command: 1784 ``\DUroletitlereference`` 1785 1786Default: 1787 use slanted font (``\textsl``) 1788 1789Example: 1790 set title references with a bold monospace font:: 1791 1792 \newcommand{\DUroletitlereference}[1]{\texttt{\textbf{#1}}} 1793 1794.. _title reference: 1795 ../ref/rst/roles.html#title-reference 1796.. _default role: 1797 ../ref/rst/directives.html#setting-the-default-interpreted-text-role 1798.. _interpreted text: 1799 ../ref/rst/restructuredtext.html#interpreted-text 1800 1801 1802text encoding 1803------------- 1804 1805The encoding of the LaTeX source file is Docutils' *output* encoding 1806but LaTeX' *input* encoding. 1807 1808Option: output-encoding_ 1809 ``--output-encoding=OUTPUT-ENCODING`` 1810 1811Default: 1812 "utf8" 1813 1814Example: 1815 Encode the LaTeX source file with the ISO `latin-1` (west european) 1816 8-bit encoding (the default in Docutils versions up to 0.6.):: 1817 1818 --output-encoding=latin-1 1819 1820Note: 1821 LaTeX comes with two options for UTF-8 support, 1822 1823 :utf8: by the standard `inputenc`_ package with only limited coverage 1824 (mainly accented characters). 1825 1826 :utf8x: supported by the `ucs`_ package covers a wider range of Unicode 1827 characters than does "utf8". It is, however, a non-standard 1828 extension and no longer developed. 1829 1830 Currently (in version 0.6), "utf8" is used if the output-encoding is 1831 any of "utf_8", "U8", "UTF", or "utf8". 1832 1833.. with utf8x: 1834 If LaTeX issues a Warning about unloaded/unknown characters adding :: 1835 1836 \PreloadUnicodePage{n} 1837 1838 (where *n* is the Unicode page-number) to the style sheet might help. 1839 1840.. _LaTeX Unicode: http://www.unruh.de/DniQ/latex/unicode/ 1841.. _output-encoding: config.html#output-encoding 1842.. _inputenc: 1843 http://ctan.org/pkg/inputenc 1844.. _ucs: 1845 http://ctan.org/pkg/unicode 1846 1847 1848transition element 1849------------------ 1850 1851Transitions__ are commonly seen in novels and short fiction, as a gap 1852spanning one or more lines, marking text divisions or signaling changes in 1853subject, time, point of view, or emphasis. 1854 1855Command: 1856 ``\DUtransition`` 1857 1858Default: 1859 A horizontal line, 1/3 of text width 1860 1861Example 1: 1862 Use three stars:: 1863 1864 \newcommand*{\DUtransition}{\centering{}*\quad*\quad*} 1865 1866 Alternatively use the more elaborated version in `transition-stars.sty`_. 1867 1868Example 2: 1869 If paragraphs are separated by indentation, you can simply use a vertical 1870 space:: 1871 1872 \newcommand*{\DUtransition}{\vspace{2ex}} 1873 1874__ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions 1875 1876.. _transition-stars.sty: ../../../sandbox/stylesheets/transition-stars.sty 1877 1878 1879Changes 1880======= 1881 1882* The Docutils HISTORY_ lists all changes during the history of docutils. 1883 Important changes are summarized in the RELEASE-NOTES_. 1884 1885.. _HISTORY: ../../HISTORY.html 1886.. _RELEASE-NOTES: ../../RELEASE-NOTES.html 1887 1888 1889Problems 1890======== 1891 1892Troubleshooting 1893--------------- 1894 1895Bad looking PDF output 1896`````````````````````` 1897 1898 What I am looking for when I try Docutils is if the PDF files I can get 1899 are of high quality. Unfortunaltely that never is the case. 1900 1901 So am I just stupid or is there a way to get really high quality pdf from 1902 Docutils? 1903 1904Make sure the default font is not a bitmap font. 1905 1906There is `Latin Modern`_ if you like the look of the standard font on paper, 1907but want nice pdf. Or select something else like Times, Palatino, ... via 1908configuration `options/settings`_. See font_ and font-encoding_. 1909 1910 1911footnote mark and text at different pages 1912````````````````````````````````````````` 1913 1914Docutils stores the footnote text in a separate node, at the position where 1915it is specified in the input document. With the default settings, the 1916footnote is put at the bottom of the page where the footnote text is located, 1917maybe far away from the footnote mark (see e.g. `<rst/demo.txt>`_). 1918 1919To get footnote mark and text at the same page, keep footnote mark and 1920footnote text close together! 1921 1922 1923non-breaking hyperlinks 1924``````````````````````` 1925 1926If you convert with ``latex`` (as opposed to ``pdflatex``), hyperlinks will 1927not wrap and sometimes stick into the margin. 1928 1929Wrong: 1930 :: 1931 1932 \usepackage[breaklinks=true]{hyperref} 1933 1934 "breaklinks" is an internal option that indicates whether the chosen 1935 driver can handle split links. (It might work to *disable* link breaking.) 1936 1937Right: 1938 Use one of the following: 1939 1940 a) compile with pdflatex_, 1941 1942 b) use the package breakurl_, 1943 1944 c) (for printout) `disable hyperlinks`_ using the package "nohyperref". 1945 1946See also the `Link text doesn’t break at end line`_ LaTeX FAQ entry. 1947 1948.. _breakurl: 1949 http://ctan.org/pkg/breakurl 1950 1951.. _Link text doesn’t break at end line: 1952 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=breaklinks 1953 1954 1955Glyph not defined in PD1 encoding 1956````````````````````````````````` 1957 1958If a section title or other link contains non-Latin (e.g. Cyrillic) 1959characters, the LaTeX log contains lots of warnings like:: 1960 1961 Package hyperref Warning: Glyph not defined in PD1 encoding, 1962 (hyperref) removing `\CYRZ' on input line 6. 1963 ... 1964 1965This can be solved with the "unicode" hyperref_option_ setting:: 1966 1967 --hyperref-option=unicode 1968 1969(works also with non-unicode input/output encoding (e.g. "koi8r" or 1970"latin1"). Newer versions of hyperref default to "unicode=true". 1971 1972.. _hyperref_option: config.html#stylesheet-latex-writers 1973 1974 1975image inclusion 1976``````````````` 1977 1978Images__ are included in LaTeX with the help of the `graphicx` package. The 1979supported file formats depend on the used driver: 1980 1981* pdflatex_ and xelatex_ work with PNG, JPG, or PDF, but **not EPS**. 1982* Standard latex_ can include **only EPS** graphics, no other format. 1983* latex + dvipdfmx works with EPS and JPG (add 'dvipdfmx' to the 1984 documentoptions_ or graphicx-option_ setting 1985 and 'bmpsize' to the stylesheet_ setting). 1986 1987If PDF-image inclusion in PDF files fails, specifying 1988``--graphicx-option=pdftex`` might help. 1989 1990For details see grfguide.pdf_. 1991 1992The Rubber_ wrapper can be used for automatic image conversion. 1993 1994Docutils expects an URI as pointer to the image file. The latex writer 1995transforms this URI to a local path. By default, LaTeX does not accept 1996spaces and more than one dot in the filename. If using "traditional" 1997filenames is not an option, adding grffile_ to the `style sheets`_ 1998can help. 1999 2000__ ../ref/rst/directives.html#images 2001.. _grfguide.pdf: 2002 http://mirrors.ctan.org/macros/latex/required/graphics/grfguide.pdf 2003.. _grffile: http://ctan.org/pkg/grffile 2004.. _graphicx-option: config.html#graphicx-option 2005 2006 2007 2008Why are my images too big? 2009`````````````````````````` 2010 2011HTML-browsers use the actual screen resolution (usually around 2012100 DPI). 2013 2014The CSS specification suggests: 2015 2016 It is recommended that the reference pixel be the visual angle of one 2017 pixel on a device with a pixel density of 96 DPI and a distance from the 2018 reader of an arm's length. 2019 2020 -- http://www.w3.org/TR/CSS2/syndata.html#length-units 2021 2022This is why pixmap images without size specification or objects with a size 2023specified in ``px`` tend to come too large in the PDF. 2024 2025Solution: 2026 Specify the image size in fixed units (``pt``, ``cm``, ``in``) or 2027 configure the `size of a pixel`_ (length unit px). 2028 2029Error ``illegal unit px`` 2030````````````````````````` 2031 2032If you convert the LaTeX source with a legacy program, you might get this 2033error. 2034 2035The unit "px" was introduced by the `pdfTeX` converter on 2005-02-04. 2036`pdfTeX` is used also for conversion into DVI format in all modern LaTeX 2037distributions (since ca. 2006). 2038 2039If updating LaTeX is not an option, just remove the "px" from the length 2040specification. HTML/CSS will default to "px" while the `latexe2` writer 2041will add the fallback unit "bp". 2042 2043Error ``Symbol \textcurrency not provided`` ... 2044``````````````````````````````````````````````` 2045 2046The currency sign (\\u00a4) is not supported by all fonts (some have 2047an Euro sign at its place). You might see an error like:: 2048 2049 ! Package textcomp Error: Symbol \textcurrency not provided by 2050 (textcomp) font family ptm in TS1 encoding. 2051 (textcomp) Default family used instead. 2052 2053(which in case of font family "ptm" is a false positive). Add either 2054 2055:warn: turn the error in a warning, use the default symbol (bitmap), or 2056:force,almostfull: use the symbol provided by the font at the users 2057 risk, 2058 2059to the document options or use a different font package. 2060 2061Search and text extraction 2062`````````````````````````` 2063 2064Search for text that contains characters outside the ASCII range (e.g. 2065umlauts) might fail. See font_ and `font encoding`_ (as well as 2066`Searching PDF files`_ for background information). 2067 2068It may help to load the `cmap` package (via `style sheets`_ or the custom 2069`LaTeX preamble`_ (see also `Proper use of cmap and mmmap`_). 2070 2071.. _Searching PDF files: 2072 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=srchpdf 2073 2074.. _Proper use of cmap and mmmap: 2075 https://tex.stackexchange.com/questions/64409/proper-use-of-cmap-and-mmap 2076 2077Unicode box drawing and block characters 2078```````````````````````````````````````` 2079 2080The easiest solution is to use xelatex_ for `PDF generation`_. 2081 2082With "traditional" TeX engines (e.g. pdflatex_): 2083 2084- Generate LaTeX code with `output-encoding`_ "utf-8". 2085 2086- Add the pmboxdraw_ package to the `style sheets`_. 2087 (For shaded boxes also add the `color` package.) 2088 2089Unfortunately, this defines only a subset of the characters 2090(see pmboxdraw.pdf_ for a list). 2091 2092.. _pmboxdraw: 2093 http://ctan.org/pkg/pmboxdraw 2094 2095.. _pmboxdraw.pdf: 2096 http://mirrors.ctan.org/macros/latex/contrib/pmboxdraw/pmboxdraw.pdf 2097 2098Bugs and open issues 2099-------------------- 2100 2101Open to be fixed or open to discussion. 2102 2103See also the entries in the `Docutils TODO list`_, 2104the BUGS_ documentation and the `SourceForge Bug Tracker`_. 2105 2106.. _Docutils TODO list: ../dev/todo.html#latex-writer 2107.. _bugs: ../../BUGS.html 2108.. _SourceForge Bug Tracker: 2109 http://sf.net/tracker/?group_id=38414&atid=422030 2110 2111 2112Footnotes and citations 2113``````````````````````` 2114 2115Initially both were implemented using figure floats, because hyperlinking 2116back and forth seemed to be impossible. Later the `figure` directive was 2117added that puts images into figure floats. 2118 2119This results in footnotes, citations, and figures possibly being mixed at 2120page foot. 2121 2122Workaround: 2123 Select footnote and citation handling with the docutils-footnotes_ and 2124 use-latex-citations_ options. 2125 2126If ``use-latex-citations`` is used, a bibliography is inserted right at 2127the end of the document. *This should be customizable*. 2128 2129If ``use-latex-citations`` is used adjacent citation references (separated 2130only by a single space or a newline) are combined to a single citation 2131group, i.e. ``[cite1]_ [cite2]_`` results in ``\cite{cite1,cite2}``. 2132The appearance in the output can be configured in a `style sheet`_. 2133 2134.. _docutils-footnotes: config.html#docutils-footnotes 2135.. _use-latex-citations: config.html#use-latex-citations 2136 2137 2138Tables 2139`````` 2140 2141* reST-documents line length is assumed to be 80 characters. The 2142 *tablewidth* is set relative to this value. If someone produces documents 2143 with line length of 132 this will lead to suboptimal results. 2144 2145 You may use the `:width:` option to manually set the table column widths. 2146 2147* Table: multicol cells are always left aligned. 2148 2149* Table cells with both multirow and multicolumn are currently not possible. 2150 2151* literal-blocks in table cells: 2152 2153 - If verbatim or flushleft is used one gets vertical space above and below. 2154 - This is bad for the topmost paragraph in a cell, therefore the writer 2155 uses raggedright. 2156 - Ragged right fails on followup paragraphs as the vertical space would be 2157 missing. 2158 2159* ``--table-style=booktabs``, ``..class:: booktab``: `booktabs` version 2160 1.00 does not work with `longtable`. This is solved in newer versions 2161 (current is 2005/04/14 v1.61803). 2162 2163 2164Figures 2165``````` 2166 2167* Figures are always as wide as the containing text. The "figwidth" argument 2168 is currently not supported. As a consequence, the "align" argument has no 2169 effect. 2170 2171* Wrapping text around figures is currently not supported. (Requires the 2172 `wrapfig`_ package.) 2173 2174.. _wrapfig: 2175 http://ctan.org/pkg/wrapfig 2176 2177 2178Miscellaneous 2179````````````` 2180 2181* Pdfbookmark level 4 (and greater) does not work (might be settable but 2182 complicated). 2183 2184* Hyperlinks are not hyphenated; this leads to bad spacing. See 2185 docs/user/rst/demo.txt 2.14 directives. 2186 2187* Pagestyle headings does not work, when sections are starred. Use LaTeX for 2188 the section numbering with the `options/settings`_ 2189 ``--no-section-numbers`` (command line) or ``sectnum_xform: False`` 2190 (config file). 2191