From 1288f35d5fab6f0867e1db652dfb5e0f3c1f60bd Mon Sep 17 00:00:00 2001 From: milde Date: Wed, 1 Apr 2015 21:09:31 +0000 Subject: [PATCH] Update HTML writer doc. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7858 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/user/html.txt | 192 +++++++++++++++++++++++++++++--------------- 1 file changed, 126 insertions(+), 66 deletions(-) diff --git a/docutils/docs/user/html.txt b/docutils/docs/user/html.txt index 8b3789563..c83de8c94 100644 --- a/docutils/docs/user/html.txt +++ b/docutils/docs/user/html.txt @@ -5,33 +5,44 @@ 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. +Since version 0.13, Docutils comes with a family of HTML writers to support + +* state of the art HTML (html_base_, html5), + +* state of the art XHTML (xhtml11_), and + +* older user agents with no/limited support for CSS and XHTML (html4css1_ + and descendants). + + 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`_ +========== =========== ================= ============================= +alias alias name output format(s) +========== =========== ================= ============================= +*html5* html-base html_base_ | HTML5_ +[#]_ | `XHTML 1 Transitional`_ -*s5* s5_html_ `XHTML 1 Transitional`_ +*xhtml* html4strict xhtml11_ | `XHTML 1.1`_ + | HTML5_ -.. html4trans_ [#]_ `XHTML 1 Transitional`_ +*html* *xhtml1* or html4css1_ `XHTML 1 Transitional`_ +[#]_ *html4* + [#]_ +.. pep_html_ `XHTML 1 Transitional`_ -*html5* html-base html_base_ | HTML5_ - | `XHTML 1 Transitional`_ +*s5* s5_html_ `XHTML 1 Transitional`_ -*xhtml* html4strict xhtml11_ | `XHTML 1.1`_ - | HTML5_ -============ =========== ================= ============================= +.. html4trans_ [#]_ `XHTML 1 Transitional`_ +========== =========== ================= ============================= For *emphazised* aliases exist ``rst2.py`` `front-end tools`_. -.. [#] *html* will become an alias for html-base in a future release. +.. [#] `html5` may become the name of an advanced HTML5 writer derived from + html-base in a future release. + +.. [#] `html` may become an alias for html-base in a future release. .. [#] TODO: how to name the alias/frontend specific to the html4css1 writer replacing "html": @@ -52,6 +63,78 @@ For *emphazised* aliases exist ``rst2.py`` `front-end tools`_. .. _front-end tools: tools.html +html_base +~~~~~~~~~ + +.. note:: The name `html_base` will change to a more appropriate one. + Candidates are `html_basic` (but beware of confusion with the + `XHTML Basic`_ document type), `html_common`, or simply `html` (name + currently used as alias by `html4css1`_). Suggestions welcome. + + +:aliases: html-base, html5 +:front-end: rst2html5.py_ +:config: `[html-base writer]`_ + +The `html-base` writer is both, basis for more specialized HTML writers and +working code generating clean and highly compatible documents. + +It generates modern `polyglot HTML`_ output (compatible with HTML5_ +and `XHTML 1 Transitional`_). Correct rendering depends on a CSS_ style +sheet. An example style sheet, html-base.css_, is provided and used by +default. + +New features and elements will only be used if they are widely supported to +make documents `viewable with any browser`_. Leaving out hard-coded +formatting information from the HTML code allows adaption of the layout with +`custom style sheets`_. + +.. _rst2html5.py: tools.html#rst2html5-py +.. _[html-base writer]: config.html#html-base-writer +.. _html-base.css: ../../docutils/writers/html_base/html-base.css +.. _custom style sheets: ../howto/html-stylesheets.html +.. _viewable with any browser: http://www.anybrowser.org/campaign + + +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_base_ 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. + +* ```` and ```` tags are not allowed in preformatted blocks + (``
``) but possible in reStructuredText with the "parsed-literal"
+  directive.
+
+The `math-output` `config setting`_ defaults to "MathML".
+
+.. _rst2xhtml.py: tools.html#rst2html5-py
+.. _config setting:
+.. _[xhtml11 writer]: config.html#xhtml11-writer
+.. _xhtml11.css: ../../docutils/writers/xhtml11/xhtml11.css
+
+
+html5
+"""""
+
+The writer name `html5` is reserved for a HTML writer that makes use of the
+new features and objects defined in HTML5 (like