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