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,975 other subscribers

Archive for the ‘reStructuredText’ Category

Create table without header in markdown/reStructuredText?

Posted by jpluimers on 2020/06/12

It looks like few of the markdown parsers can generate a table without a header: [WayBack] Create table without header in markdown – Stack Overflow.

This comes close in some generators as they generate a half-height empty header for it:

| | | |
| Normal Key| Value1 |
|__BoldKey__| Value2 |

But [WayBack] reStructuredText Markup Specification: Grid Tables do support it even if a pipe cell delimiter is inside a cell content:

| row 1, col 1 | column 2 | column 3  | column 4  |
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
| row 3        |          |           |           |



Posted in Development, Lightweight markup language, MarkDown, reStructuredText, Software Development | Leave a Comment »

Reminder: try to get vscode-restructuredtext to fully work – reStructuredText Language Support in Visual Studio Code

Posted by jpluimers on 2020/04/23

I love Visual Studio Code, but my initial tries to get [WayBack] GitHub Рvscode-restructuredtext/vscode-restructuredtext: reStructuredText Language Support in Visual Studio Code to work partially failed: editing works, but I got a non-descriptive error during preview.

All prerequisites are installed, so I needed to pause that for a while.

I still want it, as out of the box, [WayBack] Markdown editing with Visual Studio Code: Markdown Preview  works fine, but for complicated documents I tend to use reStructuredText.

Initial steps were simple, as per [WayBack] reStructuredText РVisual Studio Marketplace and editing is awesome (thanks to [WayBack] GitHub Рlextm/restructuredtext-antlr: ANTLR Grammar for reStructuredText).


Read the rest of this entry »

Posted in .NET, Development, Lightweight markup language, reStructuredText, Software Development, Visual Studio and tools, vscode Visual Studio Code | Leave a Comment »

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

Read the rest of this entry »

Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »

reStructuredText – document title and subtitle

Posted by jpluimers on 2020/04/21

Always watch how you format your reStructuredText sections: [WayBack] Docutils FAQ: 2.6 How can I indicate the document title? Subtitle?

That is why I have these comments at the top of most of my documents:

.. $ %
.. # * = + ^ ~ - : . _ ` ' "

The first two are the document title and subtitle marks, the others the level 1 through 13.


Posted in Development, Lightweight markup language, Power User, reStructuredText | Leave a Comment »

Converting html fragments to reStructuredText

Posted by jpluimers on 2019/01/09

Though normally you would write documentation in reStructuredText, then generate HTML or PDF, often you find a part of the documentation source in HTML.

Here are some sites and tools I’ve used to convert HTML fragments to reStructuredText. I favour on-line over local command-line tools as usually these kinds of conversions are “one-time only”.


Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »

%d bloggers like this: