Docutils HTML编写者¶
目录
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
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”). 1
pep_html¶
- front-end
- config
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
- config
The s5 writer inherits from html4css1. It produces XHTML for use with S5, the 鈥淪imple Standards-based Slide Show System鈥� by Eric Meyer. See Easy Slide Shows With reST & S5 for details.
html5_polyglot¶
- aliases
html5
- front-end
- config
The html5_polyglot
writer generates polyglot HTML 2 output, valid
XML 3 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. 3
New in Docutils 0.13
- 2
see also Benefits of polyglot XHTML5
- 3(1,2)
The validity of raw HTML and custom stylesheets must be ensured by the author (e.g. using safe text content).
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 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.
html4trans¶
- front-end
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.)
Overview¶
name |
alias(es) |
HTML version |
CSS version |
|
---|---|---|---|---|
html4, html |
rst2html4.py, rst2html.py |
|||
rstpep2html.py |
||||
s5 |
rst2s5.py |
|||
html5 |
rst2html5.py |
|||
xhtml, html4strict |
rst2xhtml.py |
|||
html4trans .. |
rst2html_trans |
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/
- 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/