Leading/trailing whitespace in inline <code>

[Aristotle Pagaltzis]

Hi Dan,

* Dan <markdown-discuss at drmoose.net> [2018-08-24 15:29]:
> I'm trying to document a codebase in markdown, and finding it
> difficult to include links inside my code examples. If I were writing
> HTML, I'd write:
>
> <code>perl <a href="https://daringfireball.net/projects/markdown/">Markdown.pl</a> < input.md</code>

that’s exactly what you should write in Markdown as well.

Markdown is HTML. There is a reason it doesn’t have as much syntax as
things like Textile and reStructuredText and it’s right there in the
name: unlike these others, Markdown is *not* a markup language. It’s
just HTML with some shorthand notations on top. That’s why it allows you
to just write HTML tags in your text as if it was HTML… because, it is.

So if there is no shorthand notation that does what you need, just use
the long form: HTML tags.

Consider the reason that Markdown has the backtick code span syntax:
because HTML makes it difficult to write about code – because you need
to entity-escape some very common characters. To fix that problem, the
shorthand syntax must disallow markup inside code, so that no characters
have special meaning, so that no characters need to be escaped.

Now consider your use case: you *want* to put markup inside your code.
That means you need *some* way to make *some* characters special. That
means your particular use case contradicts the requirements for the code
span shorthand.

Now, it would be possible to try and shoehorn something into the syntax
that would make it worse for its purpose (because suddenly you have to
escape some characters) but would allow putting markup into code. But
wait… marking up code is already what HTML is good at. So this would
just be a poor reinvention of HTML. Your use case is already covered
perfectly well by what HTML by itself already allows.

So, just use the HTML way of writing it. HTML is the right tool for your
job.

> But, there doesn't seem to be a way to achieve this in Markdown,
> because any markup i include inside backticks gets HTML encoded (as it
> should). The closest I can do in markdown is:
>
> `perl` [`Markdown.pl`](https://daringfireball.net/projects/markdown/)
> `< input.md`
>
> Which renders as
>
> <p><code>perl</code> <a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a> <code>< input.md</code></p>
>
> but is fraught with style issues. Not only is a space a different
> width outside <code>, but the theme I'm using puts a background and
> borders on code tags.
>
> As a workaround, would you be willing to allow _DoCodeSpans to
> preserve leading & trailing white space inside the backticks?
>
> --- Markdown.pl.orig	2018-08-24 08:47:13.603707569 -0400
> +++ Markdown.pl	2018-08-24 08:48:46.949349781 -0400
> @@ -983,8 +983,6 @@
>  			(?!`)
>  		@
>   			my $c = "$2";
> - 			$c =~ s/^[ \t]*//g; # leading whitespace
> - 			$c =~ s/[ \t]*$//g; # trailing whitespace
>   			$c = _EncodeCode($c);
>  			"<code>$c</code>";
>  		@egsx;
>
> With this patch, markdown like this:
>
> `perl `[`Markdown.pl`](https://daringfireball.net/projects/markdown/)` < input.md`
>
> renders as
>
> <p><code>perl </code><a href="https://daringfireball.net/projects/markdown/"><code>Markdown.pl</code></a><code> < input.md</code></p>
>
> with the whitespace inside the <code> and no space between the </code>
> and the <a>, making it easier to clean up the look of the resulting
> webpage with CSS.

That request would break other Markdown syntax.

Did you know you can write `` ` `` characters inside code spans without
escaping them? Your patch would make that translate into

    <code> ` </code>

which makes this feature pretty useless.

This design is because after disallowing all markup inside code spans,
there is still one remaining problem with not requiring the author to
escape anything inside code spans: how do you make it possible to write
backticks inside code spans? And without requiring them to be escaped?

Markdown’s answer is: by allowing code spans to be delimited not just
with single backticks but by a sequence of backticks of whatever length
the author wants. Then the author can just write a greater number of
backticks as a delimiter than there are any backticks in a row anywhere
in the code, and then nothing in the code needs to be escaped.

But if the code itself starts with a backtick, how is Markdown to know
where the delimiter ends and the code starts? You have to set apart the
end of the delimiter and the start of the code. The obvious way to do
that is to put a space between the delimiter and the code.

*However* – and now we finally get to the problem with your proposal –,
this space is not part of the code. It’s part of the delimiter. It only
exists in the document because of the Markdown syntax rules, not because
it is part of the code. So it *must not* be in the output.

And that is why your patch to _DoCodeSpans is wrong.

Now, it might be possible to salvage your proposal by introducing an
exception, that trimming spaces from code spans only applies when more
than a single backtick is used as the delimiter. But that would make the
rules more complicated, and it only allows you to use your workaround,
which is pretty cruddy anyway – you’re writing multiple code spans where
there really is only one piece of code.

Write it with HTML tags.

That’s really your answer.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>