The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My badges

  • Twitter Updates

  • My Flickr Stream

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 2,481 other followers

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:

  1. 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.
  2. 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 __:

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).


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: