[Docutils-checkins] SF.net SVN: docutils:[9478] trunk/docutils

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 9478
          http://sourceforge.net/p/docutils/code/9478
Author:   milde
Date:     2023-11-18 22:04:20 +0000 (Sat, 18 Nov 2023)
Log Message:
-----------
Various small documentation edits.

Format hyperlink targets,
more precise explanation of the "include" directive's `:tab-width:` option,
comments and explanations.

Modified Paths:
--------------
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/ref/rst/directives.txt
    trunk/docutils/docutils/writers/html5_polyglot/__init__.py
    trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================

--- trunk/docutils/RELEASE-NOTES.txt	2023-11-18 21:48:30 UTC (rev 9477)
+++ trunk/docutils/RELEASE-NOTES.txt	2023-11-18 22:04:20 UTC (rev 9478)
@@ -188,8 +188,6 @@
   configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
   Do not remove other ZWNBSPs.
 
-  .. _input encoding: docs/api/publisher.html#encodings
-
 * "html5" writer:
   Stop setting the "footnote-reference" class value for footnote references.
   You can use the CSS selector ``[role="doc-noteref"]``
@@ -207,6 +205,7 @@
 
   - File ``install.py``. See README.txt__ for alternatives.
 
+.. _input encoding: docs/api/publisher.html#encodings
 .. _csv-table: docs/ref/rst/directives.html#csv-table
 __ README.html#installation
 
@@ -244,8 +243,6 @@
     are now ignored by the "xetex" writer.
     Place common settings in section `[latex writers]`_.
 
-    .. _[latex writers]: docs/user/config.html#latex-writers
-
   - New command line setting output_. Obsoletes the ``<destination>``
     positional argument (cf. `future changes`__).
 
@@ -264,8 +261,6 @@
   - Removed. Use the coverage.py_ project instead,
     ``coverage run test/alltests.py`` and ``coverage report``.
 
-  .. _coverage.py: https://pypi.org/project/coverage/
-
 * tools/
 
   - Moved ``quicktest.py`` to ``tools/dev/``.
@@ -272,7 +267,9 @@
 
 * Bugfixes and improvements (see HISTORY_).
 
+.. _[latex writers]: docs/user/config.html#latex-writers
 .. _output: docs/user/config.html#output
+.. _coverage.py: https://pypi.org/project/coverage/
 
 
 Release 0.19 (2022-07-05)
@@ -293,9 +290,6 @@
 * After package installation, the CLI commands ``python -m docutils`` and
   ``docutils`` start the `generic command line front end tool`_.
 
-  .. _generic command line front end tool:
-      docs/user/tools.html#generic-command-line-front-end
-
 * Support parsing "Markdown" input with 3rd party parsers
   myst_, pycmark_, or recommonmark_.
 
@@ -306,6 +300,8 @@
 
 * Various bugfixes and improvements (see HISTORY_).
 
+.. _generic command line front end tool:
+    docs/user/tools.html#generic-command-line-front-end
 .. _myst: https://pypi.org/project/myst-docutils
 .. _pycmark: https://pypi.org/project/pycmark/
 .. _recommonmark: https://pypi.org/project/recommonmark/
@@ -358,7 +354,6 @@
       widths, if the `"widths" option`_ is set and not "auto".
       The table-style__ setting "colwidths-grid" restores the current default.
 
-      .. _"widths" option: __ docs/ref/rst/directives.html#table
       __ docs/user/config.html#table-style
 
     - Items of a definition list with class argument "details" are
@@ -394,6 +389,8 @@
 
 * New standard Docutils doctree node: <meta__>.
 
+  __ docs/ref/doctree.html#meta
+
 * New configuration settings:
 
   - [latex writers] legacy_column_widths_ and
@@ -429,9 +426,9 @@
   Fix spelling errors in documentation and docstrings.
   Thanks to Dimitri Papadopoulos.
 
