Markdown comments

Michel Fortin michel.fortin at michelf.com
Mon Sep 18 18:26:53 EDT 2006


Le 18 sept. 2006 à 11:09, John Gruber a écrit :


> Michel Fortin <michel.fortin at michelf.com> wrote on 9/17/06 at 9:51 PM:

>

>> Maybe Markdown should do something about double-hyphens inside

>> comments. This way, a user could comment out any piece of Markdown

>> text -- like this paragraph -- without having to worry about the

>> double hyphens it contains.

>

> So what can we have it turn "--" into? An obvious answer is

> em-dashes, but then you run into the problem of text encoding.

>

> We could backslash escape them.


That could work.

But consider these two comments:

<!------ Header ------->

<!-- this -- or that -->

Your proposal would change them to:

<!--\-\-\-\- Header -\-\-\-\-\-->

<!-- this -\- or that -->

Beside not being particularly nice to read, a funny thing is that the
first hyphen of the `-->` delimiter has to be "escaped", as you say
it, which just seems strange. I think the backslash in this case
should be called a separator, not an escape character.

I note that your backslash-"escape" method ensure that we are able to
reconstruct the comment in its original form. Any reason this would
be needed? If that's not needed then there is no need to escape
already existing backslashes.

And even if reconstructability is the goal, there is no real need to
compulsively escape all the backslashes either. It would be better to
simply consider the backslash character as a separator between two
hyphens, and if two hyphen are already separated by a backslash in
the original you could just add one more backslash between the two.

This

<!--\\---\- Hello\There\- ----->

could be turned into this:

<!--\\\-\-\-\\- Hello\There\- -\-\-\-->

using this regex on the comment text (text without comment delimiters):

s{(^|-)(\\*)(?=-|$)}{\1\2\\}

and turned back using:

s{(^|-)(\\*)\\(?=-|$)}{\1\2}


- - -

I think however that it is important is to keep things readable, and
I'd prefer using something less distracting than a backslash as a
separator. Using the same technique as shown above, spaces could be
used as the separator instead of backslashes. Regexes like this:

s{(^|-)( *)(?=-|$)}{\1\2 }

s{(^|-)( *) (?=-|$)}{\1\2}

would make this:

<!------ Header ------->

<!-- this -- or that -->

become:

<!-- - - - - Header - - - - - -->

<!-- this - - or that -->

and it would still be possible to rebuild the original by removing
exactly one space between each pair of hyphen.

That said, I don't think being able to rebuild the original is that
much important. Personally, I'd simply remove the extra hyphens, like
this:

<!-- Header -->

<!-- this - or that -->

Or maybe replace multiple hyphens with the same number of characters
as a sequence of hyphens and spaces (or any other sequence) too keep
the original proportions of the comment text:

<!-- - - Header - - -->

<!-- this - or that -->

But whatever technique we choose, I think it is essential that the
author be able to understand how it was transformed, that the
transformation does not affect anything not containing hyphens, and
that the comment be still be easily readable whatever how much
hyphens the original content has.

- - -

About commented scripts. This practice may not be recommended, it is
still widely in use and I think we shouldn't break it. And since the
Markdown syntax should not be processed within `<script>` tags, it
should not "fix" comments there either, it's that simple.


Michel Fortin
michel.fortin at michelf.com
http://www.michelf.com/




More information about the Markdown-Discuss mailing list