[kramdown-users] Backward incompatible changes in parser/converter

[Shawn Van Ittersum]

Will this new XHTML options syntax also apply to IALs?  Would you please send some examples of what that would look like?

Thanks,
Shawn

On Wed, 7 Apr 2010 10:23:45 +0200, Thomas Leitner wrote:
> Hi everyone,
> 
> while reading over the kramdown syntax documentation and considering the
> recent posts on the Markdown ML, I propose the following changes and
> would like to hear your opinions. Some of the following changes would
> make the next kramdown release *not* compatible with current kramdown
> documents.
> 
> One reason for some of the changes is that I would like to make the
> parser non-configurable (the Markdown ML has some discussions of the
> benefits of a non-configurable parser). This means that the parser will
> always generate the same internal element tree from a source
> document which is generally a good thing.
> 
> 
> * Moving the :auto_ids option from the kramdown parser to the converters
> 
>   This is just a minor change, mostly in the code base and will not
>   change the overall behaviour of kramdown. There is really no need
>   for the parser to do this and it removes one parser option.
> 
> * Removing the options :parse_block_html and :parse_span_html
> 
>   These are the last two parser options and should be removed to make
>   the parser non-configurable. I don't know if anyone has ever changed
>   one of these options - I haven't. The reasons for their respective
>   default values have been discussed on this ML before and a good
>   choice was made.
> 
>   One can always en-/disable parsing of specific HTML elements by using
>   the `markdown` attribute. Therefore there should be no use case for
>   this.
> 
> * Removing/changing the extensions feature
> 
>   I originally thought that the extensions feature would be quite
>   useful. However, when writing standalone documents extensions I did
>   not use them. And when writing multiple documents, for example the
>   source files for the kramdown homepage, another framework (in this
>   case [webgen][1]) provides features that are similar to the kramdown
>   extensions.
> 
>   Therefore I would like to completely remove the support for custom
>   extensions in the next release.
> 
>   Another change I would like to make is to change the syntax used for
>   the built-in extensions (comment, nomarkdown and options). The
>   current syntax is just fine but introduces a new and unnecessary
>   syntax. Since people which use Markdown are normally familiar with
>   HTML tags (or at least know how they look like), I would like to
>   completely remove the custom syntax and base the new syntax on
>   XML/HTML tags. This would have the additional benefit of having the
>   extensions available as span level elements.
> 
>   For example, setting options is currently done like this:
> 
>       {::options:: auto_ids="true"}
> 
>   The new way would look like this:
> 
>       <md:options auto_ids="true" />
> 
>   As one can see the new version is just one character longer and just
>   as easy to read.
> 
>   This change, however, would make the next kramdown release backwards
>   incompatible.
> 
> 
> I would like to incorporate all the above changes in the next release
> of kramdown and if there are no major concerns against these changes I
> will start implementing them in about two weeks.
> 
> -- Thomas
> 
> [1]: http://webgen.rubyforge.org
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users