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
|
.. include:: ../header.txt
===================
Docutils TODO lists
===================
TODO lists allow you to create a list of items with checkboxes.
In `extended Markdown`_, they are called `task lists`.
Checkbox variants
=================
[x] ASCII-art checkbox.
[ ] ASCII space character and NBSP are smaller than the x.
[ ] The "figure space" has the correct width but is not easy to type.
You may define substitutions for ballot box and checked ballot box or
other suitable Unicode characters:
.. |-| unicode:: U+2610
.. |x| unicode:: U+2611
.. |y| unicode:: U+1F5F9
|-| U+2610 BALLOT BOX
|x| U+2611 BALLOT BOX WITH CHECK
|y| U+1F5F9 BALLOT BOX WITH BOLD CHECK
List Markup
===========
Paragraphs
----------
|x| Simple *paragraphs* are easy for small lists with short values
|-| but not well suited for complex TODO items.
Line Blocks
-----------
| |x| Line blocks are rendered as "unstyled" lists.
| |y| They don't need additional styling.
| |-| However, you cannot nest block elements.
Description Lists
-----------------
.. class:: description
|x|
A *description list* works out of the box in HTML5 and XeTeX.
|-|
It looks suboptimal in the rST source (definition list with class
value "description").
[x]
Lists may use ASCII-art or substitutions.
[ ]
All list markup variants require special styling based on a
preceding class__ directive.
__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#class
Bullet Lists
------------
.. class:: todo
- |x| bullet lists (similar to the Markdown_ for `task
lists`) can be styled accordingly.
- |-| They don't look good in the rST source.
- [x] Lists may use ASCII-art or substitutions.
- [ ] The "figure space" has the correct width.
- |x| Another idea: use bullet lists with ``+`` and ``-`` markers.
+ Clean and simple markup in the source.
- A new marker character starts a new list :-(
- Requires change to the writer: Pass the "bullet" attribute to
the output document (use `HTML5 "data-" attriibutes`__?).
__ https://html.spec.whatwg.org/#embedding-custom-non-visible-data-with-the-data-*-attributes
Field Lists
-----------
.. class:: todo
:|x|: Compile this example with ``rst2html5``,
:|y|: compare markup variants,
:|-|: select the best.
.. class:: todo monospace
:[x]: ASCII-art checkbox.
:[ ]: The "figure space" has the correct width.
:[ ]: CSS styling can switch to monospace fonts for the ASCII-art boxes,
so an ASCII space character can be used.
.. class:: todo monospace brackets
:x: ASCII-art checkbox - brackets added by CSS.
: : Simple rST source, easy typing.
.. class:: todo monospace framed
:x: checkbox border added by CSS.
: : Simple rST source, easy typing.
I recommend a field list with class argument and some CSS styling.
.. _Markdown: https://www.markdownguide.org
.. _extended Markdown: https://www.markdownguide.org/extended-syntax/
.. ! The follwing CSS rules are included here as raw HTML to keep the
example compact. They compromise the HTML validity, as styling is not
allowed in the document body.
For production use, place CSS styling rules in a custom style sheet.
.. raw:: html
<style type="text/css"><!--
ul.todo {list-style-type: none;
padding-left: 0;}
ul.todo > li > p {padding-left: 1.2em;
text-indent: -1.2em;}
dl.todo > dt {font-style: normal}
dl.todo > dt > .colon {display: none}
dl.todo > dd {margin-left: 2.5em;}
dl.monospace > dt {font-family: monospace;}
dl.brackets > dt:before {content: '[';}
dl.brackets > dt:after {content: ']';}
dl.framed > dt {border: solid;
border-width: thin;
padding: 0 0.2em;
margin-top: 0.2em;
line-height: 0.9;
}
--></style>
|
