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

[<go...@us...>]

Revision: 8172
          http://sourceforge.net/p/docutils/code/8172
Author:   goodger
Date:     2017-08-17 22:28:42 +0000 (Thu, 17 Aug 2017)
Log Message:
-----------
Added a test case and updated docs/ref/rst/restructuredtext.txt for interpreted text in field list field names.

Modified Paths:
--------------
    trunk/docutils/docs/ref/rst/restructuredtext.txt
    trunk/docutils/test/test_parsers/test_rst/test_field_lists.py

Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt	2017-08-17 15:58:23 UTC (rev 8171)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt	2017-08-17 22:28:42 UTC (rev 8172)
@@ -832,7 +832,9 @@
 RFC822_ headers.  A field name may consist of any characters, but
 colons (":") inside of field names must be backslash-escaped
 when followed by whitespace.
-Inline markup is parsed in field names.  Field names are
+Inline markup is parsed in field names, but care must be taken when
+using `interpreted text`_ with explicit roles in field names: the role
+must be a suffix to the interpreted text.  Field names are
 case-insensitive when further processed or transformed.  The field
 name, along with a single colon prefix and suffix, together form the
 field marker.  The field marker is followed by whitespace and the
@@ -2651,7 +2653,29 @@
 custom interpreted text roles.  In addition, applications may support
 specialized roles.
 
+In `field lists`_, care must be taken when using interpreted text with
+explicit roles in field names: the role must be a suffix to the
+interpreted text. The following are recognized as field list items::
 
+    :`field name`:code:: interpreted text with explicit role as suffix
+
+    :a `complex`:code:\  field name: a backslash-escaped space
+                                     is necessary
+
+The following are **not** recognized as field list items::
+
+    ::code:`not a field name`: paragraph with interpreted text
+
+    :code:`not a field name`: paragraph with interpreted text
+
+Edge cases::
+
+    :field\:`name`: interpreted text (standard role) requires
+                    escaping the leading colon in a field name
+
+    :field:\`name`: not interpreted text
+
+
 Inline Literals
 ---------------
 

Modified: trunk/docutils/test/test_parsers/test_rst/test_field_lists.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_field_lists.py	2017-08-17 15:58:23 UTC (rev 8171)
+++ trunk/docutils/test/test_parsers/test_rst/test_field_lists.py	2017-08-17 22:28:42 UTC (rev 8172)
@@ -588,6 +588,94 @@
                 <paragraph>
                     not interpreted text
 """],
+[r"""
+Edge cases involving embedded colons and interpreted text.
+
+Recognized as field list items:
+
+:field\:`name`: interpreted text (standard role) requires
+                escaping a leading colon in a field name
+
+:field:name: unambiguous, no need for escapes
+
+:field::name: double colons are OK, too
+
+:field:\`name`: not interpreted text
+
+:`field name`:code:: interpreted text with role in the field name
+                     works only when the role follows the text
+
+:a `complex`:code:\  field name: field body
+
+Not recognized as field list items:
+
+::code:`not a field name`: paragraph with interpreted text
+
+:code:`not a field name`: paragraph with interpreted text
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Edge cases involving embedded colons and interpreted text.
+    <paragraph>
+        Recognized as field list items:
+    <field_list>
+        <field>
+            <field_name>
+                field:
+                <title_reference>
+                    name
+            <field_body>
+                <paragraph>
+                    interpreted text (standard role) requires
+                    escaping a leading colon in a field name
+        <field>
+            <field_name>
+                field:name
+            <field_body>
+                <paragraph>
+                    unambiguous, no need for escapes
+        <field>
+            <field_name>
+                field::name
+            <field_body>
+                <paragraph>
+                    double colons are OK, too
+        <field>
+            <field_name>
+                field:`name`
+            <field_body>
+                <paragraph>
+                    not interpreted text
+        <field>
+            <field_name>
+                <literal classes="code">
+                    field name
+            <field_body>
+                <paragraph>
+                    interpreted text with role in the field name
+                    works only when the role follows the text
+        <field>
+            <field_name>
+                a 
+                <literal classes="code">
+                    complex
+                 field name
+            <field_body>
+                <paragraph>
+                    field body
+    <paragraph>
+        Not recognized as field list items:
+    <paragraph>
+        :
+        <literal classes="code">
+            not a field name
+        : paragraph with interpreted text
+    <paragraph>
+        <literal classes="code">
+            not a field name
+        : paragraph with interpreted text
+"""],
 ]
 
 if __name__ == '__main__':

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