From 9bf734e9af95b709eb10350d3cf7c244d003535a Mon Sep 17 00:00:00 2001 From: milde Date: Mon, 30 Mar 2015 20:53:39 +0000 Subject: [PATCH] Document HTML writers. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7857 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/user/html.txt | 204 ++++++++++++++++++++++++++++++++++ docutils/docs/user/tools.txt | 18 +-- docutils/docutils/writers/__init__.py | 14 ++- 3 files changed, 221 insertions(+), 15 deletions(-) create mode 100644 docutils/docs/user/html.txt diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt new file mode 100644 index 000000000..8b3789563 --- /dev/null +++ b/docutils/docs/user/html.txt @@ -0,0 +1,204 @@ +===================== +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. + +Overview +-------- + +Since version 0.13, Docutils comes with a family of HTML writers to support +several `HTML variants`_. + +============ =========== ================= ============================= +alias alias name output format(s) +============ =========== ================= ============================= +*html* [#]_ xhtml1 or html4css1_ `XHTML 1 Transitional`_ + html4 [#]_ +.. pep_html_ `XHTML 1 Transitional`_ + +*s5* s5_html_ `XHTML 1 Transitional`_ + +.. html4trans_ [#]_ `XHTML 1 Transitional`_ + +*html5* html-base html_base_ | HTML5_ + | `XHTML 1 Transitional`_ + +*xhtml* html4strict xhtml11_ | `XHTML 1.1`_ + | HTML5_ +============ =========== ================= ============================= + +For *emphazised* aliases exist ``rst2.py`` `front-end tools`_. + +.. [#] *html* will become an alias for html-base in a future release. + +.. [#] TODO: how to name the alias/frontend specific to the html4css1 writer + replacing "html": + + :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). + +.. [#] in the sandbox + +.. _front-end tools: tools.html + + +html4css1 +~~~~~~~~~ + +:aliases: html4, html +:front-ends: rst2html.py_, rst2html4.py +:config: `[html4css1 writer]`_ + +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 with Docutils. + +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% +at 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]_ + +.. [#IE] Conformance to CSS 2.1 has been added in the IE 8 (2009), support + for XHTML in IE 9 (2011). + +.. _rst2html.py: tools.html#rst2html-py +.. _[html4css1 writer]: config.html#html4css1-writer +.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css + +-------------------------------------------------------------------------- + +The following three HTML writers inherit from `html4css1`: + +pep_html +"""""""" + +:front-end: rstpep2html.py_ +: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 specialized +Reader. + +.. _rstpep2html.py: tools.html#rstpep2html-py +.. _[pep_html writer]: config.html#pep-html-writer +.. _Python Enhancement Proposals: https://www.python.org/dev/peps/ + +s5_html +""""""" + +:alias: s5 +:front-end: rst2s5.py_ +:config: `[s5_html writer]`_ + +The `s5` writer produces XHTML output compatible with S5_, the “Simple +Standards-based Slide Show System” by Eric Meyer. This allows one to create +`Easy Slide Shows With reST & S5`_. A theme_ is required for proper +rendering + +.. _rst2s5.py: tools.html#rst2s5-py +.. _[s5_html writer]: config.html#s5-html-writer +.. _Easy Slide Shows With reST & S5: slide-shows.html +.. _S5: http://meyerweb.com/eric/tools/s5/ +.. _theme: tools.html#themes + + +html4trans +"""""""""" + +:front-end: rst2html_trans.py_ + +The `html4trans` writer (`sandbox/html4trans`_) removes the dependency on +CSS browser support. The output conforms to `XHTML 1 Transitional`_ and +contains enough formatting information to be viewed without a cascading +style sheet by a lightweight html browser. + +.. _sandbox/html4trans: ../../../sandbox/html4trans +.. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py + + +html_base +~~~~~~~~~ + +:aliases: html-base, html5 +:front-end: rst2html5.py_ +:config: `[html-base writer]`_ + +The `html-base` writer produces `polyglot HTML`_ output (compatible with +HTML5_ and `XHTML 1 Transitional`_). A CSS style sheet is required for +proper rendering; a complete style sheet, html-base.css_, is provided by +Docutils and used by default. + +.. _rst2html5.py: tools.html#rst2html5-py +.. _[html-base writer]: config.html#html-base-writer +.. _html-base.css: ../../docutils/writers/html_base/html-base.css + + +xhtml11 +~~~~~~~ +:aliases: xhtml, html4strict +:front-end: rst2xhtml.py_ +:config: `[xhtml11 writer]`_ + +The `xhtml11` writer inherits from html_base_ and adds compatibility to +`XHTML 1.1`_ (see `its source`__ for details) + +An additional style sheet adds support for a "start" value for enumerated +lists via a CSS-counter. + +__ ../../docutils/writers/xhtml11/__init__.py +.. _rst2xhtml.py: tools.html#rst2html5-py +.. _[xhtml11 writer]: config.html#xhtml11-writer + + + +HTML variants +------------- + +_`HTML5` + `HTML5, A vocabulary and associated APIs for HTML and XHTML`, + W3C Recommendation, 28 October 2014. + http://www.w3.org/TR/html5/ + +_`XHTML 1.1` + `XHTML™ 1.1 - Module-based XHTML - Second Edition`, + W3C Recommendation, 23 November 2010. + http://www.w3.org/TR/xhtml11/ + +_`XHTML 1 Transitional` + `Transitional version`_ of: + `XHTML™ 1.0 The Extensible HyperText Markup Language (Second + Edition)`, `A Reformulation of HTML 4 in XML 1.0`, + W3C Recommendation, 26 January 2000, revised 1 August 2002. + http://www.w3.org/TR/xhtml1/ + +.. _transitional version: + http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional + +_`HTML 4.01 Transitional` + Transitional version of: + `HTML 4.01 Specification`, W3C Recommendation 24 December 1999. + http://www.w3.org/TR/html4/ + +.. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines +.. _polyglot HTML: http://www.w3.org/TR/html-polyglot/ +.. _CSS: http://www.w3.org/TR/CSS/ diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt index 961e7f872..597bfed4f 100644 --- a/docutils/docs/user/tools.txt +++ b/docutils/docs/user/tools.txt @@ -101,11 +101,10 @@ rst2html.py :Reader: Standalone :Parser: reStructuredText -:Writer: html (html4css1; this will change to hmtl-base in future) +:Writer: html (html4css1_; this will change to hmtl-base_ in future) The ``rst2html.py`` front end reads standalone reStructuredText source -files and produces `HTML 4.1`_ Transitional (or `XHTML 1.0 Transitional`_) -output. +files and produces `XHTML 1.0 Transitional`_ output. A CSS stylesheet is required for proper rendering; a simple but complete stylesheet is installed and used by default (see Stylesheets_ below). @@ -138,7 +137,7 @@ or ``~/.docutils``). To experiment with styles, please see the `guide to writing HTML (CSS) stylesheets for Docutils`__. __ ../howto/html-stylesheets.html - +.. _html4css1: html.html#html4css1 rst2xhtml.py -------------- @@ -148,7 +147,7 @@ rst2xhtml.py :Writer: xhtml (xhtml11) The ``rst2xhtml11.py`` front end reads standalone reStructuredText -source files and produces clean `XHTML 1.1`_ (or `HTML 4.1`_ Strict) +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. @@ -157,13 +156,14 @@ rst2html5.py :Reader: Standalone :Parser: reStructuredText -:Writer: html5 (html-base) +:Writer: html5 (html-base_) The ``rst2html5.py`` front end reads standalone reStructuredText source files and produces simple `HTML 5`_ output (compatible to `XHTML 1.0 -Transitional`_ and `HTML 4.1`_ Transitional). A CSS 2 stylesheet is -required for proper rendering; a complete stylesheet is installed and -used by default. +Transitional`_). A CSS 2 stylesheet is required for proper rendering; a +complete stylesheet is installed and used by default. + +.. _html-base: html.html#html-base rstpep2html.py -------------- diff --git a/docutils/docutils/writers/__init__.py b/docutils/docutils/writers/__init__.py index 99c6ea88d..075c4c265 100644 --- a/docutils/docutils/writers/__init__.py +++ b/docutils/docutils/writers/__init__.py @@ -121,17 +121,19 @@ class UnfilteredWriter(Writer): _writer_aliases = { 'html': 'html4css1', # will change to html_base some day + 'html4': 'html4css1', + 'html5': 'html_base', # until a special HTML 5 writer is ready + 'html4strict': 'xhtml11', 'html-base': 'html_base', - 'html5': 'html_base', # only until a special HTML 5 writer is ready - 'xhtml': 'xhtml11', - 'xhtml10': 'html4css1', 'latex': 'latex2e', - 'xelatex': 'xetex', 'pprint': 'pseudoxml', 'pformat': 'pseudoxml', 'pdf': 'rlpdf', - 'xml': 'docutils_xml', - 's5': 's5_html'} + 's5': 's5_html', + 'xelatex': 'xetex', + 'xhtml': 'xhtml11', + 'xhtml10': 'html4css1', + 'xml': 'docutils_xml'} def get_writer_class(writer_name): """Return the Writer class from the `writer_name` module.""" -- 2.11.4.GIT