SF.net SVN: docutils:[9944 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9944
http://sourceforge.net/p/docutils/code/9944
Author: milde
Date: 2024-10-02 08:40:47 +0000 (Wed, 02 Oct 2024)
Log Message:
-----------
Document two more doctree elements + other documentation updates.
Document `<problematic>` and `<system_message>` doctree elements.
Various more or less related documentation corrections and updates.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/config.rst
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2024-09-29 09:31:39 UTC (rev 9943)
+++ trunk/docutils/RELEASE-NOTES.rst 2024-10-02 08:40:47 UTC (rev 9944)
@@ -28,15 +28,16 @@
.. code:: diff
- COMMAND [OPTIONS] [SOURCE [DESTINATION]]
- + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION]
+ + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]]
* Stop accepting the DESTINATION positional argument in Docutils 1.0.
- Use output redirection or the option ``--output=DESTINATION``
- (available since Docutils 0.20).
+ Use ``--output=DESTINATION`` (cf. the "output_" configuration setting)
+ or output redirection.
- * Accept more than one source document and the short option
- ``-o`` for ``--output`` in Docutils 2.0
+ * Accept the short option ``-o`` for ``--output`` in Docutils 1.0
+ * Accept more than one source document in Docutils 2.0
+
For the rationale, see https://clig.dev/#arguments-and-flags.
.. _entry points:
@@ -438,7 +439,7 @@
are now ignored by the "xetex" writer.
Place common settings in section `[latex writers]`_.
- - New command line setting output_. Obsoletes the ``<destination>``
+ - New configuration setting "output_". Obsoletes the ``<destination>``
positional argument (cf. `future changes`__).
__ `command-line usage pattern`_
@@ -533,8 +534,7 @@
Example:
with ``--id-prefix="DU-"``, a section with title "34. May"
- currently gets the identifier key ``DU-may`` and after the
- change the identifier key ``DU-34-may``.
+ now gets the identifier key ``DU-34-may`` instead of ``DU-may``.
- The default value for the auto_id_prefix_ setting changed to ``%``:
"use the tag name as prefix for auto-generated IDs".
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2024-09-29 09:31:39 UTC (rev 9943)
+++ trunk/docutils/docs/ref/doctree.rst 2024-10-02 08:40:47 UTC (rev 9944)
@@ -277,7 +277,6 @@
:Docutils class: ``nodes.Part``
-
Inline Elements
---------------
@@ -2254,7 +2253,8 @@
The <inline> element is a generic inline container.
:Category: `Inline Elements`_
-:Analogues: <inline> is analogous to the HTML <span> element.
+:Analogues: <inline> is analogous to the HTML_ <span> element and the
+ Docbook_ <phrase> element.
:Processing: Writers_ typically pass the classes_ attribute to the output
document and leave styling to the backend or a custom
stylesheet_. They may also process the classes_ attribute
@@ -2944,9 +2944,45 @@
<problematic>
=============
-`To be completed`_.
+The <problematic> element highlights a source part that caused a parsing
+problem.
+:Category: `Inline Elements`_
+:Analogues: <problematic> has no direct analogues in common DTDs.
+:Processing: Typically displayed in red colour.
+ If the refid_ attribute is present, the element should
+ point to the referenced element.
+:Parents: All elements employing the `%text.model`_ parameter
+ entity in their content models may contain <problematic>.
+:Children: <problematic> elements may contain text data
+ plus `inline elements`_ (`%text.model`_).
+:Attributes: The <problematic> element contains the `common attributes`_
+ and refid_.
+Examples
+--------
+
+The reStructuredText parser marks ambiguous or invalid inline syntax as
+<problematic> and adds a reference to the associated `\<system_message>`_.
+The behaviour can be configured with the `report_level`_ setting.
+
+The following paragraph contains unbalanced `inline markup`_::
+
+ a single *star
+
+Pseudo-XML_ fragment from simple parsing::
+
+ <paragraph>
+ a single
+ <problematic ids="problematic-1" refid="system-message-1">
+ *
+ star
+ <system_message backrefs="problematic-1" ids="system-message-1"
+ level="2" line="1" source="example.rst" type="WARNING">
+ <paragraph>
+ Inline emphasis start-string without end-string.
+
+
<raw>
=====
@@ -3435,9 +3471,46 @@
<system_message>
================
-`To be completed`_.
+The <system_message> element is used for feedback from the processing
+system.
+:Category: `Compound Body Elements`_
+:Analogues: <system_message> has no direct analogues in common DTDs.
+ It can be emulated with primitives and type effects.
+:Processing: Rendered similar to an `\<admonition>`_, with the generated
+ title "System Message", its type_/level_ and, if available,
+ source_ and line_.
+:Parents: All elements employing the `%body.elements`_ or
+ `%structure.model`_ parameter entities in their content models
+ may contain <system_message>.
+:Children: <system_message> elements contain one or more `body elements`_.
+:Attributes: The <system_message> element accepts the `common
+ attributes`_ plus backrefs_, level_, line_, and type_.
+:Parameter Entities: The `%body.elements`_ parameter entity directly includes
+ <system_message>. The `%structure.model`_ parameter entity
+ indirectly includes <system_message>.
+In Docutils, the generation of system messages can be configured with the
+`report_level`_ setting.
+
+Examples
+--------
+
+An undefined or misspelled directive_ generates an error message::
+
+ .. contants::
+
+Pseudo-XML_ fragment from simple parsing::
+
+ <system_message level="3" line="8" source="example.rst" type="ERROR">
+ <paragraph>
+ Unknown directive type "contants".
+ <literal_block xml:space="preserve">
+ .. contants::
+
+See also `\<problematic>`_.
+
+
<table>
=======
@@ -4417,7 +4490,8 @@
Attribute type: `%number`_. Default value: none.
-The ``level`` attribute is used in the `\<system_message>`_ element.
+The ``level`` attribute is used in the `\<system_message>`_ element to
+indicate the message's `severity level`_. See also the "type_" attribute.
``line``
@@ -4425,7 +4499,9 @@
Attribute type: `%number`_. Default value: none.
-The ``line`` attribute is used in the `\<system_message>`_ element.
+The ``line`` attribute is used in the `\<system_message>`_ element to
+indicate the position of the reported problem in the document source.
+See also the source_ attribute.
``ltrim``
@@ -4650,18 +4726,21 @@
Attribute type: `CDATA`_. Default value: none.
-The ``source`` attribute is used to store the path or URI of the
-source text that was used to produce the document tree.
+The ``source`` attribute stores the path, URI, or a description
+of the source that was used to produce the document tree. [#]_
-It is one of the `common attributes`_, declared for all Docutils
-elements but typically only used with the `\<document>`_ and
-`\<system_message>`_ elements.
+``source`` is one of the `common attributes`_ but typically only
+used with the `\<document>`_ and `\<system_message>`_ elements.
-.. note:: All ``docutils.nodes.Node`` instances also support an
- *internal* ``source`` attribute that is used when reporting
- processing problems.
+.. note:: All ``docutils.nodes.Node`` instances also support
+ *internal* ``source`` and ``line`` attributes
+ for use in diagnostic output.
+.. [#] An element's ``source`` attribute may differ from the main
+ document ``source`` if the document is assembled from several
+ sources (e.g. via the `"include" directive`_).
+
``start``
=========
@@ -4668,7 +4747,7 @@
Attribute type: `%number`_. Default value: none (implies 1).
The ``start`` attribute is used in the `\<enumerated_list>`_ element to
-store the ordinal value of the first item in the list, in decimal.
+store the ordinal value of the first item in the list, in decimal notation.
For lists beginning at value 1 ("1", "a", "A", "i", or "I"),
this attribute may be omitted.
@@ -4717,6 +4796,7 @@
.. _HTML <title> element:
https://html.spec.whatwg.org/multipage/semantics.html#the-title-element
+
``type``
=========
@@ -4723,6 +4803,8 @@
Attribute type: NMTOKEN_. Default value: none.
The ``type`` attribute is used in the `\<system_message>`_ element.
+It holds the name of the message's `severity level`_ (cf. the "level_"
+attribute).
``uri``
@@ -4778,6 +4860,7 @@
element contains significant whitespace. The attribute value should not
be set in a document instance.
+
----------------------------
Parameter Entity Reference
----------------------------
@@ -4797,6 +4880,7 @@
In addition, the Docutils DTD defines parameter entities for
`custom attribute types`_.
+
Attribute Entities
==================
@@ -4827,6 +4911,7 @@
The `\<image>`_ element directly employs the ``%align-hv.att``
parameter entity in its attribute list.
+
``%anonymous.att``
------------------
@@ -4997,6 +5082,7 @@
indirectly employed in the attribute lists of the `\<citation_reference>`_,
`\<footnote_reference>`_, `\<reference>`_, and `\<target>`_ elements.
+
``%tbl.colspec.att``
--------------------
@@ -5263,10 +5349,10 @@
`XML Exchange Table Model DTD`,
OASIS Technical Memorandum 9901:1999,
http://www.oasis-open.org/html/tm9901.html.
- W3C Recommendation,
- https://www.w3.org/TR/xml/.
.. [xml1.0] `Extensible Markup Language (XML) 1.0`,
+ W3C Recommendation,
+ https://www.w3.org/TR/xml/.
.. _DocBook: https://tdg.docbook.org/tdg/5.1/.
.. _DocBook <caution>: https://tdg.docbook.org/tdg/5.1/caution.html
@@ -5304,6 +5390,7 @@
.. _datestamp: ../user/config.html#datestamp
.. _id_prefix: ../user/config.html#id-prefix
.. _image_loading: ../user/config.html#image-loading
+.. _report_level: ../user/config.html#report-level
.. _stylesheet: ../user/config.html#stylesheet
.. _transform:
@@ -5311,6 +5398,8 @@
.. _DocInfo transform: ../api/transforms.html#docinfo
.. _DocTitle transform: ../api/transforms.html#doctitle
+.. _severity level: ../peps/pep-0258.html#error-handling
+
.. _A ReStructuredText Primer: ../user/rst/quickstart.html
.. _reStructuredText Markup Specification: rst/restructuredtext.html
.. _bibliographic data:
@@ -5327,9 +5416,10 @@
.. _explicit markup blocks: rst/restructuredtext.html#explicit-markup-blocks
.. _footnote reference: rst/restructuredtext.html#footnote-references
.. _grid table: rst/restructuredtext.html#grid-tables
-.. _indirect target: rst/restructuredtext.html#indirect-hyperlink-targets
+.. _indirect target: rst/restructuredtext.html#indirect-hyperlink-targets
+.. _inline markup: rst/restructuredtext.html#inline-markup
.. _internal hyperlink targets:
- rst/restructuredtext.html#internal-hyperlink-targets
+ rst/restructuredtext.html#internal-hyperlink-targets
.. _line block: rst/restructuredtext.html#line-blocks
.. _literal block: rst/restructuredtext.html#literal-blocks
.. _footnotes:
@@ -5376,6 +5466,7 @@
.. _identifier normalization: rst/directives.html#identifier-normalization
.. _"image" directive: rst/directives.html#image
.. _"important" directive: rst/directives.html#important
+.. _"include" directive: rst/directives.html#include
.. _"list-table": rst/directives.html#list-table
.. _"math" directive: rst/directives.html#math
.. _"meta" directive: rst/directives.html#meta
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-09-29 09:31:39 UTC (rev 9943)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2024-10-02 08:40:47 UTC (rev 9944)
@@ -457,10 +457,9 @@
reference (``note_``). Of course, each type of reference (hyperlink,
footnote, citation) may be processed and rendered differently. Some
care should be taken to avoid reference name conflicts.
+References to `substitution definitions`_ (`substitution references`_)
+use a different namespace.
-`Substitution references`_ and `substitution definitions`_ use a
-different namespace.
-
.. [#case-forgiving] Matching `substitution references`_ to
`substitution definitions`_ is `case-sensitive but forgiving`_.
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2024-09-29 09:31:39 UTC (rev 9943)
+++ trunk/docutils/docs/user/config.rst 2024-10-02 08:40:47 UTC (rev 9944)
@@ -227,8 +227,6 @@
https://docs.python.org/3/library/configparser.html
.. _Python: https://www.python.org/
.. _RFC 822: https://www.rfc-editor.org/rfc/rfc822.txt
-.. _front-end tool:
-.. _application: tools.html
__ ../api/runtime-settings.html#active-sections
@@ -396,7 +394,8 @@
See also report_level_.
-*Default*: 4 (severe). *Options*: ``--halt``, ``--strict``.
+:Default: 4 (severe).
+:Options: ``--halt``, ``--strict`` (same as ``--halt=info``).
id_prefix
@@ -407,8 +406,8 @@
format, as it is not subjected to the `identifier normalization`_.
See also auto_id_prefix_.
-*Default*: "" (no prefix).
-*Option*: ``--id-prefix`` (hidden, intended mainly for programmatic use).
+:Default: "" (no prefix).
+:Option: ``--id-prefix`` (hidden, intended mainly for programmatic use).
input_encoding
@@ -471,11 +470,11 @@
output
------
-The path of the output destination.
-An existing file will be overwritten without warning.
-Use "-" for `stdout`.
+The path of the output destination. Use "-" for `stdout`.
-Obsoletes the `\<destination>`_ positional argument
+.. Caution:: **An existing file will be overwritten** without warning!
+
+Obsoletes the `_destination`_ positional argument
(cf. `Future changes`_ in the RELEASE-NOTES).
*Default*: None (stdout). *Option*: ``--output``.
@@ -568,18 +567,16 @@
report_level
------------
-Report system messages at or higher than <level>:
+Report system messages at or higher than the given `severity level`_:
- 1 info
- 2 warning
- 3 error
- 4 severe
- 5 none
+ 1 info, 2 warning, 3 error, 4 severe, 5 none
See also halt_level_.
:Default: 2 (warning).
-:Options: ``--report``, ``-r``, ``--verbose``, ``-v``, ``--quiet``, ``-q``.
+:Options: | ``--report``, ``-r`` (with level as number or name)
+ | ``--verbose``, ``-v`` (same as ``--report=1``)
+ | ``--quiet``, ``-q`` (same as ``--report=5``)
root_prefix
@@ -714,9 +711,10 @@
traceback
---------
-Enable or disable Python tracebacks when halt-level system messages and
-other exceptions occur. Useful for debugging, and essential for issue
-reports. Exceptions are allowed to propagate, instead of being
+Enable or disable Python tracebacks when system messages with
+a severity above the `halt_level`_ and other exceptions occur.
+Useful for debugging, and essential for issue reports.
+Exceptions are allowed to propagate, instead of being
caught and reported (in a user-friendly way) by Docutils.
:Default: None (disabled). [#]_
@@ -1140,8 +1138,8 @@
embed_stylesheet
~~~~~~~~~~~~~~~~
-Embed the stylesheet in the output HTML file. The stylesheet file
-must specified by the stylesheet_path_ setting and must be
+Embed stylesheet(s) in the HTML output. The stylesheet files
+must be specified by the stylesheet_path_ setting and must be
accessible during processing.
See also `embed_stylesheet [latex writers]`_.
@@ -1879,7 +1877,7 @@
List of style files (comma-separated_). Relative paths are expanded if a
matching file is found in the stylesheet_dirs__.
If embed_stylesheet__ is False, paths are rewritten relative to
-the output file (if output_ or `\<destination>`_ are specified)
+the output file (if output_ or `_destination`_ are specified)
or the current work directory.
Overrides also stylesheet__. [#override]_
See also `stylesheet_path [html writers]`_.
@@ -1888,7 +1886,6 @@
*Default*: empty list. *Option*: ``--stylesheet-path``.
-.. _<destination>: tools.html#usage-pattern
__ `stylesheet_dirs [latex writers]`_
__ `embed_stylesheet [latex writers]`_
__
@@ -2175,7 +2172,7 @@
[applications]
==============
-Some `front end tools`_ provide additional settings.
+The following applications (`front-end tools`_) provide additional settings.
.. _buildhtml:
@@ -2372,9 +2369,12 @@
_directories
~~~~~~~~~~~~
-(``buildhtml.py`` front end.) List of paths to source
-directories, set from positional arguments.
+Only with the `[buildhtml application]`_.
+List of paths to source directories, set from `positional arguments
+<tools.html#buildhtml-py>`__.
+
+
*Default*: None (current working directory). No command-line options.
_disable_config
@@ -2386,13 +2386,18 @@
_destination
~~~~~~~~~~~~
-Path to output destination, set from positional arguments.
+Path to output destination, set from `positional arguments`_
+or the output_ setting.
-*Default*: None (stdout). No command-line options.
+Deprecated, obsoleted by the output_ setting. Will be removed
+in Docutils 2.0 (cf. `Future changes`_ in the RELEASE-NOTES).
+*Default*: None (stdout). *Option*: ``--output``.
+
+
_source
~~~~~~~
-Path to input source, set from positional arguments.
+Path to input source, set from `positional arguments`_.
*Default*: None (stdin). No command-line options.
@@ -2502,6 +2507,8 @@
.. _publish_string(): ../api/publisher.html#publish-string
.. _publish_from_doctree(): ../api/publisher.html#publish-from-doctree
+.. _severity level: ../peps/pep-0258.html#error-handling
+
.. RestructuredText Directives
.. _"class" directive: ../ref/rst/directives.html#class
.. _"code": ../ref/rst/directives.html#code
@@ -2542,8 +2549,11 @@
.. _Docutils HTML writers: html.html
-.. _front end tools: tools.html
+.. _application:
+.. _front-end tool:
+.. _front-end tools: tools.html
.. _buildhtml.py: tools.html#buildhtml-py
+.. _positional arguments: tools.html#usage-pattern
.. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
.. _Error Handlers:
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