summaryrefslogtreecommitdiff
path: root/docs/user
diff options
context:
space:
mode:
authormilde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>2010-09-20 13:07:30 +0000
committermilde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>2010-09-20 13:07:30 +0000
commit709ae3c7ffa81f97cdd78dd62e2bb37ff69b130f (patch)
tree234260156402beae1dee09ec341c0e1608847009 /docs/user
parent31892da07ed22af6258fe94b7ad2f8a0dc3ae84d (diff)
downloaddocutils-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/user')
-rw-r--r--docs/user/config.txt40
-rw-r--r--docs/user/latex.txt66
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.