Re: [ANN] bluecloth-2.0.0 released

On Apr 8, 2009, at 5:15 PM, matt neuburg wrote:

> Cool, but my response to this is the same as my response to RDiscount.
> I'm deeply invested in years of using the original Perl Markdown. I'd
> love to get off that, but in order for me to do so, it isn't enough  
> that
> a Markdown clone pass some abstract tests; it must generate HTML  
> that is
> functionally identical to the HTML that Perl Markdown generates from  
> the
> same original text. Discount, and therefore BlueCloth 2, does not.

You're absolutely correct -- Discount (and therefore anything based on  
it) generates HTML according to the Markdown Syntax Documentation (http://daringfireball.net/projects/markdown/syntax 
) and the MarkdownTest test suite released by John Gruber (http://six.pairlist.net/pipermail/markdown-discuss/2006-June/000079.html 
), and not necessarily according to what Markdown.pl generates. If  
you're counting on exactly reproducing Markdown.pl's output, you  
should definitely use Markdown.pl.

> BlueCloth.new("I'm testing  ").to_html
> #=> =====
> <p>I'm testing<br/>
> </p>
>
> That <br/> is functionally significant (it causes extra vertical
> whitespace), and Perl Markdown does *not* generate it. BlueCloth is
> apparently treating the extra spaces at the end of the input string as
> somehow significant.

Right, I'm aware of BR's functional significance in HTML. The Syntax  
documentation cited above states (under the Paragraphs and Line Breaks  
section):

   "When you do want to insert a <br /> break tag using
    Markdown, you end a line with two or more spaces, then
    type return."

Your test case doesn't have a trailing newline, and the Syntax  
document doesn't say what should happen with a line that ends with two  
spaces at the end of a document. Clearly Markdown.pl counts the  
'return' part of that description as significant, and Discount does  
not. Perhaps a case could be made to include a test for the break tag  
rule only applying to the middle of a paragraph in MarkdownTest, and  
if so I suspect David Parsons would make Discount conform to the test.  
If you have a bunch of documents that end with two spaces and no  
newline, I can see how you might not want to use Discount-based  
transformers. I personally do not, so I view this as an anomaly and a  
tradeoff I am willing to make.

> This next one is a little more involved; I'll use a here document to
> display my input text:
>
> s = <<END
> * testing
>
>        pre
>
> more li
> [...]
> As you can see, the last <p> block (containing "more li") *is* part of
> the <li> block. Since that is what Perl Markdown does, and since I  
> have
> lots of text that relies upon Markdown behaving in that way, I  
> naturally
> incline to the view that that is the "correct" answer and that
> BlueCloth's output is "wrong".

You are certainly welcome to your own view, but again, referring to  
the Syntax Documentation:

   "List items may consist of multiple paragraphs. Each subsequent
    paragraph in a list item must be indented by either 4 spaces
    or one tab:"

Your "more li" line is *not* indented by either 4 spaces or one tab,  
so I'm guessing you're counting on the "lazy" indentation of  
subsequent lines of the same paragraph. To me, two blank lines and an  
intervening PRE calls into question whether or not the next line is  
actually part of the previous LI or not when it's indented by a single  
space. I'm sure Markdown.pl agrees with your assessment, and that's  
why it marks it up the way it does.

So if by "correct" you mean "does exactly what Perl Markdown does  
despite what it says in the documentation", then yes, BlueCloth is  
wrong. I incline to the view that a Markdown implementation should  
follow what it says in the documentation and pass the test suite set  
out by the creator of Markdown (the syntax), which BlueCloth does. I'm  
certainly not suggesting that you should give up your reliance on  
Markdown.pl's output if you don't mind forking a Perl interpreter  
every time you want to transform your text to HTML.

I'm sharing my source because I've made something for myself that I  
think might be useful to others. If it isn't useful to you, either  
keep doing what does work for you or consider contributing some value  
back to the system by providing fixes. Anything else is just sound and  
fury.

--
Michael Granger <[e-mail]>
Rubymage, Architect, Believer
The FaerieMUD Consortium <http://www.FaerieMUD.org/>