From quillio at gmail.com Sat Sep 1 05:33:47 2012 From: quillio at gmail.com (Lou Quillio) Date: Fri, 31 Aug 2012 22:33:47 -0700 Subject: [kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style In-Reply-To: References: <20120831161753.43178c94@noweto> <7748A8CF-754B-4D31-87B1-9D6BCACDAE08@tidbits.com> Message-ID: On Fri, Aug 31, 2012 at 11:47 AM, Eric Sunshine wrote: > 1) [Github alternate fenced blocks]: I am not a fan of this and other > gratuitous differences from the norm, and my gut reaction is to reject > the change. The only small justification I can make for accepting it > is that it would increase the likelihood of kramdown being employed > locally to compose and preview a Markdown document which ultimately > will be viewed in rendered form on Github. (Not picking on Eric here, just easier to jump-off from his post.) I don't think that accepting backticks on the same rules as tildes is likely to collide with anything -- and it has a consistency logic. Things that are good for kramdown and don't cause user pain are good. Within limits. Thomas is a good judge of those limits. > 2) [specify language on ~~~ line]: Seems like a reasonable convenience. Agree. > 3) [syntax highlighting language]: kramdown has been around long > enough and (presumably) is widely enough used that > backward-incompatible changes should not be undertaken lightly. If I > understand correctly, the backward-incompatible change to which you > refer is that kramdown would no longer recognize lang=FOO specially. > In the interest of backward-compatibility, perhaps continue to > recognize lang=FOO if the following is true: .language-FOO is not > present and the FOO in lang=FOO does not seem to be a natural language > specification [2]. (Rough heuristic: If FOO contains a hyphen or is > only two characters in length, then it's probably a natural language > specification.) Maybe this idea needs more time to marinate, see what people do in the real world. Setting a lexer with 'lang=' has a narrow and different purpose than natural-language setting, and I'm a bit uncomfortable with conflating them. If it turns out to be an uncomplicated, common markup practice, then it's safe. We just don't know yet, and there'd be a little pain. To me, there's no rush on this one. By chance, wrt RFC1766, the author is a colleague. I'll ping and get his opinion. LQ -- Lou Quillio http://quillio.com/ From t_leitner at gmx.at Sat Sep 1 08:31:27 2012 From: t_leitner at gmx.at (Thomas Leitner) Date: Sat, 1 Sep 2012 10:31:27 +0200 Subject: [kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style In-Reply-To: References: <20120831161753.43178c94@noweto> <7748A8CF-754B-4D31-87B1-9D6BCACDAE08@tidbits.com> Message-ID: <20120901103127.5fd21543@noweto> Thanks for all the replies so far! On 2012-08-31 22:33 -0700 Lou Quillio wrote: > On Fri, Aug 31, 2012 at 11:47 AM, Eric Sunshine > wrote: > > 1) [Github alternate fenced blocks]: I am not a fan of this and > > other gratuitous differences from the norm, and my gut reaction is > > to reject the change. The only small justification I can make for > > accepting it is that it would increase the likelihood of kramdown > > being employed locally to compose and preview a Markdown document > > which ultimately will be viewed in rendered form on Github. > > (Not picking on Eric here, just easier to jump-off from his post.) > > I don't think that accepting backticks on the same rules as tildes is > likely to collide with anything -- and it has a consistency logic. > Things that are good for kramdown and don't cause user pain are good. > Within limits. Thomas is a good judge of those limits. Since Github (or more exactly, the redcarpet/sundown library) supports the php-markdown-extra style fenced code blocks there really would be no benefit of supporting github style fenced code blocks - but that's just my opinion. When I think about this issue, I also think of two similar but not too simliar cases already present in the syntax: * We already have two ways of specifying headers (atx and setext). However, since those two syntaxes differ very much from each other and have come from a historic context this is okay. * It is possible to specify unordered lists with various characters (*, + and -). The case could be made that github style code blocks should be supported because from a syntactical point of view only the character (` instead of ~) changes. However, people inherently use stars and dashes for making lists, even with pen and paper. No such thing can be said for fenced code blocks, there is no natural character for starting/ending a code block. Therfore I would not introduce another, second way to do this. > > 3) [syntax highlighting language]: kramdown has been around long > > enough and (presumably) is widely enough used that > > backward-incompatible changes should not be undertaken lightly. If I > > understand correctly, the backward-incompatible change to which you > > refer is that kramdown would no longer recognize lang=FOO specially. > > In the interest of backward-compatibility, perhaps continue to > > recognize lang=FOO if the following is true: .language-FOO is not > > present and the FOO in lang=FOO does not seem to be a natural > > language specification [2]. (Rough heuristic: If FOO contains a > > hyphen or is only two characters in length, then it's probably a > > natural language specification.) > > Maybe this idea needs more time to marinate, see what people do in the > real world. Setting a lexer with 'lang=' has a narrow and different > purpose than natural-language setting, and I'm a bit uncomfortable > with conflating them. If it turns out to be an uncomplicated, common > markup practice, then it's safe. We just don't know yet, and there'd > be a little pain. To me, there's no rush on this one. The problem is that those things *are* currently conflated. I have based the initial syntax on that of MaRuKu and it has used the `lang=LANG` for specifying the syntax highlighting language - and I didn't think enough about this when implementing it. Due to the recent Github pull request I saw that this is probably not so a good idea because the 'lang' attribute as defined by the HTML specs is only for natural languages and kramdown abuses it. Therefore I would like to get rid of it, the sooner the better. The more people use kramdown the harder it will be to make backward-incompatible changes. I know that kramdown is already widely used but I don't think that this exact feature is that widely used. Eric's idea for backward-compatibility is rather nice. So how about making the change (releasing 0.14.0 because of this) and providing such a heuristic for current users until the next major release (0.15.0 or 1.0.0)? Best regards, Thomsa From matt at tidbits.com Sat Sep 1 10:54:06 2012 From: matt at tidbits.com (Matt Neuburg) Date: Sat, 1 Sep 2012 03:54:06 -0700 Subject: [kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style In-Reply-To: <20120901103127.5fd21543@noweto> References: <20120831161753.43178c94@noweto> <7748A8CF-754B-4D31-87B1-9D6BCACDAE08@tidbits.com> <20120901103127.5fd21543@noweto> Message-ID: <83FC126D-B0EA-4859-8D81-5FEC01DD4A74@tidbits.com> And after all you are also doing fenced code blocks differently from asciidoc, but that is not a reason to add asciidoc style syntax. I speak kramdown, I speak asciidoc: I know they are not the same. m. ----- Sent from my iPad, but I am not a dork. Really. On Sep 1, 2012, at 1:31 AM, Thomas Leitner wrote: > there is no natural character for starting/ending a code > block From david.doolin at gmail.com Sat Sep 1 14:01:55 2012 From: david.doolin at gmail.com (David Doolin) Date: Sat, 1 Sep 2012 07:01:55 -0700 Subject: [kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style In-Reply-To: <20120901103127.5fd21543@noweto> References: <20120831161753.43178c94@noweto> <7748A8CF-754B-4D31-87B1-9D6BCACDAE08@tidbits.com> <20120901103127.5fd21543@noweto> Message-ID: On Sat, Sep 1, 2012 at 1:31 AM, Thomas Leitner wrote: [] > > Therefore I would like to get rid of it, the sooner the better. The Do it while you still can. -- primus inter parse From t_leitner at gmx.at Wed Sep 12 18:08:49 2012 From: t_leitner at gmx.at (Thomas Leitner) Date: Wed, 12 Sep 2012 20:08:49 +0200 Subject: [kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style In-Reply-To: <20120831161753.43178c94@noweto> References: <20120831161753.43178c94@noweto> Message-ID: <20120912200849.7f8fdce0@noweto> Thanks for all the replies! I will do the following: * Not implement Github style fenced code blocks for the time being * Implement support for setting the syntax highlighting language on the delimiter line of fenced code blocks * use class 'language-CODELANG' instead of 'lang' attr for highlighting language (a backwards incompatible change) -- Thomas On 2012-08-31 16:17 +0200 Thomas Leitner wrote: > Hi everybody, > > there is a [pull request][1] on Github which, among other things, > wants to add 1) support for Github flavored code style and 2) support > for setting the highlighting language on the delimiter line of a > fenced code block. > > [1]: https://github.com/gettalong/kramdown/pull/15 > > I also want to talk 3) about the current way of setting the > highlighting language. > > > ad 1) kramdown already has a fenced code block style: > > ~~~ > some code here > ~~~ > > Github flavored code blocks use a backtick instead: > > ``` > some code here > ``` > > I personally don't think that it is necessary or even good in this > case to provide another syntax for fenced code blocks. Using the > backtick currently only works on the Github website itself, as far as > I know. > > Also note that the kramdown (and php-markdown-extra and > python-markdown) fenced code blocks *do* work on Github, too! > > So, what do you think? > > > ad 2) Providing the syntax highlighting language on the delimiter line > is a rather nice idea and not only supported by Github but also by > other markdown implementations (like python-markdown). It would look > like this: > > ~~~~~~ ruby > class MyRuby > end > ~~~~~~~~~~~~ > > I would like to integrate this into kramdown -- does anyone have good > reasons for not using this syntax? > > > ad 3) The syntax highlighting language can currently be set by using > an IAL to specify the attribute `lang`. However, the `lang` attribute > in HTML elements is generally used for setting the natural language > of the text inside an element... > > I'm for removing this collision by following the HTML5 way of > specifying the highlighting language, which is setting the class > `language-CODELANG` on the `` element. > > This would mean that this kramdown document: > > ~~~ > some code here > ~~~ > {: .language-ruby .other attr="key"} > > would be transformed to this HTML output (in case coderay was not > used): > > 
some
> code here
> > Note that the `language-ruby` class is set on the `` element and > not on the parent `
` element!
> 
> This would be a backwards-incompatible change, what do you think?
> 
> 
> Best regards,
>   Thomas

From quillio at gmail.com  Fri Sep 14 04:12:44 2012
From: quillio at gmail.com (Lou Quillio)
Date: Thu, 13 Sep 2012 21:12:44 -0700
Subject: [kramdown-users] Syntax for specifying code highlighting
 language | Github flavored code blocks style
In-Reply-To: <20120912200849.7f8fdce0@noweto>
References: <20120831161753.43178c94@noweto> <20120912200849.7f8fdce0@noweto>
Message-ID: 

On Wed, Sep 12, 2012 at 11:08 AM, Thomas Leitner  wrote:
> Thanks for all the replies!
>
> I will do the following:
>
> * Not implement Github style fenced code blocks for the time being

Works. I had thought you were implying, originally, that there might
be a promotional benefit for kramdown by adding this alternate syntax,
if a bunch of githubbers were using it, etc. If not, leave it out --
but I think it would be safe to add if there were a good reason. Don't
need it myself.

> * Implement support for setting the syntax highlighting language on the
>   delimiter line of fenced code blocks

Cleaner. Often, the only IALs in my documents are on [fenced] code
blocks, so something a little more elegant is welcome.

> * use class 'language-CODELANG' instead of 'lang' attr for highlighting
>   language (a backwards incompatible change)

Good call. If 'lang' collides a little now, it may worsen. A little
pain now (worst case is a broken syntax-highlighting hook, not
outright broken code-block markup) is better than much pain later.
'language-CODELANG' is safely discrete, and you likely won't have to
revisit this.

LQ


-- 
Lou Quillio
http://quillio.com/

From t_leitner at gmx.at  Sun Sep 16 06:17:40 2012
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 16 Sep 2012 08:17:40 +0200
Subject: [kramdown-users] [ANN] kramdown 0.14.0
Message-ID: <20120916081740.5ce22906@noweto>

## 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.14.0 released

First of all please note that this release contains a
**backwards-incompatible** change: The syntax for specifying a code
language for a code block or code span has changed. Instead of using
`lang='CODELANG'` one has to use `.language-CODELANG` now.

This change has been introduced to avoid problems because the
`lang="..."` attribute is used by HTML for other purposes than setting
the code language. Furthermore using `.language-CODELANG` is also
proposed by HTML5 and it seems to be a good way to achieve the needed
functionality.

Other changes in this release include the possibility of setting the
code language on the starting line of a fenced code block and a way of
excluding certain headers from the table of contents by assigning the
`.no_toc` class to them.

## Changes

* 2 major changes

  - Code language is now specified via `.language-CODELANG` instead of
    `lang='CODELANG'`
  - Implemented support for setting language on fenced code block
    starting line (initial patch by Bran)

* 1 minor change

  - Headers with an ID can be prevented from showing in the TOC by
    assigning the `.no_toc` class to them (patch by Tim Bates)

* 1 bug fix

  - Numeric instead of symbolic HTML entities are now the default
    fallback (patch by Gioele Barabucci)

From svicalifornia at gmail.com  Sun Sep 16 07:19:17 2012
From: svicalifornia at gmail.com (Shawn Van Ittersum)
Date: Sun, 16 Sep 2012 00:19:17 -0700
Subject: [kramdown-users] [ANN] kramdown 0.14.0
In-Reply-To: <20120916081740.5ce22906@noweto>
References: <20120916081740.5ce22906@noweto>
Message-ID: 

When will kramdown be deemed worthy of a 1.0 version number?

Shawn

On Sep 15, 2012, at 11:17 PM, Thomas Leitner wrote:

> ## 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.14.0 released
> 
> First of all please note that this release contains a
> **backwards-incompatible** change: The syntax for specifying a code
> language for a code block or code span has changed. Instead of using
> `lang='CODELANG'` one has to use `.language-CODELANG` now.
> 
> This change has been introduced to avoid problems because the
> `lang="..."` attribute is used by HTML for other purposes than setting
> the code language. Furthermore using `.language-CODELANG` is also
> proposed by HTML5 and it seems to be a good way to achieve the needed
> functionality.
> 
> Other changes in this release include the possibility of setting the
> code language on the starting line of a fenced code block and a way of
> excluding certain headers from the table of contents by assigning the
> `.no_toc` class to them.
> 
> ## Changes
> 
> * 2 major changes
> 
>  - Code language is now specified via `.language-CODELANG` instead of
>    `lang='CODELANG'`
>  - Implemented support for setting language on fenced code block
>    starting line (initial patch by Bran)
> 
> * 1 minor change
> 
>  - Headers with an ID can be prevented from showing in the TOC by
>    assigning the `.no_toc` class to them (patch by Tim Bates)
> 
> * 1 bug fix
> 
>  - Numeric instead of symbolic HTML entities are now the default
>    fallback (patch by Gioele Barabucci)
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users


From t_leitner at gmx.at  Sun Sep 16 11:09:55 2012
From: t_leitner at gmx.at (Thomas Leitner)
Date: Sun, 16 Sep 2012 13:09:55 +0200
Subject: [kramdown-users] kramdown 1.0 (was: [ANN] kramdown 0.14.0)
In-Reply-To: 
References: <20120916081740.5ce22906@noweto>
	
Message-ID: <20120916130955.05d328b8@noweto>

On 2012-09-16 00:19 -0700 Shawn Van Ittersum wrote:
> When will kramdown be deemed worthy of a 1.0 version number?

Any time now ;-)

The syntax and the API need to be fixed for 1.0. Regarding the latest
releases it seems that there won't be much changes involving the syntax
or the API anymore.

If there is any outstanding syntax which should be incorporated into
kramdown, now would be a good time!

As for a release date: depends on the amount of additional requests
regarding new syntaxes but end of October seems reasonable!

Best regards,
  Thomas