[kramdown-users] Inline comments

[Thomas Leitner]

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