docutils-doc 0.13.1+dfsg-2 / usr / share / doc / docutils-doc / docs / user / html.html

This file is indexed.

/usr/share/doc/docutils-doc/docs/user/html.html is in docutils-doc 0.13.1+dfsg-2.

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
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<?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.13.1: http://docutils.sourceforge.net/" />
<title>Docutils HTML writers</title>
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-html-writers">
<h1 class="title">Docutils HTML writers</h1>

<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#html" id="id2">html</a></li>
<li><a class="reference internal" href="#html4css1" id="id3">html4css1</a><ul>
<li><a class="reference internal" href="#pep-html" id="id4">pep_html</a></li>
<li><a class="reference internal" href="#s5-html" id="id5">s5_html</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html5-polyglot" id="id6">html5_polyglot</a></li>
<li><a class="reference internal" href="#html-writers-in-the-sandbox" id="id7">HTML writers in the sandbox</a><ul>
<li><a class="reference internal" href="#xhtml11" id="id8">xhtml11</a></li>
<li><a class="reference internal" href="#html4trans" id="id9">html4trans</a></li>
</ul>
</li>
<li><a class="reference internal" href="#overview" id="id10">Overview</a></li>
<li><a class="reference internal" href="#references" id="id11">References</a></li>
</ul>
</div>
<div class="section" id="html">
<h1><a class="toc-backref" href="#id2">html</a></h1>
<p><span class="incremental">html</span> is an alias for the default Docutils HTML writer.
Currently, <span class="incremental">html</span> is mapped to <a class="reference internal" href="#html4css1">html4css1</a>.</p>
<p>The target may change with the development of HTML, browsers, Docutils, and
the web.</p>
<ul class="simple">
<li>Use <span class="incremental">get_writer_by_name('html')</span> 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="#id3">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>, 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.</p>
<p>The output conforms to the <a class="reference internal" href="#xhtml-1-transitional">XHTML&nbsp;1 Transitional</a> specification. It does
not validate as <a class="reference internal" href="#html-4-01-transitional">HTML&nbsp;4.01&nbsp;Transitional</a> due to the closing of empty tags
required in XML but not allowed in HTML&nbsp;4. However, the output follows the
<a class="reference external" href="http://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="http://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 <span class="incremental">Internet Explorer</span> (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 &quot;text/html&quot; (instead of
&quot;application/xhtml+xml&quot;). <a class="footnote-reference" href="#ie" id="id1">[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="#id1">[1]</a></td><td>Conformance to <a class="reference internal" href="#css-2-1">CSS 2.1</a> has been added in IE&nbsp;8 (2009), support
for XHTML in IE&nbsp;9 (2011).</td></tr>
</tbody>
</table>
<div class="section" id="pep-html">
<h2><a class="toc-backref" href="#id4">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://www.python.org/dev/peps/">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="#id5">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 <span class="incremental">s5</span> 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 &amp; S5</a> for details.</p>
</div>
</div>
<div class="section" id="html5-polyglot">
<h1><a class="toc-backref" href="#id6">html5_polyglot</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">html5</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="http://www.w3.org/TR/html-polyglot/">polyglot HTML</a> output, valid XML that
is compatible with <a class="reference internal" href="#html5">HTML5</a>.
New features and elements will only be used if they are widely supported to
make documents <a class="reference external" href="http://www.anybrowser.org/campaign">viewable with any browser</a>.</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="http://www.w3.org/TR/CSS/">CSS</a> style
sheet. The provided style sheets <a class="reference external" href="../../css/plain.css">plain.css</a> define required
and optional styling rules respectively. Adaption of the layout is possible
with <a class="reference external" href="../howto/html-stylesheets.html">custom style sheets</a>.</p>
<p>New in Docutils 0.13</p>
</div>
<div class="section" id="html-writers-in-the-sandbox">
<h1><a class="toc-backref" href="#id7">HTML writers in the sandbox</a></h1>
<p>There are two more HTML writers in the <a class="reference external" href="../dev/policies.html#the-sandbox">sandbox</a>:</p>
<div class="section" id="xhtml11">
<h2><a class="toc-backref" href="#id8">xhtml11</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">aliases:</th><td class="field-body">xhtml, html4strict</td>
</tr>
<tr class="field"><th class="field-name">front-end:</th><td class="field-body">rst2xhtml.py</td>
</tr>
<tr class="field"><th class="field-name">config:</th><td class="field-body"><span class="incremental">[xhtml11 writer]</span></td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="#xhtml-1-1">XHTML 1.1</a> is the latest version of the XML based <span class="incremental">extensible
Hypertext Markup Language</span> with an official DTD.</p>
<p>The <a class="reference external" href="../../../sandbox/html4strict/README.html">xhtml11 writer</a> lives in the Docutils <a class="reference external" href="../dev/policies.html#the-sandbox">sandbox</a> since 2008. The output
conforms to the strict requirements of <a class="reference internal" href="#xhtml-1-1">XHTML&nbsp;1.1</a>.</p>
</div>
<div class="section" id="html4trans">
<h2><a class="toc-backref" href="#id9">html4trans</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="../../../sandbox/html4trans/tools/rst2html_trans.py">rst2html_trans.py</a></td>
</tr>
</tbody>
</table>
<p>The <a class="reference external" href="../../../sandbox/html4trans/README.html">HTML writer for lightweight browsers</a> lives in the Docutils sandbox
(<a class="reference external" href="../../../sandbox/html4trans">sandbox/html4trans</a>) since 2008. It removes the dependency on CSS. The
output conforms to <a class="reference internal" href="#xhtml-1-transitional">XHTML&nbsp;1 Transitional</a> and contains sufficient
formatting information for rendering without style sheet. (Of course, this
has some <a class="reference external" href="../../../sandbox/html4trans/README.html#drawbacks">drawbacks</a>.)</p>
</div>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#id10">Overview</a></h1>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="16%" />
<col width="21%" />
<col width="25%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">alias(es)</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</td>
<td><a class="reference internal" href="#xhtml-1-transitional">XHTML&nbsp;1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS&nbsp;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&nbsp;1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS&nbsp;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&nbsp;1
Transitional</a></td>
<td><a class="reference internal" href="#css-1">CSS&nbsp;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">HTML5</a></td>
<td><a class="reference internal" href="#css-3">CSS 3</a></td>
</tr>
<tr><td><a class="reference internal" href="#xhtml11">xhtml11</a></td>
<td>xhtml,
html4strict</td>
<td>rst2xhtml.py</td>
<td><a class="reference internal" href="#xhtml-1-1">XHTML&nbsp;1.1</a></td>
<td><a class="reference internal" href="#css-3">CSS 3</a></td>
</tr>
<tr><td><a class="reference internal" href="#html4trans">html4trans</a> ..</td>
<td>&nbsp;</td>
<td>rst2html_trans</td>
<td><a class="reference internal" href="#xhtml-1-transitional">XHTML&nbsp;1
Transitional</a></td>
<td>no CSS
required</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id11">References</a></h1>
<dl class="docutils">
<dt><span class="target" id="html5">HTML5</span></dt>
<dd><span class="incremental">HTML5, A vocabulary and associated APIs for HTML and XHTML</span>,
W3C Recommendation, 28&nbsp;October 2014.
<a class="reference external" href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a></dd>
<dt><span class="target" id="xhtml-1-1">XHTML&nbsp;1.1</span></dt>
<dd><span class="incremental">XHTML™ 1.1 - Module-based XHTML - Second Edition</span>,
W3C Recommendation, 23&nbsp;November 2010.
<a class="reference external" href="http://www.w3.org/TR/xhtml11/">http://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="http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional">Transitional version</a> of:
<span class="incremental">XHTML™ 1.0 The Extensible HyperText Markup Language (Second
Edition)</span>, <span class="incremental">A Reformulation of HTML 4 in XML 1.0</span>,
W3C Recommendation, 26 January 2000, revised 1 August 2002.
<a class="reference external" href="http://www.w3.org/TR/xhtml1/">http://www.w3.org/TR/xhtml1/</a></dd>
<dt><span class="target" id="xhtml-basic">XHTML Basic</span></dt>
<dd><span class="incremental">XHTML™ Basic 1.1 - Second Edition</span>,
W3C Recommendation, 23 November 2010.
<a class="reference external" href="http://www.w3.org/TR/xhtml-basic/">http://www.w3.org/TR/xhtml-basic/</a></dd>
</dl>
<dl class="docutils">
<dt><span class="target" id="html-4-01-transitional">HTML&nbsp;4.01 Transitional</span></dt>
<dd>Transitional version of:
<span class="incremental">HTML 4.01 Specification</span>, W3C Recommendation 24 December 1999.
<a class="reference external" href="http://www.w3.org/TR/html4/">http://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="http://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&nbsp;2.1</a> specification.</dd>
<dt><span class="target" id="css-2-1">CSS 2.1</span> <span class="incremental">Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification</span>,</dt>
<dd>W3C Recommendation 07 June 2011.
<a class="reference external" href="http://www.w3.org/TR/CSS21/">http://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="http://www.w3.org/Style/CSS/specs.en.html">http://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.



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". -->
</div>
</div>
</body>
</html>

APT Browse - Built by Thomas Orozco.