Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[7852] trunk/docutils
|
From: <mi...@us...> - 2015-03-21 16:07:58
|
Revision: 7852
http://sourceforge.net/p/docutils/code/7852
Author: milde
Date: 2015-03-21 16:07:49 +0000 (Sat, 21 Mar 2015)
Log Message:
-----------
Documentation update.
Modified Paths:
--------------
trunk/docutils/docs/howto/html-stylesheets.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/docutils/writers/xetex/__init__.py
Modified: trunk/docutils/docs/howto/html-stylesheets.txt
===================================================================
--- trunk/docutils/docs/howto/html-stylesheets.txt 2015-03-21 15:59:36 UTC (rev 7851)
+++ trunk/docutils/docs/howto/html-stylesheets.txt 2015-03-21 16:07:49 UTC (rev 7852)
@@ -11,18 +11,30 @@
.. _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.
+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 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::
+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
:Contact: Your Email Address
@@ -37,10 +49,10 @@
/* 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 @@
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
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2015-03-21 15:59:36 UTC (rev 7851)
+++ trunk/docutils/docs/user/config.txt 2015-03-21 16:07:49 UTC (rev 7852)
@@ -313,7 +313,7 @@
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 @@
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 @@
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 @@
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 @@
(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 @@
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 @@
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 @@
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 @@
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 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,46 +1103,7 @@
__ `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 <stylesheet_path [html4css1 writer]_>`_:
- Default: "html-base.css"
-
-`stylesheet_dirs <stylesheet_dirs [html4css1 writer]_>`_:
- 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 <stylesheet_path [html4css1 writer]_>`_:
- Default: "html-base.css,xhtml11.css"
-
-`stylesheet_dirs <stylesheet_dirs [html4css1 writer]_>`_:
- Default: Installation-dependent. Use the --help option to get the exact
- value.
-
-math_output_:
- Default: "MathML"
-
-
[pep_html writer]
~~~~~~~~~~~~~~~~~
@@ -1256,6 +1218,50 @@
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 <stylesheet_path [html4css1 writer]_>`_:
+ Default: "html-base.css"
+
+`stylesheet_dirs <stylesheet_dirs [html4css1 writer]_>`_:
+ 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 <stylesheet_path [html4css1 writer]_>`_:
+ Default: "html-base.css,xhtml11.css"
+
+`stylesheet_dirs <stylesheet_dirs [html4css1 writer]_>`_:
+ Default: Installation-dependent. Use the --help option to get the exact
+ value.
+
+math_output_:
+ Default: "MathML"
+
+New in Docutils 0.13.
+
+
[latex2e writer]
----------------
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2015-03-21 15:59:36 UTC (rev 7851)
+++ trunk/docutils/docs/user/tools.txt 2015-03-21 16:07:49 UTC (rev 7852)
@@ -21,7 +21,7 @@
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 @@
: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 <directory> given, and their subdirectories
too. (Use the ``--local`` option to skip subdirectories.)
@@ -101,13 +101,14 @@
: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 @@
(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 @@
: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 @@
S5 <slide-shows.html>`_.
+.. _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 @@
: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 @@
: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 @@
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
====================
Modified: trunk/docutils/docutils/writers/xetex/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/xetex/__init__.py 2015-03-21 15:59:36 UTC (rev 7851)
+++ trunk/docutils/docutils/writers/xetex/__init__.py 2015-03-21 16:07:49 UTC (rev 7852)
@@ -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.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 @@
template=('Template file. Default: "%s".' % default_template,
['--template'], {'default': default_template, 'metavar': '<file>'}),
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}),
)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
