Markdown comments

[Michel Fortin]

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/