[kramdown-users] Syntax of IALs, ALDs and extensions

Shawn Van Ittersum svicalifornia at gmail.com
Fri Apr 16 06:34:32 EDT 2010

Hi Thomas,

Thanks for the write-up.  I do have some thoughts on your ideas.  Unfortuntely, I'm in the middle of something urgent right now, so I won't be able to respond in more detail for a couple of days.  Please hold off on implementation if you can, so we can all discuss your proposal.


On Fri, 16 Apr 2010 11:23:53 +0200, Thomas Leitner wrote:
> Hello everybody,
> there was much discussion about the current extension syntax and how to
> change it to
> 1) make it possible to use it inline
> 2) make the syntax shorter
> 3) allow nesting of extension tags
> I have summed up my thoughts regarding the above three points belows.
> You will find a summary at the end of the post.
> ad 1)
>   The inline syntax for extensions should be less verbose than the
>   current syntax. Shawn has posted some useful ideas in another thread
>   regarding a possible syntax - thanks to Shawn for the writeup!. I
>   agree that we would need a shorthand for the closing tag. See the
>   remarks in 2) for a proposal.
> ad 2)
>   The currently used syntax for IALs, ALDs and extensions uses
>   `{:` and `}` as common start/end tags. This syntax was mainly
>   inspired by a syntax proposal from Maruku (available in
>   docs/proposal.md of the Maruku gem). It mentions that the colon was
>   added to allow an extension syntax later on and for easily removing
>   all special tags. This is also true for kramdown which basically uses
>   just this syntax.
>   So, how do we make the current syntax shorter?
>   *IALs*: They only use the above mentioned start and end tags and
>   everything between is used as content. Therefore IALs can't be made
>   shorter. The only thing that one could remove is the leading colon
>   (see below). So the syntax will stay the same:
>       {: #id .cls key="val"}
>   *ALDs*: Nearly the same as IALs except that we could also potentially
>   drop the colon after the ALD name. However, I think having the colon
>   there is really useful to make it clear that this is a *definition*.
>   So I don't think that we can make this any shorter. So the syntax
>   will stay the same:
>       {:ald: #id .cls key="val"}
>   *Extensions*: We need to be able to differentiate between extensions
>   that have a body and those that don't. As written above a shorthand
>   closing tag would also be nice. How about the following (adapted from
>   Shawn's proposal) - only using the inline syntax, the block syntax
>   will be the same except that the start/end tags have to appear on a
>   separate line:
>   Extension without body:
>       {:options> key="val"}
>   Extension with body 
>       {:comment}some text here{:comment}
>       {:comment .id key="val"}some text here{:}
>       {:nomarkdown}this is *not* marked up{:}
>   The differences to the current syntax are:
>   * Extension names don't need to start with a colon since the missing
>     `:` after the extension name separates them from an ALD.
>   * The trailing `>` character signifies that the extension does not
>     use a body. Iff we don't want to support custom extensions, then
>     there is no need for the additional `>` character to distinguish
>     extensions with and without a body.
>   * The closing tag is either `{:NAME}` or the shorthand `{:}`.
>   Note: This new syntax also does not allow nesting of tags! However,
>   since most people will use the shorthand closing tag, we could
>   probably changed the end tag syntax to `{:/NAME}` (as proposed by
>   Shawn). This would allow support for proper nesting.
>   What do you think about this proposal? Is this a better solution than
>   the current one? Could the syntax be still more concise?
> ad 3)
>   Nesting is currently not allowed and not useful considering the
>   currently available extensions (nomarkdown, comment, options). It
>   certainly would be nice to have a syntax that allows nesting.
>   However, I don't think that there will be much additions to the above
>   three extensions - anyone having an idea for a new and generally
>   useful extension?
>   One reason why there is probably no need for other extensions is that
>   a library like kramdown is often used in conjunction with a framework
>   that provides a syntax for extension. So there is really no need for
>   allowing general extension within kramdown.
>   Regarding the issue with nesting: Has anyone used Atlassian
>   Confluence? Their markup language supports extensions but also
>   without support for nesting tags - as far as I know - and with a very
>   similar syntax.
> Removing the leading colon/making it optional?
> ----------------------------------------------
> I said in another mail that I don't want to remove the leading colon in
> IALs/ALDs/extension because it makes it easy to remove the special
> kramdown tags to get more valid Markdown text. I was thinking about
> this and how often braces are used in normal text... If they are rarely
> used, we could probably remove the leading colon and get a more concise
> syntax - what do you think about this?
> Maruku currently only needs the leading colon with ALDs but not with
> IALs where it is optional. Iff we remove the leading colon, we would
> make the syntax incompatible with Marukus...
> Summary
> =======
> I would like to introduce the following changes:
> * No syntax support for custom extensions. We keep the current
>   extensions 'comment', 'nomarkdown' and 'options'. This also means
>   that the extension syntax gets simplified (as stated above).
>   If one really wants to use custom extensions, I imagine two ways:
>   * Using a framework that does exactly this
>   * Using special XML tags like `<my:ext>`. Since this situation is
>     handled by the HTML parser, nesting of tags will work fine. One
>     only needs to adapt the HTML converter to treat the tag `my:ext`
>     specially.
> * No support for nesting the available extension since it does not make
>   sense and makes parsing the extensions unnecessarily hard
> * Update the syntax for extensions as proposed above, keeping the
>   leading colon.
> Best regards,
>   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