You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
208 lines
6.0 KiB
208 lines
6.0 KiB
7 years ago
|
.. 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
|