test/functional/input/standalone_rst_html5_polyglot.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 * Set table column widths with <style="width: ...">, not "width" argument.
  17
  18 * Horizontal 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 :Empty:
  63
  64 :fields:       must not lead to misalignment of the following content.
  65
  66 Styling with class arguments
  67 ----------------------------
  68
  69 The ``plain.css`` style sheet comes with some pre-defined style variants
  70 that can be choosen via a class argument.
  71
  72 Description lists
  73 `````````````````
  74
  75 Definition lists with the "description" class argument:
  76
  77 .. class:: description
  78
  79 description lists
  80   Definition lists that are styled like in most dictionaries,
  81   encyclopedias etc. (as well as the LaTeX `description` environment).
  82 label
  83   The term to be described. Put in boldface.
  84 content
  85   Starts on the same line and has a hanging indent.
  86
  87 Field list variants
  88 ```````````````````
  89
  90 For field lists, the "compact/open", "narrow" and "run-in" styles are defined.
  91
  92 *compact*
  93   .. class:: compact
  94
  95   :Feature: No additional space between list items.
  96
  97   :Option: The ``--compact-field-lists`` command line option (and the
  98            corresponding configuration setting) set the `compact`
  99            class argument on all "simple" field lists, if not
 100            overridden with `open`.
 101
 102   :Use:  For lists with short field body.
 103
 104 *open*
 105   .. class:: open
 106
 107   :Feature: Additional space between list items also in "simple" lists.
 108             (Overrides the ``--compact-field-lists`` command line
 109             option and the corresponding configuration setting)
 110
 111   :Use: For "simple" lists that should keep the space between list items.
 112
 113 *narrow*
 114   .. class:: narrow
 115
 116   :Feature: Less indented field body.
 117   :Use:   For lists with short field names.
 118   :A long field name:
 119        sticks into the field body and the field body starts on a
 120        new line (if not combined with `run-in`_).
 121
 122 .. _`run-in`:
 123
 124 *run-in*
 125   .. class:: run-in
 126
 127   :Feature: Field body starts on the same line also after long field
 128             names.
 129
 130   :A long field name: sticks into the field body which continues on
 131                          the same line.
 132
 133   :The next field name:  and field body should align. Long text in the field
 134                          body is wrapped and aligns with other fields.
 135
 136 Table variants
 137 ``````````````
 138
 139 The following styles can be applied to individual tables via a class
 140 argument or as document wide setting with the table-style_ configuration
 141 setting (or command line argument).
 142
 143 * Numbered tables can be achieved with the "numbered" class option:
 144
 145   .. table:: truth values
 146      :class: numbered
 147
 148      ======= ======= ==========
 149      A       B       A or B
 150      ======= ======= ==========
 151      False   False   False
 152      True    False   True
 153      False   True    True
 154      True    True    True
 155      ======= ======= ==========
 156
 157   Currently, referencing to the table by number is not supported. This is a
 158   common request and already on the `TODO list`.
 159
 160 * With the "widths" argument "auto" (or "class" value "colwidths-auto"),
 161   column widths are determined by the browser.
 162
 163   .. table::
 164      :widths: auto
 165
 166      ======= ======= ==========
 167      A       B       A or B
 168      ======= ======= ==========
 169      False   False   False
 170      True    False   True
 171      False   True    True
 172      True    True    True
 173      ======= ======= ==========
 174
 175 * A table with "booktabs" class value, is rendered similar to the style
 176   from the booktabs_ LaTeX package.
 177
 178   .. _table-style:
 179      http://docutils.sourceforge.net/docs/user/config.html#table-style
 180   .. _booktabs:
 181      http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf
 182
 183 "Booktabs" style table, numbered, centre-aligned, with auto-sized columns:
 184
 185   .. table:: I/O values
 186      :class: booktabs numbered
 187      :align: center
 188      :widths: auto
 189
 190      ======= ======= ==========
 191      Input           Output
 192      --------------- ----------
 193      A       B       A or B
 194      ======= ======= ==========
 195      False   False   False
 196      True    False   True
 197      False   True    True
 198      True    True    True
 199      ======= ======= ==========
 200
 201
 202 .. include:: data/errors.txt
 203
 204 .. footer:: |HTML 5| |validator| |valid-CSS2|
 205
 206 .. |HTML 5| image:: http://www.w3.org/html/logo/badge/html5-badge-h-css3-semantics.png
 207    :height: 31
 208    :width: 88
 209    :alt: Conforms to HTML 5
 210    :target: http://www.w3.org/TR/html5/
 211
 212 .. |validator| image:: https://validator-suite.w3.org/icons/vs-blue-256.png
 213    :height: 31
 214    :width: 88
 215    :alt: Check validity!
 216    :target: http://validator.w3.org/check?uri=referer
 217
 218 .. |valid-CSS2| image:: http://jigsaw.w3.org/css-validator/images/vcss
 219    :height: 31
 220    :width: 88
 221    :alt: Valid CSS 2.1!
 222    :target: http://jigsaw.w3.org/css-validator/check/referer