When pandoc on a reStructuredText document gives “(WARNING/2) Inline substitution_reference start-string without end-string.”
Posted by jpluimers on 2020/04/22
When fixing some of the Pandoc conversion messages from … to html, I got this warning:
Network-Protocol-Security.rst:917: (WARNING/2) Inline substitution_reference start-string without end-string.
In my experience, the line numbers do not usually match, but in this case it was accurate (not the same as Network-Protocol-Security.rst#L874 because I was still editing it).
A search for “Inline substitution_reference start-string without end-string.” did only reveal occurrences, not causes, but “Inline substitution_reference start-string without end-string”
showed post with a cause: [WayBack] python sphinx – How to include an internal reference in a code block? – Stack Overflow pointing to [WayBack] reStructuredText Markup Specification: Substitution References.
Solution is either to
- Escape
|_using a backslash like\|-. - Properly format code blocks using
::at the front and indents of the block
Lessons learned:
- When you get a pandoc message like
substitution_reference, then search for it while substituting the underscore with a space inside the [WayBack] reStructuredText Markup Specification. - Quoted strings to trim down Google search results, but you might want to leave out trailing punctuation.
Applying the lessons
I could apply the first lesson directly in a different form, when fixing Network-Protocol-Security.rst:2: (WARNING/2) Duplicate explicit target name: "wayback". tracing it back to Network-Protocol-Security.rst#L766 and these pieces of documentation by first searching for target name, then for _` and finally for `_ and __:
- [WayBack] reStructuredText Markup Specification: Inline Internal Targets.
- [WayBack] reStructuredText Markup Specification: Reference Names.
- [WayBack] reStructuredText Markup Specification: Hyperlink References.
- [WayBack] reStructuredText Markup Specification: Embedded URIs and Aliases.
Solution: ensure that hyperlink references are anonymous: do not end them with `_ (named), but with `__ (unnamed/anonymous).
This solves not only the warnings, but also the effect that the [WayBack] links at Network-Protocol-Security.rst#obtaining-binary-libssh2dll all pointed to the same URL (the first URL of the WayBack as that was the initial name).
–jeroen
Leave a Reply