Docutils HTML writers¶
注釈
This document is a working draft. Naming of writers, aliases, and front-ends may change before the release of Docutils 0.13.
Contents
Overview¶
-
name alias(es) front-end HTML version CSS version html4css1 html4 rst2html4.py XHTML 1 Transitional CSS 1 html rst2html.py XHTML 1 Transitional CSS 1 html_plain html5 rst2html5.py HTML 5 CSS 3 -
name alias(es) front-end HTML version CSS version pep_html rstpep2html.py XHTML 1 Transitional CSS 1 s5_html s5 rst2s5.py XHTML 1 Transitional CSS 1 -
name alias(es) front-end HTML version CSS version xhtml11 xhtml, html4strict rst2xhtml.py XHTML 1.1 CSS 3 html4trans rst2html_trans XHTML 1 Transitional no CSS required
Generic HTML writers¶
html4css1¶
aliases: | html4, html |
---|---|
front-ends: | rst2html4.py, rst2html.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. 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"). [1]
[1] | Conformance to CSS 2.1 has been added in IE 8 (2009), support for XHTML in IE 9 (2011). |
html_plain¶
aliases: | html5 |
---|---|
front-end: | rst2html5.py |
config: | [html-plain writer] |
The html_plain module is both, basis for other HTML writers and a versatile writer for end-users or programmatic use.
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
Aliases¶
html¶
Currently, html is an alias for the html4css1 writer.
- 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.
- 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.
html5¶
In Docutils 0.13, html5 is an alias to the html_plain writer.
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>).
Special HTML writers¶
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.
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.
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".
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 and CSS Versions¶
- HTML 5
- 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/
- HTML 4.01 Transitional
- Transitional version of: HTML 4.01 Specification, W3C Recommendation 24 December 1999. http://www.w3.org/TR/html4/
- 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/