Skip to content

Comments

fix: correct broken backslash display and enhance escape characters section#514

Open
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
CybotTM:fix/escape-characters-section
Open

fix: correct broken backslash display and enhance escape characters section#514
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
CybotTM:fix/escape-characters-section

Conversation

@CybotTM
Copy link
Contributor

@CybotTM CybotTM commented Feb 23, 2026

Summary

  • Fix the broken backslash rendering from Fix escape character notation in RstCheatSheet #507
  • Replace the :rst: text role with inline literal (double backticks) which renders correctly
  • Add more escape examples (backticks, underscores, backslash itself)
  • Add note clarifying that escaping is not needed inside code blocks

Context

PR #507 attempted to fix the backslash display by using the :rst: text role, but as confirmed by @franzholz and @ineswillenbrock, the backslash is still not rendered.

Root cause: A backslash immediately before the closing backtick is consumed by the RST parser as an escape sequence — the text role handler never receives it. See upstream issue: TYPO3-Documentation/render-guides#1188

Fix: Use inline literal markup instead, which handles the backslash correctly:

- you must escape it with a prepended :rst:`\`.
+ you must escape it with a prepended backslash (``\``).

Test plan

  • Verify the backslash renders correctly in inline code on the rendered page
  • Verify the additional code block examples render correctly
  • Verify the ref link in the note resolves correctly

…ection

The :rst: text role cannot render a lone backslash because `\` before the
closing backtick is interpreted as an escape sequence by the RST parser.
Replace with inline literal (double backticks) and add more escape examples.

Relates: TYPO3-Documentation#507
Consolidate escape examples into a single code block with rendered
output below, following the source/result pattern used elsewhere
in the cheat sheet.
@CybotTM CybotTM marked this pull request as ready for review February 23, 2026 18:15
@franzholz
Copy link
Contributor

I would say a hint to " :rst:`\`" should be given as alternative option in the note box with the comment, that this way should work in the future.

@franzholz
Copy link
Contributor

franzholz commented Feb 24, 2026

I have tested my original commit. And it also works. Shouldn't it be mentioned as a second alternative? Then everyone can choose his preferred way.

b71a7fb

with its normal meaning, you must escape it with a prepended "\\".

@CybotTM
Copy link
Contributor Author

CybotTM commented Feb 24, 2026

I would say a hint to " :rst:\" should be given as alternative option in the note box with the comment, that this way should work in the future.

IF

:rst:`\`

finally works, which will take some time as it is complicated. We can easily update the docs. Giving a hint that something will work in the future does not really help, does it?

@franzholz
Copy link
Contributor

I think it helps to add the hint about the future for persons who are learning by reading the Docs. Then they get prepared already.

@CybotTM
Copy link
Contributor Author

CybotTM commented Feb 24, 2026

I think it helps to add the hint about the future for persons who are learning by reading the Docs. Then they get prepared already.

AFAIK there is not even a decision currently if it will be fixed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants