diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2015-07-16 12:31:11 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2015-07-16 12:31:11 +0000 |
| commit | efcc824b21dcead44ed88dd7058c45084ffa8370 (patch) | |
| tree | c784dce348e3cc8d56b4df278484c4ca81ca3ff2 /docutils | |
| parent | 9246e95bf7d7833cd42e055877655ae182312d07 (diff) | |
| download | docutils-efcc824b21dcead44ed88dd7058c45084ffa8370.tar.gz | |
Rename html_base writer to html_plain, move xhtml11 writer back to sandbox.
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7901 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docutils')
29 files changed, 295 insertions, 2174 deletions
diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt index 27bfa8b4e..946e96390 100644 --- a/docutils/HISTORY.txt +++ b/docutils/HISTORY.txt @@ -43,15 +43,13 @@ Changes Since 0.12 - Add ``\colon`` macro, fix spacing around colons. Fixes [ 246 ]. - New upstream version (additional macros, piecewise integrals and sums). -* docutils/writers/html_base/ +* docutils/writers/html_plain/ - New HTML writer generating clean, polyglot_ markup conforming to `HTML 5`_ and compatible with `XHTML 1.0`_ Transitional. - CSS stylesheets ``minimal.css`` and ``plain.css`` with required and - recommended layout rules. - - Also base for the xhtml11_ writer. + The CSS stylesheets ``minimal.css`` and ``plain.css`` contain required + and recommended layout rules. * docutils/writers/html4css1/__init__.py @@ -84,16 +82,9 @@ Changes Since 0.12 - LuaLaTex compatibility: do not load "xunicode". -* docutils/writers/_`xhtml11`/ - - - New HTML writer generating `XHTML 1.1`_ styled with CSS2.1 - Moved to the docutils core from sandbox/html4strict. - - * tools/ - - New front-ends ``rst2xhtml.py`` and ``rst2html5.py`` for the - corresponding writers. + - New front-end ``rst2html5.py``. * tox.ini @@ -105,7 +96,6 @@ Changes Since 0.12 .. _polyglot: http://www.w3.org/TR/html-polyglot/ .. _HTML 5: http://www.w3.org/TR/html5/ .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/ -.. _XHTML 1.1: http://www.w3.org/TR/xhtml11/ Release 0.12 (2014-07-06) diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt index 7e6663f1b..9d2d5a0d6 100644 --- a/docutils/RELEASE-NOTES.txt +++ b/docutils/RELEASE-NOTES.txt @@ -38,19 +38,16 @@ Future changes Changes Since 0.12 ================== -* docutils/writers/ +* docutils/writers/html_plain - - New HTML writers generating `HTML 5`_ and `XHTML 1.1`_. + - New HTML writer generating `HTML 5`_. - New stylesheet ``html-base.css`` for default layout using CSS 2.1. * tools/ - - New front-ends ``rst2xhtml.py`` and ``rst2html5.py`` for the - corresponding writers. + - New front-end ``rst2html5.py``. .. _HTML 5: http://www.w3.org/TR/html5/ -.. _XHTML 1.1: http://www.w3.org/TR/xhtml11/ Release 0.12 (2014-07-06) diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt index bb904c7f1..552098e3a 100644 --- a/docutils/docs/dev/todo.txt +++ b/docutils/docs/dev/todo.txt @@ -376,6 +376,44 @@ General Especially useful for character entity sets, text transform specs, boilerplate, etc. +* Support "include" as embedded inline-compatible directive in substitution + definitions, e.g. :: + + .. |version| include:: version.txt + + This document describes version |version| of ... + + (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel) + +* Add an ``:optional: <replacement text>`` option to the "include" + directive? This would not throw an error for a missing file, instead a + warning is given and ``<replacement text>`` is used instead. It would be + the responsibility of the author to ensure the missing file does not lead + to problems later in the document. + + Use cases: + + + Standard rST syntax to replace Sphinx's "literalinclude":: + + .. include:: blah.cpp + :literal: + :optional: file ``blah.cpp`` not found + + + Variable content taken from a file, e.g. + + version.txt:: + + .. |version| replace:: 3.1 + + optionally used as:: + + .. include:: version.txt + :optional: .. |version| replace:: unknown + + This document describes version |version| of ... + + (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel) + * Parameterize the Reporter object or class? See the `2004-02-18 "rest checking and source path"`_ thread. @@ -1725,6 +1763,20 @@ when used in a document. either by running it at the command line with a ``--help`` option or through an exposed API. [Suggestion for Optik.] + - _`body.float`: Generic float that can be used for figures, tables, + code listings, flowcharts, ... + + There is a Sphinx extension by Ignacio Fernández Galván <jellby@gmail.com> + + I implemented something for generic floats in sphinx, and submitted a + pull request that is still waiting:: + + .. float:: + :type: figure + :caption: My caption + + https://github.com/sphinx-doc/sphinx/pull/1858 + Interpreted Text ---------------- @@ -2506,9 +2558,9 @@ Image and figure directives + `<../../test/functional/expected/standalone_rst_html4css1.html>`__ + `<../../test/functional/expected/standalone_rst_latex.tex>`__ -* According to the HTML standard - http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG a right- or - left-aligned image should be floated alongside the paragraph. +* The default CSS styling for HTML output (plain.css, default.css) lets + text following a right- or left-aligned image float to the side of the + image/figure. + Use this default also for LaTeX? diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt index c93889293..3f12f2659 100644 --- a/docutils/docs/user/html.txt +++ b/docutils/docs/user/html.txt @@ -5,98 +5,122 @@ Docutils HTML writers .. note:: This document is a working draft. Naming of writers, aliases, and front-ends may change before the release of Docutils 0.13. - The ⚠ symbol marks suggestions that are still open to - discussion and change. +.. contents:: Overview -------- -Docutils supports +* `Generic HTML writers`_ -* state of the art HTML (html_base_, html5) ⚠ + =========== ============== ============== ================= =========== + name alias(es) `front-end`_ HTML version CSS version + =========== ============== ============== ================= =========== + html4css1_ html4 rst2html4.py `XHTML 1 `CSS 1`_ + Transitional`_ -* state of the art XHTML (xhtml11_) ⚠ + .. html_ rst2html.py `XHTML 1 `CSS 1`_ + Transitional`_ -* older user agents with no/limited support for CSS and XHTML (html4css1_ - and descendants). + html_plain_ html5_ rst2html5.py `HTML 5`_ `CSS 3`_ + =========== ============== ============== ================= =========== -Additionally, there are special purpose writers (pep_html_, s5_html_) in the -Docutils core and others (e.g. html4trans_) in the sandbox. +* `Special HTML writers`_ -=========== ============== ============== ================= =========== -name alias(es) `front-end`_ HTML version(s) CSS version -=========== ============== ============== ================= =========== -[#base]_ HTML5_, (`XHTML 1 `CSS 3`_ - Transitional`_) + =========== ============== ============== ================= =========== + name alias(es) `front-end`_ HTML version CSS version + =========== ============== ============== ================= =========== + pep_html_ .. rstpep2html.py `XHTML 1 `CSS 1`_ + Transitional`_ -[#5]_ html5 [#5]_ rst2html5.py HTML5_, `CSS 3`_ + s5_html_ s5 rst2s5.py `XHTML 1 `CSS 1`_ + Transitional`_ + =========== ============== ============== ================= =========== -xhtml11_ xhtml, rst2xhtml.py `XHTML 1.1`_, `CSS 3`_ - html4strict (HTML5_) +* `HTML writers in the sandbox`_ -html4css1_ html_ [#h]_, rst2html.py `XHTML 1 `CSS 1`_ - html4 Transitional`_ + =========== ============== ============== ================= =========== + name alias(es) `front-end`_ HTML version CSS version + =========== ============== ============== ================= =========== + xhtml11_ xhtml, rst2xhtml.py `XHTML 1.1`_ `CSS 3`_ + html4strict -pep_html_ .. rstpep2html.py `XHTML 1 `CSS 1`_ - Transitional`_ + html4trans_ .. rst2html_trans `XHTML 1 no CSS + Transitional`_ required + =========== ============== ============== ================= =========== -s5_html_ s5 rst2s5.py `XHTML 1 `CSS 1`_ - Transitional`_ -=========== ============== ============== ================= =========== -.. [#base] TODO: Find the right name for the basic html writer. -.. [#5] `html5` may become the name for a specialised `html5 writer`_ in a - future release. +.. _front-end: tools.html -.. There is one more HTML writer in the sandbox: +Generic HTML writers +-------------------- - html4trans_ rst2html_trans `XHTML 1 no CSS - [#sandbox]_ Transitional`_ required +html4css1 +~~~~~~~~~ - .. [#sandbox] in the sandbox +:aliases: html4, html_ +:front-ends: rst2html4.py, rst2html.py_ +:config: `[html4css1 writer]`_ -.. _front-end: tools.html +The HTML Writer module, ``docutils/writers/html4css1.py``, started +as a proof-of-concept reference implementation. It is the first Docutils +writer and was up to release 0.13 the only official HTML writer. -html ----- +The output conforms to the `XHTML 1 Transitional`_ specification. It does +not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags +required in XML but not allowed in HTML 4. However, the output follows the +`HTML Compatibility Guidelines`_ for proper rendering on most HTML user +agents. -Currently, `html` is an alias for the html4css1_ writer. +Correct rendering depends on a CSS_ style sheet. A reference style sheet, +`html4css1.css`_, is provided and used by default. -.. admonition:: suggestion +To support the `Internet Explorer` (with a market share of about 90% around +2002, the time this writer was written), documents contain some hard-coded +formatting hints and are tagged as "text/html" (instead of +"application/xhtml+xml"). [#IE]_ - The writer alias `html` points to the "recommended Docutils HTML writer". - Its meaning may change with the development of HTML, browsers, Docutils, and - the web. +.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support + for XHTML in IE 9 (2011). - * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you - want the output to be up-to-date automatically. +.. TODO: How to name a specific alias/front-end pointing to html4css1? - * Use a more specific writer name or front end, if you depend on stability - of the generated HTML code, e.g. because you use a custom style sheet or - post-processing that may break otherwise. + html4 + | +1 short form of html4css1, + | -1 writer produces XHTML 1, not HTML 4 + xhtml1 + | +1 correct and short description of the output format. + | -1 may be confused with xhtml11 or xhtml (aliases for the + "new" XHTML 1.1. writer inheriting from html_plain). -html_base ------------ -:aliases: html-common, html5 [#5]_ -:front-end: rst2html5.py_ -:config: `[html-base writer]`_ +.. _rst2html.py: tools.html#rst2html-py +.. _[html4css1 writer]: config.html#html4css1-writer +.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css + -The `html_base` module is both, basis for other HTML writers and a -versatile writer for end-users or programmatic use. ⚠ +html_plain +~~~~~~~~~~ + +:aliases: html5_ +:front-end: rst2html5.py_ +:config: `[html-plain writer]`_ -It generates `polyglot HTML`_ output (compatible with HTML5_ and `XHTML 1 -Transitional`_). New features and elements will only be used if they are -widely supported to make documents `viewable with any browser`_. +The `html_plain` module is both, basis for other HTML writers and a +versatile writer for end-users or programmatic use. -Correct rendering depends on a CSS_ style sheet. Leaving out hard-coded -formatting information from the HTML code allows adaption of the layout with -`custom style sheets`_. The provided style sheets minimal.css_ and -plain.css_ define required and optional styling rules respectively. +The ``html_plain`` writer generates `polyglot HTML`_ output that is +compatible with `HTML 5`_ and `XHTML 1 Transitional`_. New features and +elements will only be used if they are widely supported to make documents +`viewable with any browser`_. There is no hard-coded formatting information +in the HTML document. Correct rendering of elements not directly supported +by HTML depends on a CSS_ style sheet. The provided style sheets +minimal.css_ and plain.css_ define required and optional styling rules +respectively. Adaption of the layout is possible with `custom style +sheets`_. New in Docutils 0.13 -.. admonition:: TODO +.. TODO Find the right name for this writer. Suggestions: @@ -118,108 +142,52 @@ New in Docutils 0.13 html-base -1 not only base class but also suited for end-users - .. _rst2html5.py: tools.html#rst2html5-py -.. _[html-base writer]: config.html#html-base-writer -.. _minimal.css: ../../docutils/writers/html_base/minimal.css -.. _plain.css: ../../docutils/writers/html_base/plain.css +.. _[html-plain writer]: config.html#html-plain-writer +.. _minimal.css: ../../docutils/writers/html_plain/minimal.css +.. _plain.css: ../../docutils/writers/html_plain/plain.css .. _custom style sheets: ../howto/html-stylesheets.html .. _viewable with any browser: http://www.anybrowser.org/campaign - -xhtml11 +Aliases ~~~~~~~ -:aliases: xhtml, html4strict -:front-end: rst2xhtml.py_ -:config: `[xhtml11 writer]`_ -`XHTML 1.1`_ is the current version of the XML based `extensible Hypertext -Markup Language`. +html +"""" -The `xhtml11` writer inherits from html_base_ and adds compatibility to the -strict requirements of `XHTML 1.1`_: +Currently, `html` is an alias for the html4css1_ writer. -* There is no attribute "lang" (only "xml:lang"). +Suggestion + The alias `html` points to the "recommended Docutils HTML writer". + Its target may change with the development of HTML, browsers, Docutils, and + the web. -* Enumerated lists don't support the 'start' attribute. + * Use `get_writer_by_name('html') or the ``rst2html.py`` front end, if you + want the output to be up-to-date automatically. - The style sheet xhtml11.css_ adds support for a "start" value for - enumerated lists via a CSS-counter. This allows also nested enumeration. + * Use a specific writer name or front end, if you depend on stability of + the generated HTML code, e.g. because you use a custom style sheet or + post-processing that may break otherwise. -* ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks - (``<pre>``). +html4 +""""" -The `math-output` `config setting`_ defaults to "MathML". +The alias `html4` provides a stable shortcut for the html4css1_ writer. New in Docutils 0.13 -.. _rst2xhtml.py: tools.html#rst2html5-py -.. _config setting: -.. _[xhtml11 writer]: config.html#xhtml11-writer -.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css - - -.. _`html5 writer`: - html5 -~~~~~ - -The writer name `html5` is reserved for a HTML writer that makes use of new -features and objects defined in HTML5 but not (yet) fit for use in -`html_base` because of limited browser support (like <video>, <aside>, or -<section>). - -In Docutils 0.13, it is an alias to the html_base_ writer. ⚠ +""""" +In Docutils 0.13, html5 is an alias to the html_plain_ writer. -html4css1 ---------- - -:aliases: html4 [#html4]_, html [#h]_ -:front-ends: rst2html.py_, rst2html4.py -:config: `[html4css1 writer]`_ - -.. [#h] `html` may become an alias for html_base in a future release. ⚠ - -The HTML Writer module, ``docutils/writers/html4css1.py``, started -as a proof-of-concept reference implementation. It is the first Docutils -writer and was up to release 0.13 the only official HTML writer. - -The output conforms to the `XHTML 1 Transitional`_ specification. -Correct rendering depends on a CSS_ style sheet. A reference style sheet, -`html4css1.css`_, is provided and used by default. - -Due to the closing of empty tags required in XML but not allowed in HTML 4, -generated documents do not validate as `HTML 4.01 Transitional`_. -However, they follow the `HTML Compatibility Guidelines`_ for proper -rendering on most HTML user agents. - -To support the `Internet Explorer` [#IE]_ (with a market share of about 90% -around 2002, the time this writer was written), documents are tagged as -"text/html" (instead of "application/xhtml+xml") and contain some hard-coded -formatting hints. - -.. [#IE] Conformance to `CSS 2.1`_ has been added in the IE 8 (2009), support - for XHTML in IE 9 (2011). - -.. [#html4] TODO: How to name a specific alias/front-end pointing to html4css1? - - html4 - | +1 short form of html4css1, - | -1 writer produces XHTML 1, not HTML 4 - xhtml1 - | +1 correct and short description of the output format. - | -1 may be confused with xhtml11 or xhtml (aliases for the - "new" XHTML 1.1. writer inheriting from html_base). - - -.. _rst2html.py: tools.html#rst2html-py -.. _[html4css1 writer]: config.html#html4css1-writer -.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css - --------------------------------------------------------------------------- +In future releases, `html5` may become a separate HTML writer that makes use +of new features and objects defined in HTML5 but not (yet) fit for use in +`html_plain`_ because of limited browser support (like <video>, <aside>, or +<section>). -The following three HTML writers inherit from `html4css1`: +Special HTML writers +-------------------- pep_html ~~~~~~~~ @@ -228,11 +196,12 @@ pep_html :config: `[pep_html writer]`_ This is a special writer for the generation of `Python Enhancement -Proposals`_ (PEPs). It adds some PEP-Specific -Options, a style sheet and template. The front-end uses also a specialised +Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific +options`_, a style sheet and template. The front-end uses also a specialised reader. .. _rstpep2html.py: tools.html#rstpep2html-py +.. _PEP-specific options: .. _[pep_html writer]: config.html#pep-html-writer .. _Python Enhancement Proposals: https://www.python.org/dev/peps/ @@ -243,9 +212,9 @@ s5_html :front-end: rst2s5.py_ :config: `[s5_html writer]`_ -The `s5` writer is used to prepare `Easy Slide Shows With reST & S5`_. It -produces XHTML for use with S5_, the “Simple Standards-based Slide Show -System” by Eric Meyer. +The `s5` writer inherits from html4css1_. It produces XHTML for use with +S5_, the “Simple Standards-based Slide Show System” by Eric Meyer. See +`Easy Slide Shows With reST & S5`_ for details. .. _rst2s5.py: tools.html#rst2s5-py .. _[s5_html writer]: config.html#s5-html-writer @@ -254,15 +223,47 @@ System” by Eric Meyer. .. _theme: tools.html#themes +HTML writers in the sandbox +--------------------------- + +There are two more HTML writers in the sandbox_: + +xhtml11 +~~~~~~~ +:aliases: xhtml, html4strict +:front-end: rst2xhtml.py +:config: `[xhtml11 writer]` + +`XHTML 1.1`_ is the current version of the XML based `extensible Hypertext +Markup Language`. + +The `xhtml11` writer inherits from html_plain_ and adds compatibility to the +strict requirements of `XHTML 1.1`_: + +* There is no attribute "lang" (only "xml:lang"). + +* Enumerated lists don't support the 'start' attribute. + + The style sheet xhtml11.css_ adds support for a "start" value for + enumerated lists via a CSS-counter. This allows also nested enumeration. + +* ``<sup>`` and ``<sub>`` tags are not allowed in preformatted blocks + (``<pre>``). + +The `math-output` `config setting`_ defaults to "MathML". + +.. _sandbox: ../dev/policies.html#the-sandbox +.. _rst2xhtml.py: tools.html#rst2html5-py +.. _config setting: +.. _[xhtml11 writer]: config.html#xhtml11-writer +.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css + + html4trans ~~~~~~~~~~ :front-end: rst2html_trans.py_ -Correct rendering of HTML+CSS requires considerable resources in form of -program code, memory space and computation time. On older machines or in -embedded devices this might pose a serious problem. - The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The output conforms to `XHTML 1 Transitional`_ and contains sufficient @@ -277,9 +278,9 @@ has some drawbacks_.) HTML and CSS Versions ---------------------- +~~~~~~~~~~~~~~~~~~~~~ -_`HTML5` +_`HTML 5` `HTML5, A vocabulary and associated APIs for HTML and XHTML`, W3C Recommendation, 28 October 2014. http://www.w3.org/TR/html5/ diff --git a/docutils/docs/user/links.txt b/docutils/docs/user/links.txt index e798fc2e9..d5ecf8f8e 100644 --- a/docutils/docs/user/links.txt +++ b/docutils/docs/user/links.txt @@ -146,24 +146,41 @@ website generators and HTML variants It can generate complete web sites (interlinked and indexed HTML pages), ePub, PDF, and others [#]_ from a set of rst source files. - + .. [#] see http://sphinx-doc.org/config.html#options-for-epub-output + .. _Sphinx: http://sphinx.pocoo.org/ * Nikola_ static site generator, use restructured text by default. + .. _nikola: http://getnikola.com/ + +* Pelican_ is a static site generator (mainly for blogs). Articles/pages can + be written in reStructuredText or Markdown format. + + .. _pelican: http://docs.getpelican.com + * rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht template, for use with ht2html_. + .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html + .. _ht2html: http://ht2html.sourceforge.net/ + * htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation bars. + .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/ + * rest2web_, by Michael Foord, is a tool for creating web sites with reStructuredText. + .. _rest2web: http://www.voidspace.org.uk/python/rest2web/ + * rst2chm_ by Oliver Rutherfurd, generates Microsoft HTML Help files from reStructuredText files. + .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/ + * `html4strict <http://docutils.sf.net/sandbox/html4strict/>`__ produces XHTML that strictly conforms to the XHTML 1.0 specification. @@ -175,22 +192,15 @@ website generators and HTML variants * A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS (stylesheets). -.. _Sphinx: http://sphinx.pocoo.org/ -.. _nikola: http://getnikola.com/ -.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html -.. _ht2html: http://ht2html.sourceforge.net/ -.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/ -.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/ -.. _rest2web: http://www.voidspace.org.uk/python/rest2web/ -.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/ + .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/ ePub ```` - + * The `rst2epub`_ project by Robert Wierschke converts simple - reStructuredText doucments into valid epub files. - - .. simple but well structured with classes/modules for epub components, + reStructuredText doucments into valid epub files. + + .. simple but well structured with classes/modules for epub components, and a standard ``setup.py`` installation file. * rst2epub2_ by Matt Harrison includes the epublib (originally by Tim @@ -262,6 +272,11 @@ Convert other formats to reStructuredText: * xhtml2rest_, written by Antonios Christofides, is a simple utility to convert XHTML to reStructuredText. +* DashTable_ by Gustav Klopp converts HTML tables into reStructuredText. + Colspan and Rowspan supported! + + .. _DashTable: https://github.com/gustavklopp/DashTable + * Sphinx_ includes a `LaTeX to Rst converter <http://svn.python.org/projects/doctools/converter/>`__ in its source code (trimmed to importing the old Python docs). diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt index 597bfed4f..47cfc490e 100644 --- a/docutils/docs/user/tools.txt +++ b/docutils/docs/user/tools.txt @@ -101,7 +101,7 @@ rst2html.py :Reader: Standalone :Parser: reStructuredText -:Writer: html (html4css1_; this will change to hmtl-base_ in future) +:Writer: html_ (html4css1_) The ``rst2html.py`` front end reads standalone reStructuredText source files and produces `XHTML 1.0 Transitional`_ output. @@ -129,7 +129,7 @@ Stylesheets 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 -different stylesheet(s), you must specify the stylesheets' locations +different stylesheet(s), specify the stylesheets' location(s) 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`` @@ -138,32 +138,24 @@ or ``~/.docutils``). To experiment with styles, please see the __ ../howto/html-stylesheets.html .. _html4css1: html.html#html4css1 +.. _html: html.html#html -rst2xhtml.py --------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: xhtml (xhtml11) - -The ``rst2xhtml11.py`` front end reads standalone reStructuredText -source files and produces clean `XHTML 1.1`_ -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 (html-base_) +:Writer: html5 (html_plain_) The ``rst2html5.py`` front end reads standalone reStructuredText source files and produces simple `HTML 5`_ output (compatible to `XHTML 1.0 -Transitional`_). A CSS 2 stylesheet is required for proper rendering; a -complete stylesheet is installed and used by default. +Transitional`_). +Correct rendering of elements not directly supported by HTML depends on a +CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css`` +define required and optional styling rules respectively. -.. _html-base: html.html#html-base +.. _html_plain: html.html#html-plain rstpep2html.py -------------- diff --git a/docutils/docutils/writers/__init__.py b/docutils/docutils/writers/__init__.py index 075c4c265..dc2497cd2 100644 --- a/docutils/docutils/writers/__init__.py +++ b/docutils/docutils/writers/__init__.py @@ -120,18 +120,18 @@ class UnfilteredWriter(Writer): _writer_aliases = { - 'html': 'html4css1', # will change to html_base some day + 'html': 'html4css1', # may change to html_plain some day 'html4': 'html4css1', - 'html5': 'html_base', # until a special HTML 5 writer is ready + 'html5': 'html_plain', # until a special HTML 5 writer is ready 'html4strict': 'xhtml11', - 'html-base': 'html_base', + 'html-plain': 'html_plain', 'latex': 'latex2e', 'pprint': 'pseudoxml', 'pformat': 'pseudoxml', 'pdf': 'rlpdf', 's5': 's5_html', 'xelatex': 'xetex', - 'xhtml': 'xhtml11', + 'xhtml': 'html_plain', 'xhtml10': 'html4css1', 'xml': 'docutils_xml'} diff --git a/docutils/docutils/writers/html4css1/__init__.py b/docutils/docutils/writers/html4css1/__init__.py index d3e9ef9fc..ef22e33a6 100644 --- a/docutils/docutils/writers/html4css1/__init__.py +++ b/docutils/docutils/writers/html4css1/__init__.py @@ -47,7 +47,7 @@ class Writer(writers.Writer): os.path.abspath(os.path.dirname(__file__)), # for math.css os.path.abspath(os.path.join( - os.path.dirname(os.path.dirname(__file__)), 'html_base')) + os.path.dirname(os.path.dirname(__file__)), 'html_plain')) ] default_template = 'template.txt' diff --git a/docutils/docutils/writers/html_base/__init__.py b/docutils/docutils/writers/html_plain/__init__.py index 583e6aed7..583e6aed7 100644 --- a/docutils/docutils/writers/html_base/__init__.py +++ b/docutils/docutils/writers/html_plain/__init__.py diff --git a/docutils/docutils/writers/html_base/math.css b/docutils/docutils/writers/html_plain/math.css index e6eec6565..e6eec6565 100644 --- a/docutils/docutils/writers/html_base/math.css +++ b/docutils/docutils/writers/html_plain/math.css diff --git a/docutils/docutils/writers/html_base/minimal.css b/docutils/docutils/writers/html_plain/minimal.css index df86a6199..df86a6199 100644 --- a/docutils/docutils/writers/html_base/minimal.css +++ b/docutils/docutils/writers/html_plain/minimal.css diff --git a/docutils/docutils/writers/html_base/plain.css b/docutils/docutils/writers/html_plain/plain.css index ba244eab9..ba244eab9 100644 --- a/docutils/docutils/writers/html_base/plain.css +++ b/docutils/docutils/writers/html_plain/plain.css diff --git a/docutils/docutils/writers/html_base/template.txt b/docutils/docutils/writers/html_plain/template.txt index 2591bce35..2591bce35 100644 --- a/docutils/docutils/writers/html_base/template.txt +++ b/docutils/docutils/writers/html_plain/template.txt diff --git a/docutils/docutils/writers/xhtml11/__init__.py b/docutils/docutils/writers/xhtml11/__init__.py deleted file mode 100644 index 2664eef8f..000000000 --- a/docutils/docutils/writers/xhtml11/__init__.py +++ /dev/null @@ -1,167 +0,0 @@ -# .. coding: utf8 -# :Author: Günter Milde <milde@users.berlios.de> -# :Revision: $Revision$ -# :Date: $Date: 2005-06-28$ -# :Copyright: © 2005, 2009 Günter Milde. -# :License: Released under the terms of the `2-Clause BSD license`_, in short: -# -# Copying and distribution of this file, with or without modification, -# are permitted in any medium without royalty provided the copyright -# notice and this notice are preserved. -# This file is offered as-is, without any warranty. -# -# .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause - -""" -Strict eXtensible HyperText Markup Language (XHTML) document Writer. - -This is a variant of Docutils' `html-base` writer. -The output conforms to the XHTML version 1.1 DTD. -""" - -__docformat__ = 'reStructuredText' - -import os -import os.path -import re - -import docutils -from docutils import frontend, nodes, utils, writers, languages -from docutils.writers import html_base - -class Writer(html_base.Writer): - - supported = ('html', 'html4', 'html4strict', 'html4css2', - 'xhtml', 'xhtml1', 'xhtml1strict', 'xhtml11') - """Formats this writer supports.""" - - default_stylesheets = ['minimal.css', 'plain.css', 'xhtml11.css'] - default_stylesheet_dirs = ['.', - os.path.abspath(os.path.dirname(__file__)), - os.path.abspath(os.path.join( - os.path.dirname(os.path.dirname(__file__)), 'html_base')) - ] - - config_section = 'xhtml11 writer' - config_section_dependencies = ('writers', 'html writer') - - settings_spec = frontend.filter_settings_spec( - html_base.Writer.settings_spec, - stylesheet_path = ( - 'Comma separated list of stylesheet paths. ' - 'Relative paths are expanded if a matching file is found in ' - 'the --stylesheet-dirs. With --link-stylesheet, ' - 'the path is rewritten relative to the output HTML file. ' - 'Default: "%s"' % ','.join(default_stylesheets), - ['--stylesheet-path'], - {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet', - 'validator': frontend.validate_comma_separated_list, - 'default': default_stylesheets}), - stylesheet_dirs = ( - 'Comma-separated list of directories where stylesheets are found. ' - 'Used by --stylesheet-path when expanding relative path arguments. ' - 'Default: "%s"' % default_stylesheet_dirs, - ['--stylesheet-dirs'], - {'metavar': '<dir[,dir,...]>', - 'validator': frontend.validate_comma_separated_list, - 'default': default_stylesheet_dirs}), - math_output = ('Math output format, one of "MathML", "HTML", ' - '"MathJax" or "LaTeX". Default: "MathML"', - ['--math-output'], - {'default': 'MathML'}), - xml_declaration = ('Prepend an XML declaration. ' - 'Default: True', - ['--xml-declaration'], - {'default': True, 'action': 'store_true', - 'validator': frontend.validate_boolean})) - - def __init__(self): - writers.Writer.__init__(self) - self.translator_class = HTMLTranslator - - -class HTMLTranslator(html_base.HTMLTranslator): - """ - This writer generates XHTML 1.1 - without formatting that interferes with a CSS stylesheet. - """ - doctype = ('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" ' - '"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\n') - doctype_mathml = ( - '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" ' - '"http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd">\n') - -# there is no attribute "lang" in XHTML 1.1 - - lang_attribute = 'xml:lang' # changed from 'lang' in XHTML 1.0 - head_prefix_template = ('<html xmlns="http://www.w3.org/1999/xhtml"' - ' xml:lang="%(lang)s">\n<head>\n') - - -# enumerated lists -# ---------------- -# The 'start' attribute does not conform to HTML4/XHTML1 Strict -# (resurfaced in HTML5) - - def visit_enumerated_list(self, node): - atts = {} - if 'start' in node: - atts['style'] = 'counter-reset: item %d;' % (node['start'] - 1) - classes = node.setdefault('classes', []) - if 'enumtype' in node: - classes.append(node['enumtype']) - if self.is_compactable(node): - classes.append('simple') - self.body.append(self.starttag(node, 'ol', **atts)) - - -# <sup> and <sub> tags (possible with parsed-literal) are not allowed -# in <pre> --- use <span> :: - - def visit_subscript(self, node): - if isinstance(node.parent, nodes.literal_block): - self.body.append(self.starttag(node, 'span', '', - CLASS='subscript')) - else: - self.body.append(self.starttag(node, 'sub', '')) - - def depart_subscript(self, node): - if isinstance(node.parent, nodes.literal_block): - self.body.append('</span>') - else: - self.body.append('</sub>') - - - def visit_superscript(self, node): - # <sup> not allowed in <pre> - if isinstance(node.parent, nodes.literal_block): - self.body.append(self.starttag(node, 'span', '', - CLASS='superscript')) - else: - self.body.append(self.starttag(node, 'sup', '')) - - def depart_superscript(self, node): - if isinstance(node.parent, nodes.literal_block): - self.body.append('</span>') - else: - self.body.append('</sup>') - -# Wrap inline MathML in <span>, as it is not allowed directly in a <pre> block -# (possible with parsed-literal):: - - math_tags = {# math_output: (block, inline, class-arguments) - 'mathml': ('div', 'span', ''), - 'html': ('div', 'span', 'formula'), - 'mathjax': ('div', 'span', 'math'), - 'latex': ('pre', 'tt', 'math'), - } - -# Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1 -# HTML5/polyglott recommends using both - - def visit_meta(self, node): - if node.hasattr('lang'): - node['xml:lang'] = node['lang'] - del(node['lang']) - meta = self.emptytag(node, 'meta', **node.non_default_attributes()) - self.add_meta(meta) diff --git a/docutils/docutils/writers/xhtml11/xhtml11.css b/docutils/docutils/writers/xhtml11/xhtml11.css deleted file mode 100644 index 8daabdd91..000000000 --- a/docutils/docutils/writers/xhtml11/xhtml11.css +++ /dev/null @@ -1,123 +0,0 @@ -/* xhtml11.css: Cascading style sheet for Docutils' xhtml11 writer. */ -/* */ -/* :Author: Günter Milde */ -/* :Copyright: © 2009, 2014 Günter Milde. */ -/* :License: Released under the terms of the `2-Clause BSD license`_, */ -/* in short: */ -/* */ -/* Copying and distribution of this file, with or without modification, */ -/* are permitted in any medium without royalty provided the copyright */ -/* notice and this notice are preserved. */ -/* This file is offered as-is, without any warranty. */ -/* */ -/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ - -/* This stylesheet contains rules specific to the output of the */ -/* XHTML 1.1 writer. It supplements the "html-base.css" stylesheet. */ -/* It validates_ as CSS2.1_ */ -/* */ -/* .. _CSS2.1: http://www.w3.org/TR/CSS2 */ -/* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */ - - -/* Ordered List (Enumeration) */ -/* -------------------------- */ - -/* XHTML 1.1 removes the "start" argument form ordered lists */ -/* (it resurfaces in HTML5). */ -/* */ -/* Use custom counters to replace the deprecated start attribute. Make */ -/* sure the resulting list resembles the list-style 'outside' with a */ -/* hanging indent. */ - -/* New ordered list: reset counter, suppress the default label */ -ol, ol.arabic, ol.loweralpha, ol.upperalpha, -ol.lowerroman, ol.upperroman { - counter-reset: item; - list-style: none -} - -/* Set the negative indent of the list label as feature of the list item */ -ol > li { - text-indent: -40px; /* Mozillas default indent */ -} -/* reset for child elements */ -ol > li > * { - text-indent: 0px; - text-indent: 0; - margin-top: 0; - /* background: lightgreen; */ -} - -/* Label */ -ol > li:before { - /* increment and typeset counter(s), */ - counter-increment: item; - content: counter(item) "."; - /* display next to the content (aligned top-right), */ - display: inline-block; - text-align: right; - vertical-align: top; - /* sum must match ol>li {text-indent:} (40px is Mozillas default) */ - width: 35px; - padding-right: 5px; -/* background: yellow; */ -} - -/* The list item's first line starts next to the label, without indent */ -ol > li > p:first-child, -ol > li > ol:first-child, -ol > li > ul:first-child, -ol > li > dl:first-child { - display: inline-block; - /* background: lightblue; */ -} - -/* default separator variants */ -ol.loweralpha > li:before { - content: counter(item, lower-alpha) ")"; -} -ol.upperalpha > li:before { - content: counter(item, upper-alpha) "."; -} -ol.lowerroman > li:before { - content: "(" counter(item, lower-roman) ")"; -} -ol.upperroman > li:before { - content: counter(item, upper-roman) ")"; -} -/* nested counters (1, 1.1, 1.1.1, etc) */ -/* nested enumerated lists "inherit" the class attribute, other lists not */ -ol.nested > li:before, ol.nested ol > li:before { - content: counters(item, ".") " "; -} - -/* "sup" and "sub" tags (possible with parsed-literal) are not allowed */ -/* in "pre" --- use "span" */ - -.subscript { - vertical-align: sub; - font-size: smaller; -} -.superscript { - vertical-align: super; - font-size: smaller; -} - -/* Field Lists */ -/* ----------- */ - -/* field-list variants:: */ - -/* wrap or truncate long field names */ -dl.field-list.fix-labelwidth > dt { - width: 8em; /* set to dl.field-list > dd margin-left - padding-left */ - overflow: hidden; -} -dl.field-list.fix-labelwidth > dd:after { - /* a "stopper" to prevent next dd floating up too far */ - content: ''; - display: block; - clear: left; - vertical-align: baseline; -} diff --git a/docutils/setup.py b/docutils/setup.py index df806e070..c96b852a3 100755 --- a/docutils/setup.py +++ b/docutils/setup.py @@ -135,7 +135,7 @@ what-you-see-is-what-you-get plaintext markup syntax.""", # wrap at col 60 'docutils.utils.math', 'docutils.writers', 'docutils.writers.html4css1', - 'docutils.writers.html_base', + 'docutils.writers.html_plain', 'docutils.writers.xhtml11', 'docutils.writers.pep_html', 'docutils.writers.s5_html', @@ -146,11 +146,11 @@ what-you-see-is-what-you-get plaintext markup syntax.""", # wrap at col 60 ], 'data_files': ([('docutils/parsers/rst/include', glob.glob('docutils/parsers/rst/include/*.txt')), - ('docutils/writers/html_base', - ['docutils/writers/html_base/minimal.css', - 'docutils/writers/html_base/plain.css', - 'docutils/writers/html_base/math.css', - 'docutils/writers/html_base/template.txt']), + ('docutils/writers/html_plain', + ['docutils/writers/html_plain/minimal.css', + 'docutils/writers/html_plain/plain.css', + 'docutils/writers/html_plain/math.css', + 'docutils/writers/html_plain/template.txt']), ('docutils/writers/html4css1', ['docutils/writers/html4css1/html4css1.css', 'docutils/writers/html4css1/template.txt']), diff --git a/docutils/test/functional/expected/standalone_rst_html_base.html b/docutils/test/functional/expected/standalone_rst_html_plain.html index 7bfce7fca..eb8d2a4ec 100644 --- a/docutils/test/functional/expected/standalone_rst_html_base.html +++ b/docutils/test/functional/expected/standalone_rst_html_plain.html @@ -1185,7 +1185,7 @@ with the default setting of <cite>field-name-limit: 14</cite>.</p> previous one but regarded "short" by html4css1.</p> </dd> </dl> -<p>With <span class="docutils literal">html_base</span>, a <cite>field list</cite> is typeset as CSS-styled <cite>definition +<p>With <span class="docutils literal">html_plain</span>, a <cite>field list</cite> is typeset as CSS-styled <cite>definition list</cite>. The default layout is similar to the look with <cite>html4css1</cite>:</p> <dl class="open field-list"> <dt>A long field name</dt> diff --git a/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml b/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml deleted file mode 100644 index 190e27204..000000000 --- a/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml +++ /dev/null @@ -1,1239 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> -<head> -<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" /> -<meta name="generator" content="Docutils 0.13: http://docutils.sourceforge.net/" /> -<title>reStructuredText Test Document</title> -<meta name="author" content="David Goodger" /> -<meta content="reStructuredText, test, parser" name="keywords" /> -<meta content="A test document, containing at least one example of each reStructuredText construct." name="description" xml:lang="en" /> -<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" /> -<link rel="stylesheet" href="../input/data/plain.css" type="text/css" /> -<link rel="stylesheet" href="../input/data/xhtml11.css" type="text/css" /> -</head> -<body> -<div class="header"> -<p>Document header</p> - -<hr class="header"/> -</div> -<div class="document" id="restructuredtext-test-document"> -<span id="doctitle"></span> -<h1 class="title">reStructuredText Test Document</h1> - -<p class="subtitle" id="examples-of-syntax-constructs"><span id="subtitle"></span>Examples of Syntax Constructs</p> -<dl class="docinfo"> -<dt class="author">Author</dt> -<dd class="author"><p>David Goodger</p></dd> -<dt class="address">Address</dt> -<dd class="address"><pre class="address">123 Example Street -Example, EX Canada -A1B 2C3 -</pre> -</dd> -<dt class="contact">Contact</dt> -<dd class="contact"><a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a></dd> -<dt class="authors">Authors</dt> -<dd class="authors"><p>Me</p> -<p>Myself</p> -<p>I</p> -</dd> -<dt class="organization">Organization</dt> -<dd class="organization">humankind</dd> -<dt class="date">Date</dt> -<dd class="date">Now, or yesterday. Or maybe even <em>before</em> yesterday.</dd> -<dt class="status">Status</dt> -<dd class="status">This is a "work in progress"</dd> -<dt class="revision">Revision</dt> -<dd class="revision">is managed by a version control system.</dd> -<dt class="version">Version</dt> -<dd class="version">1</dd> -<dt class="copyright">Copyright</dt> -<dd class="copyright">This document has been placed in the public domain. You -may do with it as you wish. You may copy, modify, -redistribute, reattribute, sell, buy, rent, lease, -destroy, or improve it, quote it at length, excerpt, -incorporate, collate, fold, staple, or mutilate it, or do -anything else to it that your or anyone else's heart -desires.</dd> -<dt class="field-name">field name</dt> -<dd class="field-name"><p>This is a "generic bibliographic field".</p> -</dd> -<dt class="field-name-2">field name "2"</dt> -<dd class="field-name-2"><p>Generic bibliographic fields may contain multiple body elements.</p> -<p>Like this.</p> -</dd> -</dl> -<div class="dedication topic"> -<p class="topic-title first">Dedication</p> -<p>For Docutils users & co-developers.</p> -</div> -<div class="abstract topic"> -<p class="topic-title first">Abstract</p> -<p>This is a test document, containing at least one example of each -reStructuredText construct.</p> -</div> -<!-- This is a comment. Note how any initial comments are moved by -transforms to after the document title, subtitle, and docinfo. --> -<!-- Above is the document title, and below is the subtitle. -They are transformed from section titles after parsing. --> -<!-- bibliographic fields (which also require a transform): --> -<div class="contents topic" id="table-of-contents"> -<p class="topic-title first">Table of Contents</p> -<ul class="auto-toc simple"> -<li><p><a class="reference internal" href="#structural-elements" id="id34"><span class="sectnum">1</span> Structural Elements</a></p> -<ul class="auto-toc"> -<li><p><a class="reference internal" href="#section-title" id="id35"><span class="sectnum">1.1</span> Section Title</a></p></li> -<li><p><a class="reference internal" href="#empty-section" id="id36"><span class="sectnum">1.2</span> Empty Section</a></p></li> -<li><p><a class="reference internal" href="#transitions" id="id37"><span class="sectnum">1.3</span> Transitions</a></p></li> -</ul> -</li> -<li><p><a class="reference internal" href="#body-elements" id="id38"><span class="sectnum">2</span> Body Elements</a></p> -<ul class="auto-toc"> -<li><p><a class="reference internal" href="#paragraphs" id="id39"><span class="sectnum">2.1</span> Paragraphs</a></p> -<ul class="auto-toc"> -<li><p><a class="reference internal" href="#inline-markup" id="id40"><span class="sectnum">2.1.1</span> Inline Markup</a></p></li> -</ul> -</li> -<li><p><a class="reference internal" href="#bullet-lists" id="id41"><span class="sectnum">2.2</span> Bullet Lists</a></p></li> -<li><p><a class="reference internal" href="#enumerated-lists" id="id42"><span class="sectnum">2.3</span> Enumerated Lists</a></p></li> -<li><p><a class="reference internal" href="#definition-lists" id="id43"><span class="sectnum">2.4</span> Definition Lists</a></p></li> -<li><p><a class="reference internal" href="#field-lists" id="id44"><span class="sectnum">2.5</span> Field Lists</a></p></li> -<li><p><a class="reference internal" href="#option-lists" id="id45"><span class="sectnum">2.6</span> Option Lists</a></p></li> -<li><p><a class="reference internal" href="#literal-blocks" id="id46"><span class="sectnum">2.7</span> Literal Blocks</a></p></li> -<li><p><a class="reference internal" href="#line-blocks" id="id47"><span class="sectnum">2.8</span> Line Blocks</a></p></li> -<li><p><a class="reference internal" href="#block-quotes" id="id48"><span class="sectnum">2.9</span> Block Quotes</a></p></li> -<li><p><a class="reference internal" href="#doctest-blocks" id="id49"><span class="sectnum">2.10</span> Doctest Blocks</a></p></li> -<li><p><a class="reference internal" href="#footnotes" id="id50"><span class="sectnum">2.11</span> Footnotes</a></p></li> -<li><p><a class="reference internal" href="#citations" id="id51"><span class="sectnum">2.12</span> Citations</a></p></li> -<li><p><a class="reference internal" href="#targets" id="id52"><span class="sectnum">2.13</span> Targets</a></p> -<ul class="auto-toc"> -<li><p><a class="reference internal" href="#duplicate-target-names" id="id53"><span class="sectnum">2.13.1</span> Duplicate Target Names</a></p></li> -<li><p><a class="reference internal" href="#id21" id="id54"><span class="sectnum">2.13.2</span> Duplicate Target Names</a></p></li> -</ul> -</li> -<li><p><a class="reference internal" href="#directives" id="id55"><span class="sectnum">2.14</span> Directives</a></p> -<ul class="auto-toc"> -<li><p><a class="reference internal" href="#document-parts" id="id56"><span class="sectnum">2.14.1</span> Document Parts</a></p></li> -<li><p><a class="reference internal" href="#images-and-figures" id="id57"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li> -<li><p><a class="reference internal" href="#admonitions" id="id58"><span class="sectnum">2.14.3</span> Admonitions</a></p></li> -<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id59"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></p></li> -<li><p><a class="reference internal" href="#target-footnotes" id="id60"><span class="sectnum">2.14.5</span> Target Footnotes</a></p></li> -<li><p><a class="reference internal" href="#replacement-text" id="id61"><span class="sectnum">2.14.6</span> Replacement Text</a></p></li> -<li><p><a class="reference internal" href="#compound-paragraph" id="id62"><span class="sectnum">2.14.7</span> Compound Paragraph</a></p></li> -<li><p><a class="reference internal" href="#parsed-literal-blocks" id="id63"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></p></li> -<li><p><a class="reference internal" href="#code" id="id64"><span class="sectnum">2.14.9</span> Code</a></p></li> -</ul> -</li> -<li><p><a class="reference internal" href="#substitution-definitions" id="id65"><span class="sectnum">2.15</span> Substitution Definitions</a></p></li> -<li><p><a class="reference internal" href="#comments" id="id66"><span class="sectnum">2.16</span> Comments</a></p></li> -<li><p><a class="reference internal" href="#raw-text" id="id67"><span class="sectnum">2.17</span> Raw text</a></p></li> -<li><p><a class="reference internal" href="#container" id="id68"><span class="sectnum">2.18</span> Container</a></p></li> -<li><p><a class="reference internal" href="#colspanning-tables" id="id69"><span class="sectnum">2.19</span> Colspanning tables</a></p></li> -<li><p><a class="reference internal" href="#rowspanning-tables" id="id70"><span class="sectnum">2.20</span> Rowspanning tables</a></p></li> -<li><p><a class="reference internal" href="#complex-tables" id="id71"><span class="sectnum">2.21</span> Complex tables</a></p></li> -<li><p><a class="reference internal" href="#list-tables" id="id72"><span class="sectnum">2.22</span> List Tables</a></p></li> -<li><p><a class="reference internal" href="#custom-roles" id="id73"><span class="sectnum">2.23</span> Custom Roles</a></p></li> -<li><p><a class="reference internal" href="#svg-images" id="id74"><span class="sectnum">2.24</span> SVG Images</a></p></li> -<li><p><a class="reference internal" href="#swf-images" id="id75"><span class="sectnum">2.25</span> SWF Images</a></p></li> -</ul> -</li> -<li><p><a class="reference internal" href="#additional-xhtml11-features" id="id76"><span class="sectnum">3</span> Additional xhtml11 features</a></p></li> -<li><p><a class="reference internal" href="#error-handling" id="id77"><span class="sectnum">4</span> Error Handling</a></p></li> -</ul> -</div> -<div class="section" id="structural-elements"> -<h1><a class="toc-backref" href="#id34"><span class="sectnum">1</span> Structural Elements</a></h1> -<div class="section" id="section-title"> -<h2 class="with-subtitle"><a class="toc-backref" href="#id35"><span class="sectnum">1.1</span> Section Title</a></h2> -<p class="section-subtitle" id="section-subtitle">Section Subtitle</p> -<p>Lone subsections are converted to a section subtitle by a transform -activated with the <span class="docutils literal"><span class="pre">--section-subtitles</span></span> command line option or the -<span class="docutils literal"><span class="pre">sectsubtitle-xform</span></span> configuration value.</p> -</div> -<div class="section" id="empty-section"> -<h2><a class="toc-backref" href="#id36"><span class="sectnum">1.2</span> Empty Section</a></h2> -</div> -<div class="section" id="transitions"> -<h2><a class="toc-backref" href="#id37"><span class="sectnum">1.3</span> Transitions</a></h2> -<p>Here's a transition:</p> -<hr class="docutils" /> -<p>It divides the section. Transitions may also occur between sections:</p> -</div> -</div> -<hr class="docutils" /> -<div class="section" id="body-elements"> -<h1><a class="toc-backref" href="#id38"><span class="sectnum">2</span> Body Elements</a></h1> -<div class="section" id="paragraphs"> -<h2><a class="toc-backref" href="#id39"><span class="sectnum">2.1</span> Paragraphs</a></h2> -<p>A paragraph.</p> -<div class="section" id="inline-markup"> -<h3><a class="toc-backref" href="#id40"><span class="sectnum">2.1.1</span> Inline Markup</a></h3> -<p>Paragraphs contain text and may contain inline markup: <em>emphasis</em>, -<strong>strong emphasis</strong>, <span class="docutils literal">inline literals</span>, standalone hyperlinks -(<a class="reference external" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id26">[5]</a>), internal -cross-references (<a class="reference internal" href="#example">example</a>), external hyperlinks with embedded URIs -(<a class="reference external" href="http://www.python.org">Python web site</a>), <a class="reference external" href="http://www.python.org/">anonymous hyperlink -references</a> <a class="footnote-reference" href="#id25" id="id31">[5]</a> (<a class="reference external" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference" href="#id32" id="id33">[7]</a>), footnote references (manually -numbered <a class="footnote-reference" href="#id8" id="id1">[1]</a>, anonymous auto-numbered <a class="footnote-reference" href="#id12" id="id2">[3]</a>, labeled auto-numbered -<a class="footnote-reference" href="#label" id="id3">[2]</a>, or symbolic <a class="footnote-reference" href="#id13" id="id4">[*]</a>), citation references (<a class="citation-reference" href="#cit2002" id="id5">[CIT2002]</a>), -substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span> -(see <a class="reference internal" href="#targets">Targets</a> below for a reference back to here). Character-level -inline markup is also possible (although exceedingly ugly!) in <em>re</em><span class="docutils literal">Structured</span><em>Text</em>. Problems are indicated by <a href="#id23"><span class="problematic" id="id24">|problematic|</span></a> text -(generated by processing errors; this one is intentional). Here is a -reference to the <a class="reference internal" href="#doctitle">doctitle</a> and the <a class="reference internal" href="#subtitle">subtitle</a>.</p> -<p>The default role for interpreted text is <cite>Title Reference</cite>. Here are -some explicit interpreted text roles: a PEP reference (<a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a>); an -RFC reference (<a class="reference external" href="http://tools.ietf.org/html/rfc2822.html">RFC 2822</a>); an abbreviation (<abbr>abb.</abbr>), an acronym -(<abbr>reST</abbr>), code (<code>print "hello world"</code>); a <sub>subscript</sub>; -a <sup>superscript</sup> and explicit roles for <cite>Docutils</cite>' -<em>standard</em> <strong>inline</strong> <span class="docutils literal">markup</span>.</p> -<!-- DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! --> -<p>Let's test wrapping and whitespace significance in inline literals: -<span class="docutils literal">This is an example of <span class="pre">--inline-literal</span> <span class="pre">--text,</span> <span class="pre">--including</span> <span class="pre">some--</span> <span class="pre">strangely--hyphenated-words.</span> <span class="pre">Adjust-the-width-of-your-browser-window</span> to see how the text is wrapped. <span class="pre">--</span> <span class="pre">----</span> <span class="pre">--------</span> Now note the spacing between the words of this sentence (words should be grouped in pairs).</span></p> -<p>If the <span class="docutils literal"><span class="pre">--pep-references</span></span> option was supplied, there should be a -live link to PEP 258 here.</p> -</div> -</div> -<div class="section" id="bullet-lists"> -<h2><a class="toc-backref" href="#id41"><span class="sectnum">2.2</span> Bullet Lists</a></h2> -<ul> -<li><p>A bullet list</p> -<ul class="simple"> -<li><p>Nested bullet list.</p></li> -<li><p>Nested item 2.</p></li> -</ul> -</li> -<li><p>Item 2.</p> -<p>Paragraph 2 of item 2.</p> -<ul class="simple"> -<li><p>Nested bullet list.</p></li> -<li><p>Nested item 2.</p> -<ul> -<li><p>Third level.</p></li> -<li><p>Item 2.</p></li> -</ul> -</li> -<li><p>Nested item 3.</p></li> -<li><p>This nested list should be compacted by the HTML writer.</p> -<span class="target" id="target"></span><!-- Even if this item contains a target and a comment. --> -</li> -</ul> -</li> -</ul> -</div> -<div class="section" id="enumerated-lists"> -<h2><a class="toc-backref" href="#id42"><span class="sectnum">2.3</span> Enumerated Lists</a></h2> -<ol class="arabic"> -<li><p>Arabic numerals.</p> -<ol class="loweralpha simple"> -<li><p>lower alpha)</p> -<ol class="lowerroman simple"> -<li><p>(lower roman)</p> -<ol class="upperalpha simple"> -<li><p>upper alpha.</p> -<ol class="upperroman simple"> -<li><p>upper roman)</p></li> -</ol> -</li> -</ol> -</li> -</ol> -</li> -</ol> -</li> -<li><p>Lists that don't start at 1:</p> -<ol class="arabic simple" style="counter-reset: item 2;"> -<li><p>Three</p></li> -<li><p>Four</p></li> -</ol> -<ol class="upperalpha simple" style="counter-reset: item 2;"> -<li><p>C</p></li> -<li><p>D</p></li> -</ol> -<ol class="lowerroman simple" style="counter-reset: item 2;"> -<li><p>iii</p></li> -<li><p>iv</p></li> -</ol> -</li> -</ol> -</div> -<div class="section" id="definition-lists"> -<h2><a class="toc-backref" href="#id43"><span class="sectnum">2.4</span> Definition Lists</a></h2> -<dl> -<dt>Term</dt> -<dd><p>Definition</p> -</dd> -<dt>Term<span class="classifier">classifier</span></dt> -<dd><p>Definition paragraph 1.</p> -<p>Definition paragraph 2.</p> -</dd> -<dt>Term</dt> -<dd><p>Definition</p> -</dd> -<dt>Term<span class="classifier">classifier one</span><span class="classifier">classifier two</span></dt> -<dd><p>Definition</p> -</dd> -</dl> -</div> -<div class="section" id="field-lists"> -<h2><a class="toc-backref" href="#id44"><span class="sectnum">2.5</span> Field Lists</a></h2> -<dl class="field-list"> -<dt>what</dt> -<dd><p>Field lists map field names to field bodies, like database -records. They are often part of an extension syntax. They are -an unambiguous variant of RFC 2822 fields.</p> -</dd> -<dt>how arg1 arg2</dt> -<dd><p>The field marker is a colon, the field name, and a colon.</p> -<p>The field body may contain one or more body elements, indented -relative to the field marker.</p> -</dd> -<dt>credits</dt> -<dd><p class="credits">This paragraph has the <cite>credits</cite> class set. (This is actually not -about credits but just for ensuring that the class attribute -doesn't get stripped away.)</p> -</dd> -</dl> -</div> -<div class="section" id="option-lists"> -<h2><a class="toc-backref" href="#id45"><span class="sectnum">2.6</span> Option Lists</a></h2> -<p>For listing command-line options:</p> -<dl class="option-list"> -<dt><kbd><span class="option">-a</span></kbd></dt> -<dd><p>command-line option "a"</p> -</dd> -<dt><kbd><span class="option">-b <var>file</var></span></kbd></dt> -<dd><p>options can have arguments -and long descriptions</p> -</dd> -<dt><kbd><span class="option">--long</span></kbd></dt> -<dd><p>options can be long also</p> -</dd> -<dt><kbd><span class="option">--input=<var>file</var></span></kbd></dt> -<dd><p>long options can also have -arguments</p> -</dd> -<dt><kbd><span class="option">--very-long-option</span></kbd></dt> -<dd><p>The description can also start on the next line.</p> -<p>The description may contain multiple body elements, -regardless of where it starts.</p> -</dd> -<dt><kbd><span class="option">-x</span>, <span class="option">-y</span>, <span class="option">-z</span></kbd></dt> -<dd><p>Multiple options are an "option group".</p> -</dd> -<dt><kbd><span class="option">-v</span>, <span class="option">--verbose</span></kbd></dt> -<dd><p>Commonly-seen: short & long options.</p> -</dd> -<dt><kbd><span class="option">-1 <var>file</var></span>, <span class="option">--one=<var>file</var></span>, <span class="option">--two <var>file</var></span></kbd></dt> -<dd><p>Multiple options with arguments.</p> -</dd> -<dt><kbd><span class="option">/V</span></kbd></dt> -<dd><p>DOS/VMS-style options too</p> -</dd> -</dl> -<p>There must be at least two spaces between the option and the -description.</p> -</div> -<div class="section" id="literal-blocks"> -<h2><a class="toc-backref" href="#id46"><span class="sectnum">2.7</span> Literal Blocks</a></h2> -<p>Literal blocks are indicated with a double-colon ("::") at the end of -the preceding paragraph (over there <span class="docutils literal"><span class="pre">--></span></span>). They can be indented:</p> -<pre class="literal-block">if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None</pre> -<p>Or they can be quoted without indentation:</p> -<pre class="literal-block">>> Great idea! -> -> Why didn't I think of that?</pre> -</div> -<div class="section" id="line-blocks"> -<h2><a class="toc-backref" href="#id47"><span class="sectnum">2.8</span> Line Blocks</a></h2> -<p>This section tests line blocks. Line blocks are body elements which -consist of lines and other line blocks. Nested line blocks cause -indentation.</p> -<div class="line-block"> -<div class="line">This is a line block. It ends with a blank line.</div> -<div class="line-block"> -<div class="line">New lines begin with a vertical bar ("|").</div> -<div class="line">Line breaks and initial indent are significant, and preserved.</div> -<div class="line-block"> -<div class="line">Continuation lines are also possible. A long line that is intended -to wrap should begin with a space in place of the vertical bar.</div> -</div> -<div class="line">The left edge of a continuation line need not be aligned with -the left edge of the text above it.</div> -</div> -</div> -<div class="line-block"> -<div class="line">This is a second line block.</div> -<div class="line"><br /></div> -<div class="line">Blank lines are permitted internally, but they must begin with a "|".</div> -</div> -<p>Another line block, surrounded by paragraphs:</p> -<div class="line-block"> -<div class="line">And it's no good waiting by the window</div> -<div class="line">It's no good waiting for the sun</div> -<div class="line">Please believe me, the things you dream of</div> -<div class="line">They don't fall in the lap of no-one</div> -</div> -<p>Take it away, Eric the Orchestra Leader!</p> -<blockquote> -<div class="line-block"> -<div class="line">A one, two, a one two three four</div> -<div class="line"><br /></div> -<div class="line">Half a bee, philosophically,</div> -<div class="line-block"> -<div class="line">must, <em>ipso facto</em>, half not be.</div> -</div> -<div class="line">But half the bee has got to be,</div> -<div class="line-block"> -<div class="line"><em>vis a vis</em> its entity. D'you see?</div> -<div class="line"><br /></div> -</div> -<div class="line">But can a bee be said to be</div> -<div class="line-block"> -<div class="line">or not to be an entire bee,</div> -<div class="line-block"> -<div class="line">when half the bee is not a bee,</div> -<div class="line-block"> -<div class="line">due to some ancient injury?</div> -<div class="line"><br /></div> -</div> -</div> -</div> -<div class="line">Singing...</div> -</div> -</blockquote> -<p>A line block, like the following poem by Christian Morgenstern, can -also be centre-aligned:</p> -<div class="align-center line-block" xml:lang="de"> -<div class="line"><strong>Die Trichter</strong></div> -<div class="line"><br /></div> -<div class="line">Zwei Trichter wandeln durch die Nacht.</div> -<div class="line">Durch ihres Rumpfs verengten Schacht</div> -<div class="line">fließt weißes Mondlicht</div> -<div class="line">still und heiter</div> -<div class="line">auf ihren</div> -<div class="line">Waldweg</div> -<div class="line">u. s.</div> -<div class="line">w.</div> -<div class="line"><br /></div> -</div> -</div> -<div class="section" id="block-quotes"> -<h2><a class="toc-backref" href="#id48"><span class="sectnum">2.9</span> Block Quotes</a></h2> -<p>Block quotes consist of indented body elements:</p> -<blockquote> -<p>My theory by A. Elk. Brackets Miss, brackets. This theory goes -as follows and begins now. All brontosauruses are thin at one -end, much much thicker in the middle and then thin again at the -far end. That is my theory, it is mine, and belongs to me and I -own it, and what it is too.</p> -<p class="attribution">—<cite>Anne Elk (Miss)</cite></p> -</blockquote> -<p>The language of a quote (like any other object) can be specified by -a class attribute:</p> -<!-- --> -<blockquote xml:lang="fr"> -<p>ReStructuredText est un langage de balisage léger utilisé -notamment dans la documentation du langage Python.</p> -</blockquote> -</div> -<div class="section" id="doctest-blocks"> -<h2><a class="toc-backref" href="#id49"><span class="sectnum">2.10</span> Doctest Blocks</a></h2> -<pre class="code python doctest">>>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions) -</pre> -</div> -<div class="section" id="footnotes"> -<h2><a class="toc-backref" href="#id50"><span class="sectnum">2.11</span> Footnotes</a></h2> -<dl class="footnote"> -<dt class="label" id="id8">[1]<span class="fn-backref">(<a href="#id1">1</a>,<a href="#id9">2</a>,<a href="#id22">3</a>)</span></dt> -<dd><p>A footnote contains body elements, consistently indented by at -least 3 spaces.</p> -<p>This is the footnote's second paragraph.</p> -</dd> -<dt class="label" id="label">[2]<span class="fn-backref">(<a href="#id3">1</a>,<a href="#id10">2</a>)</span></dt> -<dd><p>Footnotes may be numbered, either manually (as in <a class="footnote-reference" href="#id8" id="id9">[1]</a>) or -automatically using a "#"-prefixed label. This footnote has a -label so it can be referred to from multiple places, both as a -footnote reference (<a class="footnote-reference" href="#label" id="id10">[2]</a>) and as a <a class="reference internal" href="#label">hyperlink reference</a>.</p> -</dd> -<dt class="label" id="id12"><a class="fn-backref" href="#id2">[3]</a></dt> -<dd><p>This footnote is numbered automatically and anonymously using a -label of "#" only.</p> -<p>This is the second paragraph.</p> -<p>And this is the third paragraph.</p> -</dd> -<dt class="label" id="id13"><a class="fn-backref" href="#id4">[*]</a></dt> -<dd><p>Footnotes may also use symbols, specified with a "*" label. -Here's a reference to the next footnote: <a class="footnote-reference" href="#id15" id="id14">[†]</a>.</p> -</dd> -<dt class="label" id="id15"><a class="fn-backref" href="#id14">[†]</a></dt> -<dd><p>This footnote shows the next symbol in the sequence.</p> -</dd> -<dt class="label" id="id16">[4]</dt> -<dd><p>Here's an unreferenced footnote, with a reference to a -nonexistent footnote: <a href="#id87"><span class="problematic" id="id88"><span id="id17"></span>[5]_</span></a>.</p> -</dd> -</dl> -</div> -<div class="section" id="citations"> -<h2><a class="toc-backref" href="#id51"><span class="sectnum">2.12</span> Citations</a></h2> -<dl class="citation"> -<dt class="label" id="cit2002">[CIT2002]<span class="fn-backref">(<a href="#id5">1</a>,<a href="#id18">2</a>)</span></dt> -<dd><p>Citations are text-labeled footnotes. They may be -rendered separately and differently from footnotes.</p> -</dd> -</dl> -<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id18">[CIT2002]</a>, and a <a href="#id89"><span class="problematic" id="id90"><span id="id19"></span>[nonexistent]_</span></a> -citation.</p> -</div> -<div class="section" id="targets"> -<span id="another-target"></span><h2><a class="toc-backref" href="#id52"><span class="sectnum">2.13</span> Targets</a></h2> -<p id="example">This paragraph is pointed to by the explicit "example" target. A -reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline -hyperlink targets</a> are also possible.</p> -<p>Section headers are implicit targets, referred to by name. See -<a class="reference internal" href="#targets">Targets</a>, which is a subsection of <a class="reference internal" href="#body-elements">Body Elements</a>.</p> -<p>Explicit external targets are interpolated into references such as -"<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id27">[5]</a>".</p> -<p>Targets may be indirect and anonymous. Thus <a class="reference internal" href="#targets">this phrase</a> may also -refer to the <a class="reference internal" href="#targets">Targets</a> section.</p> -<p>Here's a <a href="#id91"><span class="problematic" id="id92">`hyperlink reference without a target`_</span></a>, which generates an -error.</p> -<div class="section" id="duplicate-target-names"> -<h3><a class="toc-backref" href="#id53"><span class="sectnum">2.13.1</span> Duplicate Target Names</a></h3> -<p>Duplicate names in section headers or other implicit targets will -generate "info" (level-1) system messages. Duplicate names in -explicit targets will generate "warning" (level-2) system messages.</p> -</div> -<div class="section" id="id21"> -<h3><a class="toc-backref" href="#id54"><span class="sectnum">2.13.2</span> Duplicate Target Names</a></h3> -<p>Since there are two "Duplicate Target Names" section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: <a href="#id93"><span class="problematic" id="id94">`Duplicate Target Names`_</span></a>), an error is generated.</p> -</div> -</div> -<div class="section" id="directives"> -<h2><a class="toc-backref" href="#id55"><span class="sectnum">2.14</span> Directives</a></h2> -<div class="contents local topic" id="contents"> -<ul class="auto-toc simple"> -<li><p><a class="reference internal" href="#document-parts" id="id78"><span class="sectnum">2.14.1</span> Document Parts</a></p></li> -<li><p><a class="reference internal" href="#images-and-figures" id="id79"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li> -<li><p><a class="reference internal" href="#admonitions" id="id80"><span class="sectnum">2.14.3</span> Admonitions</a></p></li> -<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id81"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></p></li> -<li><p><a class="reference internal" href="#target-footnotes" id="id82"><span class="sectnum">2.14.5</span> Target Footnotes</a></p></li> -<li><p><a class="reference internal" href="#replacement-text" id="id83"><span class="sectnum">2.14.6</span> Replacement Text</a></p></li> -<li><p><a class="reference internal" href="#compound-paragraph" id="id84"><span class="sectnum">2.14.7</span> Compound Paragraph</a></p></li> -<li><p><a class="reference internal" href="#parsed-literal-blocks" id="id85"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></p></li> -<li><p><a class="reference internal" href="#code" id="id86"><span class="sectnum">2.14.9</span> Code</a></p></li> -</ul> -</div> -<p>These are just a sample of the many reStructuredText Directives. For -others, please see -<a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html">http://docutils.sourceforge.net/docs/ref/rst/directives.html</a>.</p> -<div class="section" id="document-parts"> -<h3><a class="toc-backref" href="#id78"><span class="sectnum">2.14.1</span> Document Parts</a></h3> -<p>An example of the "contents" directive can be seen above this section -(a local, untitled table of <a class="reference internal" href="#contents">contents</a>) and at the beginning of the -document (a document-wide <a class="reference internal" href="#table-of-contents">table of contents</a>).</p> -</div> -<div class="section" id="images-and-figures"> -<h3><a class="toc-backref" href="#id79"><span class="sectnum">2.14.2</span> Images and Figures</a></h3> -<p>An image directive (also clickable -- a hyperlink reference):</p> -<a class="reference internal image-reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></a> -<p>Image with multiple IDs:</p> -<span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/title.png" id="image-target-3" src="../../../docs/user/rst/images/title.png" /> -<p>A centered image:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" class="align-center" src="../../../docs/user/rst/images/biohazard.png" /> -<p>A left-aligned image:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" class="align-left" src="../../../docs/user/rst/images/biohazard.png" /> -<p>This paragraph might flow around the image. -The specific behavior depends upon the style sheet and -the browser or rendering software used.</p> -<p>A right-aligned image:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" class="align-right" src="../../../docs/user/rst/images/biohazard.png" /> -<p>This paragraph might flow around the image. -The specific behavior depends upon the style sheet and -the browser or rendering software used.</p> -<p>For inline images see <a class="reference internal" href="#substitution-definitions">Substitution Definitions</a>.</p> -<p>Image size:</p> -<p>An image 2 em wide:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" /> -<p>An image 2 em wide and 15 pixel high:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em; height: 15px;" /> -<p>An image occupying 50% of the line width:</p> -<img alt="../../../docs/user/rst/images/title.png" src="../../../docs/user/rst/images/title.png" style="width: 50%;" /> -<p>An image 2 cm high:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="height: 2cm;" /> -<p>A <em>figure</em> is an image with a caption and/or a legend. With page-based output -media, figures might float to a different position if this helps the page -layout.</p> -<div class="figclass1 figclass2 figure"> -<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 258px;" /> -<p class="caption">Plaintext markup syntax and parser system.</p> -<div class="legend"> -<table> -<colgroup> -<col style="width: 20%" /> -<col style="width: 80%" /> -</colgroup> -<tbody> -<tr><td><p>re</p></td> -<td><p>Revised, revisited, based on 're' module.</p></td> -</tr> -<tr><td><p>Structured</p></td> -<td><p>Structure-enhanced text, structuredtext.</p></td> -</tr> -<tr><td><p>Text</p></td> -<td><p>Well it is, isn't it?</p></td> -</tr> -</tbody> -</table> -<p>This paragraph is also part of the legend.</p> -</div> -</div> -<p>A left-aligned figure:</p> -<div class="figclass1 figclass2 figure align-left" style="width: 70%"> -<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" /> -<p class="caption">This is the caption.</p> -<div class="legend"> -<p>This is the legend.</p> -<p>The legend may consist of several paragraphs.</p> -</div> -</div> -<p>This paragraph might flow around the figure.</p> -<p>The specific behavior depends upon the style sheet and the browser or -rendering software used.</p> -<p>A centered figure:</p> -<div class="figure align-center"> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" /> -<p class="caption">This is the caption.</p> -<div class="legend"> -<p>This is the legend.</p> -<p>The legend may consist of several paragraphs.</p> -</div> -</div> -<p>This paragraph might flow around the figure.</p> -<p>The specific behavior depends upon the style sheet and the browser or -rendering software used.</p> -<p>A right-aligned figure:</p> -<div class="figure align-right"> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" /> -<p class="caption">This is the caption.</p> -<div class="legend"> -<p>This is the legend.</p> -<p>The legend may consist of several paragraphs.</p> -</div> -</div> -<p>This paragraph might flow around the figure. The specific behavior depends -upon the style sheet and the browser or rendering software used.</p> -</div> -<div class="section" id="admonitions"> -<h3><a class="toc-backref" href="#id80"><span class="sectnum">2.14.3</span> Admonitions</a></h3> -<div class="admonition attention"> -<p class="admonition-title">Attention!</p> -<p>Directives at large.</p> -</div> -<div class="admonition caution"> -<p class="admonition-title">Caution!</p> -<p>Don't take any wooden nickels.</p> -</div> -<div class="admonition danger"> -<p class="admonition-title">!DANGER!</p> -<p>Mad scientist at work!</p> -</div> -<div class="admonition error"> -<p class="admonition-title">Error</p> -<p>Does not compute.</p> -</div> -<div class="admonition hint"> -<p class="admonition-title">Hint</p> -<p>It's bigger than a bread box.</p> -</div> -<div class="admonition important"> -<p class="admonition-title">Important</p> -<ul class="simple"> -<li><p>Wash behind your ears.</p></li> -<li><p>Clean up your room.</p></li> -<li><p>Call your mother.</p></li> -<li><p>Back up your data.</p></li> -</ul> -</div> -<div class="admonition note"> -<p class="admonition-title">Note</p> -<p>This is a note.</p> -</div> -<div class="admonition tip"> -<p class="admonition-title">Tip</p> -<p>15% if the service is good.</p> -</div> -<div class="admonition warning"> -<p class="admonition-title">Warning</p> -<p>Strong prose may provoke extreme mental exertion. -Reader discretion is strongly advised.</p> -</div> -<div class="admonition admonition-and-by-the-way"> -<p class="admonition-title">And, by the way...</p> -<p>You can make up your own admonition too.</p> -</div> -</div> -<div class="section" id="topics-sidebars-and-rubrics"> -<h3><a class="toc-backref" href="#id81"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></h3> -<p><em>Sidebars</em> are like miniature, parallel documents.</p> -<div class="sidebar"> -<p class="sidebar-title">Sidebar Title</p> -<p class="sidebar-subtitle">Optional Subtitle</p> -<p>This is a sidebar. It is for text outside the flow of the main -text.</p> -<p class="rubric">This is a rubric inside a sidebar</p> -<p>Sidebars often appear beside the main text with a border and a different -background or font color.</p> -</div> -<p>A <em>topic</em> is like a block quote with a title, or a self-contained section -with no subsections.</p> -<div class="topic"> -<p class="topic-title first">Topic Title</p> -<p>This is a topic.</p> -</div> -<p>A <em>rubric</em> is like an informal heading that doesn't correspond to the -document's structure. It is typically highlighted in red (hence the name).</p> -<p class="rubric">This is a rubric</p> -<p>Topics and rubrics can be used at places where a <a class="reference internal" href="#section-title">section title</a> is not -allowed (e.g. inside a directive).</p> -</div> -<div class="section" id="target-footnotes"> -<h3><a class="toc-backref" href="#id82"><span class="sectnum">2.14.5</span> Target Footnotes</a></h3> -<dl class="footnote"> -<dt class="label" id="id25">[5]<span class="fn-backref">(<a href="#id26">1</a>,<a href="#id27">2</a>,<a href="#id28">3</a>,<a href="#id31">4</a>)</span></dt> -<dd><p><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></p> -</dd> -<dt class="label" id="id29"><a class="fn-backref" href="#id30">[6]</a></dt> -<dd><p><a class="reference external" href="http://pygments.org/">http://pygments.org/</a></p> -</dd> -<dt class="label" id="id32"><a class="fn-backref" href="#id33">[7]</a></dt> -<dd><p><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></p> -</dd> -</dl> -</div> -<div class="section" id="replacement-text"> -<h3><a class="toc-backref" href="#id83"><span class="sectnum">2.14.6</span> Replacement Text</a></h3> -<p>I recommend you try <a class="reference external" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="footnote-reference" href="#id25" id="id28">[5]</a>.</p> -</div> -<div class="section" id="compound-paragraph"> -<h3><a class="toc-backref" href="#id84"><span class="sectnum">2.14.7</span> Compound Paragraph</a></h3> -<div class="some-class compound"> -<p class="compound-first">Compound 1, paragraph 1.</p> -<p class="compound-middle">Compound 1, paragraph 2.</p> -<ul class="compound-last simple"> -<li><p>Compound 1, list item one.</p></li> -<li><p>Compound 1, list item two.</p></li> -</ul> -</div> -<p>Another compound statement:</p> -<div class="compound"> -<p class="compound-first">Compound 2, a literal block:</p> -<pre class="compound-middle literal-block">Compound 2, literal.</pre> -<p class="compound-last">Compound 2, this is a test.</p> -</div> -<div class="compound"> -<p>Compound 3, only consisting of one paragraph.</p> -</div> -<div class="compound"> -<pre class="compound-first literal-block">Compound 4. -This one starts with a literal block.</pre> -<p class="compound-last">Compound 4, a paragraph.</p> -</div> -<p>Now something <em>really</em> perverted -- a nested compound block. This is -just to test that it works at all; the results don't have to be -meaningful.</p> -<div class="compound"> -<p class="compound-first">Compound 5, block 1 (a paragraph).</p> -<div class="compound-middle compound"> -<p class="compound-first">Compound 6, block 2 in compound 5.</p> -<p class="compound-last">Compound 6, another paragraph.</p> -</div> -<p class="compound-last">Compound 5, block 3 (a paragraph).</p> -</div> -<div class="compound"> -<p class="compound-first">Compound 7, with a table inside:</p> -<table class="compound-middle"> -<colgroup> -<col style="width: 33%" /> -<col style="width: 33%" /> -<col style="width: 33%" /> -</colgroup> -<tbody> -<tr><td><p>Left cell, first -paragraph.</p> -<p>Left cell, second -paragraph.</p> -</td> -<td><p>Middle cell, -consisting of -exactly one -paragraph.</p></td> -<td><p>Right cell.</p> -<p>Paragraph 2.</p> -<p>Paragraph 3.</p> -</td> -</tr> -</tbody> -</table> -<p class="compound-middle">Compound 7, a paragraph after the table.</p> -<p class="compound-last">Compound 7, another paragraph.</p> -</div> -</div> -<div class="section" id="parsed-literal-blocks"> -<h3><a class="toc-backref" href="#id85"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></h3> -<pre class="literal-block">This is a parsed literal block. - This line is indented. The next line is blank. - -Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <span class="docutils literal">literal -text</span>, <span class="subscript">sub-</span> and <span class="superscript">super</span>scripts, -inline formulas: <span><math xmlns="http://www.w3.org/1998/Math/MathML"> -<mrow><mi>A</mi><mo>=</mo><mn>2</mn><mi>π</mi><msup><mi>r</mi><mn>2</mn></msup></mrow></math></span>, -footnotes <a class="footnote-reference" href="#id8" id="id22">[1]</a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>.</pre> -</div> -<div class="section" id="code"> -<h3><a class="toc-backref" href="#id86"><span class="sectnum">2.14.9</span> Code</a></h3> -<p>Blocks of source code can be set with the <cite>code</cite> directive. If the code -language is specified, the content is parsed and tagged by the <a class="reference external" href="http://pygments.org/">Pygments</a> <a class="footnote-reference" href="#id29" id="id30">[6]</a> -syntax highlighter and can be formatted with a style sheet. (Code parsing -is turned off using the <span class="docutils literal"><span class="pre">syntax-highlight</span></span> config setting in the test -conversions in order to get identical results with/without installed -Pygments highlighter.)</p> -<pre class="code python literal-block"><code>print 'This is Python code.'</code></pre> -<p>The <span class="docutils literal"><span class="pre">:number-lines:</span></span> option (with optional start value) generates line -numbers:</p> -<pre class="code python literal-block"><code><span class="ln"> 8 </span># print integers from 0 to 9: -<span class="ln"> 9 </span>for i in range(10): -<span class="ln">10 </span> print i</code></pre> -<p>For inline code snippets, there is the <cite>code</cite> role, which can be used -directly (the code will not be parsed/tagged, as the language is not known) -or as base for special code roles, e.g. the LaTeX code in the next -paragraph.</p> -<p>Docutils uses LaTeX syntax for math directives and roles: -<code class="tex">\alpha = f(x)</code> prints <span><math xmlns="http://www.w3.org/1998/Math/MathML"> -<mrow><mi>α</mi><mo>=</mo><mi>f</mi><mo>(</mo><mi>x</mi><mo>)</mo></mrow></math></span>.</p> -<p>The <span class="docutils literal">:code:</span> option of the <cite>include</cite> directive sets the included content -as a code block, here the rst file <span class="docutils literal">header_footer.txt</span> with line numbers:</p> -<pre class="code rst literal-block"><code><span class="ln">1 </span>.. header:: Document header -<span class="ln">2 </span>.. footer:: Document footer</code></pre> -</div> -</div> -<div class="section" id="substitution-definitions"> -<h2><a class="toc-backref" href="#id65"><span class="sectnum">2.15</span> Substitution Definitions</a></h2> -<p>An inline image (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />) example:</p> -<p>(Substitution definitions are not visible in the HTML source.)</p> -</div> -<div class="section" id="comments"> -<h2><a class="toc-backref" href="#id66"><span class="sectnum">2.16</span> Comments</a></h2> -<p>Here's one:</p> -<!-- Comments begin with two dots and a space. Anything may -follow, except for the syntax of footnotes, hyperlink -targets, directives, or substitution definitions. - -Double-dashes - - "- -" - - must be escaped somehow in HTML output. - -Comments may contain non-ASCII characters: ä ö ü æ ø å --> -<p>(View the HTML source to see the comment.)</p> -</div> -<div class="section" id="raw-text"> -<h2><a class="toc-backref" href="#id67"><span class="sectnum">2.17</span> Raw text</a></h2> -<p>This does not necessarily look nice, because there may be missing white space.</p> -<p>It's just there to freeze the behavior.</p> -A test.Second test.<div class="myclass">Another test with myclass set.</div><p>This is the <span class="myrawroleclass">fourth test</span> with myrawroleclass set.</p> -Fifth test in HTML.<br />Line two.</div> -<div class="section" id="container"> -<h2><a class="toc-backref" href="#id68"><span class="sectnum">2.18</span> Container</a></h2> -<div class="custom docutils container"> -<p>paragraph 1</p> -<p>paragraph 2</p> -</div> -</div> -<div class="section" id="colspanning-tables"> -<h2><a class="toc-backref" href="#id69"><span class="sectnum">2.19</span> Colspanning tables</a></h2> -<p>This table has a cell spanning two columns:</p> -<table> -<colgroup> -<col style="width: 31%" /> -<col style="width: 31%" /> -<col style="width: 38%" /> -</colgroup> -<thead> -<tr><th class="head" colspan="2"><p>Inputs</p></th> -<th class="head"><p>Output</p></th> -</tr> -<tr><th class="head"><p>A</p></th> -<th class="head"><p>B</p></th> -<th class="head"><p>A or B</p></th> -</tr> -</thead> -<tbody> -<tr><td><p>False</p></td> -<td><p>False</p></td> -<td><p>False</p></td> -</tr> -<tr><td><p>True</p></td> -<td><p>False</p></td> -<td><p>True</p></td> -</tr> -<tr><td><p>False</p></td> -<td><p>True</p></td> -<td><p>True</p></td> -</tr> -<tr><td><p>True</p></td> -<td><p>True</p></td> -<td><p>True</p></td> -</tr> -</tbody> -</table> -</div> -<div class="section" id="rowspanning-tables"> -<h2><a class="toc-backref" href="#id70"><span class="sectnum">2.20</span> Rowspanning tables</a></h2> -<p>Here's a table with cells spanning several rows:</p> -<table> -<colgroup> -<col style="width: 44%" /> -<col style="width: 22%" /> -<col style="width: 33%" /> -</colgroup> -<thead> -<tr><th class="head"><p>Header row, column 1 -(header rows optional)</p></th> -<th class="head"><p>Header 2</p></th> -<th class="head"><p>Header 3</p></th> -</tr> -</thead> -<tbody> -<tr><td><p>body row 1, column 1</p></td> -<td><p>column 2</p></td> -<td><p>column 3</p></td> -</tr> -<tr><td><p>body row 2</p></td> -<td rowspan="2"><p>Cells may -span rows.</p></td> -<td rowspan="2"><p>Another -rowspanning -cell.</p></td> -</tr> -<tr><td><p>body row 3</p></td> -</tr> -</tbody> -</table> -</div> -<div class="section" id="complex-tables"> -<h2><a class="toc-backref" href="#id71"><span class="sectnum">2.21</span> Complex tables</a></h2> -<p>Here's a complex table, which should test all features.</p> -<table> -<colgroup> -<col style="width: 43%" /> -<col style="width: 21%" /> -<col style="width: 18%" /> -<col style="width: 18%" /> -</colgroup> -<thead> -<tr><th class="head"><p>Header row, column 1 -(header rows optional)</p></th> -<th class="head"><p>Header 2</p></th> -<th class="head"><p>Header 3</p></th> -<th class="head"><p>Header 4</p></th> -</tr> -</thead> -<tbody> -<tr><td><p>body row 1, column 1</p></td> -<td><p>column 2</p></td> -<td><p>column 3</p></td> -<td><p>column 4</p></td> -</tr> -<tr><td><p>body row 2</p></td> -<td colspan="3"><p>Cells may span columns.</p></td> -</tr> -<tr><td><p>body row 3</p></td> -<td rowspan="2"><p>Cells may -span rows.</p> -<p>Paragraph.</p> -</td> -<td colspan="2" rowspan="2"><ul class="simple"> -<li><p>Table cells</p></li> -<li><p>contain</p></li> -<li><p>body elements.</p></li> -</ul> -</td> -</tr> -<tr><td><p>body row 4</p></td> -</tr> -<tr><td><p>body row 5</p></td> -<td colspan="2"><p>Cells may also be -empty: <span class="docutils literal"><span class="pre">--></span></span></p></td> -<td></td> -</tr> -</tbody> -</table> -</div> -<div class="section" id="list-tables"> -<h2><a class="toc-backref" href="#id72"><span class="sectnum">2.22</span> List Tables</a></h2> -<p>Here's a list table exercising all features:</p> -<table class="test"> -<caption>list table with integral header</caption> -<colgroup> -<col style="width: 17%" /> -<col style="width: 33%" /> -<col style="width: 50%" /> -</colgroup> -<thead> -<tr><th class="head stub"><p>Treat</p></th> -<th class="head"><p>Quantity</p></th> -<th class="head"><p>Description</p></th> -</tr> -</thead> -<tbody> -<tr><th class="stub"><p>Albatross</p></th> -<td><p>2.99</p></td> -<td><p>On a stick!</p></td> -</tr> -<tr><th class="stub"><p>Crunchy Frog</p></th> -<td><p>1.49</p></td> -<td><p>If we took the bones out, it wouldn't be -crunchy, now would it?</p></td> -</tr> -<tr><th class="stub"><p>Gannet Ripple</p></th> -<td><p>1.99</p></td> -<td><p>On a stick!</p></td> -</tr> -</tbody> -</table> -</div> -<div class="section" id="custom-roles"> -<h2><a class="toc-backref" href="#id73"><span class="sectnum">2.23</span> Custom Roles</a></h2> -<ul> -<li><p>A role based on an existing role.</p> -<p><span class="custom docutils literal">one</span> <span class="custom docutils literal">two</span> <span class="custom docutils literal">three</span></p> -</li> -<li><p>A new role.</p> -<p><span class="customnew">one two three</span></p> -</li> -<li><p>A role with class attribute.</p> -<p><span class="special">interpreted text</span></p> -</li> -<li><p>A language-switching role:</p> -<p>Let's count in German <span xml:lang="de">eins zwei drei</span>.</p> -</li> -<li><p>A role with multiple class attributes, styled with raw directives:</p> -<p>The following works in most browsers but does not validate -(<span class="docutils literal"><style></span> is only allowed in the document head):</p> -<pre class="literal-block">.. raw:: html - - <style type="text/css"><!-- - .green {color: green;} - .sc {font-variant: small-caps;} - --></style></pre> -<p><span class="green sc" xml:lang="en-gb">British colourful text in small-caps</span>.</p> -</li> -</ul> -</div> -<div class="section" id="svg-images"> -<h2><a class="toc-backref" href="#id74"><span class="sectnum">2.24</span> SVG Images</a></h2> -<img alt="../../../docs/user/rst/images/biohazard.svg" class="align-left" src="../../../docs/user/rst/images/biohazard.svg" style="width: 48px; height: 48px;" /> -<p>Scalable vector graphics (SVG) images are the only standards-compliable way -to include vector graphics in HTML documents. However, they are not -supported by all backends/output formats. (E.g., LaTeX supports the -PDF or Postscript formats for vector graphics instead.)</p> -<p>Rendering behaviour varies, depending on</p> -<ol class="loweralpha"> -<li><p>The SVG image itself, e.g. fixed-size vs. scaling:</p> -<pre class="literal-block">width="280" viewBox="0 0 280 27" -height="27" width="100%" - height="100%"</pre> -</li> -<li><p>The method used to put the image in the document.</p> -<p>For HTML, there are several alternatives including:</p> -<ul class="simple"> -<li><p>using the HTML <span class="docutils literal"><img></span> tag (not for interactive/animated SVG),</p></li> -<li><p>using the HTML <span class="docutils literal"><object></span> tag,</p></li> -<li><p>including within SVG using the SVG <span class="docutils literal"><image></span> tag,</p></li> -<li><p>embedd the SVG code within HTML (inlining).</p></li> -</ul> -<p>The <cite>html4css1</cite> writer uses <span class="docutils literal"><object></span> tags, the <cite>html-base</cite> and <cite>xhtml11</cite> -writers use <span class="docutils literal"><img></span> tags.</p> -<!-- cf. http://edutechwiki.unige.ch/en/Using_SVG_with_HTML5_tutorial --> -</li> -<li><p>The viewing agent.</p> -<p>All up-to-date HTML browsers support SVG, however not all do this fully -and in the same manner. Many older versions, especially IE < 9, have -deficiencies or require plug-ins (i.e. don't support the <span class="docutils literal"><img></span> tag).</p> -</li> -</ol> -<p>If the image is wrapped in <span class="docutils literal"><object></span> or <span class="docutils literal"><svg></span> tags, it depends on the -<span class="docutils literal">viewBox</span> declaration inside the images root <span class="docutils literal"><svg></span> element whether an -SVG image is scaled or clipped/padded. Images wrapped in <span class="docutils literal"><img></span> are -always scaled.</p> -<ul> -<li><img alt="../../../docs/user/rst/images/title-scaling.svg" class="align-right" src="../../../docs/user/rst/images/title-scaling.svg" style="width: 50%;" /> -<p>A scaling image (scales with the browser window), occupying 50% of the line -width. The <span class="docutils literal">viewBox</span> setting in the image file enables auto-scaling also in -<span class="docutils literal"><object></span> tags and embedded SVG (if width and hight are set to 100% in the -SVG <image> tag).</p> -</li> -<li><img alt="../../../docs/user/rst/images/title.svg" class="align-right" src="../../../docs/user/rst/images/title.svg" style="width: 50%; height: 15px;" /> -<p>A fixed-size image in a box 50% wide and 15 pixles high. This image is -scaled, if wrapped in an <span class="docutils literal"><img></span> tag but clipped in an <span class="docutils literal"><object></span> tag -or within SVG.</p> -</li> -<li><img alt="../../../docs/user/rst/images/title-scaling.svg" class="align-right" src="../../../docs/user/rst/images/title-scaling.svg" style="width: 50%; height: 1.5em;" /> -<p>A right aligned, scaling image 50% wide and 1.5 em high. (This SVG image -keeps the aspect ratio.)</p> -</li> -<li><p>An inline image <img alt="inline-svg" src="../../../docs/user/rst/images/biohazard-scaling.svg" style="height: 0.8em;" /> scaled to a height of 0.8 em.</p> -</li> -<li><img alt="../../../docs/user/rst/images/biohazard-scaling.svg" class="align-right" src="../../../docs/user/rst/images/biohazard-scaling.svg" style="height: 1em;" /> -<p>A scaling image 1 em high, right aligned:</p> -</li> -<li><p>A scaling image 5 mm x 5 mm, centered, with hyperlink reference:</p> -<a class="reference internal image-reference" href="#svg-images"><img alt="../../../docs/user/rst/images/biohazard-scaling.svg" class="align-center" src="../../../docs/user/rst/images/biohazard-scaling.svg" style="width: 5mm; height: 5mm;" /></a> -</li> -<li><img alt="../../../docs/user/rst/images/biohazard.svg" class="align-right" src="../../../docs/user/rst/images/biohazard.svg" style="width: 4cm; height: 2em;" /> -<p>A fixed-size image in a 4 cm x 2 em box.</p> -</li> -</ul> -<p>Older versions of <cite>webkit</cite> based browsers (chromium, safari, midori, -konqueror) support the <span class="docutils literal"><img></span> tag but don't display contained bitmap -images in this case.</p> -<ul> -<li><img alt="../../../docs/user/rst/images/biohazard-bitmap.svg" class="align-right" src="../../../docs/user/rst/images/biohazard-bitmap.svg" style="width: 3em;" /> -<p>A small, fixed-size SVG image with embedded bitmap, The <span class="docutils literal">:width:</span> is -set to 3 em in the rST source. Does not scale if wrapped in <span class="docutils literal"><object></span> -tags.</p> -</li> -<li><img alt="../../../docs/user/rst/images/biohazard-bitmap-scaling.svg" class="align-right" src="../../../docs/user/rst/images/biohazard-bitmap-scaling.svg" style="width: 3em;" /> -<p>A scaling SVG image with embedded bitmap, 3 em wide.</p> -</li> -</ul> -<p>SVG images can also be put in figures:</p> -<blockquote> -<div class="figure align-center"> -<img alt="reStructuredText, the markup syntax" src="../../../docs/user/rst/images/title.svg" style="width: 290px; height: 28px;" /> -<p class="caption"><strong>Figure:</strong> SVG image in a figure.</p> -</div> -</blockquote> -</div> -<div class="section" id="swf-images"> -<h2><a class="toc-backref" href="#id75"><span class="sectnum">2.25</span> SWF Images</a></h2> -<p>Shockwave Flash is an image/movie format that most modern web browsers -support via a plugin. It is sometimes blocked due to privacy/security -concerns.</p> -<p>Images with extension <span class="docutils literal">.swf</span> are placed inside <object> elements. -For complete control over display options use raw HTML.</p> -<object class="align-left" data="../../../docs/user/rst/images/biohazard.swf" style="width: 4cm; height: 2em;" type="application/x-shockwave-flash"> -[biohazard.swf]</object> -<p>An SWF image in a 4 cm x 2 em box, left aligned.</p> -<p>An inline SWF image <object data="../../../docs/user/rst/images/biohazard.swf" style="width: 0.8em; height: 0.8em;" type="application/x-shockwave-flash">inline-swf</object> scaled to 0.8 em x 0.8 em.</p> -</div> -</div> -<div class="section" id="additional-xhtml11-features"> -<h1><a class="toc-backref" href="#id76"><span class="sectnum">3</span> Additional xhtml11 features</a></h1> -<p>The following features are set the the "xhtml11" writer apart from the -"html-base" writer:</p> -<ul> -<li><p>The document type is XHTML 1.1</p></li> -<li><p>An "enumerated list" with class "nested" uses nested counters:</p> -<ol class="nested arabic"> -<li><p>first point</p> -<ul class="simple"> -<li><p>Unordered list nested in enumeration.</p></li> -</ul> -<ol class="arabic"> -<li><p>first sub-point</p></li> -<li><p>second sub-point</p> -<p>With a standard paragraph</p> -<ol class="arabic simple"> -<li><p>first sub-sub-point</p></li> -</ol> -</li> -<li><p>third sub-point with a long and silly text just to test the line -wrapping in this kind of lists.</p></li> -</ol> -<dl class="simple"> -<dt>Definition list</dt> -<dd><p>nested in top-level enumeration</p> -</dd> -</dl> -</li> -<li><p>second top-level point</p></li> -</ol> -</li> -<li><p>The <span class="docutils literal"><span class="pre">html-output</span></span> setting defaults to »MathML«. If there is mathematical -content in <cite>MathML</cite> format, the document type is XHTML 1.1 plus MathML -2.0.</p> -<p>The linear mapping <span><math xmlns="http://www.w3.org/1998/Math/MathML"> -<mrow><mi>f</mi><mo>:</mo><msup><mi>ℂ</mi> -<mrow><mi>N</mi></mrow></msup><mo>⟼</mo><msup><mi>ℂ</mi> -<mrow><mi>N</mi></mrow></msup></mrow></math></span> with</p> -<div> -<math xmlns="http://www.w3.org/1998/Math/MathML" mode="display"> -<mtable> -<mtr> -<mtd><msub><mi>c</mi> -<mrow><mi>k</mi></mrow></msub><mo>=</mo><mi>F</mi><mo>(</mo><mi>k</mi><msub><mi>f</mi> -<mrow><mn>0</mn></mrow></msub><mo>)</mo><mo>=</mo><msub><mi>T</mi> -<mrow><mtext>A</mtext></mrow></msub><munderover><mo>∑</mo> -<mrow><mi>n</mi><mo>=</mo><mo>-</mo><mi>N</mi><mo>/</mo><mn>2</mn></mrow> -<mrow><mo>+</mo><mi>N</mi><mo>/</mo><mn>2</mn></mrow></munderover><mi>f</mi><mo>(</mo><msub><mi>x</mi> -<mrow><mi>n</mi></mrow></msub><mo>)</mo><msup><mtext>e</mtext> -<mrow><mo>-</mo><mn>2</mn><mi>π</mi><mtext>i</mtext><mfrac> -<mrow><mi>n</mi><mi>k</mi></mrow> -<mrow><mi>N</mi></mrow></mfrac></mrow></msup></mtd></mtr></mtable></math> -</div> -<p>for all <span><math xmlns="http://www.w3.org/1998/Math/MathML"> -<mrow><mi>a</mi><mo>∈</mo><msup><mi>ℂ</mi> -<mrow><mi>N</mi></mrow></msup></mrow></math></span> is called discrete Fourier -transformation (DFT).</p> -</li> -</ul> -</div> -<div class="section" id="error-handling"> -<h1><a class="toc-backref" href="#id77"><span class="sectnum">4</span> Error Handling</a></h1> -<p>Any errors caught during processing will generate system messages.</p> -<p>There should be five messages in the following, auto-generated -section, "Docutils System Messages":</p> -<!-- section should be added by Docutils automatically --> -</div> -<div class="system-messages section"> -<h1>Docutils System Messages</h1> -<div class="system-message" id="id23"> -<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 104); <em><a href="#id24">backlink</a></em></p> -<p>Undefined substitution referenced: "problematic".</p> -</div> -<div class="system-message" id="id87"> -<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 391); <em><a href="#id88">backlink</a></em></p> -<p>Unknown target name: "5".</p> -</div> -<div class="system-message" id="id89"> -<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 400); <em><a href="#id90">backlink</a></em></p> -<p>Unknown target name: "nonexistent".</p> -</div> -<div class="system-message" id="id91"> -<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 427); <em><a href="#id92">backlink</a></em></p> -<p>Unknown target name: "hyperlink reference without a target".</p> -</div> -<div class="system-message" id="id93"> -<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 440); <em><a href="#id94">backlink</a></em></p> -<p>Duplicate target name, cannot be used as a unique reference: "duplicate target names".</p> -</div> -</div> -</div> -<div class="footer"> -<hr class="footer" /> -<p>Document footer</p> -<p><a class="reference external" href="http://validator.w3.org/check?uri=referer"><img alt="Valid XHTML 1.1!" src="http://www.w3.org/Icons/valid-xhtml11" style="width: 88px; height: 31px;" /></a> <a class="reference external" href="http://jigsaw.w3.org/css-validator/check/referer"><img alt="Valid CSS 2.1!" src="http://jigsaw.w3.org/css-validator/images/vcss" style="width: 88px; height: 31px;" /></a></p> - -</div> -</body> -</html> diff --git a/docutils/test/functional/input/data/math.css b/docutils/test/functional/input/data/math.css index e6eec6565..4e0ec724d 100644..120000 --- a/docutils/test/functional/input/data/math.css +++ b/docutils/test/functional/input/data/math.css @@ -1,276 +1 @@ -/* -* math2html: convert LaTeX equations to HTML output. -* -* Copyright (C) 2009,2010 Alex Fernández -* -* Released under the terms of the `2-Clause BSD license'_, in short: -* Copying and distribution of this file, with or without modification, -* are permitted in any medium without royalty provided the copyright -* notice and this notice are preserved. -* This file is offered as-is, without any warranty. -* -* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause -* -* Based on eLyXer: convert LyX source files to HTML output. -* http://elyxer.nongnu.org/ -*/ -/* --end-- -* CSS file for LaTeX formulas. -*/ - -/* Formulas */ -.formula { - text-align: center; - font-family: "Droid Serif", "DejaVu Serif", "STIX", serif; - margin: 1.2em 0; -} -span.formula { - white-space: nowrap; -} -div.formula { - padding: 0.5ex; - margin-left: auto; - margin-right: auto; -} - -/* Basic features */ -a.eqnumber { - display: inline-block; - float: right; - clear: right; - font-weight: bold; -} -span.unknown { - color: #800000; -} -span.ignored, span.arraydef { - display: none; -} -.formula i { - letter-spacing: 0.1ex; -} - -/* Alignment */ -.align-left, .align-l { - text-align: left; -} -.align-right, .align-r { - text-align: right; -} -.align-center, .align-c { - text-align: center; -} - -/* Structures */ -span.overline, span.bar { - text-decoration: overline; -} -.fraction, .fullfraction { - display: inline-block; - vertical-align: middle; - text-align: center; -} -.fraction .fraction { - font-size: 80%; - line-height: 100%; -} -span.numerator { - display: block; -} -span.denominator { - display: block; - padding: 0ex; - border-top: thin solid; -} -sup.numerator, sup.unit { - font-size: 70%; - vertical-align: 80%; -} -sub.denominator, sub.unit { - font-size: 70%; - vertical-align: -20%; -} -span.sqrt { - display: inline-block; - vertical-align: middle; - padding: 0.1ex; -} -sup.root { - font-size: 70%; - position: relative; - left: 1.4ex; -} -span.radical { - display: inline-block; - padding: 0ex; - font-size: 150%; - vertical-align: top; -} -span.root { - display: inline-block; - border-top: thin solid; - padding: 0ex; - vertical-align: middle; -} -span.symbol { - line-height: 125%; - font-size: 125%; -} -span.bigsymbol { - line-height: 150%; - font-size: 150%; -} -span.largesymbol { - font-size: 175%; -} -span.hugesymbol { - font-size: 200%; -} -span.scripts { - display: inline-table; - vertical-align: middle; -} -.script { - display: table-row; - text-align: left; - line-height: 150%; -} -span.limits { - display: inline-table; - vertical-align: middle; -} -.limit { - display: table-row; - line-height: 99%; -} -sup.limit, sub.limit { - line-height: 100%; -} -span.symbolover { - display: inline-block; - text-align: center; - position: relative; - float: right; - right: 100%; - bottom: 0.5em; - width: 0px; -} -span.withsymbol { - display: inline-block; -} -span.symbolunder { - display: inline-block; - text-align: center; - position: relative; - float: right; - right: 80%; - top: 0.3em; - width: 0px; -} - -/* Environments */ -span.array, span.bracketcases, span.binomial, span.environment { - display: inline-table; - text-align: center; - border-collapse: collapse; - margin: 0em; - vertical-align: middle; -} -span.arrayrow, span.binomrow { - display: table-row; - padding: 0ex; - border: 0ex; -} -span.arraycell, span.bracket, span.case, span.binomcell, span.environmentcell { - display: table-cell; - padding: 0ex 0.2ex; - line-height: 99%; - border: 0ex; -} -/* -* CSS file for LaTeX formulas, extra stuff: -* binomials, vertical braces, stackrel, fonts and colors. -*/ - -/* Inline binomials */ -span.binom { - display: inline-block; - vertical-align: middle; - text-align: center; - font-size: 80%; -} -span.binomstack { - display: block; - padding: 0em; -} - -/* Over- and underbraces */ -span.overbrace { - border-top: 2pt solid; -} -span.underbrace { - border-bottom: 2pt solid; -} - -/* Stackrel */ -span.stackrel { - display: inline-block; - text-align: center; -} -span.upstackrel { - display: block; - padding: 0em; - font-size: 80%; - line-height: 64%; - position: relative; - top: 0.15em; - -} -span.downstackrel { - display: block; - vertical-align: bottom; - padding: 0em; -} - -/* Fonts */ -span.mathsf, span.textsf { - font-style: normal; - font-family: sans-serif; -} -span.mathrm, span.textrm { - font-style: normal; - font-family: serif; -} -span.text, span.textnormal { - font-style: normal; -} -span.textipa { - color: #008080; -} -span.fraktur { - font-family: "Lucida Blackletter", eufm10, blackletter; -} -span.blackboard { - font-family: Blackboard, msbm10, serif; -} -span.scriptfont { - font-family: "Monotype Corsiva", "Apple Chancery", "URW Chancery L", cursive; - font-style: italic; -} - -/* Colors */ -span.colorbox { - display: inline-block; - padding: 5px; -} -span.fbox { - display: inline-block; - border: thin solid black; - padding: 2px; -} -span.boxed, span.framebox { - display: inline-block; - border: thin solid black; - padding: 5px; -} - +../../../../docutils/writers/html_plain/math.css
\ No newline at end of file diff --git a/docutils/test/functional/input/data/minimal.css b/docutils/test/functional/input/data/minimal.css index d1e1e8638..899b6bbba 120000 --- a/docutils/test/functional/input/data/minimal.css +++ b/docutils/test/functional/input/data/minimal.css @@ -1 +1 @@ -../../../../docutils/writers/html_base/minimal.css
\ No newline at end of file +../../../../docutils/writers/html_plain/minimal.css
\ No newline at end of file diff --git a/docutils/test/functional/input/data/plain.css b/docutils/test/functional/input/data/plain.css index 1f2ad9396..77def792e 120000 --- a/docutils/test/functional/input/data/plain.css +++ b/docutils/test/functional/input/data/plain.css @@ -1 +1 @@ -../../../../docutils/writers/html_base/plain.css
\ No newline at end of file +../../../../docutils/writers/html_plain/plain.css
\ No newline at end of file diff --git a/docutils/test/functional/input/data/xhtml11.css b/docutils/test/functional/input/data/xhtml11.css deleted file mode 120000 index 9d6083d54..000000000 --- a/docutils/test/functional/input/data/xhtml11.css +++ /dev/null @@ -1 +0,0 @@ -../../../../docutils/writers/xhtml11/xhtml11.css
\ No newline at end of file diff --git a/docutils/test/functional/input/standalone_rst_html_base.txt b/docutils/test/functional/input/standalone_rst_html_plain.txt index 67b832f37..d53486f42 100644 --- a/docutils/test/functional/input/standalone_rst_html_base.txt +++ b/docutils/test/functional/input/standalone_rst_html_plain.txt @@ -43,7 +43,7 @@ characters" but the field name uses a proportional font. :MMMMMMMMMMMMMM: a field name that is actually longer than the previous one but regarded "short" by html4css1. -With ``html_base``, a `field list` is typeset as CSS-styled `definition +With ``html_plain``, a `field list` is typeset as CSS-styled `definition list`. The default layout is similar to the look with `html4css1`: .. class:: open diff --git a/docutils/test/functional/input/standalone_rst_xhtml11.txt b/docutils/test/functional/input/standalone_rst_xhtml11.txt deleted file mode 100644 index b5ec4242f..000000000 --- a/docutils/test/functional/input/standalone_rst_xhtml11.txt +++ /dev/null @@ -1,70 +0,0 @@ -.. include:: data/standard.txt -.. include:: data/header_footer.txt -.. include:: data/table_colspan.txt -.. include:: data/table_rowspan.txt -.. include:: data/table_complex.txt -.. include:: data/list_table.txt -.. include:: data/custom_roles.txt -.. include:: data/svg_images.txt -.. include:: data/swf_images.txt - -Additional xhtml11 features -=========================== - -The following features are set the the "xhtml11" writer apart from the -"html-base" writer: - -* The document type is XHTML 1.1 - -* An "enumerated list" with class "nested" uses nested counters: - - .. class:: nested - - #. first point - - * Unordered list nested in enumeration. - - #. first sub-point - #. second sub-point - - With a standard paragraph - - #. first sub-sub-point - - #. third sub-point with a long and silly text just to test the line - wrapping in this kind of lists. - - Definition list - nested in top-level enumeration - - #. second top-level point - -* The ``html-output`` setting defaults to »MathML«. If there is mathematical - content in `MathML` format, the document type is XHTML 1.1 plus MathML - 2.0. - - The linear mapping :math:`f: \mathbb{C}^{N}\longmapsto\mathbb{C}^{N}` with - - .. math:: - - c_{k}=F(kf_{0})=T_{\text{A}} - \sum_{n=-N/2}^{+N/2}f(x_{n})\text{e}^{-2\pi\text{i}\frac{nk}{N}} - - for all :math:`a\in\mathbb{C}^{N}` is called discrete Fourier - transformation (DFT). - -.. include:: data/errors.txt - -.. footer:: |valid-xhtml11| |valid-CSS2| - -.. |valid-xhtml11| image:: http://www.w3.org/Icons/valid-xhtml11 - :height: 31 - :width: 88 - :alt: Valid XHTML 1.1! - :target: http://validator.w3.org/check?uri=referer - -.. |valid-CSS2| image:: http://jigsaw.w3.org/css-validator/images/vcss - :height: 31 - :width: 88 - :alt: Valid CSS 2.1! - :target: http://jigsaw.w3.org/css-validator/check/referer diff --git a/docutils/test/functional/tests/math_output_mathml.py b/docutils/test/functional/tests/math_output_mathml.py index 3e9149a98..dd1017746 100644 --- a/docutils/test/functional/tests/math_output_mathml.py +++ b/docutils/test/functional/tests/math_output_mathml.py @@ -5,10 +5,10 @@ test_destination = "math_output_mathml.xhtml" # Keyword parameters passed to publish_file. reader_name = "standalone" parser_name = "rst" -writer_name = "html-base" +writer_name = "html-plain" # Settings settings_overrides['math_output'] = 'MathML' # local copy of default stylesheet: # (test runs in ``docutils/test/``, we need relative path from there.) -settings_overrides['stylesheet_dirs'] = ('.', 'functional/input/data') +settings_overrides['stylesheet_dirs'] = ('.','functional/input/data') diff --git a/docutils/test/functional/tests/standalone_rst_xhtml11.py b/docutils/test/functional/tests/standalone_rst_xhtml11.py deleted file mode 100644 index c8925ac9c..000000000 --- a/docutils/test/functional/tests/standalone_rst_xhtml11.py +++ /dev/null @@ -1,16 +0,0 @@ -# Test the xhtml11 writer: - -# common reader/parser/transform defaults for standalone tests -exec(open('functional/tests/_standalone_rst_defaults.py').read()) - -# Source and destination file names. -test_source = "standalone_rst_xhtml11.txt" -test_destination = "standalone_rst_xhtml11.xhtml" - -# Keyword parameters passed to publish_file. -writer_name = "xhtml11" - -# Settings -# local copy of default stylesheet: -# (test runs in ``docutils/test/``, we need relative path from there.) -settings_overrides['stylesheet_dirs'] = ('.', 'functional/input/data') diff --git a/docutils/test/test_writers/test_html4css1_misc.py b/docutils/test/test_writers/test_html4css1_misc.py index 7bcb8d73b..f19f9e550 100755 --- a/docutils/test/test_writers/test_html4css1_misc.py +++ b/docutils/test/test_writers/test_html4css1_misc.py @@ -100,7 +100,7 @@ class SettingsTestCase(DocutilsTestSupport.StandardTestCase): styles = core.publish_parts(self.data, writer_name='html4css1', settings_overrides=mysettings)['stylesheet'] self.assertIn('docutils/writers/html4css1/html4css1.css', styles) - self.assertIn('docutils/writers/html_base/math.css', styles) + self.assertIn('docutils/writers/html_plain/math.css', styles) def test_custom_stylesheet_linked(self): # default + custom style sheet, linked diff --git a/docutils/test/test_writers/test_html_base_misc.py b/docutils/test/test_writers/test_html_plain_misc.py index f7db124bf..b69a967f3 100644 --- a/docutils/test/test_writers/test_html_base_misc.py +++ b/docutils/test/test_writers/test_html_plain_misc.py @@ -25,7 +25,7 @@ class EncodingTestCase(DocutilsTestSupport.StandardTestCase): 'stylesheet': '', '_disable_config': True,} result = core.publish_string( - u'EUR = \u20ac', writer_name='html_base', + u'EUR = \u20ac', writer_name='html_plain', settings_overrides=settings_overrides) # Encoding a euro sign with latin1 doesn't work, so the # xmlcharrefreplace handler is used. @@ -50,7 +50,7 @@ first term: second term: second def """ - result = core.publish_string(data, writer_name='html_base', + result = core.publish_string(data, writer_name='html_plain', settings_overrides=self.settings_overrides) self.assertIn(b('<dt class="for the second item">second term:</dt>'), result) @@ -67,7 +67,7 @@ first term: second term: second def """ - result = core.publish_string(data, writer_name='html_base', + result = core.publish_string(data, writer_name='html_plain', settings_overrides=self.settings_overrides) self.assertIn(b('<dt id="second-item">second term:</dt>'), result) @@ -79,7 +79,7 @@ class SettingsTestCase(DocutilsTestSupport.StandardTestCase): def test_default_stylesheet(self): # default style sheet, embedded mysettings = {'_disable_config': True,} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] self.assertIn('Minimal style sheet ' 'for the HTML output of Docutils.', styles) @@ -88,19 +88,19 @@ class SettingsTestCase(DocutilsTestSupport.StandardTestCase): # default style sheet, linked mysettings = {'_disable_config': True, 'embed_stylesheet': False} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] - self.assertIn('docutils/writers/html_base/minimal.css', styles) + self.assertIn('docutils/writers/html_plain/minimal.css', styles) def test_math_stylesheet_linked(self): # default + math style sheet, linked mysettings = {'_disable_config': True, 'embed_stylesheet': False, 'stylesheet_path': 'minimal.css, math.css'} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] - self.assertIn('docutils/writers/html_base/minimal.css', styles) - self.assertIn('docutils/writers/html_base/math.css', styles) + self.assertIn('docutils/writers/html_plain/minimal.css', styles) + self.assertIn('docutils/writers/html_plain/math.css', styles) def test_custom_stylesheet_linked(self): # default + custom style sheet, linked @@ -108,30 +108,30 @@ class SettingsTestCase(DocutilsTestSupport.StandardTestCase): 'embed_stylesheet': False, 'stylesheet_path': 'minimal.css, ' 'data/ham.css'} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] - self.assertIn('docutils/writers/html_base/minimal.css', styles) + self.assertIn('docutils/writers/html_plain/minimal.css', styles) self.assertIn('href="data/ham.css"', styles) def test_custom_stylesheet_dir(self): mysettings = {'_disable_config': True, 'embed_stylesheet': False, - 'stylesheet_dirs': ('../docutils/writers/html_base/', + 'stylesheet_dirs': ('../docutils/writers/html_plain/', 'data'), 'stylesheet_path': 'minimal.css, ham.css'} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] - if os.path.isdir('../docutils/writers/html_base/'): - self.assertIn('docutils/writers/html_base/minimal.css', styles) + if os.path.isdir('../docutils/writers/html_plain/'): + self.assertIn('docutils/writers/html_plain/minimal.css', styles) self.assertIn('href="data/ham.css"', styles) def test_custom_stylesheet_dir_embedded(self): mysettings = {'_disable_config': True, 'embed_stylesheet': True, - 'stylesheet_dirs': ('../docutils/writers/html_base/', + 'stylesheet_dirs': ('../docutils/writers/html_plain/', 'data'), 'stylesheet_path': 'ham.css'} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] self.assertIn('dl.docutils dd {\n margin-bottom: 0.5em }', styles) @@ -150,7 +150,7 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase): def test_math_output_default(self): # HTML with math.css stylesheet (since 0.11) mysettings = {'_disable_config': True,} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] self.assertIn('convert LaTeX equations to HTML output.', styles) @@ -159,7 +159,7 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase): # use default MathJax URL mysettings = {'_disable_config': True, 'math_output': 'MathJax'} - head = core.publish_parts(self.data, writer_name='html_base', + head = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['head'] self.assertIn(self.mathjax_script % self.default_mathjax_url, head) @@ -168,14 +168,14 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase): mysettings = {'_disable_config': True, 'math_output': 'mathjax %s' % self.custom_mathjax_url} - head = core.publish_parts(self.data, writer_name='html_base', + head = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['head'] self.assertIn(self.mathjax_script % self.custom_mathjax_url, head) def test_math_output_html(self): mysettings = {'_disable_config': True, 'math_output': 'HTML'} - head = core.publish_parts(self.data, writer_name='html_base', + head = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['head'] # There should be no MathJax script when math_output is not MathJax self.assertNotIn('MathJax.js', head) @@ -185,7 +185,7 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase): 'math_output': 'HTML math.css,custom/style.css', 'stylesheet_dirs': ('.', 'functional/input/data'), 'embed_stylesheet': False} - styles = core.publish_parts(self.data, writer_name='html_base', + styles = core.publish_parts(self.data, writer_name='html_plain', settings_overrides=mysettings)['stylesheet'] self.assertEqual(u"""\ <link rel="stylesheet" href="functional/input/data/minimal.css" type="text/css" /> @@ -198,7 +198,7 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase): mysettings = {'_disable_config': True, 'math_output': 'MathJax'} # There should be no math script when text does not contain math - head = core.publish_parts('No math.', writer_name='html_base')['head'] + head = core.publish_parts('No math.', writer_name='html_plain')['head'] self.assertNotIn('MathJax', head) diff --git a/docutils/tools/rst2xhtml11.py b/docutils/tools/rst2xhtml11.py deleted file mode 100755 index ab700a27c..000000000 --- a/docutils/tools/rst2xhtml11.py +++ /dev/null @@ -1,35 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf8 -*- -# :Copyright: © 2015 Günter Milde. -# :License: Released under the terms of the `2-Clause BSD license`_, in short: -# -# Copying and distribution of this file, with or without modification, -# are permitted in any medium without royalty provided the copyright -# notice and this notice are preserved. -# This file is offered as-is, without any warranty. -# -# .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause -# -# Revision: $Revision$ -# Date: $Date$ - -""" -A minimal front end to the Docutils Publisher, producing valid XHTML 1.1 -""" - -try: - import locale # module missing in Jython - locale.setlocale(locale.LC_ALL, '') -except locale.Error: - pass - -from docutils.core import publish_cmdline, default_description - -description = (u'Generates HTML documents from standalone ' - u'reStructuredText sources that conform to the XHTML 1.1 DTD ' - u'(strict XHTML). ' - u'Requires layout rules provided by CSS 2.1 stylesheets ' - u'``html-base.css`` and ``xhtml11.css`` (or equivalent).' - + default_description) - -publish_cmdline(writer_name='xhtml11', description=description) |