-__ docs/ref/doctree.html#meta
+.. _"widths" option: __ docs/ref/rst/directives.html#table
 .. _identifier normalization:
-   docs/ref/rst/directives.html#identifier-normalization
+    docs/ref/rst/directives.html#identifier-normalization
 .. _id_prefix: docs/user/config.html#id-prefix
 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
 .. _details disclosure elements:
@@ -545,9 +542,6 @@
     "html4" or "html5" (deprecated in favour of the `"writer" setting`_
     in Docutils 0.18).
 
-  .. _"writer" setting:
-     docs/user/config.html#writer-buildhtml-application
-
 * docutils/io.py
 
   - Remove the `handle_io_errors` argument from io.FileInput/Output.
@@ -556,11 +550,12 @@
 
   - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.
 
-  .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
-
 * Various bugfixes and improvements (see HISTORY_).
 
+.. _"writer" setting: docs/user/config.html#writer-buildhtml-application
+.. _auto_id_prefix: docs/user/config.html#auto-id-prefix
 
+
 Release 0.15 (2019-07-20)
 =========================
 
@@ -641,8 +636,6 @@
 
   - New HTML writer generating `HTML 5`_.
 
-  .. _HTML 5: https://www.w3.org/TR/html5/
-
 * tools/
 
   - New front-end ``rst2html5.py``.
@@ -658,7 +651,9 @@
 
 * rst.el: The problem with ``electric-indent-mode`` has been fixed.
 
+.. _HTML 5: https://www.w3.org/TR/html5/
 
+
 Release 0.12 (2014-07-06)
 =========================
 
@@ -695,8 +690,6 @@
   - Avoid repeated class declarations in html4css1 writer
     (modified version of patch [ 104 ]).
 
-  .. _math-output: docs/user/config.html#math-output
-
 * docutils/writers/latex2e/__init__.py
 
   - Drop the simple algorithm replacing straight double quotes with
@@ -706,13 +699,15 @@
     where stylesheets are found. Used by `stylesheet_path` when expanding
     relative path arguments.
 
-  .. _SmartQuotes: docs/user/config.html#smart-quotes
-
 * docutils/writers/manpage.py
 
   - Fix [3607063] handle lines starting with a period.
   - Fix option separating comma was bold (thanks to Bill Morris).
 
+.. _math-output: docs/user/config.html#math-output
+.. _SmartQuotes: docs/user/config.html#smart-quotes
+
+
 Release 0.10 (2012-12-16)
 =========================
 
@@ -909,9 +904,9 @@
   - Drop the special `output_encoding`__ default ("latin-1").
     The Docutils wide default (usually "UTF-8") is used instead.
 
-__ docs/user/config.html#docutils-footnotes
-__ docs/user/latex.html#hyperlinks
-__ docs/user/latex.html#output-encoding
+  __ docs/user/config.html#docutils-footnotes
+  __ docs/user/latex.html#hyperlinks
+  __ docs/user/latex.html#output-encoding
 
 * manpage writer:
 
@@ -951,9 +946,9 @@
     (aligning the figure not its contents).
   - Align images with class "align-[right|center|left]"
     (allows setting the alignment of an image in a figure).
-  - Hard tabs in literal inclusions are replaced by spaces. This is
-    configurable via the new "tab-width" option of the "include" directive
-    (a negative tab-width prevents tab expansion).
+  - Hard tabs **in literal inclusions** are replaced by spaces.
+    This is configurable via the new ``:tab-width:`` option of the
+    `"include" directive`_ (a negative tab-width prevents tab expansion).
 
 * HTML writer:
 
@@ -993,7 +988,10 @@
 
   - moved from sandbox to Doctutils core.
 
+.. _"include" directive:
+    docs/ref/rst/directives.html#including-an-external-document-fragment
 
