From b31c525dab5e67bba4b5a066052deee457af46d4 Mon Sep 17 00:00:00 2001 From: milde Date: Sat, 21 Mar 2015 16:07:49 +0000 Subject: [PATCH] Documentation update. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7852 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/howto/html-stylesheets.txt | 47 ++++++------ docutils/docs/user/config.txt | 106 +++++++++++++++------------- docutils/docs/user/tools.txt | 77 +++++++++++--------- docutils/docutils/writers/xetex/__init__.py | 11 +-- 4 files changed, 131 insertions(+), 110 deletions(-) diff --git a/docutils/docs/howto/html-stylesheets.txt b/docutils/docs/howto/html-stylesheets.txt index 932c32dbb..734b2f82f 100644 --- a/docutils/docs/howto/html-stylesheets.txt +++ b/docutils/docs/howto/html-stylesheets.txt @@ -11,17 +11,29 @@ .. _Docutils: http://docutils.sourceforge.net/ -The look of Docutils' HTML output is customizable via CSS -stylesheets. The default stylesheet is called ``html4css1.css`` and -can be found in the ``writers/html4css1/`` directory of the Docutils -installation. Use the command ``rst2html.py --help`` and look at the -description of the ``--stylesheet-path`` command-line option for the -exact machine-specific location. - -To customize the stylesheet, first copy ``html4css1.css`` to the same -place as your output HTML files will go. Next, place a new file -(e.g. called ``my-docutils.css``) in the same directory and use the -following template:: +The look of Docutils' HTML output is customizable via CSS stylesheets. +The default stylesheets can be found in the +``docutils/writers/html*/`` directories of the ``html4css1`` and +``html-base`` writers in the Docutils installation. Use the front-end +command (``rst2html.py``, ``rst2html5.py`` or ``rst2xhtml.py``) with the +``--help`` option and look at the description of the ``--stylesheet-path`` +command-line option for the exact machine-specific location. + +To customize the look of HTML documents, you can override the settings +of the default stylesheet in your own stylesheet. Specify both, the +default stylesheet and your stylesheet to the ``--stylesheet`` or +``--stylesheet-path`` command line option (or the corresponding +settings in a configuration_ file), e.g. :: + + rst2html.py --stylesheet=html4css1.css,transition-stars.css + +This is the preferable approach if you want to embed the stylesheet(s), as +this ensures that an up-to-date version of ``html4css1.css`` is embedded. + +Alternatively, copy the default style sheet to the same place as your +output HTML files will go and place a new file (e.g. called +``my-docutils.css``) in the same directory and use the following +template:: /* :Author: Your Name @@ -37,10 +49,10 @@ following template:: /* Your customizations go here. For example: */ h1, h2, h3, h4, h5, h6, p.topic-title { - font-family: sans-serif } + font-family: sans-serif } For help on the CSS syntax, please see `the WDG's guide to Cascading -Style Sheets`__ and, in particular, their `list of CSS1 properties`__. +Style Sheets`__ and, in particular, their `list of CSS properties`__. Another good reference site is http://selfhtml.org (German and French). __ http://www.htmlhelp.com/reference/css/ @@ -55,15 +67,6 @@ url(html4css1.css);``") because the definitions contained in the default stylesheet are required for correct rendering (margins, alignment, etc.). -Alternatively, specify both, the default stylesheet and your stylesheet -to the ``--stylesheet`` or ``--stylesheet-path`` command line option (or the -corresponding settings in a configuration_ file), e.g. :: - - rst2html.py --stylesheet=html4css1.css,transition-stars.css - -This is the preferable approach if you want to embed the stylesheet(s), as -this ensures that an up-to-date version of ``html4css1.css`` is embedded. - If you think your stylesheet is fancy and you would like to let others benefit from your efforts, you are encouraged to post the stylesheet to the Docutils-users_ mailing list. It might find its place in the `stylesheet diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt index b456e1b0c..3d50d6d63 100644 --- a/docutils/docs/user/config.txt +++ b/docutils/docs/user/config.txt @@ -313,7 +313,7 @@ footnote_backlinks Enable or disable backlinks from footnotes and citations to their references. -Default: enabled (1). +Default: enabled (True). Options: ``--footnote-backlinks, --no-footnote-backlinks``. generator @@ -474,7 +474,7 @@ directive`_. If disabled, section numbers might be added to the output by the renderer (e.g. LaTeX or via a CSS style definition). -Default: enabled (1). +Default: enabled (True). Options: ``--section-numbering``, ``--no-section-numbering``. .. _sectnum directive: ../ref/rst/directives.html#sectnum @@ -594,7 +594,7 @@ files, such as the "include_" & "raw_". A "warning" system message (including the directive text) is inserted instead. (See also raw_enabled_ for another security-relevant setting.) -Default: enabled (1). +Default: enabled (True). Options: ``--file-insertion-enabled, --no-file-insertion``. .. _include: ../ref/rst/directives.html#include @@ -605,7 +605,7 @@ pep_references Recognize and link to standalone PEP references (like "PEP 258"). -Default: disabled (None); enabled (1) in PEP Reader. +Default: disabled (None); enabled (True) in PEP Reader. Options: ``--pep-references``. pep_base_url @@ -630,14 +630,14 @@ Enable or disable the "raw_" directive. A "warning" system message (including the directive text) is inserted instead. (See also file_insertion_enabled_ for another security-relevant setting.) -Default: enabled (1). Options: ``--raw-enabled, --no-raw``. +Default: enabled (True). Options: ``--raw-enabled, --no-raw``. rfc_references ~~~~~~~~~~~~~~ Recognize and link to standalone RFC references (like "RFC 822"). -Default: disabled (None); enabled (1) in PEP Reader. +Default: disabled (None); enabled (True) in PEP Reader. Options: ``--rfc-references``. rfc_base_url @@ -730,7 +730,7 @@ docinfo_xform Enable or disable the bibliographic field list transform (docutils.transforms.frontmatter.DocInfo). -Default: enabled (1). Options: ``--no-doc-info``. +Default: enabled (True). Options: ``--no-doc-info``. doctitle_xform ~~~~~~~~~~~~~~ @@ -739,7 +739,7 @@ Enable or disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion; docutils.transforms.frontmatter.DocTitle). -Default: enabled (1). Options: ``--no-doc-title``. +Default: enabled (True). Options: ``--no-doc-title``. sectsubtitle_xform ~~~~~~~~~~~~~~~~~~ @@ -857,7 +857,7 @@ each contain one paragraph and/or one "simple" sublist only). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document. -Default: enabled (1). +Default: enabled (True). Options: ``--compact-lists, --no-compact-lists``. compact_field_lists @@ -868,7 +868,7 @@ are "simple" (i.e., all field bodies each contain at most one paragraph). The behaviour can be specified directly via "class" attributes (values "compact" and "open") in the document. -Default: enabled (1). +Default: enabled (True). Options: ``--compact-field-lists, --no-compact-field-lists``. .. _embed_stylesheet [html4css1 writer]: @@ -982,7 +982,8 @@ the output document. Supported values are (case insensitive): The failsave fallback. -Default: "HTML math.css". Option: ``--math-output``. +Default: "HTML math.css" (MathML for the xhtml11 writer). +Option: ``--math-output``. New in Docutils 0.8. @@ -1102,45 +1103,6 @@ Default: do (1). Options: ``--no-xml-declaration``. __ `xml_declaration [docutils_xml writer]`_ -[html-base writer] -~~~~~~~~~~~~~~~~~~ - -The `html-base` writer uses the settings described in the `[html4css1 -writer]`_ section with the following exceptions: - -Removed options: - `field_name_limit`_, `option_limit`_. - -Different default for: - -`stylesheet_path `_: - Default: "html-base.css" - -`stylesheet_dirs `_: - Default: Installation-dependent. Use the --help option to get the exact - value. - - -[xhtml11 writer] -~~~~~~~~~~~~~~~~~ - -The XHTML1.1 Writer derives from the `html-base` writer and uses the same -setings. The "[html-base writer]" section of configuration files is -processed before the "[xhtml11 writer]" section. - - -Different default for: - -`stylesheet_path `_: - Default: "html-base.css,xhtml11.css" - -`stylesheet_dirs `_: - Default: Installation-dependent. Use the --help option to get the exact - value. - -math_output_: - Default: "MathML" - [pep_html writer] ~~~~~~~~~~~~~~~~~ @@ -1256,6 +1218,50 @@ The initial view mode, either "slideshow" or "outline". Default: "slidewhow". Option: ``--view-mode``. +[html-base writer] +------------------ + +The `html-base` writer uses the settings described in the `[html4css1 +writer]`_ section with the following exceptions: + +Removed options: + `field_name_limit`_, `option_limit`_. + +Different default for: + +`stylesheet_path `_: + Default: "html-base.css" + +`stylesheet_dirs `_: + Default: Installation-dependent. Use the --help option to get the exact + value. + +New in Docutils 0.13. + + +[xhtml11 writer] +---------------- + +The XHTML1.1 Writer derives from the `html-base` writer and uses the same +setings. The "[html-base writer]" section of configuration files is +processed before the "[xhtml11 writer]" section. + + +Different default for: + +`stylesheet_path `_: + Default: "html-base.css,xhtml11.css" + +`stylesheet_dirs `_: + Default: Installation-dependent. Use the --help option to get the exact + value. + +math_output_: + Default: "MathML" + +New in Docutils 0.13. + + [latex2e writer] ---------------- diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt index 28347de8e..961e7f872 100644 --- a/docutils/docs/user/tools.txt +++ b/docutils/docs/user/tools.txt @@ -21,7 +21,7 @@ processing. Rather than a single all-purpose program, Docutils has many small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), a "Parser" (which understands the syntax of the text), and a "Writer" (which knows how -to generate a specific data format). +to generate a specific data format). Most front ends have common options and the same command-line usage pattern:: @@ -66,7 +66,7 @@ buildhtml.py :Parser: reStructuredText :Writers: HTML, PEP/HTML -Use ``buildhtml.py`` to generate .html from all the .txt files +Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files (including PEPs) in each given, and their subdirectories too. (Use the ``--local`` option to skip subdirectories.) @@ -101,13 +101,14 @@ rst2html.py :Reader: Standalone :Parser: reStructuredText -:Writer: HTML (html4css1) +:Writer: html (html4css1; this will change to hmtl-base in future) The ``rst2html.py`` front end reads standalone reStructuredText source -files and produces HTML 4 (XHTML 1) "transitional" output compatible with -browsers that support cascading stylesheets (CSS). A stylesheet is -required for proper rendering; a simple but complete stylesheet is -installed and used by default (see Stylesheets_ below). +files and produces `HTML 4.1`_ Transitional (or `XHTML 1.0 Transitional`_) +output. +A CSS stylesheet is required for proper rendering; a simple but +complete stylesheet is installed and used by default (see Stylesheets_ +below). For example, to process a reStructuredText file "``test.txt``" into HTML:: @@ -128,39 +129,41 @@ Stylesheets (or a link to a stylesheet, when passing the "``--link-stylesheet``" option). A stylesheet is required for proper rendering. The default stylesheet (``docutils/writers/html4css1/html4css1.css``, located in -the installation directory) is provided for basic use. To use a -different stylesheet, you must specify the stylesheet's location with -a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a -local file) command-line option, or with `configuration file`_ -settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment -with styles, please see the `guide to writing HTML (CSS) stylesheets -for Docutils`__. +the installation directory) is provided for basic use. To use +different stylesheet(s), you must specify the stylesheets' locations +as comma-separated list with the "``--stylesheet``" (for a URL) +or "``--stylesheet-path``" (for a local file) command-line option, +or with `configuration file`_ settings (e.g. ``./docutils.conf`` +or ``~/.docutils``). To experiment with styles, please see the +`guide to writing HTML (CSS) stylesheets for Docutils`__. __ ../howto/html-stylesheets.html -rst2xhtml11.py +rst2xhtml.py -------------- :Reader: Standalone :Parser: reStructuredText -:Writer: xhtml11 +:Writer: xhtml (xhtml11) -The ``rst2xhtml11.py`` front end reads standalone reStructuredText source -files and produces clean XHTML 1.1 output. A stylesheet is required for -proper rendering; a complete stylesheet is installed and used by default. +The ``rst2xhtml11.py`` front end reads standalone reStructuredText +source files and produces clean `XHTML 1.1`_ (or `HTML 4.1`_ Strict) +output. A CSS 2 stylesheet is required for proper rendering; a complete +stylesheet is installed and used by default. rst2html5.py ------------ :Reader: Standalone :Parser: reStructuredText -:Writer: html5 +:Writer: html5 (html-base) The ``rst2html5.py`` front end reads standalone reStructuredText source -files and produces simple HTML 5 output (compatible to XHTML 1.0 -transitional). A stylesheet is required for proper rendering; a complete -stylesheet is installed and used by default. +files and produces simple `HTML 5`_ output (compatible to `XHTML 1.0 +Transitional`_ and `HTML 4.1`_ Transitional). A CSS 2 stylesheet is +required for proper rendering; a complete stylesheet is installed and +used by default. rstpep2html.py -------------- @@ -169,12 +172,12 @@ rstpep2html.py :Parser: reStructuredText :Writer: PEP/HTML -``rstpep2html.py`` reads a new-style PEP (marked up with -reStructuredText) and produces HTML. It requires a template file and -a stylesheet. By default, it makes use of a "``pep-html-template``" -file and the "``pep.css``" stylesheet (both in the -``docutils/writers/pep_html/`` directory), but these can be overridden -by command-line options or configuration files. +``rstpep2html.py`` reads a new-style PEP (marked up with reStructuredText) +and produces `XHTML 1.0 Transitional`_. It requires a template file and a +stylesheet. By default, it makes use of a "``pep-html-template``" file and +the "``pep.css``" stylesheet (both in the ``docutils/writers/pep_html/`` +directory), but these can be overridden by command-line options or +configuration files. For example, to process a PEP into HTML:: @@ -289,6 +292,12 @@ For details, please see `Easy Slide Shows With reStructuredText & S5 `_. +.. _HTML 5: http://www.w3.org/TR/html5/ +.. _HTML 4.1: http://www.w3.org/TR/html401/ +.. _XHTML 1.0 Transitional: http://www.w3.org/TR/xhtml1/ +.. _XHTML 1.1: http://www.w3.org/TR/xhtml1/ + + LaTeX-Generating Tools ====================== @@ -297,10 +306,10 @@ rst2latex.py :Reader: Standalone :Parser: reStructuredText -:Writer: LaTeX2e +:Writer: latex2e The ``rst2latex.py`` front end reads standalone reStructuredText -source files and produces LaTeX2e output. For example, to process a +source files and produces LaTeX_ output. For example, to process a reStructuredText file "``test.txt``" into LaTeX:: rst2latex.py test.txt test.tex @@ -316,11 +325,11 @@ rst2xetex.py :Reader: Standalone :Parser: reStructuredText -:Writer: XeTeX +:Writer: xetex The ``rst2xetex.py`` front end reads standalone reStructuredText source files and produces `LaTeX` output for processing with unicode-aware -TeX engines (`XeTeX` or `LuaTeX`_). For example, to process a +TeX engines (`LuaTeX`_ or `XeTeX`_). For example, to process a reStructuredText file "``test.txt``" into LaTeX:: rst2xetex.py test.txt test.tex @@ -331,9 +340,11 @@ viewing. For details see `Generating LaTeX with Docutils`_. +.. _LaTeX: https://en.wikipedia.org/wiki/LaTeX .. _XeTeX: https://en.wikipedia.org/wiki/XeTeX .. _LuaTeX: https://en.wikipedia.org/wiki/LuaTeX + XML-Generating Tools ==================== diff --git a/docutils/docutils/writers/xetex/__init__.py b/docutils/docutils/writers/xetex/__init__.py index bfa0783b0..9e70f5b24 100644 --- a/docutils/docutils/writers/xetex/__init__.py +++ b/docutils/docutils/writers/xetex/__init__.py @@ -17,8 +17,9 @@ """ XeLaTeX document tree Writer. -A variant of Docutils' standard 'latex2e' writer producing output -suited for processing with XeLaTeX (http://tug.org/xetex/). +A variant of Docutils' standard 'latex2e' writer producing LaTeX output +suited for processing with the Unicode-aware TeX engines +LuaTeX and XeTeX. """ __docformat__ = 'reStructuredText' @@ -32,9 +33,9 @@ from docutils import frontend, nodes, utils, writers, languages from docutils.writers import latex2e class Writer(latex2e.Writer): - """A writer for Unicode-based LaTeX variants (XeTeX, LuaTeX)""" + """A writer for Unicode-aware LaTeX variants (XeTeX, LuaTeX)""" - supported = ('xetex','xelatex','luatex') + supported = ('lxtex', 'xetex','xelatex','luatex', 'lualatex') """Formats this writer supports.""" default_template = 'xelatex.tex' @@ -54,7 +55,7 @@ class Writer(latex2e.Writer): template=('Template file. Default: "%s".' % default_template, ['--template'], {'default': default_template, 'metavar': ''}), latex_preamble=('Customization by LaTeX code in the preamble. ' - 'Default: select PDF standard fonts (Times, Helvetica, Courier).', + 'Default: select "Linux Libertine" fonts.', ['--latex-preamble'], {'default': default_preamble}), ) -- 2.11.4.GIT