From t_leitner at gmx.at  Sun Apr  4 02:59:31 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 4 Apr 2010 08:59:31 +0200
Subject: [kramdown-users] feature request - ignore ERB-style code
In-Reply-To: <C7D52A00.5224F%matt@tidbits.com>
References: <C7D52A00.5224F%matt@tidbits.com>
Message-ID: <20100404085931.32247366@noeato.local>

On Sun, 28 Mar 2010 15:45:04 -0700, Matt Neuburg wrote:
> It would be a great help to me if kramdown would ignore ERB
> expressions, such as this:
> 
> <% yoho="yoho" %>
> 
> What I'd like kramdown to do when it sees something like that is (1)
> ignore what's inside it, so the quotation marks are not made curly,
> (2) ignore the tag marks, so they are not entityized, and (3) ignore
> the paragraph as a whole, so it isn't wrapped in <p> tags.

You are using two markup languages: one language that processes the
whole text (i.e. kramdown) and one that processes only certain, special
tags (i.e. ERB).

It is clear that kramdown cannot and will not support this feature
request because it then would need to support, following the same
logic, JSP tags, ASP tags, PHP tags, .... kramdown is not built for
this but ERB is. ERB is designed to work on *any* text and leave all
text alone *except* its special ERB tags.

So although kramdown is written in Ruby, it will not handle ERB tags
specially. I recommend running ERB first and then kramdown since this is
what other (static) web site generation also do (e.g. [webgen][1]).

-- Thomas

[1]: http://webgen.rubyforge.org

From t_leitner at gmx.at  Sun Apr  4 03:10:59 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 4 Apr 2010 09:10:59 +0200
Subject: [kramdown-users] feature request - separate out SmartyPants
 functionality
In-Reply-To: <C7D52882.5224D%matt@tidbits.com>
References: <C7D52882.5224D%matt@tidbits.com>
Message-ID: <20100404091059.32b4f9d1@noeato.local>

On Sun, 28 Mar 2010 15:38:42 -0700, Matt Neuburg wrote:
> kramdown isn't just Markdown; it's Markdown plus SmartyPants.
> Unfortunately, this is causing trouble for my Web site-building
> framework (RubyFrontier - see URL below for more information). With
> Markdown, I am able to apply Markdown at an early stage, when a page
> is partially built, and then finish the process by applying
> SmartyPants when the page is completely built.

Why would you want to separate these two stages? Markdown converts text
to HTML and *Pants converts regular quotes to nice ones, normally
using HTML entities. So if the user already used HTML entities in the
first place, there would be no difference after running kramdown.
 
> What I'd like is an option that turns off SmartyPants functionality,
> and another option that turn on *only* SmartyPants functionality.
> That way, I could apply kramdown twice - once early in the process,
> without SmartyPants functionality, and then again at the end of the
> process, with only SmartyPants functionality.

As has been said often on the Markdown ML, adding options to customize
the parsing stage of a Markdown parser is considered harmful. I have
already included options for customizing how HTML is parsed and I
currently consider removing that option.

What you can do, however, is to customize the HTML converter to output
normal quotes instead of curly ones.

If you *only* want SmartyPants functionality, use RubyPants!

> I have a sort of workaround but it is raising more difficulties than
> it solves. The real problem is just that kramdown is doing too much.
> I really want to switch from using Markdown to using kramdown but
> this is a troublesome issue. m.

What are the parts where kramdown does too much? Since kramdown is
inspired by Maruku and PHP Markdown Extra it adds some additional
parsing functionality besides the normal Markdown syntax but this is a
feature.

-- Thomas

From t_leitner at gmx.at  Sun Apr  4 04:04:05 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 4 Apr 2010 10:04:05 +0200
Subject: [kramdown-users] Alternate Block IAL Placement
In-Reply-To: <20100326091244942768.bb6e28e8@gmail.com>
References: <20100326091244942768.bb6e28e8@gmail.com>
Message-ID: <20100404100405.5f6d8237@noeato.local>

> It would be really nice if kramdown could support attributes at the
> top of a block, in addition to the current syntax:
> 
> {: ul attributes}  <= This comes before the ul block, thus pertains
> to the ul
> * {: li attributes } Item 1
> 
> * Item 2
> 
> * Item 3

Will think about this.

-- Thomas

From t_leitner at gmx.at  Tue Apr  6 06:29:49 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 6 Apr 2010 12:29:49 +0200
Subject: [kramdown-users] [ANN] kramdown 0.6.0 released
Message-ID: <20100406122949.7c1f7314@noeato.local>

## About kramdown