+
 Release 0.5 (2008-06-25)
 ========================
 

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2023-11-18 21:48:30 UTC (rev 9477)
+++ trunk/docutils/docs/ref/rst/directives.txt	2023-11-18 22:04:20 UTC (rev 9478)
@@ -1512,8 +1512,9 @@
 
 ``tab-width`` : integer_
     Number of spaces for hard tab expansion.
-    A negative value prevents expansion of hard tabs. Defaults to the
-    tab_width_ configuration setting.
+    Must be a positive integer, except for literal inclusions and code,
+    where a negative value prevents expansion of hard tabs. 
+    Defaults to the tab_width_ configuration setting.
 
     .. _tab_width: ../../user/config.html#tab-width
 

Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2023-11-18 21:48:30 UTC (rev 9477)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2023-11-18 22:04:20 UTC (rev 9478)
@@ -284,11 +284,13 @@
     def visit_inline(self, node):
         classes = node['classes']
         node.html5tagname = 'span'
+        # Special handling for "code" directive content
         if (isinstance(node.parent, nodes.literal_block)
             and 'code' in node.parent.get('classes')
             or isinstance(node.parent, nodes.literal)
             and getattr(node.parent, 'html5tagname', None) == 'code'):
             if classes == ['ln']:
+                # line numbers are not part of the "fragment of computer code"
                 if self.body[-1] == '<code>':
                     del self.body[-1]
                 else:

Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py	2023-11-18 21:48:30 UTC (rev 9477)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py	2023-11-18 22:04:20 UTC (rev 9478)
@@ -38,6 +38,8 @@
 
 
 class ParserTestCase(unittest.TestCase):
+    maxDiff = None
+
     def test_parser(self):
         # eventually skip optional parts:
         if not with_pygments:
@@ -1035,7 +1037,7 @@
                :end-before: mork of ork
 """],
 [f"""\
-TAB expansion with literal include:
+Default TAB expansion with literal include:
 
 .. include:: {include_literal}
    :literal:
@@ -1043,7 +1045,7 @@
 f"""\
 <document source="test data">
     <paragraph>
-        TAB expansion with literal include:
+        Default TAB expansion with literal include:
     <literal_block source="{include_literal}" xml:space="preserve">
         Literal included this should **not** be *marked* `up`.
                 <- leading raw tab.
@@ -1192,7 +1194,7 @@
         .
 """],
 [f"""\
-TAB expansion with included code:
+Default TAB expansion with included code:
 
 .. include:: {include_literal}
    :code: rst
@@ -1200,7 +1202,7 @@
 f"""\
 <document source="test data">
     <paragraph>
-        TAB expansion with included code:
+        Default TAB expansion with included code:
     <literal_block classes="code rst" source="{include_literal}" xml:space="preserve">
         Literal included this should \n\
         <inline classes="generic strong">
@@ -1228,7 +1230,7 @@
 """ if PYGMENTS_2_14_PLUS else f"""\
 <document source="test data">
     <paragraph>
-        TAB expansion with included code:
+        Default TAB expansion with included code:
     <literal_block classes="code rst" source="{include_literal}" xml:space="preserve">
         Literal included this should \n\
         <inline classes="generic strong">
@@ -1303,7 +1305,7 @@
         normalized.
 """],
 [f"""\
-Custom TAB expansion with included code:
+No TAB expansion with included code:
 
 .. include:: {include_literal}
    :code: rst
@@ -1312,7 +1314,7 @@
 f"""\
 <document source="test data">
     <paragraph>
-        Custom TAB expansion with included code:
+        No TAB expansion with included code:
     <literal_block classes="code rst" source="{include_literal}" xml:space="preserve">
         Literal included this should \n\
         <inline classes="generic strong">
@@ -1340,7 +1342,7 @@
 """ if PYGMENTS_2_14_PLUS else f"""\
 <document source="test data">
     <paragraph>
-        Custom TAB expansion with included code:
+        No TAB expansion with included code:
     <literal_block classes="code rst" source="{include_literal}" xml:space="preserve">
         Literal included this should \n\
         <inline classes="generic strong">

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



