double bracket parsing

[ccoupe]

Github (known as GFM in kramdown) has this double [[this is here ]] link syntax which github renders to http:/this.site/wiki/this-is-here.md Kramdown seems to ignore this in its parsing and we (ebook) really want it if we hope to create TOC and sidebar menus. Ideas @backorder , @passenger94 ??

[IanTrudel]

The best approach would be to extend the parser to handle the double brackets. It would allow you to both convert and build TOC at the same time. You may however consider a simple pattern matching and then conversion to a more standard [this is here](http://this.site/wiki/this-is-here.md) and then feed Kramdown.

Take a look at Libraries extending the functionality of kramdown.

Would you point out a reference to Github documentation about this double brackets link feature?

[ccoupe]

I haven't found a reference to the double bracket style yet but it clearly works at github and I must have learned once. Currently the kramdown parse renders it as text which would need special casing everywhere text is allowed (following list items in case) but couple be used anywhere.

[IanTrudel]

Do you mean that double brackets could occur in multiple, or any, Kramdown convert methods? Or just in convert_text method?

My understanding of Kramdown HTML converter convert_root is used for that purpose. As you can see, it builds the TOC right there. convert method might also be a candidate for a gsub on the double brackets.

[ccoupe]

I have captured the '[[this]]' in convert_text and that's likely to be the only convert_xx method it would appear in. Since I know the top nav document (not checked in yet), I can drag in the in the other menu .md from there. The next trick I need to discover/create is proper data structure for the render phase.

[ccoupe]

Turns out that the Shoes manual markdown uses [[ internal_doc_link ]] syntax and it obviously works in Shoes.The manual is mysterious place.

[IanTrudel]

A little Christmas magic! This is a good news.

[ccoupe]

This is a good news.

Not really good news. As noted above. kramdown doesn't call any of it's convert_xxx methods for [[ x ]] - it's just text to kramdown. There may be some option or subclass thing available in kramdown but it's not going to be simple.

[IanTrudel]

Subclass is absolutely possible. I had provided in this issue links to existing custom parsers. Otherwise a simple gsub in the main convert method would do.

[ccoupe]

On the other hand, @passenger94 code to convert the manual with redcloth into .md replaced the numerous (lots and lots) [[x]] to [x] without the expected (url) following. Those we might be able to detect in convert_a since attr href doesn't exist. I don't know. It's a show stopper for converting the Shoes manual to .kd and none very pleasant if it shows up in GFM .md

[passenger94]

Not sure to follow correctly but,
if you are sure that in the end the manual is going to be a mardown at its basic form why not convert every annoyance you've met into a proper/well defined, no brainer markdown, and rebuilt from that ?
No backward compatibility issues, no ? (could be a little tedious at times, but advantage is starting from fresh and clean), what do i miss ?
I mean building the other way around : a basic md and from there specialize for github, html or Shoes

[IanTrudel]

This would be a good approach but we need to maintain compatibility with GFM because it means we can publish on both Shoes and github Wiki at any given time. Your initial approach was a gsub in the code you submitted, hence I suggested the same in the method convert. The libraries also do similarly for such cases and well before doing more complicated things, i.e. own parsers. So far we are talking about one tag only. Not sure it is as big of a deal as @ccoupe makes it seems like. :)

[ccoupe]

[[ is ]] is not detected in the convert_a. It's treated as simple text. A gsub is fine if we have enough context at the time. Perhaps it is as simple as [[this]] will be converted to shoes

 'link "this", {open_link "this"}

and open_link (from help-picky.rb) can figure it out from there. Or something else.

[IanTrudel]

Have a try in convert rather than convert_a !

[ccoupe]

@passenger94 , The more I look at the Shoes manual code (help.rb and derivatives) I do believe converting the Shoes manual to an ebook.kd would require a manual rewrite. Help.rb and the weird markup are tied in a tight knot. Never to be untied. kramdown is just too different. Also, supporting that weirdness should not be a design goal of this ebook project. Maybe somebody can add it later.

[IanTrudel]

@ccoupe Would it be possible for you to list the current hurdles? Maybe additional eyes would help. If I know which markup are giving you troubles, I could write a proof-of-concept.