Reduce Number of Tildes Produced by `!src()`

[tajmone]

I'm working on a PP tutorial, in GFM markdown, and I'm having lots of trouble trying to represent a code block which contains in itself a fenced code block produced by !src() macro. Here is the tutorial in question:

https://github.com/tajmone/markdown-guide/blob/2f8b50a/pp/tutorial_01.md#our-first-usage-test

Because of the excessive number of tildes (70 tildes):

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c}

... wrapping !src()'s output inside a fenced code block seems to fail on GitHub's preview. I've tried to enclose the block within fences with a higher number of tildes, but didn't work. Maybe there is a limit to the number of tildes (or backticks) that are taken into account by different markdown parsers, or maybe it's just too hard to keep track of such a high number of tildes. Whatever the reason, I found it hard to handle it.

Possibly, 3 tildes would be an easier amount to handle, and it would only require >=4 tildes to wrap the example in a fenced code block, so that the parsers doesn't mistake those tildes for the end of the code block.

Referencing pandoc's guide:

http://pandoc.org/MANUAL.html#fenced-code-blocks

In addition to standard indented code blocks, pandoc supports fenced code blocks. These begin with a row of three or more tildes (~) and end with a row of tildes that must be at least as long as the starting row.

Then follows an example wrapped in 6 tildes:

if (a > 3) { moveShip(5 * gravity, DOWN); }

Then it states:

If the code itself contains a row of tildes or backticks, just use a longer row of tildes or backticks at the start and end:

and as an example it wraps a 10-tildes block in 15 tildes:

code including tildes

70 tildes are by far too many, much more than required, and can pose a problem when needing to enclose them in another code block, because it would require more than 71 tildes/backticks. I'm not sure if there are other built-in PP macros that output fenced-code tildes, but I suggest a consistent reduction of their number wherever they occur (4-10 would be a more manageable number).

[tajmone]

As for the failure to render the block correctly, it seems a bug in GitHub's markdown previewer, and not related to the high number of tildes. I opened an issue for it: github/markup#1003.

Strangely, in GitHub's issues markdown preview the same code block is shown correctly.

That said, the issue of 70 tildes being difficoult to handle still applies.

[CDSoft]

70 tildes is an absolutely arbitrary length. It is supposed to be enough to enclose smaller rows of tildes in the source code it produces. I have not though about a use case of embedding source output into an outer block. Maybe a solution would be to have a parameter to define this length (as well as the choice between tildes and backticks?). I'll think about it.

[tajmone]

I agree that having a rather long row of tildes is more pleasing to the eye and helps to better frame a block of code. It is also true that to visually separate nested code blocks there should be a difference in the number of tildes that is proportional to their length.

Technically speaking, a minum of 3 tildes is required, and a container block would only need an extra tilde to wrap the inner block. But a single tilde is not enough to tell at a glance which fence belongs to what — for a 3-tildes block, a 6-tildes outer block would be visually easier to spot. So, for 10-tildes, the outer containters would have to add at least 5 tildes.

Which means that for a 70-tildes fenced line, outer blocks would require at lease 10 to 15 more tildes to be easily spotted as container blocks!

Anything above 70 characters is approaching the default wrapping value of 80 (at least, many markdown applications assume 80, or 78, as the default wrapping value). Some parsers don't handle well wrapping, and they might truncate with a new-line a sequence of unspaced same-characters tha exceeds wrapping limit (even within code/verbatim blocks). This is especially true when multiple tools are chained together (or custom pandoc filters, ecc.). This shouldn't happen ... but it does; and the proliferation of many markdown flavours, along with the lack of "official" guidelines for markdown format and parsing doesn't help either when it comes to how edge-cases are implemented.

[CDSoft]

I have pushed a new version with the macro codeblock that defines the line used to separate codeblocks.

e.g.: \codeblock(3) or \codeblock(3)(~) to use 3 tilda or \codeblock(6)(`) to use 6 backticks.

[tajmone]

Thanks a lot, it was really kind of you!

I really appreciate it. Also, choosing between tildes and backticks is a good enhancement!