`` tags are not allowed in preformatted blocks
(````).
The `math-output` configuration setting defaults to "MathML".
The `xhtml11.css `_ style sheet extends the standard
layout for CSS2-conforming HTML browsers.
Changes to the html4css1 writer
-------------------------------
Document type
~~~~~~~~~~~~~
+ The output conforms to the XHTML version 1.1 DTD::
li:before {
counter-increment: item;
content: counter(item) ".";
}
* The label is right aligned in a box. Both the label and the list
content (which Docutils puts in a paragraph node) must be displayed
as "inline-block" so that they line up::
ol > li:before {
display: inline-block;
vertical-align: top;
width: 2em;
padding-right: 0.5em;
text-align: right;
}
ol > li > p { display: inline-block; }
However, subsequent paragraphs are to be set as nested block
elements::
ol > li > p + p {
display: block;
margin-top: 0em;
}
* The hanging indent is realized via a negative "textindent"
which must be reset for the list content to prevent over-striking::
ol > li { text-indent: -2.5em; }
ol > li > p { text-indent: 0em; }
The resulting list can be customized to a large extend
* Different label types and separators are possible, e.g.::
ol.lowerroman > li:before {
content: "(" counter(item, lower-roman) ")";
}
* nested counters (1, 1.1, 1.1.1, etc)::
ol.nested > li:before {
content: counters(item, ".") ". ";
}
* chapter/section prefix, continued lists, ...
.. _W3C example: http://www.w3.org/TR/CSS2/generate.html#counters
.. _taming lists: http://www.alistapart.com/articles/taminglists/
Inline literal role with ``pre-wrap``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In contrast to the html4css1 writer, runs of whitespace are not
replaced by `` `` entities (cf. bug #1938891).
Whitespace-handling and wrapping are configured with the CSS
property ``white-space: pre-wrap``:
Whitespace is preserved by the browser. Text will wrap when
necessary, and on line breaks
However, most browsers wrap on non-word chars, too, if set to wrap
at white-space. Text like "--an-option" or the regular expression
``[+]?(\d+(\.\d*)?|\.\d+)`` may be broken at the wrong place!
The setting ``white-space: pre;`` prevents this, but also
prevents wrapping at white space, contrary to the specification__
In order to allow line-wrap at whitespace only,
words-with-non-word-chars are wrapped in s with class "pre".
+ simpler HTML code
+ White-space handling in inline literals configurable with the CSS
stylesheet. Possible values: ``normal, nowrap, pre, pre-wrap,
pre-line``.
__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#inline-literals
Table styling with CSS
~~~~~~~~~~~~~~~~~~~~~~
+ No hard-coded border setting.
+ Pre-defined table styles selected by class arguments "borderless"
and "booktabs" matching the interpretation in the latex2e writer.
SimpleListChecker also checks field-lists and docinfo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unified test if a list is compactable:
+ cleaner code
+ also works for nesting field-list in enumeration/bullet-list and
vice versa
+ also test docinfo, as a field may contain more than one paragraph
Docutils-generated section numbers in a
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Instead of hard-coded formatting with trailing `` ``,
section numbers in section headings and the toc are placed in spans
with ``class='sectnum'`` and separated from the heading by a CSS rule.
Omit redundant class arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Do not mark the first child with 'class="first"' and the last
child with 'class="last"' in definitions, table cells, field
bodies, option descriptions, and list items. Use the
``:first-child`` and ``:last-child`` selectors instad.
Language attribute name changed to 'xml:lang'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The name of the language attribute changed from 'lang' in XHTML 1.0 to
'xml:lang' in XHTML 1.1. Documents using 'lang' do not validate.
Do not omit tags
~~~~~~~~~~~~~~~~~~~~
The HTML4CSS1 writer does this to "produce visually compact lists
(less vertical whitespace)". This writer relies on CSS rules
for"visual compactness".
TODO
----
* The first list in the test `2.3. Enumerated Lists` should be
compact.
* Hanging indent for numbered section headings and ToC entries.
* search stylesheets along standard path if enclosed in <>
(like the RST syntax for include files).
* Validate output with "critical" cases not covered by
the functional test (e.g. headings with level > 6).
* Move widely supported constructs to the html4css1 writer.
* Number sections with CSS if sectnum_xform is False.
* Footnotes and Citations (for footnotes see
http://www.archiva.net/footnote/index.htm and
http://www.xmlplease.com/footnotes
References
==========
.. [cmdline-tool]
`Inside A Docutils Command-Line Front-End Tool
`_
.. [API]
`API Reference Material for Client-Developers
`_
.. [ilovetypography]
http://ilovetypography.com/2008/02/28/a-guide-to-web-typography/
.. [webtypography]
http://webtypography.net/toc/
.. [tekkie]
http://tekkie.flashbit.net/css/replacement-for-deprecated-ol-li-start-value-html-attributes,
2009.
.. [webjunction]
http://lists.webjunction.org/wjlists/web4lib/2001-September/026413.html,
2001.
.. [codelair] http://www.doheth.co.uk/codelair/html-css/deprecated#start,
2007.
.. [highdots]
http://www.highdots.com/forums/cascading-style-sheets/using-css-set-start-number-262555.html,
2008.
.. [dev.opera]
http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/,
2008.
.. [markschenk] `Publishing scientific documents with XHTML and CSS
`__
`<../html4trans>`_
is a similar sandbox project, a HTML writer producing XHTML that
contains enough formatting information to be viewed without a
cascading style sheet by a lightweight html browser
(e.g. `Dillo `__ or the console browser
`elinks `__).
_`XHTML 1.1`
`XHTML™ 1.1 - Module-based XHTML - Second Edition`,
W3C Recommendation, 23 November 2010.
http://www.w3.org/TR/xhtml11/