doc: properly handle preformatted blocks #8242
Open
+15
−11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Lowdown requires a blank line before all preformatted blocks, or it doesn't recognize them. `tools/md2man.sh` contained some ad-hoc efforts at fixing up some locations where these required blank lines are absent from the output of `tools/fromschema.py`, but it missed some. Instead of playing Whack-a-Mole, use a blanket sed expression to ensure that a blank line precedes _every_ opening ```. `esc_underscores(…)` in `tools/fromschema.py` did not work correctly on strings containing an odd number of backticks, notably the ``` delimiters surrounding preformatted text blocks. Specifically, it was dropping the last backtick since none of the alternatives in the regex matched it. Add a new alternative that matches a whole preformatted block as a single unit. `output_member(…)` in `tools/fromschema.py` was passing each line of a member's description through `esc_underscores(…)` individually, but that breaks preformatted text blocks that are naturally multi-line and leads to mistakenly escaping underscores inside such blocks. Rewrite the code to make use of the `outputs(…)` utility function that joins all the provided lines together before passing the whole text through `esc_underscores(…)`. Drive-by fix a couple of flubbed preformatted blocks in schemas. Changelog-None
whitslack
changed the title
\\preformatted blocks\\\
| @@ -21,7 +21,7 @@ def output_title(title, underline='-', num_leading_newlines=1, num_trailing_newl | |||
|
|
|||
| def esc_underscores(s): | |||
| """Backslash-escape underscores outside of backtick-enclosed spans""" | |||
| return ''.join(['\\_' if x == '_' else x for x in re.findall(r'[^`_\\]+|`(?:[^`\\]|\\.)*`|\\.|_', s)]) | |||
| return ''.join(['\\_' if x == '_' else x for x in re.findall(r'(?ms:^[ \t]*```.*?^[ \t]*```)|[^`_\\\n]++|`(?:[^`\\]|\\.)*`|\\.|[_\n]', s)]) | |||
There was a problem hiding this comment.
"++" here is wrong:
re.error: multiple repeat at position 40
There was a problem hiding this comment.
Hmm. Are you using a very old version of Python? The ++ (possessive one-or-more) quantifier works on Python 3.11.12, 3.12.10, and 3.13.3, but it gives the error you quoted on Python 3.10.17. Do you really need to maintain compatibility with ancient versions of Python? Possessive quantifiers avoid needlessly backtracking when we know that backtracking will not find any new matches, although, now that I am looking at this again, I don't think it's going to make any difference in this case since there are no assertions after that repeat, so no backtracking would ever be attempted even if the quantifier were non-possessive.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Lowdown requires a blank line before all preformatted blocks, or it doesn't recognize them.
tools/md2man.shcontained some ad-hoc efforts at fixing up some locations where these required blank lines are absent from the output oftools/fromschema.py, but it missed some. Instead of playing Whack-a-Mole, use a blanket sed expression to ensure that a blank line precedes every opening ```.esc_underscores(…)intools/fromschema.pydid not work correctly on strings containing an odd number of backticks, notably the ``` delimiters surrounding preformatted text blocks. Specifically, it was dropping the last backtick since none of the alternatives in the regex matched it. Add a new alternative that matches a whole preformatted block as a single unit.output_member(…)intools/fromschema.pywas passing each line of a member's description throughesc_underscores(…)individually, but that breaks preformatted text blocks that are naturally multi-line and leads to mistakenly escaping underscores inside such blocks. Rewrite the code to make use of theoutputs(…)utility function that joins all the provided lines together before passing the whole text throughesc_underscores(…).Drive-by fix a couple of flubbed preformatted blocks in schemas.
Checklist
Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked: