From 9ec8c1dfc79d978467625edd340c67b8b77d8b4a Mon Sep 17 00:00:00 2001 From: milde Date: Mon, 11 May 2015 15:38:58 +0000 Subject: [PATCH] Separate style sheets for required and optional layout rules. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7893 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docutils/writers/html_base/__init__.py | 5 +- docutils/docutils/writers/html_base/minimal.css | 240 +++++++++ .../writers/html_base/{html-base.css => plain.css} | 279 +---------- docutils/docutils/writers/xhtml11/__init__.py | 2 +- .../functional/expected/math_output_mathml.xhtml | 3 +- .../expected/standalone_rst_html_base.html | 87 ++-- .../expected/standalone_rst_xhtml11.xhtml | 556 +++++---------------- docutils/test/functional/input/data/html-base.css | 1 - docutils/test/functional/input/data/minimal.css | 1 + .../functional/input/standalone_rst_html_base.txt | 79 ++- .../functional/input/standalone_rst_xhtml11.txt | 338 +++---------- docutils/test/test_writers/test_html_base_misc.py | 207 ++++++++ 12 files changed, 752 insertions(+), 1046 deletions(-) create mode 100644 docutils/docutils/writers/html_base/minimal.css rename docutils/docutils/writers/html_base/{html-base.css => plain.css} (54%) delete mode 120000 docutils/test/functional/input/data/html-base.css create mode 120000 docutils/test/functional/input/data/minimal.css rewrite docutils/test/functional/input/standalone_rst_xhtml11.txt (89%) create mode 100644 docutils/test/test_writers/test_html_base_misc.py diff --git a/docutils/docutils/writers/html_base/__init__.py b/docutils/docutils/writers/html_base/__init__.py index 718b03922..583e6aed7 100644 --- a/docutils/docutils/writers/html_base/__init__.py +++ b/docutils/docutils/writers/html_base/__init__.py @@ -22,7 +22,8 @@ Basic HyperText Markup Language document tree Writer. The output conforms to the `HTML 5` specification as well as to `XHTML 1.0 transitional`. -The cascading style sheet "html-base.css" is required for proper viewing. +The cascading style sheet "minimal.css" is required for proper viewing, +the style sheet "plain.css" provides a better reading experience. """ __docformat__ = 'reStructuredText' @@ -52,7 +53,7 @@ class Writer(writers.Writer): supported = ('html', 'html5', 'html4', 'xhtml', 'xhtml10') """Formats this writer supports.""" - default_stylesheets = ['html-base.css'] + default_stylesheets = ['minimal.css','plain.css'] default_stylesheet_dirs = ['.', os.path.abspath(os.path.dirname(__file__))] default_template = 'template.txt' diff --git a/docutils/docutils/writers/html_base/minimal.css b/docutils/docutils/writers/html_base/minimal.css new file mode 100644 index 000000000..df86a6199 --- /dev/null +++ b/docutils/docutils/writers/html_base/minimal.css @@ -0,0 +1,240 @@ +/* Minimal style sheet for the HTML output of Docutils. */ +/* */ +/* :Author: Günter Milde, based on html4css1.css by David Goodger */ +/* :Id: $Id$ */ +/* :Copyright: © 2015 Günter Milde. */ +/* :License: Released under the terms of the `2-Clause BSD license`_, */ +/* in short: */ +/* */ +/* Copying and distribution of this file, with or without modification, */ +/* are permitted in any medium without royalty provided the copyright */ +/* notice and this notice are preserved. */ +/* */ +/* This file is offered as-is, without any warranty. */ +/* */ +/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ + +/* This CSS2.1_ stylesheet defines rules for Docutils elements without */ +/* HTML equivalent. It is required to make the document semantic visible. */ +/* */ +/* .. _CSS2.1: http://www.w3.org/TR/CSS2 */ +/* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */ + +/* Figure/table alignment */ +.align-left { text-align: left; } +.align-right { text-align: right; } +.align-center { clear: both; text-align: center;} + +/* titles */ +h1.title, p.subtitle { + text-align: center; +} +p.admonition-title, +p.topic-title, +p.sidebar-title, +p.rubric, +p.system-message-title { + font-weight: bold; +} +h1 + p.subtitle, +h1 + p.section-subtitle { + font-size: 1.6em; +} +h2 + p.section-subtitle { font-size: 1.28em; } +p.subtitle, +p.section-subtitle, +p.sidebar-subtitle { + font-weight: bold; + margin-top: -0.5em; +} +p.sidebar-title, +p.rubric { + font-size: larger; +} +p.rubric { color: maroon; } +a.toc-backref { + color: black; + text-decoration: none; } + +/* Warnings, Errors */ +div.caution p.admonition-title, +div.attention p.admonition-title, +div.danger p.admonition-title, +div.error p.admonition-title, +div.warning p.admonition-title, +div.system-messages h1, +div.error, +span.problematic, +p.system-message-title { + color: red; +} + +/* inline literals */ +span.docutils.literal { + font-family: monospace; + white-space: pre-wrap; +} +/* do not wraph at hyphens and similar: */ +.literal > span.pre { white-space: nowrap; } + +/* Lists */ + +/* compact and simple lists: no margin between items */ +.simple li, .compact li, +.simple ul, .compact ul, +.simple ol, .compact ol, +.simple > li p, .compact > li p, +dl.simple > dd, dl.compact > dd { + margin-top: 0; + margin-bottom: 0; +} + +/* Table of Contents */ +div.topic.contents { margin: 0; } +ul.auto-toc { + list-style-type: none; + padding-left: 1.5em; } + +/* Enumerated Lists */ +ol.arabic { list-style: decimal } +ol.loweralpha { list-style: lower-alpha } +ol.upperalpha { list-style: upper-alpha } +ol.lowerroman { list-style: lower-roman } +ol.upperroman { list-style: upper-roman } + +dt span.classifier { font-style: italic } +dt span.classifier:before { + font-style: normal; + margin: 0.5em; + content: ":"; +} + +/* Field Lists and drivatives */ +/* bold field name, content starts on the same line */ +dl.field-list > dt, +dl.option-list > dt, +dl.docinfo > dt, +dl.footnote > dt, +dl.citation > dt { + font-weight: bold; + clear: left; + float: left; + margin: 0; + padding: 0; + padding-right: 0.5em; +} +/* Offset for field content (corresponds to the --field-name-limit option) */ +dl.field-list > dd, +dl.option-list > dd, +dl.docinfo > dd { + margin-left: 9em; /* ca. 14 chars in the test examples */ +} +/* start field-body on a new line after long field names */ +dl.field-list > dd > *:first-child, +dl.option-list > dd > *:first-child +{ + display: inline-block; + width: 100%; + margin: 0; +} +/* field names followed by a colon */ +dl.field-list > dt:after, +dl.docinfo > dt:after { + content: ":"; +} + +/* Bibliographic Fields (docinfo) */ +pre.address { font: inherit; } +dd.authors > p { margin: 0; } + +/* Option Lists */ +dl.option-list { margin-left: 40px; } +dl.option-list > dt { font-weight: normal; } +span.option { white-space: nowrap; } + +/* Footnotes and Citations */ +dl > dt.label { font-weight: normal; } +dt.label > span.fn-backref { margin: 0.2em; } +dt.label > span.fn-backref > a { font-style: italic; } + +/* Line Blocks */ +div.line-block { display: block; } +div.line-block div.line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 40px; +} + +/* Images and Figures */ +img.align-left, +.figure.align-left, +object.align-left { + display: block; + margin-right: auto; +} +img.align-center, +.figure.align-center, +object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} +img.align-right, +.figure.align-right, +object.align-right { + display: block; + margin-left: auto; +} +/* reset inner alignment in figures */ +div.align-right { text-align: inherit } + +/* Admonitions and System Messages */ +div.admonition, +div.system-message, +div.sidebar{ + margin: 40px; + border: medium outset; + padding-right: 1em; + padding-left: 1em; +} + +/* Sidebar */ +div.sidebar { + width: 30%; + max-width: 26em; + float: right; + clear: right; +} + +/* Text Blocks */ +div.topic, +pre.literal-block, +pre.doctest-block, +pre.math, +pre.code { + margin-right: 40px; + margin-left: 40px; +} +pre.code .ln { color: gray; } /* line numbers */ + +/* Tables */ +table { border-collapse: collapse; } +td, th { + border-style: solid; + border-color: silver; + padding: 0 1ex; + border-width: thin; +} +td > p:first-child, th > p:first-child { margin-top: 0; } +td > p, th > p { margin-bottom: 0; } + +table > caption { + text-align: left; + margin-bottom: 0.25em +} + +table.borderless td, table.borderless th { + border: 0; + padding: 0; + padding-right: 0.5em /* separate table cells */ +} diff --git a/docutils/docutils/writers/html_base/html-base.css b/docutils/docutils/writers/html_base/plain.css similarity index 54% rename from docutils/docutils/writers/html_base/html-base.css rename to docutils/docutils/writers/html_base/plain.css index 65e128451..ba244eab9 100644 --- a/docutils/docutils/writers/html_base/html-base.css +++ b/docutils/docutils/writers/html_base/plain.css @@ -1,10 +1,11 @@ -/* Basic style sheet for the HTML output of Docutils. */ +/* CSS31_ style sheet for the output of Docutils HTML writers. */ +/* Rules for easy reading and pre-defined style variants. */ /* */ /* :Author: Günter Milde, based on html4css1.css by David Goodger */ -/* :Id: $Id$ */ +/* :Id: $Id$ */ /* :Copyright: © 2015 Günter Milde. */ /* :License: Released under the terms of the `2-Clause BSD license`_, */ -/* in short: */ +/* in short: */ /* */ /* Copying and distribution of this file, with or without modification, */ /* are permitted in any medium without royalty provided the copyright */ @@ -13,25 +14,17 @@ /* This file is offered as-is, without any warranty. */ /* */ /* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */ - - -/* This stylesheet contains basic rules for the output of the */ -/* Docutils HTML writers. It validates_ as CSS2.1_ */ -/* */ -/* .. _CSS2.1: http://www.w3.org/TR/CSS2 */ -/* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */ +/* .. _CSS3: http://www.w3.org/TR/CSS3 */ /* Document Structure */ /* ****************** */ -/* Document */ - +/* "page layout" */ body { padding: 0 5%; margin: 8px 0; } - div.document { line-height:1.3; counter-reset: table; @@ -42,30 +35,7 @@ div.document { margin: auto; } -.align-left { text-align: left; } -.align-right { text-align: right; } -.align-center { - clear: both; - text-align: center; -} - -/* Sections */ - -h1.title, p.subtitle { - text-align: center; -} - -h1 + p.subtitle { font-size: 1.6em; } -h1 + p.section-subtitle { font-size: 1.6em; } -h2 + p.section-subtitle { font-size: 1.28em; } - -a.toc-backref { - color: black; - text-decoration: none; -} - -/* Stop floating sidebars, images and figures at section level 1,2,3 */ -h1, h2, h3 { clear: both; } +/* Sections */ /* Transitions */ @@ -91,55 +61,9 @@ dl > dd { margin-bottom: 0.5em; } -/* titles */ -p.admonition-title, -p.topic-title, -p.sidebar-title, -p.system-message-title { - font-weight: bold; -} - -p.subtitle, -p.section-subtitle, -p.sidebar-subtitle { - font-weight: bold; - margin-top: -0.5em; -} - - -/* Warnings, Errors */ -div.caution p.admonition-title, -div.attention p.admonition-title, -div.danger p.admonition-title, -div.error p.admonition-title, -div.warning p.admonition-title, -div.system-messages h1, -div.error, -span.problematic, -p.system-message-title { - color: red; -} - /* Lists */ /* ========== */ -/* compact and simple lists: no margin between items */ -dl.simple > dd, dl.compact > dd, -.compact li, .compact ul, .compact ol -.simple li, .simple ul, .simple ol, -.simple > li p, .compact > li p { - margin-top: 0; - margin-bottom: 0; -} - -/* Enumerated Lists */ - -ol.arabic { list-style: decimal } -ol.loweralpha { list-style: lower-alpha } -ol.upperalpha { list-style: upper-alpha } -ol.lowerroman { list-style: lower-roman } -ol.upperroman { list-style: upper-roman } - /* Definition Lists */ dl > dd p:first-child { margin-top: 0; } @@ -150,21 +74,8 @@ dl > dd p:first-child { margin-top: 0; } /* :only-child is not part of CSS 2.1 (introduced in CSS 3) */ dd > ul:only-child, dd > ol:only-child { padding-left: 1em; } -dt span.classifier { font-style: italic } -dt span.classifier:before { - font-style: normal; - margin: 0.5em; - content: ":"; -} - -/* Field Lists */ - -/* bold field name, content starts on the same line */ -dl.field-list > dt, -dl.option-list > dt, -dl.docinfo > dt, -dl.footnote > dt, -dl.citation > dt, +/* Description Lists */ +/* styled like in most dictionaries, encyclopedias etc. */ dl.description > dt { font-weight: bold; clear: left; @@ -173,26 +84,8 @@ dl.description > dt { padding: 0; padding-right: 0.5em; } -/* Offset for field content (corresponds to the --field-name-limit option) */ -dl.field-list > dd, -dl.option-list > dd, -dl.docinfo > dd { - margin-left: 9em; /* ca. 14 chars in the test examples */ -/* padding-left: 0.5em; */ -} -/* start field-body on a new line after long field names */ -dl.field-list > dd > *:first-child, -dl.option-list > dd > *:first-child, -dl.docinfo > dd > *:first-child { - display: inline-block; - width: 100%; - margin: 0; -} -/* field names followed by a colon */ -dl.field-list > dt:after, -dl.docinfo > dt:after { - content: ":"; -} + +/* Field Lists */ /* example for custom field-name width */ dl.field-list.narrow > dd { @@ -205,19 +98,11 @@ dl.field-list.run-in > dd p { /* Bibliographic Fields */ -/* use special field-list dl.docinfo */ - -pre.address { - margin-bottom: 0; - margin-top: 0; - font: inherit; -} -dd.authors > p { margin: 0; } - +/* generally, bibliographic fields use special definition list dl.docinfo */ +/* but dedication and abstract are placed into "topic" divs */ div.abstract p.topic-title { text-align: center; } - div.dedication { margin: 2em 5em; text-align: center; @@ -227,34 +112,18 @@ div.dedication p.topic-title { font-style: normal; } -/* Option Lists */ - -dl.option-list { - margin-left: 1em; +/* Citations */ +dl.citation dt.label { + font-weight: bold; } -dl.option-list > dt { +span.fn-backref { font-weight: normal; } -span.option { - white-space: nowrap; -} /* Text Blocks */ /* ============ */ -/* Line Blocks */ - -div.line-block { - display: block; -} -div.line-block div.line-block { - margin-top: 0; - margin-bottom: 0; - margin-left: 1.5em; -} - /* Literal Blocks */ - pre.literal-block, pre.doctest-block, pre.math, pre.code { margin-left: 1.5em; @@ -282,38 +151,7 @@ div.topic p.attribution { /* Tables */ /* ====== */ -/* margins and borders for "normal" tables */ -table { - border-collapse: collapse; -} -td, th { - border-style: solid; - border-color: silver; - padding: 0 1ex; -/* some borders missing at some magnifications -/* in Firefox 31.5.0 and opera 10.63 */ - border-width: thin; -} -td > p:first-child, th > p:first-child { - margin-top: 0; -} -td > p, th > p { - margin-bottom: 0; -} -th { - vertical-align: bottom; -} - -table > caption { - text-align: left; - margin-bottom: 0.25em -} - -table.borderless td, table.borderless th { - border: 0; - padding: 0; - padding-right: 0.5em /* separate table cells */ -} +/* th { vertical-align: bottom; } */ /* "booktabs" style (no vertical lines) */ table.booktabs { @@ -322,7 +160,6 @@ table.booktabs { border-bottom: 2px solid; border-collapse: collapse; } - table.booktabs * { border: 0; } @@ -351,35 +188,13 @@ dl.footnote { border-left-width: thin; } -dl > dt.label { - font-weight: normal; -} -dt.label > span.fn-backref { - margin: 0.2em; -} -dt.label > span.fn-backref > a { - font-style: italic; -} - /* Directives */ /* ---------- */ -/* Admonitions */ -/* System Messages */ - -div.admonition, -div.system-message { - margin: 2em; - border: medium outset; - padding-right: 1em; - padding-left: 1em; -} - /* Body Elements */ /* ~~~~~~~~~~~~~ */ -/* Image and Figure */ - +/* Images and Figures */ img.align-left, .figure.align-left, object.align-left { @@ -394,38 +209,20 @@ object.align-right { float: right; margin-left: 1em } -img.align-center, -.figure.align-center, -object.align-center { - display: block; - margin-left: auto; - margin-right: auto; -} -/* reset inner alignment in figures */ -div.align-right { - text-align: inherit } - -/* Topic */ - -div.topic { margin: 2em } +/* Stop floating sidebars, images and figures at section level 1,2,3 */ +h1, h2, h3 { clear: both; } -/* Sidebar */ +/* Sidebar */ -/* in a layout with fixed margins, */ -/* the sidebar can be moved into the margin completely */ +/* Move into the margin. In a layout with fixed margins, */ +/* it can be moved into the margin completely. */ div.sidebar { - border: medium outset; - padding-right: 1em; - padding-left: 1em; width: 30%; max-width: 26em; - float: right; - clear: right; margin-left: 1em; margin-right: -5.5%; background-color: #ffffee ; } -p.sidebar-title { font-size: larger; } /* Code */ @@ -443,14 +240,6 @@ pre.code .inserted, code .inserted { background-color: #A3D289} /* Math */ /* styled separately (see math.css for math-output=HTML) */ -/* Rubric */ - -p.rubric { - font-weight: bold; - font-size: larger; - color: maroon; -} - /* Epigraph */ /* Highlights */ /* Pull-Quote */ @@ -466,15 +255,6 @@ div.footer, div.header { font-size: smaller; } -/* Contents */ - -div.topic.contents { - margin: 0; /* don't indent like a topic */ -} -ul.auto-toc { - list-style-type: none; -} - /* Inline Markup */ /* ============= */ @@ -487,17 +267,10 @@ ul.auto-toc { /* Title Reference */ /* cite */ /* Inline Literals */ - -tt.literal, span.docutils.literal { - font-family: monospace; - /* possible values: normal, nowrap, pre, pre-wrap, pre-line */ - white-space: pre-wrap; -} -/* do not wraph a hyphens and similar: */ -.literal > span.pre { white-space: nowrap; } +/* possible values: normal, nowrap, pre, pre-wrap, pre-line */ +/* span.docutils.literal { white-space: pre-wrap; } */ /* Hyperlink References */ - a { text-decoration: none; } /* External Targets */ diff --git a/docutils/docutils/writers/xhtml11/__init__.py b/docutils/docutils/writers/xhtml11/__init__.py index b30b9f065..2664eef8f 100644 --- a/docutils/docutils/writers/xhtml11/__init__.py +++ b/docutils/docutils/writers/xhtml11/__init__.py @@ -35,7 +35,7 @@ class Writer(html_base.Writer): 'xhtml', 'xhtml1', 'xhtml1strict', 'xhtml11') """Formats this writer supports.""" - default_stylesheets = ['html-base.css', 'xhtml11.css'] + default_stylesheets = ['minimal.css', 'plain.css', 'xhtml11.css'] default_stylesheet_dirs = ['.', os.path.abspath(os.path.dirname(__file__)), os.path.abspath(os.path.join( diff --git a/docutils/test/functional/expected/math_output_mathml.xhtml b/docutils/test/functional/expected/math_output_mathml.xhtml index a46bc178a..1b8e45a05 100644 --- a/docutils/test/functional/expected/math_output_mathml.xhtml +++ b/docutils/test/functional/expected/math_output_mathml.xhtml @@ -4,7 +4,8 @@ Mathematics - + +
diff --git a/docutils/test/functional/expected/standalone_rst_html_base.html b/docutils/test/functional/expected/standalone_rst_html_base.html index 441790420..65d6d4fe3 100644 --- a/docutils/test/functional/expected/standalone_rst_html_base.html +++ b/docutils/test/functional/expected/standalone_rst_html_base.html @@ -7,7 +7,8 @@ - + + @@ -139,14 +140,14 @@ They are transformed from section titles after parsing. -->

  • 3 Changes to the html4css1 writer

  • 4 Error Handling

    • @@ -1161,24 +1162,8 @@ For complete control over display options use raw HTML.

    space.

  • Put subtitles in <p> elements.

    • -
    -

    3.1 Description list

    -

    Definition lists with the description class argument:

    -
    -
    description lists
    -

    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.

    -
    -
    -
    -

    3.2 Field list handling

    +

    3.1 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.

    @@ -1200,7 +1185,7 @@ with the default setting of field-name-limit: 14.

    previous one but regarded "short" by html4css1.

    -

    With html4css2, a field list is typeset as CSS-styled definition +

    With html_base, a field list is typeset as CSS-styled definition list. The default layout is similar to the look with html4css1:

    A long field name
    @@ -1215,10 +1200,30 @@ example:

    dl.field-list > dd { margin-left: 6em; }
    +
    -

    3.2.1 Styling with class arguments

    -

    The xhtml11.css style sheet supports the following class arguments -for alternative styles:

    +

    3.2 Styling with class arguments

    +

    The plain.css style sheet comes with some pre-defined style variants +that can be choosen via a class argument.

    +
    +

    3.2.1 Description lists

    +

    Definition lists with the "description" class argument:

    +
    +
    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.

    +
    +
    +
    +
    +

    3.2.2 Field list variants

    +

    For field lists, the "compact/open", "narrow" and "run-in" styles are defined.

    compact
    @@ -1282,12 +1287,12 @@ body is wrapped and aligns with other fields.

    -
    -
    -

    3.3 Table styling with class arguments

    -

    The html-base.css style sheet provides rules for easy styling of tables -with the "class" directive or directive argument.

    -

    Numbered tables can be achieved with the numbered class option

    +
    +

    3.2.3 Table variants

    +

    The following styles can be applied to individual tables via a class +argument or as document wide setting with the table-style [7] configuration +setting (or command line argument).

    +

    Numbered tables can be achieved with the "numbered" class option

    @@ -1322,9 +1327,8 @@ with the "class" directive or directive argument.

    truth values

    Currently, referencing to the table by number is not supported. This is a common request and already on the TODO list.

    -

    In addition to the "borderless" table-style [7], the style sheet also -defines "booktabs", that will be rendered similar to the style from -the booktabs [8] LaTeX package.

    +

    A table with "booktabs" class argument, is rendered similar to the style +from the booktabs [8] LaTeX package.

    @@ -1420,17 +1424,6 @@ the headers:

    -
    -

    3.4 Maths

    -

    For maximal compatibility, the html-output setting defaults to »HTML«. -(HTML 5 accepts also MathML and SVG as nested languages.)

    -

    The linear mapping f : ℂN⟼ℂN -with

    -
    -ck = F(kf0) = TA + N ⁄ 2⎲⎳n =  − N ⁄ 2f(xn)e − 2πi(nk)/(N) -
    -

    for all a ∈ ℂN is called discrete Fourier -transformation (DFT).

    diff --git a/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml b/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml index 8802b5b37..399e23941 100644 --- a/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml +++ b/docutils/test/functional/expected/standalone_rst_xhtml11.xhtml @@ -8,7 +8,8 @@ - + + @@ -81,93 +82,81 @@ They are transformed from section titles after parsing. -->

    Table of Contents

    -

    1 Structural Elements

    +

    1 Structural Elements

    -

    1.1 Section Title

    +

    1.1 Section Title

    Section Subtitle

    Lone subsections are converted to a section subtitle by a transform activated with the --section-subtitles command line option or the sectsubtitle-xform configuration value.

    -

    1.3 Transitions

    +

    1.3 Transitions

    Here's a transition:

    It divides the section. Transitions may also occur between sections:

    @@ -175,18 +164,18 @@ activated with the --section-su
    -

    2 Body Elements

    +

    2 Body Elements

    -

    2.1 Paragraphs

    +

    2.1 Paragraphs

    A paragraph.

    -

    2.1.1 Inline Markup

    +

    2.1.1 Inline Markup

    Paragraphs contain text and may contain inline markup: emphasis, strong emphasis, inline literals, standalone hyperlinks (http://www.python.org), external hyperlinks (Python [5]), internal cross-references (example), external hyperlinks with embedded URIs (Python web site), anonymous hyperlink -references [5] (a second reference [9]), footnote references (manually +references [5] (a second reference [7]), footnote references (manually numbered [1], anonymous auto-numbered [3], labeled auto-numbered [2], or symbolic [*]), citation references ([CIT2002]), substitution references (EXAMPLE), and inline hyperlink targets @@ -208,7 +197,7 @@ live link to PEP 258 here.

    -

    2.2 Bullet Lists

    +

    2.2 Bullet Lists

    • A bullet list

        @@ -235,7 +224,7 @@ live link to PEP 258 here.

    -

    2.3 Enumerated Lists

    +

    2.3 Enumerated Lists

    1. Arabic numerals.

        @@ -271,7 +260,7 @@ live link to PEP 258 here.

    -

    2.4 Definition Lists

    +

    2.4 Definition Lists

    Term

    Definition

    @@ -289,7 +278,7 @@ live link to PEP 258 here.

    -

    2.5 Field Lists

    +

    2.5 Field Lists

    what

    Field lists map field names to field bodies, like database @@ -309,7 +298,7 @@ doesn't get stripped away.)

    -

    2.6 Option Lists

    +

    2.6 Option Lists

    For listing command-line options:

    -a
    @@ -348,7 +337,7 @@ regardless of where it starts.

    description.

    -

    2.7 Literal Blocks

    +

    2.7 Literal Blocks

    Literal blocks are indicated with a double-colon ("::") at the end of the preceding paragraph (over there -->). They can be indented:

    if literal_block:
@@ -361,7 +350,7 @@ the preceding paragraph (over there 
-
    2.8 Line Blocks
    
+
    2.8 Line Blocks
    
 
    This section tests line blocks.  Line blocks are body elements which
 consist of lines and other line blocks.  Nested line blocks cause
 indentation.
    
@@ -435,7 +424,7 @@ also be centre-aligned:
    -

    2.9 Block Quotes

    +

    2.9 Block Quotes

    Block quotes consist of indented body elements:

    My theory by A. Elk. Brackets Miss, brackets. This theory goes @@ -454,7 +443,7 @@ notamment dans la documentation du langage Python.

    -

    2.10 Doctest Blocks

    +

    2.10 Doctest Blocks

    >>> print 'Python-specific usage examples; begun with ">>>"'
 Python-specific usage examples; begun with ">>>"
 >>> print '(cut and pasted from interactive Python sessions)'
@@ -462,7 +451,7 @@ Python-specific usage examples; begun with ">>>"
    -

    2.11 Footnotes

    +

    2.11 Footnotes

    [1](1,2,3)

    A footnote contains body elements, consistently indented by at @@ -490,23 +479,23 @@ Here's a reference to the next footnote: [4]

    Here's an unreferenced footnote, with a reference to a -nonexistent footnote: [5]_.

    +nonexistent footnote: [5]_.

    -

    2.12 Citations

    +

    2.12 Citations

    [CIT2002](1,2)

    Citations are text-labeled footnotes. They may be rendered separately and differently from footnotes.

    -

    Here's a reference to the above, [CIT2002], and a [nonexistent]_ +

    Here's a reference to the above, [CIT2002], and a [nonexistent]_ citation.

    -

    2.13 Targets

    +

    2.13 Targets

    This paragraph is pointed to by the explicit "example" target. A reference can be found under Inline Markup, above. Inline hyperlink targets are also possible.

    @@ -516,47 +505,47 @@ hyperlink targets are also possible.

    "Python [5]".

    Targets may be indirect and anonymous. Thus this phrase may also refer to the Targets section.

    -

    Here's a `hyperlink reference without a target`_, which generates an +

    Here's a `hyperlink reference without a target`_, which generates an error.

    -

    2.13.1 Duplicate Target Names

    +

    2.13.1 Duplicate Target Names

    Duplicate names in section headers or other implicit targets will generate "info" (level-1) system messages. Duplicate names in explicit targets will generate "warning" (level-2) system messages.

    -

    2.13.2 Duplicate Target Names

    +

    2.13.2 Duplicate Target Names

    Since there are two "Duplicate Target Names" section headers, we cannot uniquely refer to either of them by name. If we try to (like -this: `Duplicate Target Names`_), an error is generated.

    +this: `Duplicate Target Names`_), an error is generated.

    -

    2.14 Directives

    +

    2.14 Directives

    These are just a sample of the many reStructuredText Directives. For others, please see http://docutils.sourceforge.net/docs/ref/rst/directives.html.

    -

    2.14.1 Document Parts

    +

    2.14.1 Document Parts

    An example of the "contents" directive can be seen above this section (a local, untitled table of contents) and at the beginning of the document (a document-wide table of contents).

    -

    2.14.2 Images and Figures

    +

    2.14.2 Images and Figures

    An image directive (also clickable -- a hyperlink reference):

    ../../../docs/user/rst/images/title.png

    Image with multiple IDs:

    @@ -647,7 +636,7 @@ rendering software used.

    upon the style sheet and the browser or rendering software used.

    -

    2.14.3 Admonitions

    +

    2.14.3 Admonitions

    Attention!

    Directives at large.

    @@ -696,7 +685,7 @@ Reader discretion is strongly advised.

    -

    2.14.4 Topics, Sidebars, and Rubrics

    +

    2.14.4 Topics, Sidebars, and Rubrics

    Sidebars are like miniature, parallel documents.

    Sidebar Title

    @@ -720,31 +709,25 @@ document's structure. It is typically highlighted in red (hence the name).

    allowed (e.g. inside a directive).

    -

    2.14.6 Replacement Text

    +

    2.14.6 Replacement Text

    I recommend you try Python, the best language around [5].

    -

    2.14.7 Compound Paragraph

    +

    2.14.7 Compound Paragraph

    Compound 1, paragraph 1.

    Compound 1, paragraph 2.

    @@ -808,7 +791,7 @@ paragraph.

    -

    2.14.8 Parsed Literal Blocks

    +

    2.14.8 Parsed Literal Blocks

    This is a parsed literal block.
     This line is indented.  The next line is blank.
 
@@ -819,7 +802,7 @@ inline formulas: 
 footnotes [1], hyperlink targets, and references.
    -

    2.14.9 Code

    +

    2.14.9 Code

    Blocks of source code can be set with the code directive. If the code language is specified, the content is parsed and tagged by the Pygments [6] syntax highlighter and can be formatted with a style sheet. (Code parsing @@ -846,12 +829,12 @@ as a code block, here the rst file header_footer.

    -

    2.15 Substitution Definitions

    +

    2.15 Substitution Definitions

    An inline image (EXAMPLE) example:

    (Substitution definitions are not visible in the HTML source.)

    -

    2.16 Comments

    +

    2.16 Comments

    Here's one:

    (View the HTML source to see the comment.)

    -

    2.17 Raw text

    +

    2.17 Raw text

    This does not necessarily look nice, because there may be missing white space.

    It's just there to freeze the behavior.

    A test.Second test.
    Another test with myclass set.

    This is the fourth test with myrawroleclass set.

    Fifth test in HTML.
    Line two.
    -

    2.18 Container

    +

    2.18 Container

    paragraph 1

    paragraph 2

    -

    2.19 Colspanning tables

    +

    2.19 Colspanning tables

    This table has a cell spanning two columns:

    @@ -914,7 +897,7 @@ Fifth test in HTML.
    Line two.
    -

    2.20 Rowspanning tables

    +

    2.20 Rowspanning tables

    Here's a table with cells spanning several rows:

    @@ -947,7 +930,7 @@ cell.

    -

    2.21 Complex tables

    +

    2.21 Complex tables

    Here's a complex table, which should test all features.

    @@ -996,7 +979,7 @@ empty: -->

    -

    2.22 List Tables

    +

    2.22 List Tables

    Here's a list table exercising all features:

    @@ -1029,7 +1012,7 @@ crunchy, now would it?

    list table with integral header
    -

    2.23 Custom Roles

    +

    2.23 Custom Roles

    • A role based on an existing role.

      one two three

      @@ -1057,7 +1040,7 @@ crunchy, now would it?

    -

    2.24 SVG Images

    +

    2.24 SVG Images

    ../../../docs/user/rst/images/biohazard.svg

    Scalable vector graphics (SVG) images are the only standards-compliable way to include vector graphics in HTML documents. However, they are not @@ -1142,7 +1125,7 @@ tags.

    -

    2.25 SWF Images

    +

    2.25 SWF Images

    Shockwave Flash is an image/movie format that most modern web browsers support via a plugin. It is sometimes blocked due to privacy/security concerns.

    @@ -1154,12 +1137,18 @@ For complete control over display options use raw HTML.

    An inline SWF image inline-swf scaled to 0.8 em x 0.8 em.

    -
    -

    3 Additional html4css2 features

    -
    -

    3.1 Enumerated lists with nested counters

    +
    +

    3 Additional xhtml11 features

    +

    The following features are set the the "xhtml11" writer apart from the +"html-base" writer:

    +
      +

    • The document type is XHTML 1.1

      • +

    • An "enumerated list" with class "nested" uses nested counters:

      1. first point

        +
          +

        • Unordered list nested in enumeration.

          • +

        1. first sub-point

        2. second sub-point

          @@ -1171,9 +1160,6 @@ For complete control over display options use raw HTML.

        3. third sub-point with a long and silly text just to test the line wrapping in this kind of lists.

        -
          -

        • Unordered list nested in enumeration.

          • -
        Definition list

        nested in top-level enumeration

        @@ -1182,297 +1168,14 @@ wrapping in this kind of lists.

      2. second top-level point

      -
    -
    -

    3.2 Description list

    -

    Definition lists with the description class argument:

    -
    -
    description lists
    -

    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.

    -
    -
    -
    -
    -

    3.3 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 html4css2, a field list is typeset as CSS-styled definition -list. The default layout is similar to the look with html4css1:

    -
    -
    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 or -fix-labelwidth class arguments).

    -
    -
    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; }
    -
    -
    -
    -

    3.3.1 Styling with class arguments

    -

    The xhtml11.css style sheet supports the following class arguments -for alternative styles:

    -
    -
    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
    -
    -
    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
    -
    -
    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 or fix-labelwidth).

    -
    -
    -
    -
    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.

    -
    -
    -
    -
    fix-labelwidth
    -
    -
    Feature
    -

    The width of the field name (label) is fixed. Long labels -wrap.

    -
    -
    this long field name
    -

    will wrap.

    -
    -
    the next field name
    -

    and field body should align.

    - -
    -
    Problem
    -

    Non-wrappable field names are truncated.

    -
    -
    a_very_long_field_name
    -

    is truncated if it can not wrap.

    -
    -
    -
    -
    -
    -
    -
    -

    3.4 Table styling with class arguments

    -

    The html-base.css style sheet provides rules for easy styling of tables -with the "class" directive or directive argument.

    -

    Numbered tables can be achieved with the numbered class option

    - - ----- - - - - - - - - - - - - - - - - - - - - - - - - -
    truth values

    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.

    -

    In addition to the "borderless" table-style [7], the style sheet also -defines "booktabs", that will be rendered similar to the style from -the booktabs [8] LaTeX package.

    - ----- - - - - - - - - - - - - - - - - - - -

    False

    False

    False

    True

    False

    True

    False

    True

    True

    True

    True

    True

    -

    This table also uses the "align-left" class argument, to left-align -the headers:

    - ----- - - - - - - - - - - - - - - - - - - - - - - - - -

    A

    B

    A or B

    False

    False

    False

    True

    False

    True

    False

    True

    True

    True

    True

    True

    -

    Of course, also "booktabs" style tables can be numbered:

    - - ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    I/O values

    Inputs

    Output

    A

    B

    A or B

    False

    False

    False

    True

    False

    True

    False

    True

    True

    True

    True

    True

    -
    -
    -

    3.5 Maths

    -

    The html-output setting defaults to »MathML«. If there is mathematical -content in MathML format, the document type is XHTML 1.1 plus MathML 2.0.

    + +

  • The html-output setting defaults to »MathML«. If there is mathematical +content in MathML format, the document type is XHTML 1.1 plus MathML +2.0.

    The linear mapping f:ℂ N⟼ℂ -N -with

    +N with

    @@ -1492,10 +1195,11 @@ with

    a∈ℂ N     is called discrete Fourier transformation (DFT).

    -
    +
    • +
    -

    4 Error Handling

    +

    4 Error Handling

    Any errors caught during processing will generate system messages.

    There should be five messages in the following, auto-generated section, "Docutils System Messages":

    @@ -1507,20 +1211,20 @@ section, "Docutils System Messages":

    System Message: ERROR/3 (functional/input/data/standard.txt, line 104); backlink

    Undefined substitution referenced: "problematic".

    -
    -

    System Message: ERROR/3 (functional/input/data/standard.txt, line 391); backlink

    +
    +

    System Message: ERROR/3 (functional/input/data/standard.txt, line 391); backlink

    Unknown target name: "5".

    -
    -

    System Message: ERROR/3 (functional/input/data/standard.txt, line 400); backlink

    +
    +

    System Message: ERROR/3 (functional/input/data/standard.txt, line 400); backlink

    Unknown target name: "nonexistent".

    -
    -

    System Message: ERROR/3 (functional/input/data/standard.txt, line 427); backlink

    +
    +

    System Message: ERROR/3 (functional/input/data/standard.txt, line 427); backlink

    Unknown target name: "hyperlink reference without a target".

    -
    -

    System Message: ERROR/3 (functional/input/data/standard.txt, line 440); backlink

    +
    +

    System Message: ERROR/3 (functional/input/data/standard.txt, line 440); backlink

    Duplicate target name, cannot be used as a unique reference: "duplicate target names".

    diff --git a/docutils/test/functional/input/data/html-base.css b/docutils/test/functional/input/data/html-base.css deleted file mode 120000 index b02ed730c..000000000 --- a/docutils/test/functional/input/data/html-base.css +++ /dev/null @@ -1 +0,0 @@ -../../../../docutils/writers/html_base/html-base.css \ No newline at end of file diff --git a/docutils/test/functional/input/data/minimal.css b/docutils/test/functional/input/data/minimal.css new file mode 120000 index 000000000..d1e1e8638 --- /dev/null +++ b/docutils/test/functional/input/data/minimal.css @@ -0,0 +1 @@ +../../../../docutils/writers/html_base/minimal.css \ No newline at end of file diff --git a/docutils/test/functional/input/standalone_rst_html_base.txt b/docutils/test/functional/input/standalone_rst_html_base.txt index 1ae91134d..67b832f37 100644 --- a/docutils/test/functional/input/standalone_rst_html_base.txt +++ b/docutils/test/functional/input/standalone_rst_html_base.txt @@ -24,22 +24,6 @@ Changes to the html4css1 writer * Put subtitles in

    elements. -Description list ----------------- - -Definition lists with the ``description`` class argument: - -.. class:: description - -description lists - 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 handling ------------------- @@ -59,7 +43,7 @@ characters" but the field name uses a proportional font. :MMMMMMMMMMMMMM: a field name that is actually longer than the previous one but regarded "short" by html4css1. -With `html4css2`, a `field list` is typeset as CSS-styled `definition +With ``html_base``, a `field list` is typeset as CSS-styled `definition list`. The default layout is similar to the look with `html4css1`: .. class:: open @@ -76,10 +60,30 @@ list`. The default layout is similar to the look with `html4css1`: dl.field-list > dd { margin-left: 6em; } 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 +````````````````` -The ``xhtml11.css`` style sheet supports the following class arguments -for alternative styles: +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 @@ -125,14 +129,14 @@ for alternative styles: :The next field name: and field body should align. Long text in the field body is wrapped and aligns with other fields. +Table variants +`````````````` -Table styling with class arguments ----------------------------------- - -The ``html-base.css`` style sheet provides rules for easy styling of tables -with the "class" directive or directive argument. +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 +Numbered tables can be achieved with the "numbered" class option .. table:: truth values :class: numbered @@ -149,9 +153,8 @@ Numbered tables can be achieved with the ``numbered`` class option Currently, referencing to the table by number is not supported. This is a common request and already on the `TODO list`. -In addition to the "borderless" table-style_, the style sheet also -defines "booktabs", that will be rendered similar to the style from -the booktabs_ LaTeX package. +A table with "booktabs" class argument, is rendered similar to the style +from the booktabs_ LaTeX package. .. _table-style: http://docutils.sourceforge.net/docs/user/config.html#table-style @@ -199,24 +202,6 @@ Of course, also "booktabs" style tables can be numbered: ===== ===== ====== -Maths ------ - -For maximal compatibility, the ``html-output`` setting defaults to »HTML«. -(HTML 5 accepts also MathML and SVG as nested languages.) - -The linear mapping :math:`f: \mathbb{C}^{N}\longmapsto\mathbb{C}^{N}` -with - -.. math:: - - c_{k}=F(kf_{0})=T_{\text{A}} - \sum_{n=-N/2}^{+N/2}f(x_{n})\text{e}^{-2\pi\text{i}\frac{nk}{N}} - -for all :math:`a\in\mathbb{C}^{N}` is called discrete Fourier -transformation (DFT). - - .. include:: data/errors.txt .. footer:: |HTML 5| |validator| |valid-CSS2| diff --git a/docutils/test/functional/input/standalone_rst_xhtml11.txt b/docutils/test/functional/input/standalone_rst_xhtml11.txt dissimilarity index 89% index 80214ea59..b5ec4242f 100644 --- a/docutils/test/functional/input/standalone_rst_xhtml11.txt +++ b/docutils/test/functional/input/standalone_rst_xhtml11.txt @@ -1,268 +1,70 @@ -.. 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 - -Additional html4css2 features -================================ - -Enumerated lists with nested counters -------------------------------------- - -.. class:: nested - -#. first point - - #. first sub-point - #. second sub-point - - With a standard paragraph - - #. first sub-sub-point - - #. third sub-point with a long and silly text just to test the line - wrapping in this kind of lists. - - * Unordered list nested in enumeration. - - Definition list - nested in top-level enumeration - -#. second top-level point - - -Description list ----------------- - -Definition lists with the ``description`` class argument: - -.. class:: description - -description lists - 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 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 `html4css2`, 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`_ or - `fix-labelwidth`_ class arguments). - -: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; } - -Styling with class arguments -```````````````````````````` - -The ``xhtml11.css`` style sheet supports the following class arguments -for alternative styles: - -*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`_ or `fix-labelwidth`_). - - .. _`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. - - .. _`fix-labelwidth`: - -*fix-labelwidth* - .. class:: fix-labelwidth - - :Feature: The width of the field name (label) is fixed. Long labels - wrap. - - :this long field name: will wrap. - - :the next field name: and field body should align. - - .. If the field name is wrapped but the field body just - one line, following field bodies "float up" if not - prevented by a dummy dd:after element in the CSS. - - :Problem: Non-wrappable field names are truncated. - - :a_very_long_field_name: - is truncated if it can not wrap. - - -Table styling with class arguments ----------------------------------- - -The ``html-base.css`` style sheet provides rules for easy styling of tables -with the "class" directive or directive 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`. - -In addition to the "borderless" table-style_, the style sheet also -defines "booktabs", that will be 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 - -.. class:: booktabs - -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== - -This table also uses the "align-left" class argument, to left-align -the headers: - -.. class:: booktabs align-left - -===== ===== ======= - A B A or B -===== ===== ======= -False False False -True False True -False True True -True True True -===== ===== ======= - - -Of course, also "booktabs" style tables can be numbered: - -.. table:: I/O values - :class: numbered booktabs - - ===== ===== ====== - Inputs Output - ------------ ------ - A B A or B - ===== ===== ====== - False False False - True False True - False True True - True True True - ===== ===== ====== - - -Maths ------ - -The ``html-output`` setting defaults to »MathML«. If there is mathematical -content in `MathML` format, the document type is XHTML 1.1 plus MathML 2.0. - -The linear mapping :math:`f: \mathbb{C}^{N}\longmapsto\mathbb{C}^{N}` -with - -.. math:: - - c_{k}=F(kf_{0})=T_{\text{A}} - \sum_{n=-N/2}^{+N/2}f(x_{n})\text{e}^{-2\pi\text{i}\frac{nk}{N}} - -for all :math:`a\in\mathbb{C}^{N}` is called discrete Fourier -transformation (DFT). - - -.. include:: data/errors.txt - -.. footer:: |valid-xhtml11| |valid-CSS2| - -.. |valid-xhtml11| image:: http://www.w3.org/Icons/valid-xhtml11 - :height: 31 - :width: 88 - :alt: Valid XHTML 1.1! - :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 +.. 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 + +Additional xhtml11 features +=========================== + +The following features are set the the "xhtml11" writer apart from the +"html-base" writer: + +* The document type is XHTML 1.1 + +* An "enumerated list" with class "nested" uses nested counters: + + .. class:: nested + + #. first point + + * Unordered list nested in enumeration. + + #. first sub-point + #. second sub-point + + With a standard paragraph + + #. first sub-sub-point + + #. third sub-point with a long and silly text just to test the line + wrapping in this kind of lists. + + Definition list + nested in top-level enumeration + + #. second top-level point + +* The ``html-output`` setting defaults to »MathML«. If there is mathematical + content in `MathML` format, the document type is XHTML 1.1 plus MathML + 2.0. + + The linear mapping :math:`f: \mathbb{C}^{N}\longmapsto\mathbb{C}^{N}` with + + .. math:: + + c_{k}=F(kf_{0})=T_{\text{A}} + \sum_{n=-N/2}^{+N/2}f(x_{n})\text{e}^{-2\pi\text{i}\frac{nk}{N}} + + for all :math:`a\in\mathbb{C}^{N}` is called discrete Fourier + transformation (DFT). + +.. include:: data/errors.txt + +.. footer:: |valid-xhtml11| |valid-CSS2| + +.. |valid-xhtml11| image:: http://www.w3.org/Icons/valid-xhtml11 + :height: 31 + :width: 88 + :alt: Valid XHTML 1.1! + :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 diff --git a/docutils/test/test_writers/test_html_base_misc.py b/docutils/test/test_writers/test_html_base_misc.py new file mode 100644 index 000000000..f7db124bf --- /dev/null +++ b/docutils/test/test_writers/test_html_base_misc.py @@ -0,0 +1,207 @@ +#! /usr/bin/env python +# coding: utf-8 + +# $Id$ +# Authors: Lea Wiemann, Dmitry Shachnev, Günter Milde +# Maintainer: docutils-develop@lists.sourceforge.net +# Copyright: This module has been placed in the public domain. + +""" +Miscellaneous HTML writer tests. +""" + +from __init__ import DocutilsTestSupport +from docutils import core +from docutils._compat import b +import os + +class EncodingTestCase(DocutilsTestSupport.StandardTestCase): + + def test_xmlcharrefreplace(self): + # Test that xmlcharrefreplace is the default output encoding + # error handler. + settings_overrides={ + 'output_encoding': 'latin1', + 'stylesheet': '', + '_disable_config': True,} + result = core.publish_string( + u'EUR = \u20ac', writer_name='html_base', + settings_overrides=settings_overrides) + # Encoding a euro sign with latin1 doesn't work, so the + # xmlcharrefreplace handler is used. + self.assertIn(b('EUR = €'), result) + +class MovingArgsTestCase(DocutilsTestSupport.StandardTestCase): + + settings_overrides={'stylesheet_path': '', + # 'embed_stylesheet': False, + '_disable_config': True, + } + + def test_definition_list_item_classes(self): + # Do not drop class arguments for the definition list item. + # Pass them to to the term node instead. + data = """\ +first term: + fist def + + .. class:: for the second item + +second term: + second def +""" + result = core.publish_string(data, writer_name='html_base', + settings_overrides=self.settings_overrides) + self.assertIn(b('

    second term:
    '), + result) + + def test_definition_list_item_name(self): + # Do not drop the "name" of the definition list item. + # Pass it to to the term node instead. + data = """\ +first term: + first def + + .. _second item: + +second term: + second def +""" + result = core.publish_string(data, writer_name='html_base', + settings_overrides=self.settings_overrides) + self.assertIn(b('
    second term:
    '), + result) + + +class SettingsTestCase(DocutilsTestSupport.StandardTestCase): + data = 'test' + + def test_default_stylesheet(self): + # default style sheet, embedded + mysettings = {'_disable_config': True,} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + self.assertIn('Minimal style sheet ' + 'for the HTML output of Docutils.', styles) + + def test_default_stylesheet_linked(self): + # default style sheet, linked + mysettings = {'_disable_config': True, + 'embed_stylesheet': False} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + self.assertIn('docutils/writers/html_base/minimal.css', styles) + + def test_math_stylesheet_linked(self): + # default + math style sheet, linked + mysettings = {'_disable_config': True, + 'embed_stylesheet': False, + 'stylesheet_path': 'minimal.css, math.css'} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + self.assertIn('docutils/writers/html_base/minimal.css', styles) + self.assertIn('docutils/writers/html_base/math.css', styles) + + def test_custom_stylesheet_linked(self): + # default + custom style sheet, linked + mysettings = {'_disable_config': True, + 'embed_stylesheet': False, + 'stylesheet_path': 'minimal.css, ' + 'data/ham.css'} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + self.assertIn('docutils/writers/html_base/minimal.css', styles) + self.assertIn('href="data/ham.css"', styles) + + def test_custom_stylesheet_dir(self): + mysettings = {'_disable_config': True, + 'embed_stylesheet': False, + 'stylesheet_dirs': ('../docutils/writers/html_base/', + 'data'), + 'stylesheet_path': 'minimal.css, ham.css'} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + if os.path.isdir('../docutils/writers/html_base/'): + self.assertIn('docutils/writers/html_base/minimal.css', styles) + self.assertIn('href="data/ham.css"', styles) + + def test_custom_stylesheet_dir_embedded(self): + mysettings = {'_disable_config': True, + 'embed_stylesheet': True, + 'stylesheet_dirs': ('../docutils/writers/html_base/', + 'data'), + 'stylesheet_path': 'ham.css'} + styles = core.publish_parts(self.data, writer_name='html_base', + settings_overrides=mysettings)['stylesheet'] + self.assertIn('dl.docutils dd {\n margin-bottom: 0.5em }', styles) + +class MathTestCase(DocutilsTestSupport.StandardTestCase): + + """Attention: This class tests the current implementation of maths support + which is open to change in future Docutils releases. """ + + mathjax_script = '