SF.net SVN: docutils:[9923 ] trunk
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9923
http://sourceforge.net/p/docutils/code/9923
Author: milde
Date: 2024-09-10 15:30:31 +0000 (Tue, 10 Sep 2024)
Log Message:
-----------
Documentation update.
Fix/update links, add crosslinks.
Restructure and update content.
Modified Paths:
--------------
trunk/docutils/FAQ.rst
trunk/docutils/docs/howto/html-stylesheets.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/html.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docs/user/links.rst
trunk/docutils/docs/user/rst/quickstart.rst
trunk/docutils/test/functional/expected/standalone_rst_html5.html
trunk/docutils/test/functional/input/data/html5-features.rst
trunk/sandbox/stylesheets/index.txt
Modified: trunk/docutils/FAQ.rst
===================================================================
--- trunk/docutils/FAQ.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/FAQ.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -199,14 +199,10 @@
What's the standard abbreviation for "reStructuredText"?
--------------------------------------------------------
-"RST" and "ReST" (or "reST") are both acceptable. Care should be
-taken with capitalization, to avoid confusion with "REST__", an
-acronym for "Representational State Transfer".
+"RST" (or "rST") and "ReST" (or "reST") are both acceptable.
+Care should be taken with capitalization, to avoid confusion with
+"REST__", an acronym for "Representational State Transfer".
-The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
-they overemphasize reStructuredText's predecessor, Zope's
-StructuredText.
-
__ https://en.wikipedia.org/wiki/Representational_State_Transfer
@@ -213,13 +209,8 @@
What's the standard filename extension for a reStructuredText file?
-------------------------------------------------------------------
-It's ".txt". ReStructuredText source files are meant to be readable as
-plaintext, and most operating systems already associate ".txt" with text
-files.
+The most commonly used extensions are ".rst" and ".txt".
-That said, we see an increasing number of projects settling on
-the extension ".rst".
-
Also see `What's the official MIME type for reStructuredText data?`_
@@ -245,55 +236,25 @@
Here's an ordinary paragraph.
-Counterexample::
+See also `A reStructuredText Primer`__
+and the `reStructuredText Markup Specification`__.
- Here's an ordinary paragraph.
+__ docs/user/rst/quickstart.html#document-title-subtitle
+__ docs/ref/rst/restructuredtext.html#document-title
- This is *not* a Document Title
- ==============================
-
- The "ordinary paragraph" above the section title
- prevents it from becoming the document title.
-
-Another counterexample::
-
- This is not the Document Title, because...
- ===========================================
-
- Here's an ordinary paragraph.
-
- ... the title adornment is not unique
- =====================================
-
- Another ordinary paragraph.
-
-
How can I represent esoteric characters (e.g. character entities) in a document?
--------------------------------------------------------------------------------
For example, say you want an em-dash (XML character entity —,
-Unicode character U+2014) in your document: use a real em-dash.
-Insert literal characters (e.g. type a *real* em-dash) into your
-input file, using whatever encoding suits your application, and tell
-Docutils the input encoding. Docutils uses Unicode internally, so the
-em-dash character is U+2014 internally.
+Unicode character U+2014) in your document.
-Emacs users should refer to the `Emacs Support for reStructuredText`__
-document. Tips for other editors are welcome.
+ReStructuredText has no character entity subsystem. [#]_
+However, Docutils uses Unicode so you use a literal character
+(e.g. a "real" em-dash) for all charactes supported by the
+`input encoding`_ (by default "UTF-8").
-__ tools/editors/emacs/README.html
-
-ReStructuredText has no character entity subsystem; it doesn't know
-anything about XML character entities.
-To Docutils, "—" in input text is
-7 discrete characters; no interpretation happens. When writing HTML,
-the "&" is converted to "&", so in the raw output you'd see
-"&mdash;". There's no difference in interpretation for text
-inside or outside inline literals or literal blocks -- there's no
-character entity interpretation in either case.
-
-If you can't use a Unicode-compatible encoding and must rely on 7-bit
-ASCII, there is a workaround:
+If you are restricted to 7-bit ASCII or a legacy encoding,
+there is a workaround:
`Standard Substitution Definition Sets`_ provide equivalents of
XML & HTML character entity sets as substitution definitions. [#]_
For example, the Japanese yen currency symbol can be used as follows::
@@ -302,9 +263,7 @@
|yen| 600 for a complete meal? That's cheap!
-.. [#] Thanks to David Priest for the original idea.
-
-You can create custom `substitution definitions`_ in your document
+You can also create custom `substitution definitions`_ in your document
using the "unicode_" directive, e.g.::
.. |--| unicode:: U+2013 .. en dash
@@ -322,6 +281,15 @@
thus you need to add spaces ("``foo |---| bar``") and advise the
reStructuredText parser to trim the spaces.
+.. [#] reStructuredText doesn't know anything about XML character
+ entities. To Docutils, "—" in input text is 7 discrete
+ characters; no interpretation happens. When writing HTML, the
+ "&" is converted to "``&``", so in the raw output you'd see
+ "``&mdash;``" and in the HTML browser "—".
+
+.. [#] Thanks to David Priest for the original idea.
+
+.. _input encoding: docs/user/config.html#input-encoding
.. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html
.. _substitution definitions: docs/ref/rst/restructuredtext.html
#substitution-definitions
@@ -382,8 +350,7 @@
-----------------------------------------------------------------------
People have tossed the idea around, and some implementations of
-reStructuredText-generating tools can be found in the `Docutils Link
-List`_.
+reStructuredText-generating tools can be found in the `Docutils Links`_.
There's no reason why reStructuredText should not be round-trippable
to/from XML; any technicalities which prevent round-tripping would be
@@ -399,44 +366,19 @@
tool that does 80% of the work automatically, leaving the other 20%
for manual tweaks.
-.. _Docutils Link List: docs/user/links.html
+.. _Docutils Link List:
+.. _Docutils Links: docs/user/links.html
Are there any Wikis that use reStructuredText syntax?
-----------------------------------------------------
-There are several, with various degrees of completeness. With no
-implied endorsement or recommendation, and in no particular order:
+Yes, see `Wikis`__ in the `Docutils Links`_.
-* `Ian Bicking's experimental code
- <https://docutils.sourceforge.io/sandbox/ianb/wiki/Wiki.py>`__
+__ docs/user/links.html#wikis
-* `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support;
- `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__
-* Zope-based `Zwiki <http://zwiki.org/>`__
-* Zope3-based Zwiki (in the Zope 3 source tree as
- ``zope.products.zwiki``)
-
-* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
-
-* `Trac <http://trac.edgewall.com//>`__ `supports using
- reStructuredText
- <http://trac.edgewall.com//wiki/WikiRestructuredText>`__ as
- an alternative to wiki markup. This includes support for `TracLinks
- <http://trac.edgewall.com//wiki/TracLinks>`__ from within
- RST text via a custom RST reference-directive or, even easier, an
- interpreted text role 'trac'
-
-Please `let us know`_ of any other reStructuredText Wikis.
-
-.. dead link
-.. The example application for the `Web Framework Shootout
-.. <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
-.. reStructuredText.
-
-
Are there any Weblog (Blog) projects that use reStructuredText syntax?
----------------------------------------------------------------------
Modified: trunk/docutils/docs/howto/html-stylesheets.rst
===================================================================
--- trunk/docutils/docs/howto/html-stylesheets.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/howto/html-stylesheets.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -61,7 +61,7 @@
__ https://developer.mozilla.org/en-US/docs/Web/CSS
It is important that you do not edit a copy of ``html4css1.css``
-directly because ``html4css1.css`` is frequently updated with each new
+directly because ``html4css1.css`` may be updated with a new
release of Docutils.
Also make sure that you import ``html4css1.css`` (using "``@import
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/ref/doctree.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -4001,7 +4001,10 @@
_`%measure`
| A number which may be immediately followed by a unit or percent sign.
- Resolves to CDATA_.
+ ReStructuredText supports `CSS2 length units`_.
+ Handling of values without unit depends on the writer/output format
+ (see the writer specific documentation in the `user documentation`__
+ for details). Resolves to CDATA_.
| Used in the `height`_ and `width`_ attributes. Python data type: ``str``.
_`%number`
@@ -4028,7 +4031,9 @@
and `stub`_ attributes.
Python data type: ``int``.
+__ ../index.html#introductory-tutorial-material-for-end-users
+
Names and identifiers
=====================
@@ -5312,6 +5317,7 @@
.. _bibliographic fields: rst/restructuredtext.html#bibliographic-fields
.. _block quote: rst/restructuredtext.html#block-quotes
.. _bullet list: rst/restructuredtext.html#bullet-lists
+.. _CSS2 length units: rst/restructuredtext.html#length-units
.. _citations: rst/restructuredtext.html#citations
.. _definition list: rst/restructuredtext.html#definition-lists
.. _directive: rst/restructuredtext.html#directives
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/ref/rst/directives.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -2203,14 +2203,19 @@
A _`list of integers` may be comma- or whitespace-separated.
-:_`length`: number followed by one of the supported `length units`_
+:_`length`: number, optionally followed by one of the
+ supported `length units`_
+ Handling of values without unit depends on the writer/output format.
+ See the writer specific documentation in the `user doc`__ for details.
+
+ __ ../../index.html#introductory-tutorial-material-for-end-users
+
:_`path`: local filesystem path
Newlines are removed.
The `root_prefix`_ configuration setting can be used to tell Docutils
- to interpret root paths (starting with "/") relative to a "project
- directory".
+ to interpret paths starting with "/" relative to a "project directory".
:_`text`: free text
@@ -2218,8 +2223,8 @@
:_`URI`: _`URI reference`
- Full URI or `relative reference`_ (absolute or relative path reference),
- cf. :RFC:`3986`.
+ Full URI or `relative reference`_
+ (absolute or relative path reference, cf. :RFC:`3986`).
Whitespace is removed (cf. `external hyperlink targets`_ in the
reStructuredText specification).
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -490,18 +490,22 @@
title and possibly other metadata elements (author, date, etc.; see
`Bibliographic Fields`_).
-.. _document title:
+Document Title
+``````````````
-Specifically, there is no way to indicate a document title and subtitle
-explicitly in reStructuredText. [#]_ Instead, a lone top-level `section
-title`_ can be treated as the *document title*. Similarly, a lone
-second-level section title immediately after the document title can
-become the *document subtitle*. The rest of the sections are then lifted
-up a level or two. See the `DocTitle transform`_ for details.
+Specifically, there is no special syntax to indicate a *document title*
+and *subtitle* in reStructuredText. [#]_
+Instead, a uniquely-adorned top-level `section title`_ can be treated as
+the document title. Similarly, a uniquely-adorned second-level section
+title immediately after the document title can become the document
+subtitle. The rest of the sections are then lifted up a level or two.
+See `A ReStructuredText Primer`__ for examples
+and the `DocTitle transform`_ for details.
.. [#] The `"title"`_ directive sets the document's `metadata title`_
that does not become part of the document body.
+__ ../../user/rst/quickstart.html#document-title-subtitle
Sections
--------
@@ -3112,9 +3116,8 @@
https://www.w3.org/TR/css-values-3/#lengths
.. _How to configure the size of a pixel:
../../user/latex.html#size-of-a-pixel
-__ ../../user/
+__ ../../index.html#introductory-tutorial-material-for-end-users
-
Percentage Units
----------------
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/user/config.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -171,9 +171,9 @@
Configuration File Sections & Entries
-------------------------------------
-Below are the Docutils `runtime settings`_, listed by config file section.
-Sections correspond to Docutils components (module name
-or alias; section names are always in lowercase letters).
+Below are the Docutils runtime settings, listed by config file section.
+Sections correspond to Docutils components (module name or alias; always
+in lowercase letters).
.. important:: Any setting may be specified in any section, but only
settings from "`active sections`_" will be used.
@@ -1080,6 +1080,8 @@
[html writers]
--------------
+Common settings for the `Docutils HTML writers`_.
+
.. _attribution [html writers]:
attribution
@@ -2538,6 +2540,8 @@
.. _option lists: ../ref/rst/restructuredtext.html#option-lists
.. _tables: ../ref/rst/restructuredtext.html#tables
+.. _Docutils HTML writers: html.html
+
.. _front end tools: tools.html
.. _buildhtml.py: tools.html#buildhtml-py
Modified: trunk/docutils/docs/user/html.rst
===================================================================
--- trunk/docutils/docs/user/html.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/user/html.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -6,6 +6,12 @@
.. contents::
+This document describes the HTML writers provided by Docutils.
+
+The default `length unit`_ in HTML is "px" (pixels, 1 px = 1/96 in).
+
+.. _length unit: ../ref/rst/restructuredtext.html#length-units
+
html
----
@@ -26,19 +32,58 @@
post-processing that may break otherwise.
+html5
+-----
+
+:aliases: _`html5_polyglot`
+:front-end: rst2html5_
+:config: `[html5 writer]`_
+
+The *html5* writer generates valid XML that conforms to the
+`HTML standard`_ (`polyglot HTML`_). [#safetext]_
+New features and elements are used if they are widely supported.
+See the `HTML5 test page`_ (and the sources `html5-features.rst`_ and
+`html5-text-level-tags.rst`_) for differences to the html4css1_ writer.
+
+There is no hard-coded formatting information in the HTML document.
+Correct rendering of elements not directly supported by HTML depends on a
+CSS_ style sheet. The provided style sheet minimal.css_ defines required
+styling rules; plain.css_ and responsive.css_ add optional rules for
+better legibility. Adaption of the layout is possible with `custom style
+sheets`_. [#safetext]_
+
+.. [#safetext] The validity of raw HTML and custom stylesheets must be
+ ensured by the author.
+
+.. _HTML5 test page: https://docutils.sourceforge.io/test/functional/
+ expected/standalone_rst_html5.html#differences-to-the-html4css1-writer
+.. _html5-features.rst: https://docutils.sourceforge.io/test/functional/
+ input/data/html5-features.rst
+.. _html5-text-level-tags.rst: https://docutils.sourceforge.io/test/functional/
+ input/data/html5-text-level-tags.rst
+.. _rst2html5: tools.html#rst2html5
+.. _[html5 writer]: config.html#html5-writer
+.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
+.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
+.. _responsive.css: ../../docutils/writers/html5_polyglot/responsive.css
+.. _custom style sheets: ../howto/html-stylesheets.html
+.. _viewable with any browser: http://www.anybrowser.org/campaign
+.. _Benefits of polyglot XHTML5: http://xmlplease.com/xhtml/xhtml5polyglot/
+
+
html4css1
---------
-:aliases: html4, html_
-:front-ends: rst2html4_, rst2html_
-:config: `[html4css1 writer]`_
+:aliases: html4, html_
+:front-end: rst2html4_
+:config: `[html4css1 writer]`_
The HTML Writer module, ``docutils/writers/html4css1.py``, was the first
Docutils writer and up to release 0.13 the only official HTML writer.
-The output conforms to the `XHTML 1 Transitional`_ specification. It does
-not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags
-required in XML but not allowed in HTML 4. However, the output follows the
+The output conforms to the `XHTML 1 Transitional`_ specification. It does
+not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags
+required in XML but not allowed in HTML 4. However, the output follows the
`HTML Compatibility Guidelines`_ for proper rendering on most HTML user
agents.
@@ -45,12 +90,17 @@
Correct rendering depends on a CSS_ style sheet. A reference style sheet,
`html4css1.css`_, is provided and used by default.
-To support the `Internet Explorer` (with a market share of about 90% around
-2002, the time this writer was written), documents contain some hard-coded
-formatting hints and are tagged as "text/html" (instead of
-"application/xhtml+xml"). [#IE]_
+To support the `Internet Explorer` (with a market share of about 90%
+around 2002, the time this writer was written), documents contain some
+hard-coded formatting hints and are tagged as "text/html" (instead of
+"application/xhtml+xml"). Additional class values serve as surrogate for
+the "first"/"last" pseudo-classes introduced in CSS 2.1. [#IE]_
-.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
+Tables are used for description lists, field lists, docinfo, footnotes,
+and option lists. Videos and SVG images are wrapped in <object> elements
+and cannot be embedded.
+
+.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
for XHTML in IE 9 (2011).
.. _rst2html: tools.html#rst2html
@@ -62,7 +112,7 @@
~~~~~~~~
:front-end: ``docutils --reader=pep --writer=pep_html``
-:config: `[pep_html writer]`_
+:config: `[pep_html writer]`_, `[html4css1 writer]`_
This is a special writer for the generation of `Python Enhancement
Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
@@ -78,7 +128,7 @@
:alias: s5
:front-end: rst2s5_
-:config: `[s5_html writer]`_
+:config: `[s5_html writer]`_, `[html4css1 writer]`_
The `s5` writer inherits from html4css1_. It produces XHTML for use with
S5_, the “Simple Standards-based Slide Show System” by Eric Meyer. See
@@ -91,69 +141,12 @@
.. _theme: tools.html#themes
-html5
------
+3rd-party HTML writers
+----------------------
-:aliases: _`html5_polyglot`
-:front-end: rst2html5_
-:config: `[html5 writer]`_
+For additional HTML writers, see the `Docutils link list`__
+and the sandbox_.
-The ``html5`` writer generates `polyglot HTML`_ output, valid
-XML [#safetext]_ that is compatible with `HTML5`_. New features and elements
-are used if they are widely supported.
-See the `HTML5 test page`_ (and the sources `html5-features.rst`_ and
-`html5-text-level-tags.rst`_) for further differences to the html4css1_
-writer.
-
-There is no hard-coded formatting information in the HTML document.
-Correct rendering of elements not directly supported by HTML depends on a
-CSS_ style sheet. The provided style sheet minimal.css_ defines required
-styling rules; plain.css_ and responsive.css_ add optional rules for
-better legibility. Adaption of the layout is possible with `custom style
-sheets`_. [#safetext]_
-
-New in Docutils 0.13
-
-.. [#safetext] The validity of raw HTML and custom stylesheets must be
- ensured by the author.
-.. _HTML5 test page: https://docutils.sourceforge.io/test/functional/
- expected/standalone_rst_html5.html#changes-to-the-html4css1-writer
-.. _html5-features.rst: https://docutils.sourceforge.io/test/functional/
- input/data/html5-features.rst
-.. _html5-text-level-tags.rst: https://docutils.sourceforge.io/test/functional/
- input/data/html5-text-level-tags.rst
-.. _rst2html5: tools.html#rst2html5
-.. _[html5 writer]: config.html#html5-writer
-.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
-.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
-.. _responsive.css: ../../docutils/writers/html5_polyglot/responsive.css
-.. _custom style sheets: ../howto/html-stylesheets.html
-.. _viewable with any browser: http://www.anybrowser.org/campaign
-.. _Benefits of polyglot XHTML5: http://xmlplease.com/xhtml/xhtml5polyglot/
-
-
-Overview
---------
-
-================ =========== ============== ================= ===========
-name aliases `front-end`_ HTML version CSS version
-================ =========== ============== ================= ===========
-html4css1_ html4, rst2html4, `XHTML 1 `CSS 1`_
- html_ rst2html Transitional`_
-
-pep_html_ .. rstpep2html `XHTML 1 `CSS 1`_
- Transitional`_
-
-s5_html_ s5 rst2s5 `XHTML 1 `CSS 1`_
- Transitional`_
-
-html5_polyglot_ html5 rst2html5 `HTML5`_ `CSS 3`_
-
-================ =========== ============== ================= ===========
-
-For additional alternatives, see the `Docutils link list`__ and the
-sandbox_.
-
__ https://docutils.sourceforge.io/docs/user/links.html
#website-generators-and-html-variants
.. _sandbox: ../dev/policies.html#the-sandbox
@@ -162,16 +155,10 @@
References
----------
-_`HTML5`
- `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
- W3C Recommendation, 28 October 2014.
- https://www.w3.org/TR/2014/REC-html5-20141028/
+_`HTML Standard`
+ `HTML Living Standard`.
+ https://html.spec.whatwg.org/multipage/
-_`XHTML 1.1`
- `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
- W3C Recommendation, 23 November 2010.
- https://www.w3.org/TR/xhtml11/
-
_`XHTML 1 Transitional`
`Transitional version`_ of:
`XHTML™ 1.0 The Extensible HyperText Markup Language (Second
@@ -179,15 +166,7 @@
W3C Recommendation, 26 January 2000, revised 1 August 2002.
https://www.w3.org/TR/xhtml1/
-_`XHTML Basic`
- `XHTML™ Basic 1.1 - Second Edition`,
- W3C Recommendation, 23 November 2010.
- https://www.w3.org/TR/xhtml-basic/
-
-.. _transitional version:
- https://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
-
-_`HTML 4.01 Transitional`
+_`HTML 4.01 Transitional`
Transitional version of:
`HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
https://www.w3.org/TR/html4/
@@ -194,33 +173,37 @@
.. _`CSS 1`:
-_`CSS Level 1`:
+_`CSS Level 1`:
The features defined in the `CSS1 specification`_, but using the syntax
and definitions in the `CSS 2.1`_ specification.
-_`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
+_`CSS 2.1`
+ `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
W3C Recommendation 07 June 2011.
https://www.w3.org/TR/CSS21/
-_`CSS 3`:
- CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
+_`CSS 3`:
+ CSS Level 3 builds on CSS Level 2 module by module, using the CSS 2.1
specification as its core.
- Specifications: https://www.w3.org/Style/CSS/specs.en.html
+ | Specifications: https://www.w3.org/Style/CSS/specs.en.html
+ | Validator: http://jigsaw.w3.org/css-validator/
- Validator: http://jigsaw.w3.org/css-validator/
-
.. other references
----------------
.. _HTML Compatibility Guidelines: https://www.w3.org/TR/xhtml1/#guidelines
-.. _CSS: https://www.w3.org/TR/CSS/
-.. _CSS1 specification: https://www.w3.org/TR/2008/REC-CSS1-20080411/
+.. _transitional version:
+ https://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
+
.. _polyglot HTML: https://www.w3.org/TR/html-polyglot/
.. Beware. This specification is no longer in active maintenance and the
HTML Working Group does not intend to maintain it further.
+.. _CSS: https://www.w3.org/TR/CSS/
+.. _CSS1 specification: https://www.w3.org/TR/2008/REC-CSS1-20080411/
+
.. Appendix
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/user/latex.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -100,6 +100,9 @@
:sp: scaled point (1sp = 1/65536pt)
:bp: "big" point (`DTP point`) (1 bp = 1/72 in)
+The **default length unit** (added by the latex writer to length
+values without unit) is the `DTP point` "bp".
+
.. attention:: Different definitions of the unit "pt"!
* In Docutils (as well as CSS) the unit symbol "pt" denotes the
@@ -118,9 +121,6 @@
In `raw LaTeX`_ and `custom style sheets`_, the `DTP point` must be
specified as "bp", while "pt" is interpreted as `LaTeX point`.
-The default length unit (added by Docutils to length specifications
-without unit) is the "DTP point".
-
.. _length units: ../ref/rst/restructuredtext.html#length-units
Modified: trunk/docutils/docs/user/links.rst
===================================================================
--- trunk/docutils/docs/user/links.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/user/links.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -14,16 +14,17 @@
.. contents::
-This document contains links users of Docutils and reStructuredText
-may find useful. Many of the projects
-listed here are hosted in the `Docutils Sandbox`_. If you have
-something to publish, you can get write access, too!
+This document contains links that users of Docutils_ and reStructuredText_
+may find useful.
The most current version of this link list can always be found at
https://docutils.sourceforge.io/docs/user/links.html.
+If you find outdated or broken links or want to suggest additions,
+please `let us know`__ and we'll update the list here.
.. _Docutils: https://docutils.sourceforge.io/
-.. _Docutils Sandbox: https://docutils.sourceforge.io/sandbox/README.html
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+__ mailing-lists.html#docutils-users
Editors
@@ -45,7 +46,7 @@
plugin for Vim that emulates two-pane outliner with
support for reStructuredText (since version 4.0b2).
- - `Riv: Take notes in rst <https://github.com/Rykka/riv.vim>`__ Vim
+ - `Riv: Take notes in rST <https://github.com/Rykka/riv.vim>`__ Vim
plugin to take notes in reStructured text.
* `reStructuredText Language Support for Visual Studio Code`__
@@ -279,7 +280,7 @@
.. _DashTable: https://github.com/gustavklopp/DashTable
-* Sphinx_ includes a `LaTeX to Rst converter
+* Sphinx_ includes a `LaTeX to rST converter
<https://svn.python.org/projects/doctools/converter/>`__ in its source code
(trimmed to importing the old Python docs).
@@ -326,14 +327,14 @@
.. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
+.. _Docutils Sandbox: https://docutils.sourceforge.io/sandbox/README.html
+
Related Applications
--------------------
Applications using docutils/reStructuredText and helper applications.
-* For Wikis, please see the `FAQ entry about Wikis`_.
-
* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
* `Project Gutenberg`_ uses Docutils for its "ebookmaker_"
@@ -362,6 +363,31 @@
.. _repository: ../dev/repository.html
+Wikis
+`````
+
+* Trac_ supports `using reStructuredText`__ as an alternative to wiki markup.
+ This includes support for TracLinks_ from within reStructuredText
+ via a custom rST reference-directive or, even easier, an interpreted
+ text role "trac".
+
+ __ http://trac.edgewall.com//wiki/WikiRestructuredText
+
+* MoinMoin_ includes a `ReStructuredText Parser
+ <http://moinmo.in/HelpOnParsers/ReStructuredText>`__.
+
+* Ian Bicking's experimental `wiki module`__ in the sandbox.
+
+ __ https://docutils.sourceforge.io/sandbox/ianb/wiki
+
+* Zope-based Zwiki_
+ (requires Zope2, which reached end of life on December 31, 2020).
+
+.. _TracLinks: http://trac.edgewall.com//wiki/TracLinks
+.. _MoinMoin: http://moinmo.in/
+.. _ZWiki: https://github.com/simonmichael/ZWiki
+
+
Tools
`````
@@ -370,7 +396,7 @@
.. _rstcheck: https://pypi.python.org/pypi/rstcheck
-* restview_ is a viewer for ReStructuredText documents.
+* restview_ is a viewer for reStructuredText documents.
Pass the name of a ReStructuredText document to restview, and it will
launch a web server on localhost:random-port and open a web browser. It
@@ -402,7 +428,7 @@
.. _Sphinx extensions: https://www.sphinx-doc.org/en/master/usage/extensions/
.. _Python documentation: https://docs.python.org/
-.. _Trac: https://trac.edgewall.org/
+.. _Trac: https://trac.edgewall.org
.. _PyLit: https://codeberg.org/milde/pylit
Modified: trunk/docutils/docs/user/rst/quickstart.rst
===================================================================
--- trunk/docutils/docs/user/rst/quickstart.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/docs/user/rst/quickstart.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -329,10 +329,10 @@
may be formatted somewhat differently (e.g. the HTML writer by default
shows it as a centered heading).
-To indicate the document title in reStructuredText, use a unique adornment
-style at the beginning of the document. To indicate the document subtitle,
-use another unique adornment style immediately after the document title. For
-example::
+To indicate the document title in reStructuredText, use a section title
+with unique adornment style at the beginning of the document.
+To indicate the document subtitle, use another unique adornment style
+immediately after the document title. For example::
================
Document Title
@@ -351,7 +351,29 @@
overline-and-underlined titles (but not underlined-only) may be inset
for aesthetics.
+Counterexample::
+ Here's an ordinary paragraph.
+
+ This is *not* a Document Title
+ ==============================
+
+ The "ordinary paragraph" above the section title
+ prevents it from becoming the document title.
+
+Another counterexample::
+
+ This is not the Document Title, because...
+ ===========================================
+
+ Here's an ordinary paragraph.
+
+ ... the title adornment is not unique
+ =====================================
+
+ Another ordinary paragraph.
+
+
Images
------
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2024-09-10 15:30:31 UTC (rev 9923)
@@ -1283,7 +1283,7 @@
</li>
<li><p>Set table column widths with <style="width: ...">, not "width" argument.</p></li>
<li><p>Horizontal alignment of table heads with CSS.</p></li>
-<li><p>Do not drop paragraph objects, use CSS rules to prevent unwanted vertical
+<li><p>Do not drop paragraph elements, use CSS rules to prevent unwanted vertical
space.</p></li>
<li><p>Put subtitles in <p> elements.</p></li>
<li><p>Use the new semantic tags <main>, <section>, <header>,
Modified: trunk/docutils/test/functional/input/data/html5-features.rst
===================================================================
--- trunk/docutils/test/functional/input/data/html5-features.rst 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/docutils/test/functional/input/data/html5-features.rst 2024-09-10 15:30:31 UTC (rev 9923)
@@ -14,7 +14,7 @@
* Horizontal alignment of table heads with CSS.
-* Do not drop paragraph objects, use CSS rules to prevent unwanted vertical
+* Do not drop paragraph elements, use CSS rules to prevent unwanted vertical
space.
* Put subtitles in <p> elements.
Modified: trunk/sandbox/stylesheets/index.txt
===================================================================
--- trunk/sandbox/stylesheets/index.txt 2024-09-10 08:01:52 UTC (rev 9922)
+++ trunk/sandbox/stylesheets/index.txt 2024-09-10 15:30:31 UTC (rev 9923)
@@ -3,7 +3,7 @@
=======================
:Author: Lea Wiemann and others
-:Contact: [email protected]
+:Contact: [email protected]
:Revision: $Revision$
:Date: $Date$
:Copyright: This document has been placed in the public domain.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins