test/functional/input/standalone_rst_html_plain.txt

   1 .. include:: data/standard.txt
   2 .. include:: data/header_footer.txt
   3 .. include:: data/table_colspan.txt
   4 .. include:: data/table_rowspan.txt
   5 .. include:: data/table_complex.txt
   6 .. include:: data/list_table.txt
   7 .. include:: data/custom_roles.txt
   8 .. include:: data/svg_images.txt
   9 .. include:: data/swf_images.txt
  10
  11 Changes to the html4css1 writer
  12 ===============================
  13
  14 * Use only meta keywords recognized by HTML 5.
  15
  16 * Style table column widths with CSS rule, not "width" argument.
  17
  18 * Vertical alignment of table heads with CSS.
  19
  20 * Field lists as styled definition lists.
  21
  22 * Do not drop paragraph objects, use CSS rules to prevent unwanted vertical
  23   space.
  24
  25 * Put subtitles in <p> elements.
  26
  27 Field list handling
  28 -------------------
  29
  30 The following list demonstrates the problems with the html4css1
  31 approach: the `field-name-limit` setting is given in "number of
  32 characters" but the field name uses a proportional font.
  33
  34 :The field name:  is typeset on the same line, unless it is "long".
  35
  36 :this field name: is considered "long" in the html table rendering by
  37                   the html4css1 writer with the default setting of
  38                   ``--field-name-limit=14``.
  39
  40 :iiiiiiiiiiiiiii: a field name that is considered "long" by html4css1
  41                   with the default setting of `field-name-limit: 14`.
  42
  43 :MMMMMMMMMMMMMM: a field name that is actually longer than the
  44                  previous one but regarded "short" by html4css1.
  45
  46 With ``html_plain``, a `field list` is typeset as CSS-styled `definition
  47 list`. The default layout is similar to the look with `html4css1`:
  48
  49 .. class:: open
  50
  51 :A long field name: sticks into the field body.
  52
  53                 The field body is pushed to the next line (you can suppress
  54                 this behaviour with the `run-in`_ class argument).
  55
  56 :Customization: of the field name width is possible with CSS instead
  57                 of the `field-name-limit` configuration setting, for
  58                 example::
  59
  60                     dl.field-list > dd { margin-left: 6em; }
  61
  62 Styling with class arguments
  63 ----------------------------
  64
  65 The ``plain.css`` style sheet comes with some pre-defined style variants
  66 that can be choosen via a class argument.
  67
  68 Description lists
  69 `````````````````
  70
  71 Definition lists with the "description" class argument:
  72
  73 .. class:: description
  74
  75 description lists
  76   Definition lists that are styled like in most dictionaries,
  77   encyclopedias etc. (as well as the LaTeX `description` environment).
  78 label
  79   The term to be described. Put in boldface.
  80 content
  81   Starts on the same line and has a hanging indent.
  82
  83 Field list variants
  84 ```````````````````
  85
  86 For field lists, the "compact/open", "narrow" and "run-in" styles are defined.
  87
  88 *compact*
  89   .. class:: compact
  90
  91   :Feature: No additional space between list items.
  92
  93   :Option: The ``--compact-field-lists`` command line option (and the
  94            corresponding configuration setting) set the `compact`
  95            class argument on all "simple" field lists, if not
  96            overridden with `open`.
  97
  98   :Use:  For lists with short field body.
  99
 100 *open*
 101   .. class:: open
 102
 103   :Feature: Additional space between list items also in "simple" lists.
 104             (Overrides the ``--compact-field-lists`` command line
 105             option and the corresponding configuration setting)
 106
 107   :Use: For "simple" lists that should keep the space between list items.
 108
 109 *narrow*
 110   .. class:: narrow
 111
 112   :Feature: Less indented field body.
 113   :Use:   For lists with short field names.
 114   :A long field name:
 115        sticks into the field body and the field body starts on a
 116        new line (if not combined with `run-in`_).
 117
 118 .. _`run-in`:
 119
 120 *run-in*
 121   .. class:: run-in
 122
 123   :Feature: Field body starts on the same line also after long field
 124             names.
 125
 126   :A long field name: sticks into the field body which continues on
 127                          the same line.
 128
 129   :The next field name:  and field body should align. Long text in the field
 130                          body is wrapped and aligns with other fields.
 131
 132 Table variants
 133 ``````````````
 134
 135 The following styles can be applied to individual tables via a class
 136 argument or as document wide setting with the table-style_ configuration
 137 setting (or command line argument).
 138
 139 Numbered tables can be achieved with the "numbered" class option
 140
 141 .. table:: truth values
 142    :class: numbered
 143
 144    ======= ======= ==========
 145    A       B       A or B
 146    ======= ======= ==========
 147    False   False   False
 148    True    False   True
 149    False   True    True
 150    True    True    True
 151    ======= ======= ==========
 152
 153 Currently, referencing to the table by number is not supported. This is a
 154 common request and already on the `TODO list`.
 155
 156 A table with "booktabs" class argument, is rendered similar to the style
 157 from the booktabs_ LaTeX package.
 158
 159 .. _table-style:
 160    http://docutils.sourceforge.net/docs/user/config.html#table-style
 161 .. _booktabs:
 162    http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf
 163
 164 .. class:: booktabs
 165
 166 =====  =====  ======
 167 False  False  False
 168 True   False  True
 169 False  True   True
 170 True   True   True
 171 =====  =====  ======
 172
 173 This table also uses the "align-left" class argument, to left-align
 174 the headers:
 175
 176 .. class:: booktabs align-left
 177
 178 =====  =====  =======
 179   A      B    A or B
 180 =====  =====  =======
 181 False  False  False
 182 True   False  True
 183 False  True   True
 184 True   True   True
 185 =====  =====  =======
 186
 187
 188 Of course, also "booktabs" style tables can be numbered:
 189
 190 .. table:: I/O values
 191    :class: numbered booktabs
 192
 193    =====  =====  ======
 194       Inputs     Output
 195    ------------  ------
 196      A      B    A or B
 197    =====  =====  ======
 198    False  False  False
 199    True   False  True
 200    False  True   True
 201    True   True   True
 202    =====  =====  ======
 203
 204
 205 .. include:: data/errors.txt
 206
 207 .. footer:: |HTML 5| |validator| |valid-CSS2|
 208
 209 .. |HTML 5| image:: http://www.w3.org/html/logo/badge/html5-badge-h-css3-semantics.png
 210    :height: 31
 211    :width: 88
 212    :alt: Conforms to HTML 5
 213    :target: http://www.w3.org/TR/html5/
 214
 215 .. |validator| image:: https://validator-suite.w3.org/icons/vs-blue-256.png
 216    :height: 31
 217    :width: 88
 218    :alt: Check validity!
 219    :target: http://validator.w3.org/check?uri=referer
 220
 221 .. |valid-CSS2| image:: http://jigsaw.w3.org/css-validator/images/vcss
 222    :height: 31
 223    :width: 88
 224    :alt: Valid CSS 2.1!
 225    :target: http://jigsaw.w3.org/css-validator/check/referer