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
|
.. include:: data/standard.txt
.. include:: data/header_footer.txt
.. include:: data/table_colspan.txt
.. include:: data/table_rowspan.txt
.. include:: data/table_complex.txt
.. include:: data/list_table.txt
.. include:: data/custom_roles.txt
.. include:: data/svg_images.txt
.. include:: data/swf_images.txt
Changes to the html4css1 writer
===============================
* Use only meta keywords recognized by HTML 5.
* Set table column widths with <style="width: ...">, not "width" argument.
* Horizontal alignment of table heads with CSS.
* Field lists as styled definition lists.
* Do not drop paragraph objects, use CSS rules to prevent unwanted vertical
space.
* Put subtitles in <p> elements.
Field list handling
-------------------
The following list demonstrates the problems with the html4css1
approach: the `field-name-limit` setting is given in "number of
characters" but the field name uses a proportional font.
:The field name: is typeset on the same line, unless it is "long".
:this field name: is considered "long" in the html table rendering by
the html4css1 writer with the default setting of
``--field-name-limit=14``.
:iiiiiiiiiiiiiii: a field name that is considered "long" by html4css1
with the default setting of `field-name-limit: 14`.
:MMMMMMMMMMMMMM: a field name that is actually longer than the
previous one but regarded "short" by html4css1.
With ``html_plain``, a `field list` is typeset as CSS-styled `definition
list`. The default layout is similar to the look with `html4css1`:
.. class:: open
:A long field name: sticks into the field body.
The field body is pushed to the next line (you can suppress
this behaviour with the `run-in`_ class argument).
:Customization: of the field name width is possible with CSS instead
of the `field-name-limit` configuration setting, for
example::
dl.field-list > dd { margin-left: 6em; }
:Empty:
:fields: must not lead to misalignment of the following content.
Styling with class arguments
----------------------------
The ``plain.css`` style sheet comes with some pre-defined style variants
that can be choosen via a class argument.
Description lists
`````````````````
Definition lists with the "description" class argument:
.. class:: description
description lists
Definition lists that are styled like in most dictionaries,
encyclopedias etc. (as well as the LaTeX `description` environment).
label
The term to be described. Put in boldface.
content
Starts on the same line and has a hanging indent.
Field list variants
```````````````````
For field lists, the "compact/open", "narrow" and "run-in" styles are defined.
*compact*
.. class:: compact
:Feature: No additional space between list items.
:Option: The ``--compact-field-lists`` command line option (and the
corresponding configuration setting) set the `compact`
class argument on all "simple" field lists, if not
overridden with `open`.
:Use: For lists with short field body.
*open*
.. class:: open
:Feature: Additional space between list items also in "simple" lists.
(Overrides the ``--compact-field-lists`` command line
option and the corresponding configuration setting)
:Use: For "simple" lists that should keep the space between list items.
*narrow*
.. class:: narrow
:Feature: Less indented field body.
:Use: For lists with short field names.
:A long field name:
sticks into the field body and the field body starts on a
new line (if not combined with `run-in`_).
.. _`run-in`:
*run-in*
.. class:: run-in
:Feature: Field body starts on the same line also after long field
names.
:A long field name: sticks into the field body which continues on
the same line.
:The next field name: and field body should align. Long text in the field
body is wrapped and aligns with other fields.
Table variants
``````````````
The following styles can be applied to individual tables via a class
argument or as document wide setting with the table-style_ configuration
setting (or command line argument).
* Numbered tables can be achieved with the "numbered" class option:
.. table:: truth values
:class: numbered
======= ======= ==========
A B A or B
======= ======= ==========
False False False
True False True
False True True
True True True
======= ======= ==========
Currently, referencing to the table by number is not supported. This is a
common request and already on the `TODO list`.
* A table with "booktabs" class value, is rendered similar to the style
from the booktabs_ LaTeX package.
.. _table-style:
http://docutils.sourceforge.net/docs/user/config.html#table-style
.. _booktabs:
http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf
"Booktabs" style table, numbered, centre-aligned, with auto-sized columns:
.. table:: I/O values
:class: booktabs numbered
:align: center
:widths: auto
======= ======= ==========
Input Output
--------------- ----------
A B A or B
======= ======= ==========
False False False
True False True
False True True
True True True
======= ======= ==========
.. include:: data/errors.txt
.. footer:: |HTML 5| |validator| |valid-CSS2|
.. |HTML 5| image:: http://www.w3.org/html/logo/badge/html5-badge-h-css3-semantics.png
:height: 31
:width: 88
:alt: Conforms to HTML 5
:target: http://www.w3.org/TR/html5/
.. |validator| image:: https://validator-suite.w3.org/icons/vs-blue-256.png
:height: 31
:width: 88
:alt: Check validity!
:target: http://validator.w3.org/check?uri=referer
.. |valid-CSS2| image:: http://jigsaw.w3.org/css-validator/images/vcss
:height: 31
:width: 88
:alt: Valid CSS 2.1!
:target: http://jigsaw.w3.org/css-validator/check/referer
|
