SF.net SVN: docutils:[10113 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Tue, 29 Apr 2025 20:36:07 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10113
http://sourceforge.net/p/docutils/code/10113
Author: milde
Date: 2025-04-29 20:36:06 +0000 (Tue, 29 Apr 2025)
Log Message:
-----------
Documentation fixes and update.
alternatives.rst:
* "standard definition files" are now included as part of Docutils.
* the "dfn" role (defined in the "html-roles.txt" standard definition file
corresponds to the HTML `<dfn>` element for the defining term.
It can be used instead of a simple emphasis for a more semantic markup.
todo.rst:
* tools/buildhtml.py has now an "--ignore" option for files,
* "container" directive now reports an error if the :class: option is used
(classes are passed as argument),
* definition list line numbers are fixed,
* `frontend.filter_settings_spec` is not suited to filter command line options
that don't apply,
* the `--section-numbering` command line option is implemented,
* front-end tools will accept more than one source document in Docutils 2.0
(see RELEASE-NOTES).
Modified Paths:
--------------
trunk/docutils/FAQ.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/api/transforms.rst
trunk/docutils/docs/dev/rst/alternatives.rst
trunk/docutils/docs/dev/todo.rst
trunk/docutils/docs/eps/ep-001.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docutils/parsers/rst/include/html-roles.txt
Modified: trunk/docutils/FAQ.rst
===================================================================
--- trunk/docutils/FAQ.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/FAQ.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -690,6 +690,16 @@
:A: Answer.
+How can I mark up a TODO list?
+------------------------------
+
+You may use a field list with class argument and some CSS styling.
+For an example see `Docutils TODO lists`_ and its source todo-lists.rst_.
+
+.. _Docutils TODO lists: docs/user/todo-lists.html
+.. _todo-lists.rst: docs/user/todo-lists.rst
+
+
.. _bidi:
Can I produce documents in right-to-left languages?
@@ -809,16 +819,6 @@
.. [#] The "x-" prefix means it's an unregistered MIME type.
-How can I mark up a TODO list?
-------------------------------
-
-You may use a field list with class argument and some CSS styling.
-For an example see `Docutils TODO lists`_ and its source todo-lists.rst_.
-
-.. _Docutils TODO lists: docs/user/todo-lists.html
-.. _todo-lists.rst: docs/user/todo-lists.rst
-
-
How can I specify an image grid?
--------------------------------
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -40,8 +40,6 @@
For the rationale, see https://clig.dev/#arguments-and-flags.
-.. _entry points:
- https://packaging.python.org/en/latest/specifications/entry-points/
Document Tree / Docutils DTD
----------------------------
@@ -314,7 +312,7 @@
`utils.Reporter.set_conditions()`
obsolete, set attributes via configuration settings or directly.
-Removed localisations:
+Removed localisations
Mistranslations of the "admonition" directive name:
Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
"sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
@@ -321,6 +319,10 @@
"zauważenie" (pl) (introduced in Docutils 0.21)
or the English name "admonition".
+New files
+ ``docutils/parsers/rst/include/html-roles.txt``
+ `Standard definition file`_ for additional roles matching HTML tags.
+
Removed files
``tools/rst2odt_prepstyles.py``
Obsoleted by `writers.odf_odt.prepstyles`.
@@ -367,12 +369,14 @@
- Use ``python -m docutils.writers.odf_odt.prepstyles``
to `strip the page size`__ from an ODT writer stylesheet.
- __ docs/user/odt.html#page-size
-
.. [#] Some Linux distributions already use the short names.
.. [#] The final rendering is done by a Sphinx-based build system
(cf. :PEP:`676`).
+ .. _entry points:
+ https://packaging.python.org/en/latest/specifications/entry-points/
+ __ docs/user/odt.html#page-size
+
* reStructuredText:
- Use the same CSV format for the ``:header:`` option and the main data
@@ -1424,6 +1428,7 @@
docs/ref/rst/directives.html#including-an-external-document-fragment
.. _"widths" option: docs/ref/rst/directives.html#table
+.. _Standard definition file: docs/ref/rst/definitions.html
.. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
.. _configuration settings: docs/user/config.html
Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docs/api/transforms.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -216,7 +216,9 @@
Transforms Reference
====================
-Incomplete. See also `Transforms Listed in Priority Order`_
+.. Note:: This section is still incomplete.
+
+See also `Transforms Listed in Priority Order`_
and the sources in `docutils/transforms`__.
__ https://docutils.sourceforge.io/docutils/transforms/
Modified: trunk/docutils/docs/dev/rst/alternatives.rst
===================================================================
--- trunk/docutils/docs/dev/rst/alternatives.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docs/dev/rst/alternatives.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -254,6 +254,25 @@
Syntax #3 was chosen for reStructuredText.
+``term`` Role
+=============
+
+Add a "term" role for unfamiliar or specialized terminology?
+Probably not as a standard role; there is no real use case, and emphasis
+is enough for most cases.
+For semantic markup, authors may define a `custom role`_ or include the
+"html-roles.txt" `standard definition file`_ that defines (`amongst
+others`__) the "dfn" role (the "html5" writer selects the corresponding
+`HTML <dfn> element`_).
+
+.. _custom role: ../../ref/rst/directives.html#role
+.. _standard definition file: ../../ref/rst/definitions.html
+__ ../../ref/rst/definitions.html#additional-roles-for-html
+.. _HTML <dfn> element:
+ https://html.spec.whatwg.org/multipage/text-level-semantics.html
+ #the-dfn-element
+
+
Comments
========
@@ -2740,8 +2759,11 @@
Literal block?
Hmm... Non-strict indentation isn't such a good idea.
+Except for `field lists`_.
+.. _field lists: ../../ref/rst/restructuredtext.html#field-lists
+
Lazy Indentation of List Items
==============================
@@ -3010,15 +3032,9 @@
A "unicode" directive has been implemented to allow direct
specification of esoteric characters. In combination with the
-substitution construct, "include" files defining common sets of
-character entities can be defined and used. `A set of character
-entity set definition files have been defined`__ (`tarball`__).
-There's also `a description and instructions for use`__.
+substitution construct, `standard definition files`_ for common
+sets of character entities are provided for inclusion.
-__ https://docutils.sourceforge.io/tmp/charents/
-__ https://docutils.sourceforge.io/tmp/charents.tgz
-__ https://docutils.sourceforge.io/tmp/charents/README.html
-
To allow for `character-level inline markup`_, a limited form of
character processing has been added to the spec and parser: escaped
whitespace characters are removed from the processed document. Any
@@ -3025,6 +3041,7 @@
further character processing will be of this functional type, rather
than of the character-encoding type.
+.. _standard definition files: ../../ref/rst/definitions.html
.. _character-level inline markup:
../../ref/rst/restructuredtext.html#character-level-inline-markup
@@ -3109,7 +3126,7 @@
However, superscripts are seldom needed, and new syntax would break
existing documents. When it's needed, the ``:superscript:``
-(``:sup:``) role can we used as well.
+(``:sup:``) role can be used as well.
Code Execution
@@ -3164,18 +3181,20 @@
required to associate annotations with the original text (by name, or
positionally as in anonymous targets?).
-There have not been many requests for such feature, though. Also,
+There have not been many requests for such feature, though. [#]_ Also,
cluttering WYSIWYG plaintext with annotations may not seem like a good
-idea, and there is no "tool tip" in formats other than HTML.
+idea, and there is no "tool tip" in formats other than HTML. [#]_
+.. [#] But see the `feature-request ticket #108`__.
-``term`` Role
-=============
+.. [#] As of 2025, there are also annotations in the output formats
+ OpenDocument and PDF/LaTeX (the LaTeX package "pdfcomment" provides a
+ \pdftooltip macro that creates pop-ups in PDF output).
-Add a "term" role for unfamiliar or specialized terminology? Probably
-not; there is no real use case, and emphasis is enough for most cases.
+ __ https://sourceforge.net/p/docutils/feature-requests/108/
+
Object references
=================
Modified: trunk/docutils/docs/dev/todo.rst
===================================================================
--- trunk/docutils/docs/dev/todo.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docs/dev/todo.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -65,10 +65,10 @@
Move to a Git repository.
-* This is a long standing `feature request`__
- (with pointers to Sphinx issues and discussion).
+See `feature requests #58`__
+(with pointers to Sphinx issues and discussion).
- __ https://sourceforge.net/p/docutils/feature-requests/58/
+__ https://sourceforge.net/p/docutils/feature-requests/58/
* From a `post by David Goodger`__
@@ -111,8 +111,8 @@
Sourceforge supports multiple Git repositories per project, so we can
switch the version control system independent of the decision on an
-eventual switch of the host.
-Cf. https://sourceforge.net/p/forge/documentation/Git/
+eventual switch of the host
+(cf. https://sourceforge.net/p/forge/documentation/Git/).
General
@@ -516,11 +516,6 @@
.. _traits: http://code.enthought.com/traits/
.. _SciPy: http://www.scipy.org/
-* tools/buildhtml.py: Extend the --prune option ("prune" config
- setting) to accept file names (generic path) in addition to
- directories (e.g. --prune=docs/user/rst/cheatsheet.rst, which should
- *not* be converted to HTML).
-
* Add support for _`plugins`.
* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
@@ -673,7 +668,7 @@
they do.
* Document the transforms_ (perhaps in docstrings?): how they're used,
- what they do, dependencies & order considerations.
+ what they do, dependencies & order considerations. In progress.
* Document the HTML classes used by html4css1.py.
@@ -833,16 +828,11 @@
__ rst/alternatives.html#or-not-to-do
-Bugs
-----
-* A container directive with ``:class:`` option gets the spurious
- class value "class".
-
Misc
----
-* Another list problem::
+* A list problem::
* foo
* bar
@@ -1146,40 +1136,17 @@
(explicitly), just implicitly/automatically. See rev. 1.74 of
docutils/parsers/rst/states.py for an example of how to set.
- - The line numbers of definition list items are wrong::
+ - See also `feature requests #41`__
- $ rst2pseudoxml --expose-internal-attribute line
- 1
- 2
- 3
+ __ https://sourceforge.net/p/docutils/feature-requests/41/
- 5
- 6
- 7
+* Unprintable characters like NULL in the rST source are in most cases
+ an indication of a problem (corrupt source file, wrong encoding, ...).
+ The same goes for combining characters at the start of a line, etc.
+ It may be helpful, if Docutils issued a Warning for problematic
+ characters in the source (except for literals).
- <document source="<stdin>">
- <definition_list>
- <definition_list_item internal:line="3">
- <term>
- 1
- <definition>
- <paragraph internal:line="2">
- 2
- 3
- <definition_list_item internal:line="6">
- <term>
- 5
- <definition>
- <paragraph internal:line="6">
- 6
- 7
-* .. _none source:
-
- Quite a few nodes are getting a "None" source attribute as well. In
- particular, see the bodies of definition lists.
-
-
Adaptable file extensions
-------------------------
@@ -1337,15 +1304,11 @@
Math Markup
-----------
-Since Docutils 0.8, a "math" role and directive using LaTeX math
-syntax as input format is part of reStructuredText.
+* Use a "Transform" for math format conversions as extensively discussed
+ in the `math directive issues`__ thread in May 2008?
-Open issues:
+ __ http://osdir.com/ml/text.docutils.devel/2008-05/threads.html
-* Use a "Transform" for math format conversions as extensively discussed in
- the "math directive issues" thread in May 2008
- (http://osdir.com/ml/text.docutils.devel/2008-05/threads.html)?
-
* Generic `math-output setting`_ (currently specific to HTML).
(List of math-output preferences?)
@@ -1501,15 +1464,7 @@
.. _Hevea: http://para.inria.fr/~maranget/hevea/
.. _KaTeX: https://katex.org
-client side JavaScript conversion
- Use TeX notation in the web page and JavaScript in the displaying browser.
- (implemented as `math-output setting`_ "mathjax").
- * jqMath_ (faster and lighter than MathJax_)
-
- .. _MathJax: http://www.mathjax.org/
- .. _jqMath: http://mathscribe.com/author/jqmath.html
-
OpenOffice output
`````````````````
@@ -2034,15 +1989,6 @@
[DG 2017-01-02:] +0.
- Discussion
- The syntax could be left in reST (for a set period of time?).
-
- [DG 2017-01-02:] The syntax must be left in reST, practically
- forever. Removing it would introduce a huge backwards
- incompatibility. Any syntax removal must be preceded by a thorough
- review and planning, including a deprecation warning process. My
- opinion: it's not worth it.
-
* "Normalize" special admonitions (note, hint, warning, ...) during parsing
(similar to _`transforms.writer_aux.Admonitions`). There is no need to
keep them as distinct elements in the doctree specification.
@@ -2059,8 +2005,8 @@
+1 reduce the complexity of the doctree
(there is no 1:1 rST syntax element <-> doctree node mapping anyway).
- +2 every writer needs 9 visit_*/depart_* method pairs to handle the 9
- subtypes of an admonition, i.e. we could but also remove 36 redundant
+ +1 every writer needs 9 visit_*/depart_* method pairs to handle the 9
+ subtypes of an admonition, i.e. we could remove 72 redundant
methods (HTML, LaTeX, Manpage, ODF).
-1 the most unfortunately named of these directives will survive. [#]_
@@ -2234,7 +2180,7 @@
omitting ``<p>`` tags. List compacting would need to be done by
adjusting CSS margins instead.
- :2015-04-02: The new html writer no longer strips <p> tags but adds the
+ :2015-04-02: The "html5" writer no longer strips <p> tags but adds the
class value ``simple`` to the list.
Formatting is done by CSS --- configurable by a custom style
sheet.
@@ -2250,7 +2196,7 @@
If the first item of a field body is not a paragraph,
it would begin on the following line.
- :2015-04-02: The new html writer writes field-lists as definition lists
+ :2015-04-02: The "html5" writer writes field-lists as definition lists
with class ``field-list``.
Formatting is done by CSS --- configurable by a custom style
sheet. The default style sheet has some examples, including a
@@ -2396,6 +2342,7 @@
.. _latex-variants:
../../../sandbox/latex-variants/README.html
+
Bug fixes
---------
@@ -2431,6 +2378,7 @@
+ pointers to advanced packages and their use in the `latex writer
documentation`_.
+
Configurable placement of figure and table floats
`````````````````````````````````````````````````
@@ -2523,6 +2471,7 @@
.. _enumitem: https://www.ctan.org/pkg/enumitem
+
Default layout
--------------
@@ -2558,6 +2507,7 @@
.. _compound paragraph:
../ref/rst/directives.html#compound-paragraph
+
Tables
``````
@@ -2613,6 +2563,7 @@
table title. In analogy to the 'figure' directive this should map to a
table float.
+
Image and figure directives
```````````````````````````
@@ -2646,8 +2597,6 @@
a figure in LaTeX is 100 % of the text width, setting the 'align'
argument has currently no effect on the LaTeX output.
-* Multiple author entries in docinfo (same thing as in html).
-
* Consider supporting the "compact" option and class argument (from
rst2html) as some lists look better compact and others need the space.
@@ -2757,8 +2706,6 @@
--stylesheet-path second.css ...
-
-
Front-End Tools
===============
@@ -2766,20 +2713,12 @@
initialize ``settings_spec`` in ``__init__`` or ``init_options``?
* Disable common options that don't apply?
- (This should now be easier with ``frontend.filter_settings_spec``.)
-* Add ``--section-numbering`` command line option. The "sectnum"
- directive should override the ``--no-section-numbering`` command
- line option then.
+* Implement the following suggestion from clig.dev?
-* Implement the following suggestions from clig.dev?
-
Display output on success, but keep it brief.
provide a --quiet option to suppress all non-essential output.
- Consider chaining several args as input and use --output
- (or redirection) for output.
-
-- https://clig.dev/#help
.. _partial parsing:
Modified: trunk/docutils/docs/eps/ep-001.rst
===================================================================
--- trunk/docutils/docs/eps/ep-001.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docs/eps/ep-001.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -244,6 +244,9 @@
.. Link to any existing implementation and details about its state, e.g.
proof-of-concept.
+Since 2025-04-29, enhancement proposals are available as part of the
+Docutils Documentation under https://docutils.sourceforge.io/docs/eps/.
+
The sandbox_ contains a directory for
`enhancement proposals in "pre-draft" stage`_.
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-04-29 20:36:06 UTC (rev 10113)
@@ -395,6 +395,7 @@
``figname`` : text_
Add *text* to the `names attribute`_ of the <figure> element
(the "name_" option is applied to the nested <image>).
+ New in Docutils 0.22.
``figwidth`` : "image", length_, or percentage_ of current line width
The width of the figure.
Modified: trunk/docutils/docutils/parsers/rst/include/html-roles.txt
===================================================================
--- trunk/docutils/docutils/parsers/rst/include/html-roles.txt 2025-04-27 20:43:12 UTC (rev 10112)
+++ trunk/docutils/docutils/parsers/rst/include/html-roles.txt 2025-04-29 20:36:06 UTC (rev 10113)
@@ -1,4 +1,4 @@
-.. Standard definition file for additonal roles matching HTML tags.
+.. Standard definition file for additional roles matching HTML tags.
:Copyright: © 2025 Günter Milde.
:License: Released under the terms of the
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