kramdown (sic, not Kramdown or KramDown, just kramdown) is a *free*
GPL-licensed [Ruby](http://www.ruby-lang.org) library for parsing a
superset of Markdown. It is completely written in Ruby, supports
standard Markdown (with some minor modifications) and various
extensions that have been made popular by the [PHP Markdown Extra]
package and [Maruku].
Homepage for installation instructions and documentation:
    http://kramdown.rubyforge.org


## kramdown 0.6.0 released

This release adds syntax support for block and inline LaTeX math (for
example: $$e^{i\pi}=?$$). Aside from that there are the usual small
enhancements and bug fixes.

## Changes

* Major changes:

  - Added syntax support for block and inline LaTeX math

* Minor changes:

  - Added a man page for the kramdown binary
  - Added a CLI option for selecting the input format and changed the
    output format option to `-o`
  - Small syntax change for list items: the last list item text is now
    also wrapped in a paragraph tag if all other list items are.
  - Added documentation on available parsers and converters

* Bug fixes:

  - Fixed problem where clearly invalid email autolinks were permitted
    (reported by Eric Sunshine)
  - Added documentation for autolinks (reported by Eric Sunshine)
  - Fixed performance problem related to emphasis parsing (reported by
    Chris Heald)
  - Fixed bug RF#27957: document templates were missing from
    distribution packages (reported by Alex Bargi)
  - Fixed problem with LaTeX converter handling HTML elements not
    correctly

* Deprecation notes:

  - The CLI options `-f` will be removed in the next release.

From t_leitner at gmx.at  Wed Apr  7 04:23:45 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Wed, 7 Apr 2010 10:23:45 +0200
Subject: [kramdown-users] Backward incompatible changes in parser/converter
Message-ID: <20100407102345.1555dd90@noeato.local>

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

From svicalifornia at gmail.com  Wed Apr  7 06:58:03 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Wed, 7 Apr 2010 20:58:03 +1000
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <20100407102345.1555dd90@noeato.local>
References: <20100407102345.1555dd90@noeato.local>
Message-ID: <20100407205803341216.f9d1d493@gmail.com>

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

From t_leitner at gmx.at  Wed Apr  7 10:40:13 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Wed, 7 Apr 2010 16:40:13 +0200
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <20100407205803341216.f9d1d493@gmail.com>
References: <20100407102345.1555dd90@noeato.local>
	<20100407205803341216.f9d1d493@gmail.com>
Message-ID: <20100407164013.1754a670@noeato.local>

On Wed, 7 Apr 2010 20:58:03 +1000, Shawn Van Ittersum wrote:
> Will this new XHTML options syntax also apply to IALs?  Would you
> please send some examples of what that would look like?

No, IALs and ALDs will stay the same since they fulfill a completely
different purpose. Also, the extensions always stand alone whereas IALs
are always applied to an element. Therefore it would not "look"
good when using XML tags for this purpose.

-- Thomas

From svicalifornia at gmail.com  Wed Apr  7 14:12:35 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Thu, 8 Apr 2010 04:12:35 +1000
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <20100407164013.1754a670@noeato.local>
References: <20100407102345.1555dd90@noeato.local>
	<20100407205803341216.f9d1d493@gmail.com>
	<20100407164013.1754a670@noeato.local>
Message-ID: <20100408041235130864.f0b578c8@gmail.com>

OK.

There is something nice about having a uniform syntax to wrap all kramdown "tags."  I can't imagine a suitably concise XHTML representation of IALs, so I'd suggest keeping the extensions in curly-brace format for uniformity.  Wouldn't it be odd to say, "These kramdown tags/directives look like this, but these IAL tags look altogether different..."?

Juse like all ERB tags have <% %> wrappers, I think there should be similar consistency in kramdown.

If you do keep curly braces, I think the directive syntax could be simplified.  Instead of this:

{::options:: ...}

why not this:

{options ...}  or  {kd-options ...}

Why are all the colons necessary?

Shawn

On Wed, 7 Apr 2010 16:40:13 +0200, Thomas Leitner wrote:
> On Wed, 7 Apr 2010 20:58:03 +1000, Shawn Van Ittersum wrote:
>> Will this new XHTML options syntax also apply to IALs?  Would you
>> please send some examples of what that would look like?
> 
> No, IALs and ALDs will stay the same since they fulfill a completely
> different purpose. Also, the extensions always stand alone whereas IALs
> are always applied to an element. Therefore it would not "look"
> good when using XML tags for this purpose.
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From sunshine at sunshineco.com  Thu Apr  8 05:21:47 2010
From: sunshine at sunshineco.com (Eric Sunshine)
Date: Thu, 08 Apr 2010 05:21:47 -0400
Subject: [kramdown-users] Backward incompatible changes in
	parser/converter
In-Reply-To: <20100408041235130864.f0b578c8@gmail.com>
References: <20100407102345.1555dd90@noeato.local>	<20100407205803341216.f9d1d493@gmail.com>	<20100407164013.1754a670@noeato.local>
	<20100408041235130864.f0b578c8@gmail.com>
Message-ID: <4BBDA02B.9050502@sunshineco.com>

I was going to make the similar observation that, while XHTML-like 
syntax may be well-known, users of Markdown (with extensions) have also 
already become accustomed to IALs and, by extension, the closely related 
{::foo::} syntax. Thomas, you mentioned the Markdown mailing list. Was 
there relevant discussion there which prompted proposed change?

In any event, if the syntax does change, it probably would be worthwhile 
to continue recognizing the old syntax for some time, and not remove it 
as quickly as some of the other deprecated features have been removed. I 
suggest this since (my impression is that) kramdown has already a wider 
audience than the webgen user base.

-- ES


On 4/7/2010 2:12 PM, Shawn Van Ittersum wrote:
> OK.
>
> There is something nice about having a uniform syntax to wrap all kramdown "tags."  I can't imagine a suitably concise XHTML representation of IALs, so I'd suggest keeping the extensions in curly-brace format for uniformity.  Wouldn't it be odd to say, "These kramdown tags/directives look like this, but these IAL tags look altogether different..."?
>
> Juse like all ERB tags have<% %>  wrappers, I think there should be similar consistency in kramdown.
>
> If you do keep curly braces, I think the directive syntax could be simplified.  Instead of this:
>
> {::options:: ...}
>
> why not this:
>
> {options ...}  or  {kd-options ...}
>
> Why are all the colons necessary?
>
> Shawn
>
> On Wed, 7 Apr 2010 16:40:13 +0200, Thomas Leitner wrote:
>> On Wed, 7 Apr 2010 20:58:03 +1000, Shawn Van Ittersum wrote:
>>> Will this new XHTML options syntax also apply to IALs?  Would you
>>> please send some examples of what that would look like?
>>
>> No, IALs and ALDs will stay the same since they fulfill a completely
>> different purpose. Also, the extensions always stand alone whereas IALs
>> are always applied to an element. Therefore it would not "look"
>> good when using XML tags for this purpose.
>>
>> -- Thomas
>> _______________________________________________
>> kramdown-users mailing list
>> kramdown-users at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/kramdown-users
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users
>

From t_leitner at gmx.at  Thu Apr  8 06:42:54 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Thu, 8 Apr 2010 12:42:54 +0200
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <20100408041235130864.f0b578c8@gmail.com>
References: <20100407102345.1555dd90@noeato.local>
	<20100407205803341216.f9d1d493@gmail.com>
	<20100407164013.1754a670@noeato.local>
	<20100408041235130864.f0b578c8@gmail.com>
Message-ID: <20100408124254.67dc6a84@noeato.local>

> Juse like all ERB tags have <% %> wrappers, I think there should be
> similar consistency in kramdown.

Thanks for pointing this out!
 
> If you do keep curly braces, I think the directive syntax could be
> simplified.  Instead of this:
> 
> {::options:: ...}
> 
> why not this:
> 
> {options ...}  or  {kd-options ...}
> 
> Why are all the colons necessary?

I don't like the `{options ...}` form since this can be too easily
invoked accidentally. I think that the IAL and ALD syntax are okay in
this regard, ie. `{: .class}` and `{:NAME: .class}` are not much to
type and visually and syntactically different from anything a user would
normally use inside a curly brace.

I particularly like that ALDs, IALs and extensions start with `{:`
because it makes filtering them out to get better standard Markdown
compatibility very easy.

I don't know how to make the extension syntax more concise while
respecting the above. Any suggestions are welcome!

-- Thomas

From t_leitner at gmx.at  Thu Apr  8 06:48:16 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Thu, 8 Apr 2010 12:48:16 +0200
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <4BBDA02B.9050502@sunshineco.com>
References: <20100407102345.1555dd90@noeato.local>
	<20100407205803341216.f9d1d493@gmail.com>
	<20100407164013.1754a670@noeato.local>
	<20100408041235130864.f0b578c8@gmail.com>
	<4BBDA02B.9050502@sunshineco.com>
Message-ID: <20100408124816.37bbca3a@noeato.local>

On Thu, 08 Apr 2010 05:21:47 -0400, Eric Sunshine wrote:
> I was going to make the similar observation that, while XHTML-like 
> syntax may be well-known, users of Markdown (with extensions) have
> also already become accustomed to IALs and, by extension, the closely
> related {::foo::} syntax. Thomas, you mentioned the Markdown mailing
> list. Was there relevant discussion there which prompted proposed
> change?

No, not in this regard. There was some general discussion about
Markdown, Markdown extensions, the future direction of Markdown and
that Markdown syntax should not be configurable which lead to the
other points of my initial mail.
 
> In any event, if the syntax does change, it probably would be
> worthwhile to continue recognizing the old syntax for some time, and
> not remove it as quickly as some of the other deprecated features
> have been removed. I suggest this since (my impression is that)
> kramdown has already a wider audience than the webgen user base.

That is most probably correct since webgen is a tool for a special
purpose and kramdown a library meant to replace Maruku - which is used
by many such tools as well as other apps like radiant - as default
library for parsing Markdown with extensions.

I will keep that in mind when considering making other syntax changes.

-- Thomas

From michaelfranzl at gmx.at  Sat Apr 10 14:40:21 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Sat, 10 Apr 2010 20:40:21 +0200
Subject: [kramdown-users] Line break
Message-ID: <4BC0C615.7050207@gmx.at>

Would it make sense to implement the following:

Source text:

     First paragraph

     Second paragraph
     not a paragraph just a line break

HTML:

     <p>First paragraph</p>
     <p>Second paragraph<br>not a paragraph just a line break</p>

That would be very intuitive IMO.

Michael

From matt at tidbits.com  Sat Apr 10 15:12:43 2010
From: matt at tidbits.com (Matt Neuburg)
Date: Sat, 10 Apr 2010 12:12:43 -0700
Subject: [kramdown-users] Line break
In-Reply-To: <4BC0C615.7050207@gmx.at>
References: <4BC0C615.7050207@gmx.at>
Message-ID: <26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>

Surely the use of two spaces after the words "second paragraph" to signal the break explicitly is not too much to ask of end-users. m.

On Apr 10, 2010, at 11:40 AM, Michael Franzl wrote:

> Source text:
> 
>    First paragraph
> 
>    Second paragraph
>    not a paragraph just a line break
> 
> HTML:
> 
>    <p>First paragraph</p>
>    <p>Second paragraph<br>not a paragraph just a line break</p>
> 
> That would be very intuitive IMO.


From svicalifornia at gmail.com  Sat Apr 10 16:07:15 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Sun, 11 Apr 2010 06:07:15 +1000
Subject: [kramdown-users] Line break
In-Reply-To: <26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>
References: <4BC0C615.7050207@gmx.at>
	<26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>
Message-ID: <B364E553-E73D-41A7-9F8E-3662C2AC1225@gmail.com>

Michael,

I happen to like "line break on newline" also.  Google "github  
flavored markdown" to code to produce this and other behaviors.

Shawn
[sent from mobile phone]

On Apr 11, 2010, at 5:12 AM, Matt Neuburg <matt at tidbits.com> wrote:

> Surely the use of two spaces after the words "second paragraph" to  
> signal the break explicitly is not too much to ask of end-users. m.
>
> On Apr 10, 2010, at 11:40 AM, Michael Franzl wrote:
>
>> Source text:
>>
>>   First paragraph
>>
>>   Second paragraph
>>   not a paragraph just a line break
>>
>> HTML:
>>
>>   <p>First paragraph</p>
>>   <p>Second paragraph<br>not a paragraph just a line break</p>
>>
>> That would be very intuitive IMO.
>
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From michaelfranzl at gmx.at  Sun Apr 11 01:39:49 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Sun, 11 Apr 2010 07:39:49 +0200
Subject: [kramdown-users] Line break
In-Reply-To: <26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>
References: <4BC0C615.7050207@gmx.at>
	<26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>
Message-ID: <4BC160A5.4030208@gmx.at>

Matt Neuburg wrote:
> Surely the use of two spaces after the words "second paragraph" to signal the break explicitly is not too much to ask of end-users. m.

No, it isn't too much. I should have looked into the documentation 
before, which is great btw.

Thanks,
Michael

From t_leitner at gmx.at  Sun Apr 11 02:58:01 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 11 Apr 2010 08:58:01 +0200
Subject: [kramdown-users] Line break
In-Reply-To: <4BC160A5.4030208@gmx.at>
References: <4BC0C615.7050207@gmx.at>
	<26A33929-51E5-4989-A1E8-E0B0A29E0404@tidbits.com>
	<4BC160A5.4030208@gmx.at>
Message-ID: <20100411085801.34a2bbca@noeato.local>

On Sun, 11 Apr 2010 07:39:49 +0200, Michael Franzl wrote:
> Matt Neuburg wrote:
> > Surely the use of two spaces after the words "second paragraph" to
> > signal the break explicitly is not too much to ask of end-users. m.
> 
> No, it isn't too much. I should have looked into the documentation 
> before, which is great btw.

Thanks!

Not turning new lines into hard breaks is one of the features Markdown
differentiates from Textile. Moreover, if you consider the roots of
Markdown, ie. email messages, you will find that text in most email
messages is broken at 72 characters (like in this mail) to avoid long
lines and horizontal scrolling so that it always looks good no matter
if the mail program supports wrapping long lines or not. However, since
all web browser have to do line wrapping, it isn't an issue there - and
the Markdown syntax takes advantage of that (i.e. converting such a
pargraph into one HTML paragraph without newlines).

-- Thomas

From michaelfranzl at gmx.at  Sun Apr 11 03:39:03 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Sun, 11 Apr 2010 09:39:03 +0200
Subject: [kramdown-users] Inline comments
Message-ID: <4BC17C97.40203@gmx.at>

Kramdown supports block-like comments:

     {::comment:}
     This text is completely ignored by kramdown
     {::comment:}

Would it make sense to implement inline comments, like in this ERB 
example:

     This text is completely <%# find better word %> ignored by kramdown

Michael

From t_leitner at gmx.at  Sun Apr 11 13:47:06 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 11 Apr 2010 19:47:06 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <4BC17C97.40203@gmx.at>
References: <4BC17C97.40203@gmx.at>
Message-ID: <20100411194706.1bfa76ef@noeato.local>

On Sun, 11 Apr 2010 09:39:03 +0200, Michael Franzl wrote:
> Kramdown supports block-like comments:
> 
>      {::comment:}
>      This text is completely ignored by kramdown
>      {::comment:}
> 
> Would it make sense to implement inline comments, like in this ERB 
> example:
> 
>      This text is completely <%# find better word %> ignored by

Yeah, it would be nice to have an inline syntax for extensions like
`comment`. However, I don't think that the block syntax for extensions
should be used inline because of its verbosity. Any suggestions?

-- Thomas

From michaelfranzl at gmx.at  Sun Apr 11 15:48:28 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Sun, 11 Apr 2010 21:48:28 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100411194706.1bfa76ef@noeato.local>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
Message-ID: <4BC2278C.9020701@gmx.at>

Thomas Leitner wrote:
>> Would it make sense to implement inline comments, like in this ERB 
>> example:
>>
>>      This text is completely <%# find better word %> ignored by
> 
> Yeah, it would be nice to have an inline syntax for extensions like
> `comment`. However, I don't think that the block syntax for extensions
> should be used inline because of its verbosity. Any suggestions?

What about

    This is a ((comment))

or

    This is a #comment#

Michael


From svicalifornia at gmail.com  Sun Apr 11 16:46:29 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Mon, 12 Apr 2010 06:46:29 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <4BC2278C.9020701@gmx.at>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at>
Message-ID: <20100412064629373023.047b9d19@gmail.com>

Those won't work because kramdown text may contain bits of other languages where those parentheses or hash marks must be preserved, not interpreted by kramdown.

Again, I advocate a single consistent syntax for kramdown directives, which is currently:  {: ... }

With that in mind, I suggest:

   {:comment} skip this {:/comment}

or alternatively:

   There is something {:comment: skip this } hidden in this sentence.

Shawn

On Sun, 11 Apr 2010 21:48:28 +0200, Michael Franzl wrote:
> Thomas Leitner wrote:
>>> Would it make sense to implement inline comments, like in this ERB 
>>> example:
>>> 
>>>      This text is completely <%# find better word %> ignored by
>> 
>> Yeah, it would be nice to have an inline syntax for extensions like
>> `comment`. However, I don't think that the block syntax for extensions
>> should be used inline because of its verbosity. Any suggestions?
> 
> What about
> 
>    This is a ((comment))
> 
> or
> 
>    This is a #comment#
> 
> Michael
> 
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From sunshine at sunshineco.com  Sun Apr 11 22:59:49 2010
From: sunshine at sunshineco.com (Eric Sunshine)
Date: Sun, 11 Apr 2010 22:59:49 -0400
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412064629373023.047b9d19@gmail.com>
References: <4BC17C97.40203@gmx.at>
	<20100411194706.1bfa76ef@noeato.local>	<4BC2278C.9020701@gmx.at>
	<20100412064629373023.047b9d19@gmail.com>
Message-ID: <4BC28CA5.5010603@sunshineco.com>

On 4/11/2010 4:46 PM, Shawn Van Ittersum wrote:
> Again, I advocate a single consistent syntax for kramdown
> directives,  which is currently: {: ... }

I agree with Shawn that a consistent syntax is preferable.

 > With that in mind, I suggest:
 >   {:comment} skip this {:/comment}

This feels unusually XML-like and inconsistent with the rest of the 
kramdown extension syntax. Also, it is hardly less verbose than the more 
obvious:

   {::comment:}skip this{::comment:}

Personally, given that {::comment:} already exists (though does not 
presently work in-line), I don't mind the verbosity.

 > or alternatively:
 >   There is something {:comment: skip this } hidden in this...

This also is reasonable. To be consistent with existing extension syntax 
(http://kramdown.rubyforge.org/syntax.html#extension-blocks), however, 
it would be:

   There is something {::comment:: skip this} hidden in this...

-- ES


On 4/11/2010 4:46 PM, Shawn Van Ittersum wrote:
> Those won't work because kramdown text may contain bits of other languages where those parentheses or hash marks must be preserved, not interpreted by kramdown.
>
> Again, I advocate a single consistent syntax for kramdown directives, which is currently:  {: ... }
>
> With that in mind, I suggest:
>
>     {:comment} skip this {:/comment}
>
> or alternatively:
>
>     There is something {:comment: skip this } hidden in this sentence.
>
> Shawn
>
> On Sun, 11 Apr 2010 21:48:28 +0200, Michael Franzl wrote:
>> Thomas Leitner wrote:
>>>> Would it make sense to implement inline comments, like in this ERB
>>>> example:
>>>>
>>>>       This text is completely<%# find better word %>  ignored by
>>>
>>> Yeah, it would be nice to have an inline syntax for extensions like
>>> `comment`. However, I don't think that the block syntax for extensions
>>> should be used inline because of its verbosity. Any suggestions?
>>
>> What about
>>
>>     This is a ((comment))
>>
>> or
>>
>>     This is a #comment#
>>
>> Michael
>>
>> _______________________________________________
>> kramdown-users mailing list
>> kramdown-users at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/kramdown-users
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users
>

From svicalifornia at gmail.com  Mon Apr 12 01:11:44 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Mon, 12 Apr 2010 15:11:44 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <4BC28CA5.5010603@sunshineco.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
Message-ID: <20100412151144984956.36fc4aac@gmail.com>

On Sun, 11 Apr 2010 22:59:49 -0400, Eric Sunshine wrote:
>> With that in mind, I suggest:
>>   {:comment} skip this {:/comment}
> 
> This feels unusually XML-like and inconsistent with the rest of the 
> kramdown extension syntax. Also, it is hardly less verbose than the 
> more obvious:
> 
>   {::comment:}skip this{::comment:}

I think using the same tag to toggle comment status on and off will be problematic.  The editor may overlook the first comment tag and think that the comment begins with the second tag, especially if the commented string is sufficiently long.  This will lead to a great deal of confusion.

SGML, HTML, and XML use a slash to denote close tags distinct from open tags to avoid the above problem.  If kramdown tags are going to be used as containers in this manner, then the tags should similarly have distinct open and close forms.

Shawn

From sunshine at sunshineco.com  Mon Apr 12 02:11:18 2010
From: sunshine at sunshineco.com (Eric Sunshine)
Date: Mon, 12 Apr 2010 02:11:18 -0400
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412151144984956.36fc4aac@gmail.com>
References: <4BC17C97.40203@gmx.at>
	<20100411194706.1bfa76ef@noeato.local>	<4BC2278C.9020701@gmx.at>
	<20100412064629373023.047b9d19@gmail.com>	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
Message-ID: <4BC2B986.6040808@sunshineco.com>

On 4/12/2010 1:11 AM, Shawn Van Ittersum wrote:
> On Sun, 11 Apr 2010 22:59:49 -0400, Eric Sunshine wrote:
>>> With that in mind, I suggest:
>>>    {:comment} skip this {:/comment}
>> This feels unusually XML-like and inconsistent with the rest of the
>> kramdown extension syntax. Also, it is hardly less verbose than the
>> more obvious:
>>    {::comment:}skip this{::comment:}
> I think using the same tag to toggle comment status on and off will
> be problematic.  The editor may overlook the first comment tag and
> think that the comment begins with the second tag, especially if the
> commented string is sufficiently long. [...] SGML, HTML, and XML use
> a slash to denote close tags distinct from open tags to avoid the
> above problem.  If kramdown tags are going to be used as containers
> in this manner, then the tags should similarly have distinct open and
> close forms.

I mentioned the above possible syntax since the block form already uses 
the same tag to open and close comments (and 'nomarkdown', etc.). For 
instance, the following already is accepted:

   {::comment:}
   skip this
   {::comment:}

Reference: http://kramdown.rubyforge.org/syntax.html#extension-blocks

-- ES

From michaelfranzl at gmx.at  Mon Apr 12 02:14:18 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Mon, 12 Apr 2010 08:14:18 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412151144984956.36fc4aac@gmail.com>
References: <4BC17C97.40203@gmx.at>
	<20100411194706.1bfa76ef@noeato.local>	<4BC2278C.9020701@gmx.at>
	<20100412064629373023.047b9d19@gmail.com>	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
Message-ID: <4BC2BA3A.9010304@gmx.at>

Shawn Van Ittersum wrote:
> I think using the same tag to toggle comment status on and off will be problematic.  The editor may overlook the first comment tag and think that the comment begins with the second tag, especially if the commented string is sufficiently long.  This will lead to a great deal of confusion.
> 
> SGML, HTML, and XML use a slash to denote close tags distinct from open tags to avoid the above problem.  If kramdown tags are going to be used as containers in this manner, then the tags should similarly have distinct open and close forms.

Inline comments would only be used for short notes. If longer comments 
are needed, the block version is suitable. So why not use the 
following version, it is a good compromise between verbosity and 
familiar kramdown syntax?

     There is something {::comment:: skip this} hidden in this...

Michael


From svicalifornia at gmail.com  Mon Apr 12 02:31:45 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Mon, 12 Apr 2010 16:31:45 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <4BC2B986.6040808@sunshineco.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
Message-ID: <20100412163145935180.c3e32d9d@gmail.com>

Well, I can still see that being a source of great confusion, even more so when the tags are wrapped around a block.  I would at least like kramdown to support an alternate close-tag syntax, so I can make sure that my documents can use distinctive close tags.  Having to track whether each {::nomarkdown:} or other state-toggle tag is opening or closing in a long document could be a major pain.

Shawn

On Mon, 12 Apr 2010 02:11:18 -0400, Eric Sunshine wrote:
> On 4/12/2010 1:11 AM, Shawn Van Ittersum wrote:
>> On Sun, 11 Apr 2010 22:59:49 -0400, Eric Sunshine wrote:
>>>> With that in mind, I suggest:
>>>>    {:comment} skip this {:/comment}
>>> This feels unusually XML-like and inconsistent with the rest of the
>>> kramdown extension syntax. Also, it is hardly less verbose than the
>>> more obvious:
>>>    {::comment:}skip this{::comment:}
>> I think using the same tag to toggle comment status on and off will
>> be problematic.  The editor may overlook the first comment tag and
>> think that the comment begins with the second tag, especially if the
>> commented string is sufficiently long. [...] SGML, HTML, and XML use
>> a slash to denote close tags distinct from open tags to avoid the
>> above problem.  If kramdown tags are going to be used as containers
>> in this manner, then the tags should similarly have distinct open and
>> close forms.
> 
> I mentioned the above possible syntax since the block form already 
> uses the same tag to open and close comments (and 'nomarkdown', 
> etc.). For instance, the following already is accepted:
> 
>   {::comment:}
>   skip this
>   {::comment:}
> 
> Reference: http://kramdown.rubyforge.org/syntax.html#extension-blocks
> 
> -- ES
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From t_leitner at gmx.at  Mon Apr 12 14:32:07 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Mon, 12 Apr 2010 20:32:07 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412163145935180.c3e32d9d@gmail.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
Message-ID: <20100412203207.4655ce81@noeato.local>

On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
> Well, I can still see that being a source of great confusion, even
> more so when the tags are wrapped around a block.  I would at least
> like kramdown to support an alternate close-tag syntax, so I can make
> sure that my documents can use distinctive close tags.  Having to
> track whether each {::nomarkdown:} or other state-toggle tag is
> opening or closing in a long document could be a major pain.

You are correct in this regard, there should probably be a difference
between the start and end tag of an extension block. What about having
`{::comment:}` as start and `{::}` as end tag? This should be no
problem *except* when one wants to nest extension tags which is also
not supported currently (and therefore no problem). This approach would
also be less verbose.

-- Thomas

From michaelfranzl at gmx.at  Mon Apr 12 16:17:50 2010
From: michaelfranzl at gmx.at (Michael Franzl)
Date: Mon, 12 Apr 2010 22:17:50 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412203207.4655ce81@noeato.local>
References: <4BC17C97.40203@gmx.at>
	<20100411194706.1bfa76ef@noeato.local>	<4BC2278C.9020701@gmx.at>
	<20100412064629373023.047b9d19@gmail.com>	<4BC28CA5.5010603@sunshineco.com>	<20100412151144984956.36fc4aac@gmail.com>	<4BC2B986.6040808@sunshineco.com>	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
Message-ID: <4BC37FEE.4090400@gmx.at>

Thomas Leitner wrote:
> On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
>> Well, I can still see that being a source of great confusion, even
>> more so when the tags are wrapped around a block.  I would at least
>> like kramdown to support an alternate close-tag syntax, so I can make
>> sure that my documents can use distinctive close tags.  Having to
>> track whether each {::nomarkdown:} or other state-toggle tag is
>> opening or closing in a long document could be a major pain.
> 
> You are correct in this regard, there should probably be a difference
> between the start and end tag of an extension block. What about having
> `{::comment:}` as start and `{::}` as end tag? This should be no
> problem *except* when one wants to nest extension tags which is also
> not supported currently (and therefore no problem). This approach would
> also be less verbose.

What about an short alias:

   Something is {::c:}hidden{::} in here.

Michael

From svicalifornia at gmail.com  Mon Apr 12 21:14:31 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 13 Apr 2010 11:14:31 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100412203207.4655ce81@noeato.local>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
Message-ID: <20100413111431316612.788e8411@gmail.com>

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.

Shawn

On Mon, 12 Apr 2010 20:32:07 +0200, Thomas Leitner wrote:
> On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
>> Well, I can still see that being a source of great confusion, even
>> more so when the tags are wrapped around a block.  I would at least
>> like kramdown to support an alternate close-tag syntax, so I can make
>> sure that my documents can use distinctive close tags.  Having to
>> track whether each {::nomarkdown:} or other state-toggle tag is
>> opening or closing in a long document could be a major pain.
> 
> You are correct in this regard, there should probably be a difference
> between the start and end tag of an extension block. What about having
> `{::comment:}` as start and `{::}` as end tag? This should be no
> problem *except* when one wants to nest extension tags which is also
> not supported currently (and therefore no problem). This approach would
> also be less verbose.
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From svicalifornia at gmail.com  Mon Apr 12 21:18:34 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 13 Apr 2010 11:18:34 +1000
Subject: [kramdown-users] Fwd: Re:  Inline comments
Message-ID: <20100413111834542728.3be84d06@gmail.com>

Minor correction to my previous message:

HTML-attribute
#id-name | .class-name | attribute="value"

Shawn

----- Begin forwarded message -----
From: Shawn Van Ittersum <svicalifornia at gmail.com>
Date: Tue, 13 Apr 2010 11:14:31 +1000
To: kramdown-users at rubyforge.org
Subject: Re: [kramdown-users] Inline comments

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.

Shawn

On Mon, 12 Apr 2010 20:32:07 +0200, Thomas Leitner wrote:
> On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
>> Well, I can still see that being a source of great confusion, even
>> more so when the tags are wrapped around a block.  I would at least
>> like kramdown to support an alternate close-tag syntax, so I can make
>> sure that my documents can use distinctive close tags.  Having to
>> track whether each {::nomarkdown:} or other state-toggle tag is
>> opening or closing in a long document could be a major pain.
> 
> You are correct in this regard, there should probably be a difference
> between the start and end tag of an extension block. What about having
> `{::comment:}` as start and `{::}` as end tag? This should be no
> problem *except* when one wants to nest extension tags which is also
> not supported currently (and therefore no problem). This approach would
> also be less verbose.
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From svicalifornia at gmail.com  Mon Apr 12 21:24:29 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 13 Apr 2010 11:24:29 +1000
Subject: [kramdown-users] Fwd: Re:  Inline comments
Message-ID: <20100413112429581230.a0263ef5@gmail.com>

Another suggestion:  Allow an optional slash at the end of extension tags that do not have a body.

{::toc /}

{::options arg1, arg2 /}

The ending slash makes it more clearly visually (following the conventions established by XML) that these tags have no body.

Shawn

----- Begin forwarded message -----
From: Shawn Van Ittersum <svicalifornia at gmail.com>
Date: Tue, 13 Apr 2010 11:18:34 +1000
To: kramdown-users at rubyforge.org
Subject: Fwd: Re: [kramdown-users] Inline comments

Minor correction to my previous message:

HTML-attribute
#id-name | .class-name | attribute="value"

Shawn

----- Begin forwarded message -----
From: Shawn Van Ittersum <svicalifornia at gmail.com>
Date: Tue, 13 Apr 2010 11:14:31 +1000
To: kramdown-users at rubyforge.org
Subject: Re: [kramdown-users] Inline comments

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.

Shawn

On Mon, 12 Apr 2010 20:32:07 +0200, Thomas Leitner wrote:
> On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
>> Well, I can still see that being a source of great confusion, even
>> more so when the tags are wrapped around a block.  I would at least
>> like kramdown to support an alternate close-tag syntax, so I can make
>> sure that my documents can use distinctive close tags.  Having to
>> track whether each {::nomarkdown:} or other state-toggle tag is
>> opening or closing in a long document could be a major pain.
> 
> You are correct in this regard, there should probably be a difference
> between the start and end tag of an extension block. What about having
> `{::comment:}` as start and `{::}` as end tag? This should be no
> problem *except* when one wants to nest extension tags which is also
> not supported currently (and therefore no problem). This approach would
> also be less verbose.
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From t_leitner at gmx.at  Tue Apr 13 02:16:22 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 13 Apr 2010 08:16:22 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100413111431316612.788e8411@gmail.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
	<20100413111431316612.788e8411@gmail.com>
Message-ID: <20100413081622.074fb832@noeato.local>

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

From svicalifornia at gmail.com  Tue Apr 13 02:36:06 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 13 Apr 2010 16:36:06 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100413081622.074fb832@noeato.local>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
	<20100413111431316612.788e8411@gmail.com>
	<20100413081622.074fb832@noeato.local>
Message-ID: <20100413163606054430.a4ea8fb1@gmail.com>

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:

<div>
  Here's a block.
</div>
<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:

{:.important}
This is an important notice

or

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

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.

Shawn

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

From t_leitner at gmx.at  Tue Apr 13 05:33:40 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 13 Apr 2010 11:33:40 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100413163606054430.a4ea8fb1@gmail.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
	<20100413111431316612.788e8411@gmail.com>
	<20100413081622.074fb832@noeato.local>
	<20100413163606054430.a4ea8fb1@gmail.com>
Message-ID: <20100413113340.1f4950d0@noeato.local>

On Tue, 13 Apr 2010 16:36:06 +1000, Shawn Van Ittersum wrote:
> 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.

No inner prefix, just a plain XML namespace, ie.
{::comment}...{:/comment} becomes <md:comment>...</md:comment>. This
should be compatible with all HTML template languages! However, I
already mentioned this suggestion in another thread about "Backward
incompatible changes..." and the answers clearly showed that a
consistent syntax was preferred over extension via XML namespaces.

Regarding nesting of tags: think about how Java multiline comments
cannot be nested (ie. `/* .... */`). The same is currently true for
kramdown extensions.

Another point: there needs to be a way to mark an extension that does
not have a body. This is currently done by using two colons instead of
one after the extension name. I would like to keep the syntax easy, ie.
everything between `{::NAME` and `}` should be syntactically equal to
the contents of an IAL. Therefore the only place to add information
whether the extension has a body or not is directly before or after
`NAME`.

> 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:
>
> <SNIP />
>
> <kd-ial .important>
> This is an important notice
> <kd-/>
> 
> 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.

IALs won't be affected, this discussion is purely about the extensions
and its syntax, ie. comment, nomarkdown and options. 

-- Thomas

From svicalifornia at gmail.com  Tue Apr 13 06:02:34 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 13 Apr 2010 20:02:34 +1000
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100413113340.1f4950d0@noeato.local>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
	<20100413111431316612.788e8411@gmail.com>
	<20100413081622.074fb832@noeato.local>
	<20100413163606054430.a4ea8fb1@gmail.com>
	<20100413113340.1f4950d0@noeato.local>
Message-ID: <20100413200234293412.e0fbc595@gmail.com>

Last week, I suggested that there should be a single consistent tag style for both IALs and extensions, and you seemed to agree:

>> Juse like all ERB tags have <% %> wrappers, I think there should be
>> similar consistency in kramdown.
> 
> Thanks for pointing this out!

So how can we discuss extension tag style without also examining the impacts if the proposed styles are carried to IALs for consistency?

Shawn

On Tue, 13 Apr 2010 11:33:40 +0200, Thomas Leitner wrote:
> On Tue, 13 Apr 2010 16:36:06 +1000, Shawn Van Ittersum wrote:
>> 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.
> 
> No inner prefix, just a plain XML namespace, ie.
> {::comment}...{:/comment} becomes <md:comment>...</md:comment>. This
> should be compatible with all HTML template languages! However, I
> already mentioned this suggestion in another thread about "Backward
> incompatible changes..." and the answers clearly showed that a
> consistent syntax was preferred over extension via XML namespaces.
> 
> Regarding nesting of tags: think about how Java multiline comments
> cannot be nested (ie. `/* .... */`). The same is currently true for
> kramdown extensions.
> 
> Another point: there needs to be a way to mark an extension that does
> not have a body. This is currently done by using two colons instead of
> one after the extension name. I would like to keep the syntax easy, ie.
> everything between `{::NAME` and `}` should be syntactically equal to
> the contents of an IAL. Therefore the only place to add information
> whether the extension has a body or not is directly before or after
> `NAME`.
> 
>> 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:
>> 
>> <SNIP />
>> 
>> <kd-ial .important>
>> This is an important notice
>> <kd-/>
>> 
>> 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.
> 
> IALs won't be affected, this discussion is purely about the extensions
> and its syntax, ie. comment, nomarkdown and options. 
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From t_leitner at gmx.at  Tue Apr 13 11:50:42 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 13 Apr 2010 17:50:42 +0200
Subject: [kramdown-users] Inline comments
In-Reply-To: <20100413200234293412.e0fbc595@gmail.com>
References: <4BC17C97.40203@gmx.at> <20100411194706.1bfa76ef@noeato.local>
	<4BC2278C.9020701@gmx.at> <20100412064629373023.047b9d19@gmail.com>
	<4BC28CA5.5010603@sunshineco.com>
	<20100412151144984956.36fc4aac@gmail.com>
	<4BC2B986.6040808@sunshineco.com>
	<20100412163145935180.c3e32d9d@gmail.com>
	<20100412203207.4655ce81@noeato.local>
	<20100413111431316612.788e8411@gmail.com>
	<20100413081622.074fb832@noeato.local>
	<20100413163606054430.a4ea8fb1@gmail.com>
	<20100413113340.1f4950d0@noeato.local>
	<20100413200234293412.e0fbc595@gmail.com>
Message-ID: <20100413175042.3e60d60e@noeato.local>

On Tue, 13 Apr 2010 20:02:34 +1000, Shawn Van Ittersum wrote:
> Last week, I suggested that there should be a single consistent tag
> style for both IALs and extensions, and you seemed to agree:
> 
> >> Juse like all ERB tags have <% %> wrappers, I think there should be
> >> similar consistency in kramdown.
> > 
> > Thanks for pointing this out!
> 
> So how can we discuss extension tag style without also examining the
> impacts if the proposed styles are carried to IALs for consistency?

I think it is the other way around: IALs will stay the same, extensions
probably too but the extensions syntax *may* be changed. I.e. the
syntax for IALs (and ALDs) is of no concern in this discussion since it
will not be changed. The point of the discussion is whether the syntax
of extensions should be slightly changed (e.g. removal of trailing
colons, syntax support for nesting, ...) or not. However, since everyone
would like to have a similar syntax for IALs and extensions, there are
some constraints regarding the syntax of extensions based on the
syntax of IALs (as laid out in my previous mail). This ensures the
consistency of the syntax, even if the extension syntax is changed.

-- Thomas

From t_leitner at gmx.at  Fri Apr 16 05:23:53 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Fri, 16 Apr 2010 11:23:53 +0200
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
Message-ID: <20100416112353.01646de1@noeato.local>

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

From svicalifornia at gmail.com  Fri Apr 16 06:34:32 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Fri, 16 Apr 2010 20:34:32 +1000
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100416112353.01646de1@noeato.local>
References: <20100416112353.01646de1@noeato.local>
Message-ID: <20100416203432944108.5904f5e6@gmail.com>

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.

Thanks,
Shawn

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

From t_leitner at gmx.at  Mon Apr 19 11:40:35 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Mon, 19 Apr 2010 17:40:35 +0200
Subject: [kramdown-users] Backward incompatible changes in
 parser/converter
In-Reply-To: <20100407102345.1555dd90@noeato.local>
References: <20100407102345.1555dd90@noeato.local>
Message-ID: <20100419174035.30fa2fe2@noeato.local>

> * Removing the options :parse_block_html and :parse_span_html

These two options won't be removed for now.

-- Thomas

From sunshine at sunshineco.com  Mon Apr 19 15:37:28 2010
From: sunshine at sunshineco.com (Eric Sunshine)
Date: Mon, 19 Apr 2010 15:37:28 -0400
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100416112353.01646de1@noeato.local>
References: <20100416112353.01646de1@noeato.local>
Message-ID: <4BCCB0F8.6070403@sunshineco.com>

Hi Thomas,

I was going to wait until Shawn posted since he probably has more 
significant comments to make, whereas mine are fairly minor. However, it 
seems best to write down my thoughts down before forgetting them entirely.

On 4/16/2010 5:23 AM, Thomas Leitner wrote:
>    So, how do we make the current syntax shorter?
>    *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"}

The mnemonic significance to the ">" is not entirely obvious other than 
">" being a closing symbol of XML/HTML tokens. My personal aesthetic 
reaction also is that it also looks rather ugly.  Some other 
possibilities, including mnemonic hints:

     {:options/ key="val"}  hint: XML/HTML
     {:options$ key="val"}  hint: regular expressions
     {:options. key="val"}  hint: written language
     {:options! key="val"}  hint: emphatic "that's all!"
     {:/options key="val"}  hint: XML/HTML

The last example could potentially be confused as a closing tag (if you 
go that route), thus probably would not be wise. Shawn's proposal of 
"{:options ... /}" also had merit in the spirit of XML/HTML, although I 
understand that you prefer to have such tokens at the start rather than 
end of the sequence. (Perhaps you could clarify the reasoning behind 
this.) If tokens at the end of sequence were allowed, then another 
possibility would be:

     {:options key="val":}  hint: symmetry of {: and :}

> 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?

The conservative in me feels uncomfortable with the idea of removing or 
making optional the leading colon. The sequence "{:" is sufficiently 
uncommon in text that I don't worry about conflicts, but opening with a 
bare "{" seems too dangerous.

> 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...

Is it documented anywhere that the leading colon is optional in Maruku 
IALs? I never knew this until you mentioned it and I tested it for 
myself. Every example on the Maruku site includes the colon. In any 
event, unnecessarily breaking compatibility with Maruku (or other 
Markdown processors) seems like a bad idea.

-- ES

From svicalifornia at gmail.com  Tue Apr 20 00:24:26 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 20 Apr 2010 14:24:26 +1000
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <4BCCB0F8.6070403@sunshineco.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
Message-ID: <20100420142426663263.59e9c710@gmail.com>

Sorry it has taken me so long to reply.  A lot going on lately! :)

Eric pretty well summarized my feelings on the ">" syntax.  To that, I'll add that because ">" is used so commonly in HTML/XML to end tags, it's very confusing to find it in the middle of a kramdown tag.  This is even more troublesome when we consider that HTML/XML/ERB will likely appear in some kramdown documents.

I apologize for not seeing the syntax on ALDs.  I hadn't used them yet, so I went to check that out.  I also went to the Maruku docs on attribute lists (which are here: http://maruku.rubyforge.org/proposal.html).  I see now that my proposed syntax for extensions didn't differentiate them clearly enough from ALDs.

So here's a new set of proposals:

1. Personally, I wish the Maruku team had adopted the equal sign (=) to assign attributes to references in ALDs:

  {:ref=.class1 #id ... }

I'd like to request that as an optional alternate syntax to the Maruku convention, as it is so much clearer than adding an extra colon.  However, we should still support the Maruku convention, so we'll still need to make the extension syntax distinct (see next point).

2. Amending my proposal for extensions, I had also considered with the idea of a standard prefix character on extension directives.  In this case, we don't even need the colon, since the prefix serves as a signal that we are invoking a kramdown extension.  Since invoking an extension is something like calling a subroutine, it seems appropriate (and also looks pretty good, I think) to borrow the ampersand from Perl:

  {&extension arg1 arg2 ... }

Other alternatives would include:

  {@extension arg1 arg2 ... }
  {!extension arg1 arg2 ... }
  {%extension arg1 arg2 ... }

Then we make a rule that ALD reference names can't start with such a prefix character, and there we have the distinction between ALDs and extensions.

3. For indicating closing tags and tags with no body, I continue to advocate the use of the slash as in HTML/XML:

  {&nomarkdown}Content{/nomarkdown}
  {&options ... /}
  {&shorthand}Content{/}

(Note that the ampersand is not necessary on the closing tag.)

Adopting the slash takes advantage of decades of HTML convention and familiarity, without actually using the angle brackets <...> that will get confused with ERB and HTML tags that should be left untouched by kramdown.

4. It would be incredibly cool if kramdown would support custom extensions in the future.  I'm working on a software documentation project now in kramdown, where I will often need to link to a separate system that contains database schema definitions.  I would love to define a ruby method and be able to call it in the middle of my kramdown documents:

  User data is stored in the {&db_schema_link users /} table.

with a corresponding Ruby method (note the return value of the custom extension method is in kramdown syntax, to be evaluated by kramdown):

  def db_schema_link(table_name)
	"[#{table_name}](http://docs.project.com/schema/#{table_name}.html)"
  end

The method would be defined in the Ruby context in which the kramdown document was executed.  There could also be a new standard extensions to define inline custom extensions, or include a Ruby file to be evaluated in the kramdown context and define the custom extensions:

  {&ruby}
	def my_extension ...
    
    end
  {/}
  {&require my_extensions.rb /}

5. With the added support for custom extensions, we will have a clear use case for nested extension calls:

  {&comment}
	This block contains a {&custom_extension}invocation{/}
    but we can still quickly comment it by surrounding it with a comment tag.
  {/}

  {&one_custom_extension} might also take {&another_extension}'s return value{/} as part of its input.{/}


In summary, I think we should adopt slashes as in HTML, support tag nesting, and use this syntax:

IAL  {: ...}
ALD  {:ref:  ...}  or  {:ref = ...}
Ext  {&extension}{/extension}  or  {&extension /}

Shawn

On Mon, 19 Apr 2010 15:37:28 -0400, Eric Sunshine wrote:
> Hi Thomas,
> 
> I was going to wait until Shawn posted since he probably has more 
> significant comments to make, whereas mine are fairly minor. However, 
> it seems best to write down my thoughts down before forgetting them 
> entirely.
> 
> On 4/16/2010 5:23 AM, Thomas Leitner wrote:
>>    So, how do we make the current syntax shorter?
>>    *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"}
> 
> The mnemonic significance to the ">" is not entirely obvious other 
> than ">" being a closing symbol of XML/HTML tokens. My personal 
> aesthetic reaction also is that it also looks rather ugly.  Some 
> other possibilities, including mnemonic hints:
> 
>     {:options/ key="val"}  hint: XML/HTML
>     {:options$ key="val"}  hint: regular expressions
>     {:options. key="val"}  hint: written language
>     {:options! key="val"}  hint: emphatic "that's all!"
>     {:/options key="val"}  hint: XML/HTML
> 
> The last example could potentially be confused as a closing tag (if 
> you go that route), thus probably would not be wise. Shawn's proposal 
> of "{:options ... /}" also had merit in the spirit of XML/HTML, 
> although I understand that you prefer to have such tokens at the 
> start rather than end of the sequence. (Perhaps you could clarify the 
> reasoning behind this.) If tokens at the end of sequence were 
> allowed, then another possibility would be:
> 
>     {:options key="val":}  hint: symmetry of {: and :}
> 
>> 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?
> 
> The conservative in me feels uncomfortable with the idea of removing 
> or making optional the leading colon. The sequence "{:" is 
> sufficiently uncommon in text that I don't worry about conflicts, but 
> opening with a bare "{" seems too dangerous.
> 
>> 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...
> 
> Is it documented anywhere that the leading colon is optional in 
> Maruku IALs? I never knew this until you mentioned it and I tested it 
> for myself. Every example on the Maruku site includes the colon. In 
> any event, unnecessarily breaking compatibility with Maruku (or other 
> Markdown processors) seems like a bad idea.
> 
> -- ES
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From t_leitner at gmx.at  Tue Apr 20 03:37:58 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 20 Apr 2010 09:37:58 +0200
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <4BCCB0F8.6070403@sunshineco.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
Message-ID: <20100420093758.418e963c@noeato.local>

> >    Extension without body:
> >        {:options>  key="val"}
> 
> The mnemonic significance to the ">" is not entirely obvious other
> than ">" being a closing symbol of XML/HTML tokens. My personal
> aesthetic reaction also is that it also looks rather ugly.  Some
> other possibilities, including mnemonic hints:
> 
>      {:options/ key="val"}  hint: XML/HTML
>      {:options$ key="val"}  hint: regular expressions
>      {:options. key="val"}  hint: written language
>      {:options! key="val"}  hint: emphatic "that's all!"
>      {:/options key="val"}  hint: XML/HTML

I agree that `>` is not perfect for the job.
 
> The last example could potentially be confused as a closing tag (if
> you go that route), thus probably would not be wise. Shawn's proposal
> of "{:options ... /}" also had merit in the spirit of XML/HTML,
> although I understand that you prefer to have such tokens at the
> start rather than end of the sequence. (Perhaps you could clarify the
> reasoning behind this.) If tokens at the end of sequence were
> allowed, then another possibility would be:
> 
>      {:options key="val":}  hint: symmetry of {: and :}

One reason why I would like to have the token at the start is that it
is easier to parse and when you encounter such a tag you immediately
know that it contains no body. However, this should not hinder us - I'm
perfectly willing to put a token at the end!

Regarding the colon as the token: Although the symmetry seems nice, I
fear that the colon can be overlooked to easily. Therefore I would
rather go with a slash instead of a colon, also keeping in mind Shawn's
proposal and the similarity to XML/XHTML.

> > 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?
> 
> The conservative in me feels uncomfortable with the idea of removing
> or making optional the leading colon. The sequence "{:" is
> sufficiently uncommon in text that I don't worry about conflicts, but
> opening with a bare "{" seems too dangerous.

Okay, that's good to hear :-) I kinda feel the same - I was just
throwing it in because we were already talking about syntax changes. So
we will have the leading colon in IALs/ALDs/extension.

> > 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...
> 
> Is it documented anywhere that the leading colon is optional in
> Maruku IALs? I never knew this until you mentioned it and I tested it
> for myself. Every example on the Maruku site includes the colon. In
> any event, unnecessarily breaking compatibility with Maruku (or other 
> Markdown processors) seems like a bad idea.

I don't think that it is documented anywhere, I found it while looking
through Maruku's sources. Since the leading colon will stay, there is
also no problem with compatibility.

-- Thomas

From t_leitner at gmx.at  Tue Apr 20 04:17:06 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 20 Apr 2010 10:17:06 +0200
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100420142426663263.59e9c710@gmail.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
Message-ID: <20100420101706.0399325f@noeato.local>

> Eric pretty well summarized my feelings on the ">" syntax.  To that,
> I'll add that because ">" is used so commonly in HTML/XML to end
> tags, it's very confusing to find it in the middle of a kramdown
> tag.  This is even more troublesome when we consider that
> HTML/XML/ERB will likely appear in some kramdown documents.

As I replied to Eric's mail, it was just one of the characters that
came in mind and I agree that it might be confusing.

> 1. Personally, I wish the Maruku team had adopted the equal sign (=)
> to assign attributes to references in ALDs:
> 
>   {:ref=.class1 #id ... }
> 
> I'd like to request that as an optional alternate syntax to the
> Maruku convention, as it is so much clearer than adding an extra
> colon.  However, we should still support the Maruku convention, so
> we'll still need to make the extension syntax distinct (see next
> point).

I don't think that the equal sign would be a good choice. I.e., while
reading your above example one can easily think that `ref` has the
value `.class1`. I also don't want to add optional alternate syntax if
there is no good reason for it - convenience is too little. 

So I would rather stay with `{:ref: .cls #id key="val"}` regarding ALDs.
 
> 2. Amending my proposal for extensions, I had also considered with
> the idea of a standard prefix character on extension directives.  In
> this case, we don't even need the colon, since the prefix serves as a
> signal that we are invoking a kramdown extension.  Since invoking an
> extension is something like calling a subroutine, it seems
> appropriate (and also looks pretty good, I think) to borrow the
> ampersand from Perl:
> 
>   {&extension arg1 arg2 ... }
> 
> Other alternatives would include:
> 
>   {@extension arg1 arg2 ... }
>   {!extension arg1 arg2 ... }
>   {%extension arg1 arg2 ... }
> 
> Then we make a rule that ALD reference names can't start with such a
> prefix character, and there we have the distinction between ALDs and
> extensions.

ALD names already have such a restriction - see
http://kramdown.rubyforge.org/syntax.html#attribute-list-definitions

Also, for consistency I don't want to omit the leading colon, even in
extensions. And I think that the ampersand is too "blocky", ie. the
beginning of the extension name is hard to read. The exclamation mark
would be a better choice in this regard I think.

> 4. It would be incredibly cool if kramdown would support custom
> extensions in the future.  I'm working on a software documentation
> project now in kramdown, where I will often need to link to a
> separate system that contains database schema definitions.  I would
> love to define a ruby method and be able to call it in the middle of
> my kramdown documents:
> 
>   User data is stored in the {&db_schema_link users /} table.
> 
> with a corresponding Ruby method (note the return value of the custom
> extension method is in kramdown syntax, to be evaluated by kramdown):
> 
>   def db_schema_link(table_name)
> 	"[#{table_name}](http://docs.project.com/schema/#{table_name}.html)"
>   end

I think that this is not the way to go. You are mixing two things here:
a markup language that is used for writing probably large amounts of
text and which supports a certain syntax for marking up some parts of
the text. And a template processor which is used to execute arbitrary
code.

kramdown is a markup language and not a template processor. Its syntax
is used for semantically marking up parts of the text as paragraph,
block quotes, emphasis, link and so on. This has and should have nothing
to do with executing arbitrary code. While implementing kramdown I
thought that this would be good idea and therefore added support for
it, even using it on the kramdown homepage... However, my opinion on
that changed.

The current "extensions" are useful in kramdown as a markup language
since often one wants to omit draft text or one's notes from the output
(comment) or work around an edge case where kramdown does not work
correctly (nomarkdown) or wants to set options on how the kramdown
document is converted (options).

What you want to achieve can already be achieved in a much simpler way:
just use ERB tags and run ERB first and the kramdown. This will do
exactly what you want! And it is much more flexible than any solution
within kramdown. If you don't want to be tied to a syntax that is Ruby
specific, you can use another template processor like [moustache] which
is language agnostic.

   Therefore I think that extensions in kramdown are really not that
            useful and I would like to remove them!

As for the syntax: In the case of not having custom extensions, it can
be simplied to something like the following (same for block and span
extensions):

  {:comment}some comment{:/comment}      # verbose form
  {:comment}some comment{:/}             # short form
  {:options key="val" /}                 # no-body form

In this case we also don't need an extra differentiator like `!` at the
beginning of a extension name since the names are "well known". Also
note that the short form would need to have the leading colon as well!

[moustache]: http://mustache.github.com/

-- Thomas

ps. The repo version now contains the last missing syntax from
Maruku/PHP Markdown extra: abbreviations ;-)

From svicalifornia at gmail.com  Tue Apr 20 04:31:20 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Tue, 20 Apr 2010 18:31:20 +1000
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100420101706.0399325f@noeato.local>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
Message-ID: <20100420183120360818.87d63fce@gmail.com>

On Tue, 20 Apr 2010 10:17:06 +0200, Thomas Leitner wrote:
>> 1. Personally, I wish the Maruku team had adopted the equal sign (=)
>> to assign attributes to references in ALDs:
>> 
>>   {:ref=.class1 #id ... }
>> 
>> I'd like to request that as an optional alternate syntax to the
>> Maruku convention, as it is so much clearer than adding an extra
>> colon.  However, we should still support the Maruku convention, so
>> we'll still need to make the extension syntax distinct (see next
>> point).
> 
> I don't think that the equal sign would be a good choice. I.e., while
> reading your above example one can easily think that `ref` has the
> value `.class1`. I also don't want to add optional alternate syntax if
> there is no good reason for it - convenience is too little. 

Both good points.  The Maruku syntax is fine.

> Also, for consistency I don't want to omit the leading colon, even in
> extensions. And I think that the ampersand is too "blocky", ie. the
> beginning of the extension name is hard to read. The exclamation mark
> would be a better choice in this regard I think.

OK.  Works for me.

>> 4. It would be incredibly cool if kramdown would support custom
>> extensions in the future.  I'm working on a software documentation
>> project now in kramdown, where I will often need to link to a
>> separate system that contains database schema definitions.  I would
>> love to define a ruby method and be able to call it in the middle of
>> my kramdown documents:
>> 
>>   User data is stored in the {&db_schema_link users /} table.
>> 
>> with a corresponding Ruby method (note the return value of the custom
>> extension method is in kramdown syntax, to be evaluated by kramdown):
>> 
>>   def db_schema_link(table_name)
>> 	"[#{table_name}](http://docs.project.com/schema/#{table_name}.html)"
>>   end
> 
> I think that this is not the way to go. You are mixing two things here:
> a markup language that is used for writing probably large amounts of
> text and which supports a certain syntax for marking up some parts of
> the text. And a template processor which is used to execute arbitrary
> code.
> 
> kramdown is a markup language and not a template processor. Its syntax
> is used for semantically marking up parts of the text as paragraph,
> block quotes, emphasis, link and so on. This has and should have nothing
> to do with executing arbitrary code. While implementing kramdown I
> thought that this would be good idea and therefore added support for
> it, even using it on the kramdown homepage... However, my opinion on
> that changed.
> 
> The current "extensions" are useful in kramdown as a markup language
> since often one wants to omit draft text or one's notes from the output
> (comment) or work around an edge case where kramdown does not work
> correctly (nomarkdown) or wants to set options on how the kramdown
> document is converted (options).
> 
> What you want to achieve can already be achieved in a much simpler way:
> just use ERB tags and run ERB first and the kramdown. This will do
> exactly what you want! And it is much more flexible than any solution
> within kramdown. If you don't want to be tied to a syntax that is Ruby
> specific, you can use another template processor like [moustache] which
> is language agnostic.

Well, OK.  Kind of a disappointment, but I can live with it.  And you're right, it seems like there's no need to rebuild an ERB-style template engine in kramdown, when there's already ERB.  I'll have to modify the kramdown-wiki I've made to process ERB before kramdown.  No big deal.

>    Therefore I think that extensions in kramdown are really not that
>             useful and I would like to remove them!

For all that I've contributed on this matter of extensions syntax, I've never actually used them yet, so I don't even know if I would miss them.  But it seems like other have and might.

> As for the syntax: In the case of not having custom extensions, it can
> be simplied to something like the following (same for block and span
> extensions):
> 
>   {:comment}some comment{:/comment}      # verbose form
>   {:comment}some comment{:/}             # short form
>   {:options key="val" /}                 # no-body form
> 
> In this case we also don't need an extra differentiator like `!` at the
> beginning of a extension name since the names are "well known". Also
> note that the short form would need to have the leading colon as well!

So you're suggesting that the extension names be "reserved words," not available as ALD reference names.  I'm cool with that.

Shawn

From t_leitner at gmx.at  Tue Apr 20 09:45:34 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Tue, 20 Apr 2010 15:45:34 +0200
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100420183120360818.87d63fce@gmail.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
	<20100420183120360818.87d63fce@gmail.com>
Message-ID: <20100420154534.7f8e799e@noeato.local>

> >    Therefore I think that extensions in kramdown are really not that
> >             useful and I would like to remove them!
> 
> For all that I've contributed on this matter of extensions syntax,
> I've never actually used them yet, so I don't even know if I would
> miss them.  But it seems like other have and might.

Yes, some might already use them. However, I think that this is a
minority and we can transition to the new syntax in the next release
while deprecating the old functionality and removing in a following
one.
 
> > In this case we also don't need an extra differentiator like `!` at
> > the beginning of a extension name since the names are "well known".
> > Also note that the short form would need to have the leading colon
> > as well!
> 
> So you're suggesting that the extension names be "reserved words,"
> not available as ALD reference names.  I'm cool with that.

Not really reserved words, no. Since there is a syntactic difference
between ALDs and extension names (no trailing colon), even the
extension names can be used as ALD names although that is surely not
recommened.

-- Thomas

From sunshine at sunshineco.com  Tue Apr 20 10:48:01 2010
From: sunshine at sunshineco.com (Eric Sunshine)
Date: Tue, 20 Apr 2010 10:48:01 -0400
Subject: [kramdown-users] Syntax of IALs, ALDs and extensions
In-Reply-To: <20100420101706.0399325f@noeato.local>
References: <20100416112353.01646de1@noeato.local>	<4BCCB0F8.6070403@sunshineco.com>	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
Message-ID: <4BCDBEA1.20703@sunshineco.com>

On 4/20/2010 4:17 AM, Thomas Leitner wrote:
> What you want to achieve can already be achieved in a much simpler way:
> just use ERB tags and run ERB first and the kramdown. This will do
> exactly what you want! And it is much more flexible than any solution
> within kramdown. If you don't want to be tied to a syntax that is Ruby
> specific, you can use another template processor like [moustache] which
> is language agnostic.

I agree with Thomas. It seems better for kramdown to remain 
(programming) language-agnostic, and to have proper separation between 
mark-up and ERB-like functionality. Such separation provides at least a 
couple important benefits: (1) Simplifies implementation of 
kramdown-compatible processors in other languages (Python, C#, etc.) 
since they do not have to incorporate Ruby-isms. (2) Greatly reduces the 
need for other kramdown-compatible implementations since one 
language-agnostic implementation can suffice for many needs. (Take HAML, 
as a counter-example, where clones or near-clones have popped up because 
people want to embed their favorite language -- Python, Lua, etc. -- 
within HAML, whereas the original only allows embedding Ruby.) With 
proper separation, users are free to employ whichever ERB-like 
pre-processor supports their favorite language.

> As for the syntax: In the case of not having custom extensions, it can
> be simplied to something like the following (same for block and span
> extensions):
>    {:comment}some comment{:/comment}      # verbose form
>    {:comment}some comment{:/}             # short form
>    {:options key="val" /}                 # no-body form

I think this is reasonable and should be easily grasped by new users 
(especially those coming from XML/HTML). Also, it still retains the 
"essence" of existing Markdown extensions (IAL, ALD, etc.), and thus 
does not feel so out of place as some of the other proposals.

-- ES

From svicalifornia at gmail.com  Sun Apr 25 01:53:57 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Sun, 25 Apr 2010 15:53:57 +1000
Subject: [kramdown-users] TOC
Message-ID: <20100425155357139214.3dd0fc8a@gmail.com>

Hi Thomas,

Was the {:toc} extension added to kramdown, or is it still on the to-do list?

Shawn

From t_leitner at gmx.at  Sun Apr 25 05:56:47 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 25 Apr 2010 11:56:47 +0200
Subject: [kramdown-users] TOC
In-Reply-To: <20100425155357139214.3dd0fc8a@gmail.com>
References: <20100425155357139214.3dd0fc8a@gmail.com>
Message-ID: <20100425115647.7303ea3f@noeato>

> Was the {:toc} extension added to kramdown, or is it still on the
> to-do list?

It is still on my TODO list. I'm thinking about whether to add this as
an extension -- it doesn't not provide a real value regarding parsing,
therefore I would rather not have it as an extension -- or by adding a
additionaly processor between parsers and converters which works in the
same manner as Maruku's implementation of the TOC and the current
implementation of syntax highlighting.

-- Thomas

From t_leitner at gmx.at  Wed Apr 28 02:26:19 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Wed, 28 Apr 2010 08:26:19 +0200
Subject: [kramdown-users] Problem with new extension syntax
In-Reply-To: <20100420183120360818.87d63fce@gmail.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
	<20100420183120360818.87d63fce@gmail.com>
Message-ID: <20100428082619.6c66c7c8@noeato.local>

> > As for the syntax: In the case of not having custom extensions, it
> > can be simplied to something like the following (same for block and
> > span extensions):
> > 
> >   {:comment}some comment{:/comment}      # verbose form
> >   {:comment}some comment{:/}             # short form
> >   {:options key="val" /}                 # no-body form
> > 
> > In this case we also don't need an extra differentiator like `!` at
> > the beginning of a extension name since the names are "well known".
> > Also note that the short form would need to have the leading colon
> > as well!
> 
> So you're suggesting that the extension names be "reserved words,"
> not available as ALD reference names.  I'm cool with that.

Now I finally completely understand what you meant here ;-) I simply
overlooked this case...

The problem is that

    {:comment}

can either be an IAL referencing the ALD named "comment" or the start
tag of an extension. This should not be the case! It should
syntactically be clear whether this is an extension or an IAL. Also,
since Maruku uses the above syntax for declaring an IAL, we would break
compatibility if we just reserved some ALD names.

Therefore I suggest using two colons before the extension name, like
this:

    {::comment}some comment made here{:/comment}
    {::options key="val" /}

This would remedy the situation but needs another character for
differentiation.

Suggestions? Ideas? Comments?

-- Thomas

From svicalifornia at gmail.com  Wed Apr 28 09:33:37 2010
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Wed, 28 Apr 2010 23:33:37 +1000
Subject: [kramdown-users] Problem with new extension syntax
In-Reply-To: <20100428082619.6c66c7c8@noeato.local>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
	<20100420183120360818.87d63fce@gmail.com>
	<20100428082619.6c66c7c8@noeato.local>
Message-ID: <20100429003337514102.1cd62f4f@gmail.com>

Well, I prefer {:!comment...}, but double-colon works too.

Shawn

On Wed, 28 Apr 2010 08:26:19 +0200, Thomas Leitner wrote:
>>> As for the syntax: In the case of not having custom extensions, it
>>> can be simplied to something like the following (same for block and
>>> span extensions):
>>> 
>>>   {:comment}some comment{:/comment}      # verbose form
>>>   {:comment}some comment{:/}             # short form
>>>   {:options key="val" /}                 # no-body form
>>> 
>>> In this case we also don't need an extra differentiator like `!` at
>>> the beginning of a extension name since the names are "well known".
>>> Also note that the short form would need to have the leading colon
>>> as well!
>> 
>> So you're suggesting that the extension names be "reserved words,"
>> not available as ALD reference names.  I'm cool with that.
> 
> Now I finally completely understand what you meant here ;-) I simply
> overlooked this case...
> 
> The problem is that
> 
>     {:comment}
> 
> can either be an IAL referencing the ALD named "comment" or the start
> tag of an extension. This should not be the case! It should
> syntactically be clear whether this is an extension or an IAL. Also,
> since Maruku uses the above syntax for declaring an IAL, we would break
> compatibility if we just reserved some ALD names.
> 
> Therefore I suggest using two colons before the extension name, like
> this:
> 
>     {::comment}some comment made here{:/comment}
>     {::options key="val" /}
> 
> This would remedy the situation but needs another character for
> differentiation.
> 
> Suggestions? Ideas? Comments?
> 
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

From t_leitner at gmx.at  Wed Apr 28 14:52:48 2010
From: t_leitner at gmx.at (Thomas Leitner)
Date: Wed, 28 Apr 2010 20:52:48 +0200
Subject: [kramdown-users] Problem with new extension syntax
In-Reply-To: <20100429003337514102.1cd62f4f@gmail.com>
References: <20100416112353.01646de1@noeato.local>
	<4BCCB0F8.6070403@sunshineco.com>
	<20100420142426663263.59e9c710@gmail.com>
	<20100420101706.0399325f@noeato.local>
	<20100420183120360818.87d63fce@gmail.com>
	<20100428082619.6c66c7c8@noeato.local>
	<20100429003337514102.1cd62f4f@gmail.com>
Message-ID: <20100428205248.5c5a0cfa@noeato.local>

On Wed, 28 Apr 2010 23:33:37 +1000, Shawn Van Ittersum wrote:
> Well, I prefer {:!comment...}, but double-colon works too.

Why the bang instead of the colon? Does it mean something special in
such a context?

-- Thomas