Repository navigation
Clarify nested inline metadata blocks - #2138
jw9829 wants to merge 1 commit into
Conversation
Sorry, something went wrong.
rgommers
left a comment
There was a problem hiding this comment.
Thanks for working on this @jw9829. I checked the history in gh-1960: the greedy behavior was deliberate, and the closing-marker precedence paragraph and C# example were added specifically to explain it. So a clarification to the text is correct in principle.
The proposed sentence is accurate, but doesn't quite address the surprising part of gh-1960. Its examples already have a closing marker before the second opener. What's unclear is why that apparent closing marker becomes content.
Here is a suggested revision. This also changes # /// text to # /// text. so the example doesn’t conflict with the prohibition on nested openers.
@@
- # /// text
+ # /// text.
@@
A starting line MUST NOT be placed between another starting line and its ending
-line. The reference regular expression treats a second starting line as content
-of the existing block, not as a new block. Tools MAY produce an error in this
-case. Unclosed blocks MUST be ignored.
+line. In such cases tools MAY produce an error. Unclosed blocks MUST be ignored.
@@
In circumstances where there is a discrepancy between the text specification
and the regular expression, the text specification takes precedence.
+The regular expression intentionally matches greedily, using the last possible
+ending line within an uninterrupted sequence of valid embedded content lines.
+This permits a standalone ``///`` within embedded content, as in the C# example
+above; non-greedy matching would truncate that example. Consequently, apparent
+blocks separated only by valid embedded content lines, including ``#``, are
+matched as one block, with intervening delimiters included as content. An actual
+blank line separates blocks; multiple separate blocks of the same type remain
+an error.
+
Sorry, something went wrong.
Reviewers
Requested changes must be addressed to merge this pull request.
The reference regex treats a second starting line before the closing line as content of the existing block.
Fixes #1960.
📚 Documentation preview 📚: https://python-packaging-user-guide--2138.org.readthedocs.build/en/2138/