SF.net SVN: docutils:[9781 ] trunk/docutils

Revision: 9781
          http://sourceforge.net/p/docutils/code/9781
Author:   milde
Date:     2024-07-28 10:50:23 +0000 (Sun, 28 Jul 2024)
Log Message:
-----------
rST parser warns about empty footnotes and citations.

The reStructuredText parser now adds a "warning"-level system
message for footnotes and citations without content block
instead of generating invalid elements.

(Block-level content is mandatory for `<footnote>` and `<citation>`
elements according to the Docutils DTD.)

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docutils/parsers/rst/states.py
    trunk/docutils/test/test_parsers/test_rst/test_citations.py
    trunk/docutils/test/test_parsers/test_rst/test_footnotes.py
    trunk/docutils/test/test_writers/test_latex2e.py
    trunk/docutils/test/test_writers/test_manpage.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/HISTORY.txt	2024-07-28 10:50:23 UTC (rev 9781)
@@ -84,6 +84,10 @@
   - Renamed `normalized_role_options()` to `normalized_role_options()`
     (it is now also used for directive options).
 
+* docutils/parsers/rst/states.py
+
+  - Raise warning for empty footnotes and citations.
+
 * docutils/readers/__init__.py:
 
   - Deprecate "parser_name" argument of `Reader.__init__()`.

Modified: trunk/docutils/docutils/parsers/rst/states.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/states.py	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/docutils/parsers/rst/states.py	2024-07-28 10:50:23 UTC (rev 9781)
@@ -1913,6 +1913,8 @@
             self.document.set_id(footnote, footnote)
         if indented:
             self.nested_parse(indented, input_offset=offset, node=footnote)
+        else:
+            footnote += self.reporter.warning('Footnote content expected.')
         return [footnote], blank_finish
 
     def citation(self, match):
@@ -1930,6 +1932,8 @@
         self.document.note_explicit_target(citation, citation)
         if indented:
             self.nested_parse(indented, input_offset=offset, node=citation)
+        else:
+            citation += self.reporter.warning('Citation content expected.')
         return [citation], blank_finish
 
     def hyperlink_target(self, match):

Modified: trunk/docutils/test/test_parsers/test_rst/test_citations.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_citations.py	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/test/test_parsers/test_rst/test_citations.py	2024-07-28 10:50:23 UTC (rev 9781)
@@ -120,11 +120,14 @@
     <citation ids="citation" names="citation">
         <label>
             citation
+        <system_message level="2" line="2" source="test data" type="WARNING">
+            <paragraph>
+                Citation content expected.
     <paragraph>
         That was an empty citation.
 """],
 ["""\
-.. [citation]
+.. [citation] The Source
 No blank line.
 """,
 """\
@@ -132,6 +135,8 @@
     <citation ids="citation" names="citation">
         <label>
             citation
+        <paragraph>
+            The Source
     <system_message level="2" line="2" source="test data" type="WARNING">
         <paragraph>
             Explicit markup ends without a blank line; unexpected unindent.

Modified: trunk/docutils/test/test_parsers/test_rst/test_footnotes.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_footnotes.py	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/test/test_parsers/test_rst/test_footnotes.py	2024-07-28 10:50:23 UTC (rev 9781)
@@ -100,20 +100,24 @@
             whose block starts on line 2.
 """],
 ["""\
+An empty footnote raises a warning:
+
 .. [1]
 
-That was an empty footnote.
 """,
 """\
 <document source="test data">
+    <paragraph>
+        An empty footnote raises a warning:
     <footnote ids="footnote-1" names="1">
         <label>
             1
-    <paragraph>
-        That was an empty footnote.
+        <system_message level="2" line="4" source="test data" type="WARNING">
+            <paragraph>
+                Footnote content expected.
 """],
 ["""\
-.. [1]
+.. [1] spamalot
 No blank line.
 """,
 """\
@@ -121,6 +125,8 @@
     <footnote ids="footnote-1" names="1">
         <label>
             1
+        <paragraph>
+            spamalot
     <system_message level="2" line="2" source="test data" type="WARNING">
         <paragraph>
             Explicit markup ends without a blank line; unexpected unindent.

Modified: trunk/docutils/test/test_writers/test_latex2e.py
===================================================================
--- trunk/docutils/test/test_writers/test_latex2e.py	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/test/test_writers/test_latex2e.py	2024-07-28 10:50:23 UTC (rev 9781)
@@ -56,7 +56,6 @@
 
     def test_defaults(self):
         settings = self.settings.copy()
-        settings['validate'] = False  # we test an invalid footnote
         self.run_samples(samples_default, settings)
 
     def test_docutils_toc(self):
@@ -328,9 +327,7 @@
 ["""\
 .. [1] paragraph
 
-.. [2]
-
-.. [3] 1. enumeration
+.. [2] 1. enumeration
 """,
 # expected output
 head_template.substitute(dict(parts,
@@ -353,9 +350,7 @@
 paragraph
 }
 %
-\DUfootnotetext{footnote-2}{footnote-2}{2}{}
-%
-\DUfootnotetext{footnote-3}{footnote-3}{3}{
+\DUfootnotetext{footnote-2}{footnote-2}{2}{
 \begin{enumerate}
 \item enumeration
 \end{enumerate}

Modified: trunk/docutils/test/test_writers/test_manpage.py
===================================================================
--- trunk/docutils/test/test_writers/test_manpage.py	2024-07-28 10:50:12 UTC (rev 9780)
+++ trunk/docutils/test/test_writers/test_manpage.py	2024-07-28 10:50:23 UTC (rev 9781)
@@ -30,6 +30,7 @@
         ("[email protected]", r"me@\:home.here"),
         )
 
+
 class URIBreakpointsTestCase(unittest.TestCase):
 
     def test_insert(self):
@@ -53,7 +54,6 @@
                         settings_overrides={
                             '_disable_config': True,
                             'strict_visitor': True,
-                            'validate': False,  # allow testing invalid doctree
                         }).decode()
                     self.assertEqual(case_expected, output)
 
@@ -417,7 +417,7 @@
 
 totest['citation'] = [
         [""".. [docutils] blah blah blah
-.. [empty_citation]
+.. [citation2] Another Source
 """,
 document_start + indend_macros + """.TH "" "" "" ""
 .SH Name
@@ -424,7 +424,8 @@
  \\- \n\
 .IP [docutils] 5
 blah blah blah
-.IP [empty_citation] 5
+.IP [citation2] 5
+Another Source
 .\\" End of generated man page.
 """],
 ]

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