[kramdown-users] Inline comments

Shawn Van Ittersum svicalifornia at gmail.com
Tue Apr 13 02:36:06 EDT 2010

1. There would have to be a suitable inner prefix to isolate Markdown tags from other valid XML.  ERB has <% %>, PHP has <? ?>, HTML reserves <!  > for comments, ASP, JSP, Perl Template::Toolkit, and other templating engines all have their own syntaxes.  It's a dangerous land mine.

2. IALs are used to modify DOM blocks and spans.  It seems very weird to use a XML-like tag to modify an adjacent DOM element.  That would be like an HTML tag modifying another peer-level HTML tag, like so:

  Here's a block.
<b /> # oh yeah, btw, make the preceding block bold.

It just doesn't make much sense.

I briefly considered the possibility of IALs being turned into container tags, but that just gets messy really fast.  The main point of IAL syntax in kramdown (for me, at least) is to make a nice shorthand and avoid the explicit tag hierarchy structure require by HTML.  Which is nicer:

This is an important notice


<kd-ial .important>
This is an important notice

This example also clearly shows that the IAL syntax of unquoted strings inside an IAL doesn't look right at all inside an XML-style tag.

For all of the above reasons, I think we should stick with the curly-brace syntax.


On Tue, 13 Apr 2010 08:16:22 +0200, Thomas Leitner wrote:
> On Tue, 13 Apr 2010 11:14:31 +1000, Shawn Van Ittersum wrote:
>> Well, as we are working on the clearest and easiest syntax for
>> kramdown tags, let's review the full kramdown tag syntax, starting
>> with the tags used most often:
>> --
>> IAL:
>> {: HTML-attribute [, HTML-attribute, ...] }
>> Spaces within the braces are optional.
>> --
>> HTML-attribute
>> #id-name | .class-name : attribute="value"
>> --
>> Generalized kramdown tag
>> Based on the above, this is the general syntax for a kramdown tag of
>> any kind: {: ...}
>> --
>> Extensions
>> 1. I don't see a need to have additional colons at the end extension
>> tags.  The other kramdown tags don't have them, and there's no reason
>> that extension tags need them, as they are already differentiated by
>> two colons at the beginning of the tag.  They should be stripped off
>> for simplicity (made optional for backwards compatibility).
>> 2. While kramdown does not yet support nested tags, it would be very
>> handy if it did, and we should design the syntax to accommodate it,
>> so that we are not limited by the syntax choices we make today.
>> 3. Thanks to 25 years of SGML, HTML, and XML, the slash character is
>> widely known and understood as a tag modifier to indicate closing.
>> HTML is the most pervasive of Web languages, so we would do well to
>> adopt this character and inherit the meaning it has already built up
>> for us.
>> 4. We should plan now to support arguments and attributes on
>> extensions, to make them more useful in the future.
>> 5. Several people have expressed interest in a shorthand closing tag,
>> which I share.  This can be accomplished using the slash and making
>> the extension command text optional on the closing tag.
>> With those observations, I propose these possibilities:
>> Opening tag
>> {::nomarkdown}      Standard form
>> {:: nomarkdown }    Optional spaces
>> {::nomarkdown::}    Optional ending colons
>> {:: nomarkdown ::}  Optional space and ending colons
>> Opening tag with arguments and attributes
>> {::nomarkdown arg1 arg2 attr1="..." attr2="..."}
>> Closing tag
>> {::/nomarkdown}     Double-colon standard form
>> {:/nomarkdown}      Alternate shorter form; single-colon followed by
>> slash indicates closing extension tag {:/}                Shorthand:
>> close the last opened extension
>> Example:
>> {::nomarkdown}
>> This is a block with no markdown{::comment}, and this is a comment
>> that will be omitted{:/comment} {:/nomarkdown}
>> Note: With the above syntax, I withdraw my prior request for
>> {::comment this is a comment} syntax.  {::tag}This new syntax{:/} is
>> short enough and ensures that we don't have special-case syntax only
>> for certain extensions, which may be hard to parse and limiting of
>> future expandability of the extensions feature.
> Thanks for this proposal and the nice write-up! However, *if* we want
> to do all the above, wouldn't it be easier to just use namespaced XML
> tags since the above proposal is just that with `<` substituted by
> `{::` and `>` by `}`?
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

More information about the kramdown-users mailing list