ulvis.paste.net

Paste Search Dynamic
Recent pastes
Docutils HTML writers
  1. =====================
  2. Docutils HTML writers
  3. =====================
  4.  
  5. .. contents::
  6.  
  7. html
  8. ----
  9.  
  10. `html` is an alias for the default Docutils HTML writer.
  11. Currently, `html` is mapped to html4css1_.
  12.  
  13. The target may change with the development of HTML, browsers, Docutils, and
  14. the web.
  15.  
  16. * Use ``get_writer_by_name('html')`` or the rst2html.py_ front end, if you
  17.   want the output to be up-to-date automatically.
  18.  
  19. * Use a specific writer name or front end, if you depend on stability of the
  20.   generated HTML code, e.g. because you use a custom style sheet or
  21.   post-processing that may break otherwise.
  22.  
  23.  
  24. html4css1
  25. ---------
  26.  
  27. :aliases:    html4, html_
  28. :front-ends: rst2html4.py, rst2html.py_
  29. :config:     `[html4css1 writer]`_
  30.  
  31. The HTML Writer module, ``docutils/writers/html4css1.py``, was the first
  32. Docutils writer and up to release 0.13 the only official HTML writer.
  33.  
  34. The output conforms to the `XHTMLĀ 1 Transitional`_ specification. It does
  35. not validate as `HTMLĀ 4.01Ā Transitional`_ due to the closing of empty tags
  36. required in XML but not allowed in HTMLĀ 4. However, the output follows the
  37. `HTML Compatibility Guidelines`_ for proper rendering on most HTML user
  38. agents.
  39.  
  40. Correct rendering depends on a CSS_ style sheet. A reference style sheet,
  41. `html4css1.css`_, is provided and used by default.
  42.  
  43. To support the `Internet Explorer` (with a market share of about 90% around
  44. 2002, the time this writer was written), documents contain some hard-coded
  45. formatting hints and are tagged as "text/html" (instead of
  46. "application/xhtml+xml"). [#IE]_
  47.  
  48. .. [#IE] Conformance to `CSS 2.1`_ has been added in IEĀ 8 (2009), support
  49.    for XHTML in IEĀ 9 (2011).
  50.  
  51. .. _rst2html.py: tools.html#rst2html-py
  52. .. _[html4css1 writer]: config.html#html4css1-writer
  53. .. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
  54.  
  55. pep_html
  56. ~~~~~~~~
  57.  
  58. :front-end: rstpep2html.py_
  59. :config:    `[pep_html writer]`_
  60.  
  61. This is a special writer for the generation of `Python Enhancement
  62. Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
  63. options`_, a style sheet and template. The front-end uses also a specialised
  64. reader.
  65.  
  66. .. _rstpep2html.py: tools.html#rstpep2html-py
  67. .. _PEP-specific options:
  68. .. _[pep_html writer]: config.html#pep-html-writer
  69. .. _Python Enhancement Proposals: https://www.python.org/dev/peps/
  70.  
  71. s5_html
  72. ~~~~~~~
  73.  
  74. :alias:     s5
  75. :front-end: rst2s5.py_
  76. :config:    `[s5_html writer]`_
  77.  
  78. The `s5` writer inherits from html4css1_. It produces XHTML for use with
  79. S5_, the ā€œSimple Standards-based Slide Show Systemā€¯ by Eric Meyer.  See
  80. `Easy Slide Shows With reST & S5`_ for details.
  81.  
  82. .. _rst2s5.py: tools.html#rst2s5-py
  83. .. _[s5_html writer]: config.html#s5-html-writer
  84. .. _Easy Slide Shows With reST & S5: slide-shows.html
  85. .. _S5: http://meyerweb.com/eric/tools/s5/
  86. .. _theme: tools.html#themes
  87.  
  88.  
  89. html5_polyglot
  90. --------------
  91.  
  92. :aliases: html5
  93. :front-end: rst2html5.py_
  94. :config: `[html5 writer]`_
  95.  
  96. The ``html5_polyglot`` writer generates `polyglot HTML`_ [#]_ output, valid
  97. XML [#safetext]_ that is compatible with `HTML5`_. New features and elements
  98. will only be used if they are widely supported to make documents `viewable
  99. with any browser`_.
  100.  
  101. There is no hard-coded formatting information in the HTML document. Correct
  102. rendering of elements not directly supported by HTML depends on a CSS_ style
  103. sheet. The provided style sheets minimal.css_ and plain.css_ define required
  104. and optional styling rules respectively. Adaption of the layout is possible
  105. with `custom style sheets`_. [#safetext]_
  106.  
  107. New in Docutils 0.13
  108.  
  109. .. [#] see also `Benefits of polyglot XHTML5`_
  110. .. [#safetext] The validity of raw HTML and custom stylesheets must be
  111.    ensured by the author (e.g. using `safe text content`_).
  112.  
  113. .. _rst2html5.py: tools.html#rst2html5-py
  114. .. _[html5 writer]: config.html#html5-writer
  115. .. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
  116. .. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
  117. .. _custom style sheets: ../howto/html-stylesheets.html
  118. .. _viewable with any browser: http://www.anybrowser.org/campaign
  119. .. _Benefits of polyglot XHTML5: http://xmlplease.com/xhtml/xhtml5polyglot/
  120. .. _safe text content:
  121.      https://www.w3.org/TR/html-polyglot/#dfn-safe-text-content
  122.  
  123.  
  124. HTML writers in the sandbox
  125. ---------------------------
  126.  
  127. There are two more HTML writers in the sandbox_:
  128.  
  129. .. _sandbox: ../dev/policies.html#the-sandbox
  130.  
  131. xhtml11
  132. ~~~~~~~
  133. :aliases:   xhtml, html4strict
  134. :front-end: rst2xhtml.py
  135. :config:    `[xhtml11 writer]`
  136.  
  137. `XHTML 1.1`_ is the latest version of the XML based `extensible
  138. Hypertext Markup Language` with an official DTD.
  139.  
  140. The `xhtml11 writer`_ lives in the Docutils sandbox_ since 2008. The output
  141. conforms to the strict requirements of `XHTMLĀ 1.1`_.
  142.  
  143. .. _xhtml11 writer: ../../../sandbox/html4strict/README.html
  144.  
  145.  
  146. html4trans
  147. ~~~~~~~~~~
  148.  
  149. :front-end: rst2html_trans.py_
  150.  
  151. The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
  152. (`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
  153. output conforms to `XHTMLĀ 1 Transitional`_ and contains sufficient
  154. formatting information for rendering without style sheet. (Of course, this
  155. has some drawbacks_.)
  156.  
  157. .. _HTML writer for lightweight browsers:
  158.    ../../../sandbox/html4trans/README.html
  159. .. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
  160. .. _sandbox/html4trans: ../../../sandbox/html4trans
  161. .. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
  162.  
  163.  
  164. Overview
  165. --------
  166.  
  167. =============== =========== ============== ================= ===========
  168. name            alias(es)   `front-end`_   HTML version      CSS version
  169. =============== =========== ============== ================= ===========
  170. html4css1_      html4,      rst2html4.py,  `XHTMLĀ 1          `CSSĀ 1`_
  171.                 html_       rst2html.py    Transitional`_
  172.  
  173. pep_html_       ..          rstpep2html.py `XHTMLĀ 1          `CSSĀ 1`_
  174.                                            Transitional`_
  175.  
  176. s5_html_        s5          rst2s5.py      `XHTMLĀ 1          `CSSĀ 1`_
  177.                                            Transitional`_
  178.  
  179. html5_polyglot_ html5       rst2html5.py   `HTML5`_          `CSS 3`_
  180.  
  181. xhtml11_        xhtml,      rst2xhtml.py   `XHTMLĀ 1.1`_      `CSS 3`_
  182.                 html4strict
  183.  
  184. html4trans_ ..              rst2html_trans `XHTMLĀ 1          no CSS
  185.                                            Transitional`_    required
  186. =============== =========== ============== ================= ===========
  187.  
  188.  
  189. References
  190. ----------
  191.  
  192. _`HTML5`
  193.    `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
  194.    W3C Recommendation, 28Ā October 2014.
  195.    http://www.w3.org/TR/html5/
  196.  
  197. _`XHTMLĀ 1.1`
  198.    `XHTMLā„¢ 1.1 - Module-based XHTML - Second Edition`,
  199.    W3C Recommendation, 23Ā November 2010.
  200.    http://www.w3.org/TR/xhtml11/
  201.  
  202. _`XHTML 1 Transitional`
  203.    `Transitional version`_ of:
  204.    `XHTMLā„¢ 1.0 The Extensible HyperText Markup Language (Second
  205.    Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
  206.    W3C Recommendation, 26 January 2000, revised 1 August 2002.
  207.    http://www.w3.org/TR/xhtml1/
  208.  
  209. _`XHTML Basic`
  210.    `XHTMLā„¢ Basic 1.1 - Second Edition`,
  211.    W3C Recommendation, 23 November 2010.
  212.    http://www.w3.org/TR/xhtml-basic/
  213.  
  214. .. _transitional version:
  215.    http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
  216.  
  217. _`HTMLĀ 4.01 Transitional`
  218.   Transitional version of:
  219.   `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
  220.   http://www.w3.org/TR/html4/
  221.  
  222. .. _`CSSĀ 1`:
  223.  
  224. _`CSS Level 1`:
  225.   The features defined in the `CSS1 specification`_, but using the syntax
  226.   and definitions in the `CSSĀ 2.1`_ specification.
  227.  
  228. _`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
  229.   W3C Recommendation 07 June 2011.
  230.   http://www.w3.org/TR/CSS21/
  231.  
  232. _`CSS 3`:
  233.   CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
  234.   specification as its core.
  235.  
  236.   Specifications: http://www.w3.org/Style/CSS/specs.en.html
  237.  
  238.   Validator: http://jigsaw.w3.org/css-validator/
  239.  
  240. .. other references
  241.    ----------------
  242.  
  243. .. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
  244. .. _CSS: http://www.w3.org/TR/CSS/
  245. .. _CSS1 specification: http://www.w3.org/TR/2008/REC-CSS1-20080411/
  246. .. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
  247.  
  248.    .. Beware. This specification is no longer in active maintenance and the
  249.       HTML Working Group does not intend to maintain it further.
  250.  
  251. .. Appendix
  252.  
  253.  
  254.       On the question of Polyglot markup, there seems to be little
  255.       consensus. One line of argument suggests that, to the extent that it
  256.       is practical to obey the Robustness principle, it makes sense to do
  257.       so. That is, if you're generating HTML markup for the web, and you can
  258.       generate Polyglot markup that is also directly consumable as XML, you
  259.       should do so. Another line of argument suggests that even under the
  260.       most optimistic of projections, so tiny a fraction of the web will
  261.       ever be written in Polyglot that there's no practical benefit to
  262.       pursuing it as a general strategy for consuming documents from the
  263.       web. If you want to consume HTML content, use an HTML parser that
  264.       produces an XML-compatible DOM or event stream.
  265.  
  266.       -- https://www.w3.org/TR/html-xml-tf-report/#conclusions
  267.  
  268.   Further development
  269.  
  270.   On 2016-05-25, David Goodger wrote:
  271.  
  272.   > In addition, I'd actually like to see the HTML writer(s) with
  273.   > fully-parameterized classes, i.e. removing hard-coded *classes* as well as
  274.   > formatting. This way, any user who wants to (e.g.) write reST for use with
  275.   > Bootstrap can easily work around any naming conflicts.
  276.  
  277.  
  278.  
  279.   Problems with html4css1 writer:
  280.  
  281.   1. Limiting ourself to CSS LevelĀ 1 requires use of hard-coded HTML
  282.      formatting to get all rST objects mapped to HTML.
  283.      Hard-coded HTML formatting is considered bad practice.
  284.  
  285.   2. Maths cannot be included in MathML format without rendering a
  286.      hmtl4css1-generated document invalid.
  287.  
  288.      (XHTMLĀ 1.1. is the only member of the "HTML4 family" allowing embedding
  289.      of MathML. However, hard-coded HTML formatting prevents its use.)
  290.  
  291.  
  292.  
  293.   Comparison of current HTML versions
  294.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  295.  
  296.   XHTML1.1
  297.   """"""""
  298.  
  299.   +2 XML-based with official DTD
  300.      +1 allows processing with XML-tool-chain
  301.      +1 allows validating against the DTD
  302.  
  303.   +1 writer exists (in sandbox) and in active use since 2008
  304.  
  305.   -1 "old" format
  306.   -1 requires to work around restrictions lifted in HTML5
  307.      ("start" argument for enumerated lists, some tags in parsed literal)
  308.      which makes code and documents more complicated
  309.  
  310.   HTML5
  311.   """""
  312.   +1 more recent
  313.   +1 simpler to write, less restrictions
  314.  
  315.   +1 writer exists and in active use since 2015
  316.  
  317.   +1 new page structure elements such as <main>, <section>, <article>,
  318.      <header>, <footer>, <aside>, <nav> and <figure>
  319.      provide better matches for the rst document model.
  320.  
  321.   -1 new elements not yet supported by many browsers.
  322.  
  323.   -2 no DTD
  324.      - no proper validation possible (there is an experimental validator)
  325.      - no standard interface to post-processing XML-tools
  326.  
  327.   -1 two concurring definitions:
  328.      W3C standard and WHATWG "HTML Living Standard".
  329.  
  330. .. _front-end: tools.html
Parsed in 0.028 seconds