diff options
author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2010-09-20 13:07:30 +0000 |
---|---|---|
committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2010-09-20 13:07:30 +0000 |
commit | 709ae3c7ffa81f97cdd78dd62e2bb37ff69b130f (patch) | |
tree | 234260156402beae1dee09ec341c0e1608847009 /docs | |
parent | 31892da07ed22af6258fe94b7ad2f8a0dc3ae84d (diff) | |
download | docutils-709ae3c7ffa81f97cdd78dd62e2bb37ff69b130f.tar.gz |
latex2e writer update, preparing for the new xetex writer
- Load `babel` package only if required.
- New config setting "hyperref-options".
No hard-coded "unicode" hyperref option (clash with xetex).
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@6427 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docs')
-rw-r--r-- | docs/user/config.txt | 40 | ||||
-rw-r--r-- | docs/user/latex.txt | 66 |
2 files changed, 84 insertions, 22 deletions
diff --git a/docs/user/config.txt b/docs/user/config.txt index 935e0a45f..c07ba9d6a 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -319,8 +319,16 @@ _`input_encoding_error_handler` --input-encoding, -i``. _`language_code` - `ISO 639`_ 2-letter language code (3-letter codes used only if no - 2-letter code exists). + Case-insensitive `language tag`_ as defined in `BCP 47`_. + + A typical language identifier consists of a 2-letter language code + from `ISO 639`_ (3-letter codes can be used if no 2-letter code + exists). The language identifier can have an optional subtag, + typically for variations based on country (from `ISO 3166`_ + 2-letter country codes). Avoid subtags except where they add + useful distinguishing information. Examples of language tags + include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and + "de-1901". Default: English ("en"). Options: ``--language, -l``. @@ -935,11 +943,31 @@ _`use_latex_abstract` Default: off. Options: ``--use-latex-abstract, --topic-abstract``. _`hyperlink_color` - Color of any hyperlinks embedded in text. Use "0" to disable - coloring of links. + Color of any hyperlinks embedded in text. + + * "0" or "false" disable coloring of links. (Links will be marked + by red boxes that are not printed), + * "black" results in “invisible“ links, + + Set hyperref_options_ to "draft" to completely disable + hyperlinking. Default: "blue". Option: ``--hyperlink-color``. +_`hyperref_options` + Options for the `hyperref TeX package`_. If hyperlink_color_ is + not "false", the expansion of :: + + 'colorlinks=true,linkcolor=%s,urlcolor=%s' % ( + hyperlink_color, self.hyperlink_color + + is prepended. For documents typeset in Cyrillic script, + ``--hyperref-options=unicode`` is recommended. + + Default: "". Option: ``--hyperref-options``. + + .. _hyperref TeX package: http://tug.org/applications/hyperref/ + _`documentclass` Specify latex documentclass. @@ -1232,7 +1260,11 @@ _`_source` Default: stdin (None). No command-line options. +.. _language tag: http://www.w3.org/International/articles/language-tags/ +.. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt .. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php +.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/ + 02iso-3166-code-lists/index.html .. [#pwd] Path relative to the working directory of the process at launch. diff --git a/docs/user/latex.txt b/docs/user/latex.txt index e59b245aa..1fe67b024 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -211,14 +211,12 @@ The LaTeX code generation can be configured via Options ------- -Options to the Docutils LaTeX writer are specified as +Options can be specified as -command-line options - to the conversion command (run ``rst2latex.py --help`` to get a list of +* command-line options (run ``rst2latex.py --help`` to get a list of available options), or -configuration settings - in a configuration file (see `Docutils Configuration`_ for details). +* configuration settings (see `Docutils Configuration`_ for details). .. _Docutils Configuration: ../user/config.html @@ -296,8 +294,8 @@ Example: latex-preamble_ setting in a configuration file:: latex-preamble: \renewcommand{\ttdefault}{txtt} - \usepackage{mathptmx} % Times - \usepackage[scaled=.92]{helvet} % Helvetica + \usepackage{mathptmx} % Times + \usepackage[scaled=.92]{helvet} % Helvetica .. _latex-preamble: ../user/config.html#latex-preamble @@ -819,7 +817,7 @@ d) PSNFSS_ Postscript fonts old-style figures -1 bad rendering in xpdf viewer (auto-hinting leads to different x-hight for different characters at some magnifications) - (this is fixed in recent versions). + (this is fixed in recent versions). Times +1 the serif `PDF Standard Font`_, @@ -1048,15 +1046,17 @@ Example: hyperlinks ---------- +Options: + hyperlink-color_, hyperref-options_ + Hyperlinks are realized using the hyperref_ package. As it re-defines many standard LaTeX macros, this package is loaded last, *after* the style sheets. -However, you can load hyperref with custom options (or before a -package that requires its presence) in a `style sheet`_ or the `LaTeX -preamble`_, e.g. :: - - \usepackage[unicode,colorlinks=true,linkcolor=green]{hyperref} +However, you can load hyperref before a package that requires its +presence in a `style sheet`_ or the `LaTeX preamble`_ (see example +below). This will ignore options set with hyperlink-color_ and +hyperref-options_. URLs are typeset with the "url" package (loaded implicitely by "hyperref"). The font of URLs can be defined with the ``\urlstyle`` command. Valid @@ -1077,19 +1077,27 @@ Example: See also `non-breaking hyperlinks`_. +.. _hyperlink-color: + ../user/config.html#hyperlink-color +.. _hyperref-options: + ../user/config.html#hyperref-options + + disable hyperlinks `````````````````` -To suppress the hyper-linking completely (e.g. for printing or to avoid -clashes with other packages), load the "nohyperref" package that comes with -the "hyperref" bundle. +To suppress the hyper-linking completely (e.g. for printing or to +avoid clashes with other packages), set hyperref-options_ to "draft" +or load the "nohyperref" package that comes with the "hyperref" +bundle. Option: - ``--stylesheet=nohyperref,url`` + ``--hyperref-options=draft`` LaTeX code:: \usepackage{nohyperref,url} + \urlstyle{same} .. _hyperref: http://mirror.ctan.org/help/Catalogue/entries/hyperref.html @@ -1715,6 +1723,7 @@ not wrap and sometimes stick into the margin. Wrong: :: + \usepackage[breaklinks=true]{hyperref} "breaklinks" is an internal option that indicates whether the chosen @@ -1740,6 +1749,27 @@ See also the `Link text doesn’t break at end line`_ FAQ entry. http://www.tex.ac.uk/cgi-bin/texfaq2html?label=breaklinks +Glyph not defined in PD1 encoding +````````````````````````````````` + +If a section title or other link contains e.g. cyrillic characters, +the LaTeX log contains lots of warnings like:: + + Package hyperref Warning: Glyph not defined in PD1 encoding, + (hyperref) removing `\CYRZ' on input line 6. + ... + +This can be solved with the "unicode" hyperref_option_ setting:: + + --hyperref-option=unicode + +(works also with non-unicode input/output encoding (e.g. "koi8r" or +"latin1"). However, this setting clashes with the XeTeX_ engine and is +therefore not made a default. + +.. _hyperref_option: ../user/config.html#stylesheet-latex2e-writer + + image inclusion ``````````````` @@ -1812,7 +1842,7 @@ an Euro sign at its place). You might see an error like:: :warn: turn the error in a warning, use the default symbol (bitmap), or :force,almostfull: use the symbol provided by the font at the users - risk, + risk, to the document options or use a different font package. |