Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8644] trunk/docutils
|
From: <mi...@us...> - 2021-03-26 13:51:39
|
Revision: 8644
http://sourceforge.net/p/docutils/code/8644
Author: milde
Date: 2021-03-26 13:51:36 +0000 (Fri, 26 Mar 2021)
Log Message:
-----------
Documentation update.
Fix or remove broken links.
Adapt to changes in recent versions.
Adapt to state of the art in HTML and web browsers.
Modified Paths:
--------------
trunk/docutils/BUGS.txt
trunk/docutils/FAQ.txt
trunk/docutils/README.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/dev/policies.txt
trunk/docutils/docs/howto/html-stylesheets.txt
trunk/docutils/docs/howto/security.txt
trunk/docutils/docs/index.txt
trunk/docutils/docs/peps/pep-0256.txt
trunk/docutils/docs/peps/pep-0258.txt
trunk/docutils/docs/ref/rst/restructuredtext.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/links.txt
trunk/docutils/docs/user/tools.txt
trunk/docutils/docutils/writers/_html_base.py
Modified: trunk/docutils/BUGS.txt
===================================================================
--- trunk/docutils/BUGS.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/BUGS.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -208,8 +208,8 @@
over implicit targets. But if an explicit target comes after an
implicit target with the same name, the ID of the first (implicit)
target remains based on the implicit name. Since HTML fragment
- identifiers based on the IDs, the first target keeps the name. For
- example::
+ identifiers are based on the IDs, the first target keeps the name.
+ For example::
.. contents::
Modified: trunk/docutils/FAQ.txt
===================================================================
--- trunk/docutils/FAQ.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/FAQ.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -11,7 +11,7 @@
:Date: $Date$
:Revision: $Revision$
-:Web site: http://docutils.sourceforge.net/
+:Web site: https://docutils.sourceforge.io/
:Copyright: This document has been placed in the public domain.
.. contents::
@@ -26,7 +26,7 @@
to the `Docutils-users`_ mailing list. Project members should feel
free to edit the source text file directly.
-.. _master copy: http://docutils.sourceforge.net/FAQ.html
+.. _master copy: https://docutils.sourceforge.io/FAQ.html
.. _let us know:
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
@@ -40,10 +40,10 @@
Docutils_ is a system for processing plaintext documentation into
useful formats, such as HTML, XML, and LaTeX. It supports multiple
-types of input, such as standalone files (implemented), inline
-documentation from Python modules and packages (under development),
-`PEPs (Python Enhancement Proposals)`_ (implemented), and others as
-discovered.
+types of input, such as standalone files, `PEPs (Python Enhancement
+Proposals)`_, and string input. Client code may add other input types,
+e.g. Sphinx_ comes with an extension to extract inline documentation
+from Python modules and packages.
The Docutils distribution consists of:
@@ -52,7 +52,7 @@
* several `front-end tools`_ (such as ``rst2html.py``, which converts
reStructuredText input into HTML output);
* a `test suite`_; and
-* extensive documentation_.
+* documentation_.
For an overview of the Docutils project implementation, see `PEP
258`_, "Docutils Design Specification".
@@ -59,7 +59,7 @@
Docutils is implemented in Python_.
-.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils: https://docutils.sourceforge.io/
.. _PEPs (Python Enhancement Proposals):
http://www.python.org/peps/pep-0012.html
.. _can be used by client code: docs/api/publisher.html
@@ -108,35 +108,37 @@
Is there a GUI authoring environment for Docutils?
--------------------------------------------------
-DocFactory_ is under development. It uses wxPython and looks very
-promising.
+DocFactory_ is under development. See also the links to editors_
+supporting reStructuredText.
.. _DocFactory:
http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
+.. _editors: docs/user/links.html#editors
What is the status of the Docutils project?
-------------------------------------------
-Although useful and relatively stable, Docutils is experimental code,
-with APIs and architecture subject to change.
+Docutils is mainly stable, with documented APIs and architecture
+subject to change after announcement and a transition period.
-Our highest priority is to fix bugs as they are reported. So the
-latest code from the repository_ (or the snapshots_) is almost always
-the most stable (bug-free) as well as the most featureful.
+We fix bugs as they are reported. So the latest code from the
+repository_ (or the snapshots_) are almost always the most stable
+as well as the most featureful.
What is the Docutils project release policy?
--------------------------------------------
-It's "release early & often". We also have automatically-generated
+Besides the regular releases_, we provide automatically-generated
snapshots_ which always contain the latest code from the repository_.
As the project matures, we may formalize on a
stable/development-branch scheme, but we're not using anything like
that yet.
+.. _releases: https://pypi.org/project/docutils/#history
+.. _snapshots: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
.. _repository: docs/dev/repository.html
-.. _snapshots: http://docutils.sourceforge.net/#download
reStructuredText
@@ -163,10 +165,10 @@
.. _Quick reStructuredText: docs/user/rst/quickref.html
.. _reStructuredText Markup Specification:
docs/ref/rst/restructuredtext.html
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _StructuredText:
http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
-.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
+.. _Setext: https://docutils.sourceforge.io/mirror/setext.html
Why is it called "reStructuredText"?
@@ -211,11 +213,9 @@
Are there any reStructuredText editor extensions?
-------------------------------------------------
-See `Editor Support for reStructuredText`__.
+See the list of editors_ supporting reStructuredText.
-__ tools/editors/README.html
-
How can I indicate the document title? Subtitle?
-------------------------------------------------
@@ -288,10 +288,7 @@
|yen| 600 for a complete meal? That's cheap!
-For earlier versions of Docutils, equivalent files containing
-character entity set substitution definitions using the "unicode_"
-directive `are available`_. Please read the `description and
-instructions`_ for use. Thanks to David Priest for the original idea.
+Thanks to David Priest for the original idea.
If you insist on using XML-style charents, you'll have to implement a
pre-processing system to convert to UTF-8 or something. That
@@ -312,8 +309,8 @@
:trim:
Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---|
-bar``", rendered as "foo |--| bar; foo |---| bar". (Note that Mozilla
-and Firefox may render this incorrectly.) The ``:trim:`` option for
+bar``", rendered as "foo |--| bar; foo |---| bar".
+The ``:trim:`` option for
the em dash is necessary because you cannot write "``foo|---|bar``";
thus you need to add spaces ("``foo |---| bar``") and advise the
reStructuredText parser to trim the spaces.
@@ -320,10 +317,10 @@
.. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html
.. _unicode: docs/ref/rst/directives.html#unicode-character-codes
-.. _are available: http://docutils.sourceforge.net/tmp/charents/
-.. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz
+.. _are available: https://docutils.sourceforge.io/tmp/charents/
+.. _tarball: https://docutils.sourceforge.io/tmp/charents.tgz
.. _description and instructions:
- http://docutils.sourceforge.net/tmp/charents/README.html
+ https://docutils.sourceforge.io/tmp/charents/README.html
.. _to-do list: docs/dev/todo.html
@@ -763,10 +760,10 @@
or geresh_) will suffice.
Moreover, it's possible to translate_ all reStructuredText keywords.
-This was not yet done for any RTL language, but when it is, it will be
-possible to write an RTL document with vitually no English. This will
-allow reasonable use of editors limited to a single base direction for
-the whole document (like Notepad, Vim and text boxes in Firefox).
+Docutils 0.17 includes translations for Arab, Hebrew, and
+Persian/Farsi. This should allow reasonable use of editors limited to
+a single base direction for the whole document (like Notepad, Vim and
+text boxes in Firefox).
.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/
.. _geresh: http://www.typo.co.il/~mooffie/geresh/
@@ -778,7 +775,7 @@
* Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and
http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py.
Put them both in the same directory and make them executable.
-
+
* Use ``rst2html_hibidi.py`` instead of ``rst2html.py``.
* It infers dir attributes in the HTML from the text. It does it
@@ -817,7 +814,7 @@
* Select this new stylesheet with ``--stylesheet=<file>`` or the
stylesheet_ setting.
-
+
* Now if you need to override the direction of some element (from a
paragraph to a whole section), write::
@@ -855,16 +852,16 @@
--------------------------------------------------------
While there is no registered MIME type for reStructuredText, the
-"official unofficial" standard MIME type is "text/x-rst". This was
+"official unofficial" standard MIME type is "text/x-rst". [#]_ This was
invented for the build system for PEPs (Python Enhancement Proposals),
and it's used by the python.org web site build system.
-(The "x-" prefix means it's an unregistered MIME type.)
-
Also see `What's the standard filename extension for a
reStructuredText file?`_
+.. [#] The "x-" prefix means it's an unregistered MIME type.
+
HTML Writer
===========
@@ -871,28 +868,16 @@
What is the status of the HTML Writer?
--------------------------------------
-The HTML Writer module, ``docutils/writers/html4css1.py``, is a
-proof-of-concept reference implementation. While it is a complete
-implementation, some aspects of the HTML it produces may be incompatible
-with older browsers or specialized applications (such as web templating).
-The sandbox has some alternative HTML writers, contributions are welcome.
+The default HTML Writer module, ``docutils/writers/html4css1.py``, is
+a proof-of-concept reference implementation. While it is a complete
+implementation, some aspects of the HTML it produces may be outdated or
+incompatible with older browsers or specialized applications (such as
+web templating).
+For the full selection see `Docutils HTML writers`_
-What kind of HTML does it produce?
-----------------------------------
+.. _Docutils HTML writers: docs/user/html.html
-It produces XHTML compatible with the `XHTML 1.0`_ specification. A
-cascading stylesheet is required for proper viewing with a modern
-graphical browser. Correct rendering of the HTML produced depends on
-the CSS support of the browser. A general-purpose stylesheet,
-``html4css1.css`` is provided with the code, and is embedded by
-default. It is installed in the "writers/html4css1/" subdirectory
-within the Docutils package. Use the ``--help`` command-line option
-to see the specific location on your machine.
-
-.. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
-
-
What browsers are supported?
----------------------------
@@ -899,9 +884,9 @@
No specific browser is targeted; all modern graphical browsers should
work. Some older browsers, text-only browsers, and browsers without
full CSS support are known to produce inferior results. Firefox,
-Safari, Mozilla (version 1.0 and up), Opera, and MS Internet Explorer
-(version 5.0 and up) are known to give good results. Reports of
-experiences with other browsers are welcome.
+Safari, Opera, Chrome, Edge, and MS Internet Explorer (version 5.0 and up)
+are known to give good results. Reports of experiences with other
+browsers are welcome.
Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why?
@@ -967,12 +952,12 @@
effectively reserve these tags to provide 6 levels of heading beyond the
single document title.
-HTML is being used for dumb formatting for nothing but final display.
-A stylesheet *is required*, and one is provided; see `What kind of
-HTML does it produce?`_ above. Of course, you're welcome to roll your
-own. The default stylesheet provides rules to format ``<h1
-class="title">`` and ``<h2 class="subtitle">`` differently from
-ordinary ``<h1>`` and ``<h2>``::
+With "html4css1", HTML is being used for dumb formatting for nothing
+but final display. A stylesheet *is required*, and one is provided;
+see `Docutils HTML writers`_. Of course, you're
+welcome to roll your own. The default stylesheet provides rules to
+format ``<h1 class="title">`` and ``<h2 class="subtitle">``
+differently from ordinary ``<h1>`` and ``<h2>``::
h1.title {
text-align: center }
@@ -1001,6 +986,7 @@
__ https://www.w3.org/TR/html53/sections.html#headings-and-sections
+
How are lists formatted in HTML?
--------------------------------
@@ -1061,8 +1047,8 @@
markers) is completely governed by the stylesheet, so either the
browser can't find the stylesheet (try enabling the
`embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the
-browser can't understand it (try a recent Firefox, Mozilla, Konqueror,
-Opera, Safari, or even MSIE).
+browser can't understand it (try a not too old Firefox, Chrome, Opera,
+Safari, Edge, or even MSIE).
.. _embed_stylesheet: docs/user/config.html#embed-stylesheet
@@ -1151,26 +1137,18 @@
Shouldn't this be "application/xhtml+xml" instead of "text/html"?
-In a perfect web, the Docutils XHTML output would be 100% strict
-XHTML. But it's not a perfect web, and a major source of imperfection
-is Internet Explorer. Despite it's drawbacks, IE still represents the
-majority of web browsers, and cannot be ignored.
-
Short answer: if we didn't serve XHTML as "text/html" (which is a
perfectly valid thing to do), it couldn't be viewed in Internet
Explorer.
-Long answer: see the `"Criticisms of Internet Explorer" Wikipedia
-entry <http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML>`__.
+Long answer: In a perfect web, the Docutils XHTML output would be 100%
+strict XHTML. But it's not a perfect web, and a major source of
+imperfection is Internet Explorer. When the "html4css1"
+writer was created, IE represented the overwhelming majority of web
+browsers "in the wild".
+The behaviour is kept for backwards compatibility while
+modern, semantic HTML output is available with the "html5" writer.
-However, there's also `Sending XHTML as text/html Considered
-Harmful`__. What to do, what to do? We're damned no matter what we
-do. So we'll continue to do the practical instead of the pure:
-support the browsers that are actually out there, and not fight for
-strict standards compliance.
-
-__ http://hixie.ch/advocacy/xhtml
-
(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan
G. Isaac.)
@@ -1234,11 +1212,11 @@
.. Here's a code css to make a table colourful::
/* Table: */
-
+
th {
background-color: #ede;
}
-
+
/* alternating colors in table rows */
table.docutils tr:nth-child(even) {
background-color: #F3F3FF;
@@ -1246,9 +1224,9 @@
table.docutils tr:nth-child(odd) {
background-color: #FFFFEE;
}
-
+
table.docutils tr {
border-style: solid none solid none;
border-width: 1px 0 1px 0;
border-color: #AAAAAA;
- }
+ }
Modified: trunk/docutils/README.txt
===================================================================
--- trunk/docutils/README.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/README.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -44,8 +44,8 @@
The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
-XML, and LaTeX. Support for the following sources has been
-implemented:
+LaTeX, troff (man pages), OpenOffice, and native XML. Support for the
+following sources has been implemented:
* Standalone files.
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/RELEASE-NOTES.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -28,19 +28,19 @@
* `html5` writer:
Semantic tags:
Use <aside> instad of <dl> for footnote text and citations,
- <aside> for topics (except abstract), admonitions, and system messages,
+ <aside> for topics (except abstract), admonitions, and system messages,
and <nav> for the Table of Contents.
-
+
Write footnote brackets and field term colons to HTML, so that
- they are present also without CSS and when copying text.
- Hide with CSS if required.
+ they are present also without CSS and when copying text.
+ Hide with CSS if required.
Use <summary> and <details> tags for term and definition of a
definition list with class value "details".
-
+
Move attribution behind the blockquote to comply with
https://html.spec.whatwg.org/#the-blockquote-element.
-
+
* `s5_html` writer:
Remove the IE PNG Fix by Angus Turnbull. IE has native PNG
support since version 7.
@@ -75,7 +75,8 @@
* The default value for auto_id_prefix_ will change to "%". This means
auto-generated IDs will use the tag name as prefix. Set auto_id_prefix_ to
- "id" if you want unchanged auto-IDs or to "%" if you want descriptive IDs.
+ "id" if you want unchanged auto-IDs or to "%" if you want the new
+ feature already in 0.17.
* The default HTML writer "html" with frontend ``rst2html.py`` may change
from "html4css1" to "html5".
@@ -83,9 +84,9 @@
Use ``get_writer_by_name('html')`` or the rst2html.py_ front end, if you
want the output to be up-to-date automatically.
- Use a specific writer name or front end, if you depend on stability of the
- generated HTML code, e.g. because you use a custom style sheet or
- post-processing that may break otherwise.
+ Use the "html4" writer or ``rst2html4.py``, if you depend on
+ stability of the generated HTML code, e.g. because you use a custom
+ style sheet or post-processing that may break otherwise.
.. _id_prefix: docs/user/config.html#id-prefix
.. _auto_id_prefix: docs/user/config.html#auto-id-prefix
@@ -100,9 +101,9 @@
* Installing with ``setup.py`` now requires setuptools_.
Alternatively, install with pip_.
-* The generic command line front end ``docutils-cli.py`` allows the
- free selection of reader, parser, and writer components.
-
+* The generic command line front end tool docutils_cli.py_ allows
+ the free selection of reader, parser, and writer components.
+
* New, experimental wrapper to integrate the
`recommonmark`__ Markdown parser for use with Docutils.
@@ -128,7 +129,6 @@
- New optional style ``responsive.css``, adapts to different screen
sizes.
-
.. _initial_header_level: docs/user/config.html#initial-header-level
__ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
@@ -152,6 +152,7 @@
.. _setuptools: https://pypi.org/project/setuptools/
.. _pip: https://pypi.org/project/pip/
+.. _docutils_cli.py: docs/user/tools.html#docutils-cli-py
.. _legacy_class_functions: docs/user/config.html#legacy-class-functions
.. _graphicx_option: docs/user/config.html#graphicx-option
.. _docutils.sty: https://ctan.org/pkg/docutils
Modified: trunk/docutils/docs/dev/policies.txt
===================================================================
--- trunk/docutils/docs/dev/policies.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/dev/policies.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -93,7 +93,7 @@
* Look at the Docutils sources to see how similar features are implemented,
learn to do it "the Docutils way".
-* Prepare the a patch or an addition to the existing documentation.
+* Prepare a patch or an addition to the existing documentation.
Include links.
* If you are familiar with version control, consider creating a `feature
@@ -634,13 +634,10 @@
For the bash shell, add this to your ``~/.profile``::
PYTHONPATH=$HOME/projects/docutils/docutils
- PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils
export PYTHONPATH
The first line points to the directory containing the ``docutils``
- package. The second line adds the directory containing the
- third-party modules Docutils depends on. The third line exports
- this environment variable.
+ package. The second line exports this environment variable.
You many also want to add the ``tools`` directory to your binary ``PATH``::
@@ -656,9 +653,9 @@
/usr/local/lib/python2.7/site-packages/
Alternatively, use a `path configuration file`__.
-
+
__ https://docs.python.org/library/site.html
-
+
You may also want to copy or link the front-end tools in
``docutils/tools`` to a suitable place in your binary PATH, e.g., ::
Modified: trunk/docutils/docs/howto/html-stylesheets.txt
===================================================================
--- trunk/docutils/docs/howto/html-stylesheets.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/howto/html-stylesheets.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -51,12 +51,12 @@
h1, h2, h3, h4, h5, h6, p.topic-title {
font-family: sans-serif }
-For help on the CSS syntax, please see `the WDG's guide to Cascading
-Style Sheets`__ and, in particular, their `list of CSS properties`__.
-Another good reference site is http://selfhtml.org (German and French).
+For help on the CSS syntax, see, e.g., the `W3C Specification`_, the
+`WDG's guide to Cascading Style Sheets`__, or the `MDN Web Docs`__.
+.. _W3C Specification: https://www.w3.org/Style/CSS/#specs
__ http://www.htmlhelp.com/reference/css/
-__ http://www.htmlhelp.com/reference/css/all-properties.html
+__ 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
Modified: trunk/docutils/docs/howto/security.txt
===================================================================
--- trunk/docutils/docs/howto/security.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/howto/security.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -159,12 +159,15 @@
`"Configuration Files"`_ section of `Docutils Configuration`_.
To fully secure a recent Docutils installation, the configuration file
-should contain the following lines::
+should contain the following lines ::
[general]
file-insertion-enabled: off
raw-enabled: no
+and untrusted users must be prevented to modify or create local
+configuration files that overwrite these settings.
+
.. _Docutils front-end tools: ../user/tools.html
.. _"Configuration Files": ../user/config.html#configuration-files
.. _Docutils Configuration: ../user/config.html
@@ -173,13 +176,13 @@
Version Applicability
=====================
-The ``file_insertion_enabled`` & ``raw_enabled`` settings were added
-to Docutils 0.3.9; previous versions will ignore these settings.
+The "file_insertion_enabled_" and "raw_enabled_" settings were added
+to Docutils 0.3.9; previous versions will ignore these settings.
A bug existed in the configuration file handling of these settings in
-Docutils 0.4 and earlier: the right-hand-side of the (the
-values) needed to be left blank::
-
+Docutils 0.4 and earlier: the right-hand-side needed to be left blank
+(no values)::
+
[general]
file-insertion-enabled:
raw-enabled:
@@ -186,7 +189,9 @@
The bug was fixed with the 0.4.1 release on 2006-11-12.
+The "line_length_limit_" is new in Docutils 0.17.
+
Related Documents
=================
Modified: trunk/docutils/docs/index.txt
===================================================================
--- trunk/docutils/docs/index.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/index.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -94,8 +94,8 @@
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
-* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
- `text source <user/rst/quickstart.txt>`__)
+* `A ReStructuredText Primer <user/rst/quickstart.html>`__
+ (see also the `text source <user/rst/quickstart.txt>`__)
* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
only; 1 page for syntax, 1 page directive & role reference)
Modified: trunk/docutils/docs/peps/pep-0256.txt
===================================================================
--- trunk/docutils/docs/peps/pep-0256.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/peps/pep-0256.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -4,7 +4,7 @@
Last-Modified: $Date$
Author: David Goodger <go...@py...>
Discussions-To: <do...@py...>
-Status: Draft
+Status: Rejected
Type: Standards Track
Content-Type: text/x-rst
Created: 01-Jun-2001
@@ -11,6 +11,12 @@
Post-History: 13-Jun-2001
+Rejection Notice
+================
+
+This proposal seems to have run out of steam.
+
+
Abstract
========
Modified: trunk/docutils/docs/peps/pep-0258.txt
===================================================================
--- trunk/docutils/docs/peps/pep-0258.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/peps/pep-0258.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -4,7 +4,7 @@
Last-Modified: $Date$
Author: David Goodger <go...@py...>
Discussions-To: <do...@py...>
-Status: Draft
+Status: Rejected
Type: Standards Track
Content-Type: text/x-rst
Requires: 256, 257
@@ -12,6 +12,15 @@
Post-History: 13-Jun-2001
+================
+Rejection Notice
+================
+
+While this may serve as an interesting design document for the
+now-independent docutils, it is no longer slated for inclusion in the
+standard library.
+
+
==========
Abstract
==========
Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -1263,7 +1263,7 @@
-- Sherlock Holmes
A block quote may end with an attribution: a text block beginning with
-"--", "---", or a true em-dash, flush left within the block quote. If
+``--``, ``---``, or a true em-dash, flush left within the block quote. If
the attribution consists of multiple lines, the left edges of the
second and subsequent lines must align.
@@ -2472,12 +2472,12 @@
5. If an inline markup start-string is immediately preceded by one of the
ASCII characters ``' " < ( [ {`` or a similar
non-ASCII character [#openers]_, it must not be followed by the
- corresponding closing character from ``' " ) ] } >`` or a similar non-ASCII
- character [#closers]_. (For quotes, matching characters can be any of
- the `quotation marks in international usage`_.)
+ corresponding closing character from ``' " > ) ] }`` or a similar
+ non-ASCII character [#closers]_. (For quotes, matching characters can
+ be any of the `quotation marks in international usage`_.)
-If the configuration setting `simple-inline-markup`_ is False (default),
-additional conditions apply to the characters "around" the
+If the configuration setting `character-level-inline-markup`_ is False
+(default), additional conditions apply to the characters "around" the
inline markup:
6. Inline markup start-strings must start a text block or be
@@ -2548,15 +2548,15 @@
For languages that don't use whitespace between words (e.g. Japanese or
-Chinese) it is recommended to set `simple-inline-markup`_ to True and
-eventually escape inline markup characters.
+Chinese) it is recommended to set `character-level-inline-markup`_ to
+True and eventually escape inline markup characters.
The examples breaking rules 6 and 7 above show which constructs may need
special attention.
+.. _character-level-inline-markup:
+ ../../user/config.html#character-level-inline-markup
-.. _simple-inline-markup: ../../user/config.html#simple-inline-markup
-
Recognition order
-----------------
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/user/config.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -116,8 +116,8 @@
Example
=======
-This is the contents of the ``tools/docutils.conf`` configuration file
-supplied with Docutils::
+This is from the ``tools/docutils.conf`` configuration file supplied
+with Docutils::
# These entries affect all processing:
[general]
@@ -126,12 +126,17 @@
generator: on
# These entries affect HTML output:
+ [html writers]
+ embed-stylesheet: no
+
[html4css1 writer]
- # Required for docutils-update, the website build system:
- stylesheet-path: ../docutils/writers/html4css1/html4css1.css
- embed-stylesheet: no
+ stylesheet-path: docutils/writers/html4css1/html4css1.css
field-name-limit: 20
+ [html5 writer]
+ stylesheet-dirs: docutils/writers/html5_polyglot/
+ stylesheet-path: minimal.css, responsive.css
+
Individual configuration sections and settings are described in the
following section.
@@ -602,7 +607,7 @@
character_level_inline_markup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Experimental setting to relax the `inline markup recognition rules`_
+Relax the `inline markup recognition rules`_
requiring whitespace or punctuation around inline markup.
Allows character level inline markup without escaped whithespace and is
@@ -646,7 +651,7 @@
definition. To prevent extraordinary high processing times or memory
usage for certain input constructs, a "warning" system message is
inserted instead.
-
+
Default: 10 000.
Option: ``--line-length-limit``
@@ -1052,7 +1057,7 @@
https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
See https://www.jsdelivr.com/ for details and terms of use.
-
+
__ https://www.mathjax.org/#gettingstarted
* Use a local MathJax installation on the *client* machine, e.g.::
@@ -1176,18 +1181,18 @@
borderless
No borders around the table.
-
+
booktabs
Lines above and below the table and a thin line after the head.
-
+
align-left, align-center, align-right
Align the tables
-
+
colwidths-auto
Delegate the determination of table column widths to the backend
(leave out the ``<colgroup>`` column specification).
See also the "widths" option of the `table directive`_.
-
+
captionbelow
Place the table caption below the table
(only with the `HTML5 writer`_, new in 0.17).
Modified: trunk/docutils/docs/user/links.txt
===================================================================
--- trunk/docutils/docs/user/links.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/user/links.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -18,10 +18,10 @@
something to publish, you can get write access, too!
The most current version of this link list can always be found at
-http://docutils.sourceforge.net/docs/user/links.html.
+https://docutils.sourceforge.io/docs/user/links.html.
-.. _Docutils: http://docutils.sourceforge.net/
-.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
+.. _Docutils: http://docutils.sourceforge.io/
+.. _Docutils Sandbox: https://docutils.sourceforge.io/sandbox/README.html
Editors
@@ -58,24 +58,23 @@
Latest version of the plugin is available from `bittner @ github`_
(See also: `Gedit third party plugins`__).
+ .. _bittner @ github: https://github.com/bittner/gedit-reST-plugin
__ https://wiki.gnome.org/Apps/Gedit/ThirdPartyPlugins-v3.8
- .. _bittner @ github: https://github.com/bittner/gedit-reST-plugin
-
-* A BBEdit_/TextWrangler `language module`__ for editing reST documents.
-
- .. _BBEdit: https://en.wikipedia.org/wiki/BBEdit
- __ http://ericfromcanada.bitbucket.org/
-
* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
Docutils.
+
+ .. _DocFactory: https://docutils.sourceforge.io/sandbox/gschwant/docfactory/doc/
* ReSTedit_ by Bill Bumgarner is a Docutils GUI for Mac OS X.
+ .. _ReSTedit: https://svn.red-bean.com/restedit/trunk/README.html
+
* Leo_ is an outliner_, written in Python using PyQt. It can be used as IDE
for literal programming, as a filing cabinet holding any kind of data and
as `document editor`__ with outlines containing reStructuredText markup.
+ .. _Leo: http://leoeditor.com/
.. _outliner: http://en.wikipedia.org/wiki/Outliner
__ http://leoeditor.com/tutorial-rst3.html
@@ -85,74 +84,59 @@
* `rsted <https://github.com/anru/rsted>`_ is a "simple online editor for
reStructuredText on Flask". You can try it on http://rst.ninjs.org/
-.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
-.. _ReSTedit: http://www.friday.com/bbum/index.php?s=restedit
-.. _Leo: http://leoeditor.com/
-
Export
------
-Convert reStructuredText to other formats:
+Projects providing additional export routes.
PDF
```
-* `rst2pdf (reportlab)
- <http://rst2pdf.googlecode.com>`_ is a tool to go
- directly from reStructuredText to PDF, via `reportlab
- <http://www.reportlab.org/rl_toolkit.html>`_. No LaTeX installation is
- required.
+* `rst2pdf (reportlab)`__ is a tool to go directly from
+ reStructuredText to PDF, via ReportLab__. No LaTeX installation
+ is required.
+
+ __ https://pypi.org/project/rst2pdf/
+ __ https://pypi.org/project/reportlab/
-* `rst2pdf (pdflatex)
- <http://docutils.sourceforge.net/sandbox/blais/rst2pdf/>`_ by Martin Blais
- is a minimal front end producing LaTeX, compiling the LaTeX file, getting
- the produced output to the destination location and finally deleting all
- the messy temporary files that this process generates.
+* `rst2pdf (pdflatex)`__ by Martin Blais is a minimal front end
+ producing LaTeX, compiling the LaTeX file, getting the produced
+ output to the destination location and finally deleting all the
+ messy temporary files that this process generates.
+
+ __ https://docutils.sourceforge.io/sandbox/blais/rst2pdf/
-* `rst2pdf (rubber)
- <http://docutils.sf.net/sandbox/rst2pdf/README.html>`_ is
- a front end for the generation of PDF documents from a reStructuredText
- source via LaTeX in one step cleaning up intermediate files. It uses the
- `rubber <http://iml.univ-mrs.fr/~beffara/soft/rubber/>`_ Python wrapper
+* `rst2pdf (rubber)`__ is a front end for the generation of PDF
+ documents from a reStructuredText source via LaTeX in one step
+ cleaning up intermediate files. It uses the rubber__ Python wrapper
for LaTeX and friends.
+
+ __ https://docutils.sourceforge.io/sandbox/rst2pdf/README.html
+ __ https://launchpad.net/rubber
-* ``py.rest`` from the Codespeak `py Lib scripts`_ converts
- reStructuredText files to HTML and PDF (cleaning up the intermediate
- latex files). Similar to ``buildhtml.py``, it looks recursively for
- .txt files in the given PATHS.
-
* rlpdf_ is another PDF Writer based on ReportLabs.
+ .. _rlpdf: https://docutils.sourceforge.io/sandbox/dreamcatcher/rlpdf/
+
* RinohType_ is a pure Python PDF Writer based on a document template and a
style sheet (beta).
-.. _py Lib scripts: http://codespeak.net/py/dist/bin.html
-.. _rlpdf: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
-.. _RinohType: http://pypi.python.org/pypi/RinohType/0.2.1
+ .. _RinohType: http://pypi.python.org/pypi/RinohType/0.2.1
-OpenOffice
-``````````
-
-* Since version 0.5, the odtwriter_ by Dave Kuhlman is part of the Docutils_
- core.
-
-.. _odtwriter: http://docutils.sf.net/docs/user/odt.html
-
-
website generators and HTML variants
````````````````````````````````````
-* The Sphinx_ Python Documentation Generator by Georg Brandl was originally
- created to translate the `Python documentation`_, and is now `used by
- <http://sphinx.pocoo.org/examples.html>`__ a wide choice of projects.
+* The Sphinx_ Python Documentation Generator by Georg Brandl was
+ originally created to translate the `Python documentation`_.
+ In the meantime, there is a wide range of `Projects using Sphinx`__
It can generate complete web sites (interlinked and indexed HTML pages),
- ePub, PDF, and others [#]_ from a set of rst source files.
+ ePub, LaTeX, and others from a set of rST source files.
+
+ .. _Sphinx: https://www.sphinx-doc.org
+ __ https://www.sphinx-doc.org/en/master/examples.html
- .. [#] see http://sphinx-doc.org/config.html#options-for-epub-output
- .. _Sphinx: http://sphinx.pocoo.org/
-
* The Nikola_ static site generator, uses reStructuredText by
default.
@@ -159,7 +143,7 @@
.. _nikola: http://getnikola.com/
* Pelican_ is a static site generator (mainly for blogs). Articles/pages can
- be written in reStructuredText or Markdown\ [#markdown]_ format.
+ be written in reStructuredText or Markdown_ format.
.. _pelican: http://docs.getpelican.com
@@ -167,16 +151,10 @@
.. _tinkerer: http://tinkerer.me
-* rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht
- template, for use with ht2html_.
-
- .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
- .. _ht2html: http://ht2html.sourceforge.net/
-
* htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation
bars.
- .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
+ .. _htmlnav: https://docutils.sourceforge.io/sandbox/gschwant/htmlnav/
* rest2web_, by Michael Foord, is a tool for creating web sites with
reStructuredText.
@@ -183,51 +161,40 @@
.. _rest2web: http://www.voidspace.org.uk/python/rest2web/
-* rst2chm_ by Oliver Rutherfurd, generates Microsoft HTML Help files from
- reStructuredText files.
-
- .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
-
-* `html4strict <http://docutils.sf.net/sandbox/html4strict/>`__
- produces XHTML that strictly conforms to the XHTML 1.0 specification.
-
-* `html4trans <http://docutils.sf.net/sandbox/html4trans/>`__
+* `html4trans <https://docutils.sourceforge.io/sandbox/html4trans/>`__
produces XHTML conforming to the version 1.0 Transitional DTD that
contains enough formatting information to be viewed by a lightweight HTML
browser without CSS support.
* A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS
- (stylesheets).
+ stylesheets.
- .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
+ .. _simple HTML writer: https://docutils.sourceforge.io/sandbox/bbum/DocArticle/
ePub
````
-* The `rst2epub`_ project by Robert Wierschke converts simple
- reStructuredText doucments into valid epub files.
-
- .. simple but well structured with classes/modules for epub components,
- and a standard ``setup.py`` installation file.
-
* rst2epub2_ by Matt Harrison includes the epublib (originally by Tim
Tambin) and a rst2epub.py executable for the conversion.
+ .. _rst2epub2: https://github.com/mattharrison/rst2epub2
+
* Sphinx_ provides ePub as output option, too.
-.. _rst2epub: https://bitbucket.org/wierob/rst2epub
-.. _rst2epub2: https://github.com/mattharrison/rst2epub2
-
Others
``````
-* Pandoc_ is a document converter that can write Markdown\ [#markdown]_,
+* Pandoc_ is a document converter that can write Markdown_,
reStructuredText, HTML, LaTeX, RTF, DocBook XML, and S5.
+
+ .. _Pandoc: https://pandoc.org/
* restxsl_ by Michael Alyn Miller, lets you transform reStructuredText
documents into XML/XHTML files using XSLT stylesheets.
+ .. _restxsl: http://www.strangeGizmo.com/products/restxsl/
+
* An `XSLT script`__ by Ladislav Lhotka enables reStructuredText annotations
to be included in RELAG NG XML schemas.
@@ -235,33 +202,34 @@
* `DocBook Writer`_ by Oliver Rutherfurd.
+ .. _DocBook Writer: https://docutils.sourceforge.io/sandbox/oliverr/docbook/
+
* Nabu_, written by Martin Blais, is a publishing system which
extracts information from reStructuredText documents and stores it
in a database. Python knowledge is required to write extractor
- functions (see `Writing an Extractor`_) and to retrieve the data
- from the database again.
+ functions and to retrieve the data from the database again.
+
+ .. _Nabu: https://github.com/blais/nabu
* The `pickle writer`_ by Martin Blais pickles the document tree to a binary
string. Later unpickling will allow you to publish with other Writers.
+ .. _pickle writer: https://docutils.sourceforge.io/sandbox/blais/pickle_writer/
+
* The `Texinfo Writer`_, by Jon Waltman converts reStructuredText to
Texinfo, the documentation format used by the GNU project and the
Emacs text editor. Texinfo can be used to produce multiple output
formats, including HTML, PDF, and Info.
+ .. _Texinfo Writer: https://docutils.sourceforge.io/sandbox/texinfo-writer/README.html
+
* For `confluence CMS`_ see https://github.com/netresearch/rst2confluence.
+ .. _confluence CMS: http://www.atlassian.com/software/confluence
+
* Deploying into wikis might be aided by deploy-rst_.
-.. _Pandoc: http://sophos.berkeley.edu/macfarlane/pandoc/
-.. _restxsl: http://www.strangeGizmo.com/products/restxsl/
-.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
-.. _Nabu: http://furius.ca/nabu/
-.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
-.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
-.. _Texinfo Writer: http://docutils.sf.net/sandbox/texinfo-writer/README.html
-.. _confluence CMS: http://www.atlassian.com/software/confluence
-.. _deploy-rst: https://github.com/netresearch/deploy-rst
+ .. _deploy-rst: https://github.com/netresearch/deploy-rst
Import
@@ -269,18 +237,33 @@
Convert other formats to reStructuredText:
-* recommonmark_ is a Markdown\ [#markdown]_ (CommonMark_) parser for docutils.
+* recommonmark_ is a Markdown_ (CommonMark_) parser for
+ docutils originally created by Luca Barbato.
+
+ Docutils "markdown" parser (new in Docutils 0.17) is a wrapper
+ around recommonmark.
+
+ .. _recommonmark: https://github.com/rtfd/recommonmark
+ .. _Markdown: http://daringfireball.net/projects/markdown/syntax>
+ .. _CommonMark: http://commonmark.org/
+
* sxw2rest_, by Trent W. Buck, converts StarOffice XML Writer (SXW)
files to reStructuredText.
+ .. _sxw2rest: http://twb.ath.cx/~twb/darcs/sxw2rest/
+
* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
dumps of the document tree (e.g. created with rst2xml.py) back to
reStructuredText.
+
+ .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
* xhtml2rest_, written by Antonios Christofides, is a simple utility
to convert XHTML to reStructuredText.
+ .. _xhtml2rest: https://docutils.sourceforge.io/sandbox/wiemann/xhtml2rest/
+
* DashTable_ by Gustav Klopp converts HTML tables into reStructuredText.
Colspan and Rowspan supported!
@@ -290,30 +273,18 @@
<http://svn.python.org/projects/doctools/converter/>`__ in its source code
(trimmed to importing the old Python docs).
-* Pandoc_ can read Markdown\ [#markdown]_ and (subsets of) HTML, and LaTeX and export to
- (amongst others) reStructuredText.
+* Pandoc_ can read Markdown_ and (subsets of) HTML, and LaTeX and
+ export to (amongst others) reStructuredText.
* PySource_, by Tony Ibbs, is an experimental Python source Reader.
There is some related code in David Goodger's sandbox
(pysource_reader_) and a `Python Source Reader`_ document.
-.. [#markdown]
- `Markdown <http://daringfireball.net/projects/markdown/syntax>`__ is
- another lightwight markup language. See also documentation on `Common
- markup for Markdown and reStructuredText`_.
+ .. _PySource: https://docutils.sourceforge.io/sandbox/tibs/pysource/
+ .. _pysource_reader: https://docutils.sourceforge.io/sandbox/davidg/pysource_reader/
+ .. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
-.. _recommonmark: https://github.com/rtfd/recommonmark
-.. _CommonMark: http://commonmark.org/
-.. _sxw2rest: http://twb.ath.cx/~twb/darcs/sxw2rest/
-.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
-.. _xhtml2rest: http://docutils.sf.net/sandbox/wiemann/xhtml2rest/
-.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/
-.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/
-.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
-.. _Common markup for Markdown and reStructuredText:
- https://gist.github.com/dupuy/1855764
-
Extensions
----------
@@ -324,9 +295,13 @@
roles and/or directives and built preprocessors for TeX math for
both LaTeX and HTML output on top of it.
+ .. _preprocessing module: https://docutils.sourceforge.io/sandbox/cben/rolehack/
+
* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
to handle everything one might do with Docutils.
+ .. _Makefile: https://docutils.sourceforge.io/sandbox/cben/make/
+
* The `ASCII art to SVG converter`_ (aafigure) developed by
Chris Liechti can parse ASCII art images, embedded in reST documents and
output an image. This would mean that simple illustrations could be
@@ -333,19 +308,13 @@
embedded as ASCII art in the reST source and still look nice when
converted to e.g. HTML
-* zot4rst_ by Erik Hetzner is an extension that allows users to write reST
- documents using citations from a Zotero_ library.
+ .. _ASCII art to SVG converter:
+ https://docutils.sourceforge.io/sandbox/cliechti/aafigure/
* Quick and easy publishing reStructuredText source files as blog posts
on blogger.com is possible with `rst2blogger`_ .
-.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
-.. _Makefile: http://docutils.sf.net/sandbox/cben/make/
-.. _ASCII art to SVG converter:
- http://docutils.sf.net/sandbox/cliechti/aafigure/
-.. _zot4rst: http://e6h.org/~egh/hg/zotero-plain
-.. _Zotero: http://www.zotero.org/
-.. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
+ .. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
Related Applications
@@ -395,6 +364,8 @@
Since version 2.6, the `Python documentation`_ is based on
reStructuredText and Sphinx.
+
+ .. _Python documentation: http://docs.python.org/
* Trac_, a project management and bug/issue tracking system, supports
`using reStructuredText
@@ -401,30 +372,25 @@
<http://trac.edgewall.org/wiki/WikiRestructuredText>`__ as an
alternative to wiki markup.
+ .. _Trac: http://trac.edgewall.org/
+
* PyLit_ provides a bidirectional text <--> code converter for *literate
programming with reStructuredText*.
-* If you are developing a Qt app, rst2qhc_ lets you generate the whole help
- automatically from reStructuredText. That includes keywords, TOC,
- multiple manuals per project, filters, project file, collection project
- file, and more.
+ .. _PyLit: http://repo.or.cz/pylit.git
-.. _Python documentation: http://docs.python.org/
-.. _Trac: http://trac.edgewall.org/
-.. _PyLit: http://repo.or.cz/pylit.git
-.. _rst2qhc: http://rst2qhc.googlecode.com
-
CMS Systems
```````````
* Plone_ and Zope_ both support reStructuredText markup.
+
* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope_"
application that is complete and ready to install.
.. _Plone: http://plone.org/
.. _Zope: http://www.zope.org/
-.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
+.. _ZReST: https://docutils.sourceforge.io/sandbox/richard/ZReST/
Presentations
@@ -433,32 +399,35 @@
* rst2html5_ transform restructuredtext documents to html5 + twitter's
bootstrap css, deck.js or reveal.js
+ .. _rst2html5: https://github.com/marianoguerra/rst2html5
+
* landslide_ generates HTML5 slideshows from markdown, ReST, or textile.
+ .. _landslide: https://github.com/adamzap/landslide
+
* `native support for S5 <slide-shows.s5.html>`_.
* The `PythonPoint interface`_ by Richard Jones produces PDF
- presentations using ReportLabs' PythonPoint_.
+ presentations using ReportLabs' PythonPoint.
+ .. _PythonPoint interface:
+ https://docutils.sourceforge.io/sandbox/richard/pythonpoint/
+
* rst2beamer_ generates a LaTeX source that uses the `Beamer` document class.
Can be converted to PDF slides with pdfLaTeX/XeLaTeX/LuaLaTeX.
+ .. _rst2beamer: https://docutils.sourceforge.io/sandbox/rst2beamer/
+
* InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
reStructuredText for markup, although it renders only a subset of rst.
+
+ .. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
+ .. _Inkscape: http://inkscape.org/
* rst2outline_ translates a reStructuredText document to a plain text
outline. This can then be transformed to PowerPoint.
-* Pandoc_ can also be used to produce slides, as shown in this
- `Pandoc Slides Demo`_
+ .. _rst2outline: https://docutils.sourceforge.io/sandbox/rst2outline/
-.. _PythonPoint: http://www.reportlab.org/python_point.html
-.. _PythonPoint interface: http://docutils.sf.net/sandbox/richard/pythonpoint/
-.. _rst2beamer: http://docutils.sf.net/sandbox/rst2beamer/
-.. _Inkscape: http://inkscape.org/
-.. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
-.. _rst2html5: https://github.com/marianoguerra/rst2html5
-.. _landslide: https://github.com/adamzap/landslide
-.. _rst2outline: http://docutils.sf.net/sandbox/rst2outline/
-.. _Pandoc Slides Demo:
- http://johnmacfarlane.net/pandoc/demo/example9/producing-slide-shows-with-pandoc
+* Pandoc_ can also be used to produce slides
+
Modified: trunk/docutils/docs/user/tools.txt
===================================================================
--- trunk/docutils/docs/user/tools.txt 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docs/user/tools.txt 2021-03-26 13:51:36 UTC (rev 8644)
@@ -69,7 +69,9 @@
latex__, xelatex_, xml_, odt_, Pseudo-XML_
__ `Generating LaTeX with Docutils`_
+.. _Generating LaTeX with Docutils: latex.html
+
HTML-Generating Tools
=====================
@@ -464,15 +466,11 @@
Command-Line Options
====================
-Each front-end tool supports command-line options for one-off
-customization. For persistent customization, use `configuration
-files`_. Command-line options take priority over configuration file
-settings.
+Command-line options are intended for one-off customization.
+They take priority over configuration file settings.
Use the "--help" option on each of the front ends to list the
-command-line options it supports. Command-line options and their
-corresponding configuration file entry names are listed in the
-`Docutils Configuration Files`_ document.
+command-line options it supports.
.. _configuration file:
@@ -483,10 +481,11 @@
Configuration files are used for persistent customization; they can be
set once and take effect every time you use a front-end tool.
-For details, see `Docutils Configuration Files`_.
+Command-line options and their corresponding configuration file entry
+names are listed in the `Docutils Configuration Files`_ document.
.. _Docutils Configuration Files: config.html
-.. _Generating LaTeX with Docutils: latex.html
+
..
Local Variables:
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2021-03-26 13:51:21 UTC (rev 8643)
+++ trunk/docutils/docutils/writers/_html_base.py 2021-03-26 13:51:36 UTC (rev 8644)
@@ -514,9 +514,9 @@
if (isinstance(node, (nodes.enumerated_list, nodes.bullet_list))
and not self.settings.compact_lists):
return False
- # more special cases:
+ # Table of Contents:
if (self.topic_classes == ['contents']):
- # TODO: look for "auto-toc" instead and remove self.topic_classes
+ # TODO: look in parent nodes, remove self.topic_classes?
return True
# check the list items:
return self.check_simple_list(node)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
