The Wiert Corner – irregular stream of stuff

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

  • My badges

  • Twitter Updates

    • RT @WietsedeBoer2: Als (grond)water zo schaars is, waarom krijgt dit bedrijf dan een vergunning voor oppompen van 500.000 m3 water? Ergens… 3 hours ago
    • RT @bitsoffreedom: Stel vragen! En belangrijker, dit is gewoon iets voor het kabinet om netjes te regelen, dat is beter voor de ondernemers… 3 hours ago
    • RT @Crash2411: This tweet was postmarked last month 3 hours ago
    • RT @Afelia: Mailadresse. Die politische Debatte über digitale Bildung hängt solide 15 Jahre hinterher. 3 hours ago
    • RT @TerliWetter: “Nahezu sein gesamter Maisbestand hat sich in Popcorn verwandelt. Schuld ist wohl die aktuelle Hitzewelle, die deutschland… 3 hours ago
  • 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,052 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).

–jeroen

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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: