| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/thread-self/root/usr/share/doc/python3-docutils/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Docutils HTML writers</title>
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="header">
<a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a>
<hr class="header"/>
</div>
<div class="document" id="docutils-html-writers">
<h1 class="title">Docutils HTML writers</h1>
<!-- Minimal menu bar for inclusion in documentation sources
in ``docutils/docs/*/`` sub-diretories.
Attention: this is not a standalone document. -->
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#html" id="toc-entry-1">html</a></li>
<li><a class="reference internal" href="#html4css1" id="toc-entry-2">html4css1</a><ul>
<li><a class="reference internal" href="#pep-html" id="toc-entry-3">pep_html</a></li>
<li><a class="reference internal" href="#s5-html" id="toc-entry-4">s5_html</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html5" id="toc-entry-5">html5</a></li>
<li><a class="reference internal" href="#overview" id="toc-entry-6">Overview</a></li>
<li><a class="reference internal" href="#references" id="toc-entry-7">References</a></li>
</ul>
</div>
<div class="section" id="html">
<h1><a class="toc-backref" href="#toc-entry-1">html</a></h1>
<p><cite>html</cite> is an alias for the default Docutils HTML writer.</p>
<p>The default may change with the development of HTML, browsers, Docutils,
and the web.
Currently, <cite>html</cite> is mapped to <a class="reference internal" href="#html4css1">html4css1</a>, it will become an alias for
<a class="reference internal" href="#html5-1">html5</a> in Docutils 2.0.</p>
<ul class="simple">
<li>Use <tt class="docutils literal"><span class="pre">get_writer_by_name('html')</span></tt> or the <a class="reference external" href="tools.html#rst2html-py">rst2html.py</a> front end, if you
want the output to be up-to-date automatically.</li>
<li>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.</li>
</ul>
</div>
<div class="section" id="html4css1">
<h1><a class="toc-backref" href="#toc-entry-2">html4css1</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">aliases:</th><td class="field-body">html4, <a class="reference internal" href="#html">html</a></td>
</tr>
<tr class="field"><th class="field-name">front-ends:</th><td class="field-body">rst2html4.py, <a class="reference external" href="tools.html#rst2html-py">rst2html.py</a></td>
</tr>
<tr class="field"><th class="field-name">config:</th><td class="field-body"><a class="reference external" href="config.html#html4css1-writer">[html4css1 writer]</a></td>
</tr>
</tbody>
</table>
<p>The HTML Writer module, <tt class="docutils literal">docutils/writers/html4css1.py</tt>, was the first
Docutils writer and up to release 0.13 the only official HTML writer.</p>
<p>The output conforms to the <a class="reference internal" href="#xhtml-1-transitional">XHTML 1 Transitional</a> specification. It does
not validate as <a class="reference internal" href="#html-4-01-transitional">HTML 4.01 Transitional</a> due to the closing of empty tags
required in XML but not allowed in HTML 4. However, the output follows the
<a class="reference external" href="https://www.w3.org/TR/xhtml1/#guidelines">HTML Compatibility Guidelines</a> for proper rendering on most HTML user
agents.</p>
<p>Correct rendering depends on a <a class="reference external" href="https://www.w3.org/TR/CSS/">CSS</a> style sheet. A reference style sheet,
<a class="reference external" href="../../css/html4css1.css">html4css1.css</a>, is provided and used by default.</p>
<p>To support the <cite>Internet Explorer</cite> (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"). <a class="footnote-reference" href="#ie" id="footnote-reference-1">[1]</a></p>
<table class="docutils footnote" frame="void" id="ie" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-1">[1]</a></td><td>Conformance to <a class="reference internal" href="#css-2-1">CSS 2.1</a> has been added in IE 8 (2009), support
for XHTML in IE 9 (2011).</td></tr>
</tbody>
</table>
<div class="section" id="pep-html">
<h2><a class="toc-backref" href="#toc-entry-3">pep_html</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">front-end:</th><td class="field-body"><a class="reference external" href="tools.html#rstpep2html-py">rstpep2html.py</a></td>
</tr>
<tr class="field"><th class="field-name">config:</th><td class="field-body"><a class="reference external" href="config.html#pep-html-writer">[pep_html writer]</a></td>
</tr>
</tbody>
</table>
<p>This is a special writer for the generation of <a class="reference external" href="https://peps.python.org/">Python Enhancement
Proposals</a> (PEPs). It inherits from <a class="reference internal" href="#html4css1">html4css1</a> and adds some <a class="reference external" href="config.html#pep-html-writer">PEP-specific
options</a>, a style sheet and template. The front-end uses also a specialised
reader.</p>
</div>
<div class="section" id="s5-html">
<h2><a class="toc-backref" href="#toc-entry-4">s5_html</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">alias:</th><td class="field-body">s5</td>
</tr>
<tr class="field"><th class="field-name">front-end:</th><td class="field-body"><a class="reference external" href="tools.html#rst2s5-py">rst2s5.py</a></td>
</tr>
<tr class="field"><th class="field-name">config:</th><td class="field-body"><a class="reference external" href="config.html#s5-html-writer">[s5_html writer]</a></td>
</tr>
</tbody>
</table>
<p>The <cite>s5</cite> writer inherits from <a class="reference internal" href="#html4css1">html4css1</a>. It produces XHTML for use with
<a class="reference external" href="http://meyerweb.com/eric/tools/s5/">S5</a>, the “Simple Standards-based Slide Show System” by Eric Meyer. See
<a class="reference external" href="slide-shows.html">Easy Slide Shows With reST & S5</a> for details.</p>
</div>
</div>
<div class="section" id="html5">
<h1><a class="toc-backref" href="#toc-entry-5">html5</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">aliases:</th><td class="field-body"><span class="target" id="html5-polyglot">html5_polyglot</span></td>
</tr>
<tr class="field"><th class="field-name">front-end:</th><td class="field-body"><a class="reference external" href="tools.html#rst2html5-py">rst2html5.py</a></td>
</tr>
<tr class="field"><th class="field-name">config:</th><td class="field-body"><a class="reference external" href="config.html#html5-writer">[html5 writer]</a></td>
</tr>
</tbody>
</table>
<p>The <tt class="docutils literal">html5_polyglot</tt> writer generates <a class="reference external" href="https://www.w3.org/TR/html-polyglot/">polyglot HTML</a> <a class="footnote-reference" href="#footnote-1" id="footnote-reference-2">[2]</a> output, valid
XML <a class="footnote-reference" href="#safetext" id="footnote-reference-3">[3]</a> that is compatible with <a class="reference internal" href="#html5-1">HTML5</a>. New features and elements
are used if they are widely supported.</p>
<p>There is no hard-coded formatting information in the HTML document.
Correct rendering of elements not directly supported by HTML depends on a
<a class="reference external" href="https://www.w3.org/TR/CSS/">CSS</a> style sheet. The provided style sheet <a class="reference external" href="../../css/minimal.css">minimal.css</a> defines required
styling rules; <a class="reference external" href="../../css/responsive.css">responsive.css</a> add optional rules for
better legibility. Adaption of the layout is possible with <a class="reference external" href="../howto/html-stylesheets.html">custom style
sheets</a>. <a class="footnote-reference" href="#safetext" id="footnote-reference-4">[3]</a></p>
<p>New in Docutils 0.13</p>
<table class="docutils footnote" frame="void" id="footnote-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-2">[2]</a></td><td>see also <a class="reference external" href="http://xmlplease.com/xhtml/xhtml5polyglot/">Benefits of polyglot XHTML5</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="safetext" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#footnote-reference-3">1</a>, <a class="fn-backref" href="#footnote-reference-4">2</a>)</em> The validity of raw HTML and custom stylesheets must be
ensured by the author.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#toc-entry-6">Overview</a></h1>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="16%" />
<col width="20%" />
<col width="25%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">aliases</th>
<th class="head"><a class="reference external" href="tools.html">front-end</a></th>
<th class="head">HTML version</th>
<th class="head">CSS version</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><a class="reference internal" href="#html4css1">html4css1</a></td>
<td>html4,
<a class="reference internal" href="#html">html</a></td>
<td>rst2html4.py,
rst2html.py</td>
<td><a class="reference internal" href="#xhtml-1-transitional">XHTML 1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS 1</a></td>
</tr>
<tr><td><a class="reference internal" href="#pep-html">pep_html</a></td>
<td><!-- -->
</td>
<td>rstpep2html.py</td>
<td><a class="reference internal" href="#xhtml-1-transitional">XHTML 1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS 1</a></td>
</tr>
<tr><td><a class="reference internal" href="#s5-html">s5_html</a></td>
<td>s5</td>
<td>rst2s5.py</td>
<td><a class="reference internal" href="#xhtml-1-transitional">XHTML 1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS 1</a></td>
</tr>
<tr><td><a class="reference internal" href="#html5-polyglot">html5_polyglot</a></td>
<td>html5</td>
<td>rst2html5.py</td>
<td><a class="reference internal" href="#html5-1">HTML5</a></td>
<td><a class="reference internal" href="#css-3">CSS 3</a></td>
</tr>
</tbody>
</table>
<p>For additional alternatives, see the <a class="reference external" href="https://docutils.sourceforge.io/docs/user/links.html#website-generators-and-html-variants">Docutils link list</a> and the
<a class="reference external" href="../dev/policies.html#the-sandbox">sandbox</a>.</p>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#toc-entry-7">References</a></h1>
<dl class="docutils">
<dt><span class="target" id="html5-1">HTML5</span></dt>
<dd><cite>HTML5, A vocabulary and associated APIs for HTML and XHTML</cite>,
W3C Recommendation, 28 October 2014.
<a class="reference external" href="https://www.w3.org/TR/2014/REC-html5-20141028/">https://www.w3.org/TR/2014/REC-html5-20141028/</a></dd>
<dt><span class="target" id="xhtml-1-1">XHTML 1.1</span></dt>
<dd><cite>XHTML™ 1.1 - Module-based XHTML - Second Edition</cite>,
W3C Recommendation, 23 November 2010.
<a class="reference external" href="https://www.w3.org/TR/xhtml11/">https://www.w3.org/TR/xhtml11/</a></dd>
<dt><span class="target" id="xhtml-1-transitional">XHTML 1 Transitional</span></dt>
<dd><a class="reference external" href="https://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional">Transitional version</a> of:
<cite>XHTML™ 1.0 The Extensible HyperText Markup Language (Second
Edition)</cite>, <cite>A Reformulation of HTML 4 in XML 1.0</cite>,
W3C Recommendation, 26 January 2000, revised 1 August 2002.
<a class="reference external" href="https://www.w3.org/TR/xhtml1/">https://www.w3.org/TR/xhtml1/</a></dd>
<dt><span class="target" id="xhtml-basic">XHTML Basic</span></dt>
<dd><cite>XHTML™ Basic 1.1 - Second Edition</cite>,
W3C Recommendation, 23 November 2010.
<a class="reference external" href="https://www.w3.org/TR/xhtml-basic/">https://www.w3.org/TR/xhtml-basic/</a></dd>
</dl>
<dl class="docutils">
<dt><span class="target" id="html-4-01-transitional">HTML 4.01 Transitional</span></dt>
<dd>Transitional version of:
<cite>HTML 4.01 Specification</cite>, W3C Recommendation 24 December 1999.
<a class="reference external" href="https://www.w3.org/TR/html4/">https://www.w3.org/TR/html4/</a></dd>
</dl>
<dl class="docutils" id="css-1">
<dt><span class="target" id="css-level-1">CSS Level 1</span>:</dt>
<dd>The features defined in the <a class="reference external" href="https://www.w3.org/TR/2008/REC-CSS1-20080411/">CSS1 specification</a>, but using the syntax
and definitions in the <a class="reference internal" href="#css-2-1">CSS 2.1</a> specification.</dd>
<dt><span class="target" id="css-2-1">CSS 2.1</span> <cite>Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification</cite>,</dt>
<dd>W3C Recommendation 07 June 2011.
<a class="reference external" href="https://www.w3.org/TR/CSS21/">https://www.w3.org/TR/CSS21/</a></dd>
<dt><span class="target" id="css-3">CSS 3</span>:</dt>
<dd><p class="first">CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
specification as its core.</p>
<p>Specifications: <a class="reference external" href="https://www.w3.org/Style/CSS/specs.en.html">https://www.w3.org/Style/CSS/specs.en.html</a></p>
<p class="last">Validator: <a class="reference external" href="http://jigsaw.w3.org/css-validator/">http://jigsaw.w3.org/css-validator/</a></p>
</dd>
</dl>
<!-- other references
- - - - - - - - - - - - - - - - -->
<blockquote>
<!-- Beware. This specification is no longer in active maintenance and the
HTML Working Group does not intend to maintain it further. -->
</blockquote>
<!-- 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. -->
</div>
</div>
</body>
</html>