Fix and enhance code segmentation for folded and embedded block-comments

[sjorek]

Foreword: This pull-request got larger than I wished. And if you want me to split it up into several smaller requests, I'll do so, but I suggest to give it at least a try, once …

The rendered results are here:

• http://sjorek.github.io/groc/utils.html
• http://sjorek.github.io/groc/languages.html

Summary of bugs, faults and traps I've fixed:

1. All language-specific delimiters and marks as those for single-line and multi-line block-comments, as well as the
   foldPrefix and ignorePrefix are now properly escaped if used in regular-expressions.
2. By introducing a new flag strictMultiLineEnd and changing the code accordingly, it is now possible to nest block-
   comments of syntax A in block-comments of syntax B, as those in the handlebars or html+php
   syntax-definitions, which are supported by pygments.
   Example (handlebars): {{! A nested <!-- block-comment --> … }}
   Example (html+php): <!-- A nested <?php /* block-comment */ ?> … -->
   The previous solution stopped a the first block-comment closing mark, which is obviously wrong.
3. The above change made it necessary to separate the block-line matcher from the single-line matcher. Therefore I
   developed a new way to handle this. This new implementation seems to be more solid - at least I hope so.
4. foldPrefix and ignorePrefix can be a string of arbitrary length now. (This happened by accident)
5. The larger regular-expressions got comments to enhance their readability.
6. I cleaned the code-comments of lib/utils.coffee to enhance readability.
7. @achingbrain Block-comments can now be embedded into code, and they can be folded too. Some examples
   have been added directly into the code. To achieve this, the change (3.) was necessary too. And I needed to
   tweak the CSS and behavior-Javascript a little bit, to make it work.
8. Empty comment lines from block-comments start- and end-marks are not collected anymore, examples are
   embedded into code.
9. I added some clarifying comments to lib/languages.coffee all related to the changes above, and cleaned the file
   a little bit to enhance consistency.
10. Code which immediately follows a block-comment's closing-mark does not get lost anymore, hence the close-
    mark is recognized now if it is not placed at the EOL.

Ehhmm, that's all I guess … hope we find a way to get this merged in or at least discuss and solve the issues tackled by this request.

Cheers,
Stephan
🙈 🙉 🙊

[sjorek]

There is one thing I need to fix left … I'll update this request hopefully within the next 30 minutes …

[sjorek]

I updated the pull-request a last time (I hope 😰) and complemented this pull-request's description.

[sjorek]

… damned … still not perfect … an update follows soon.

[sjorek]

So here we are … I'm convinced we'll find an agreement … 😏

Stephan

[kmdavis]

2 things I don't like (about the output):

1. it should never be possible for a folded comment block to obscure a code block: … if we start this comment with “^” instead of “}” it and all ...

2. the coffeescript block comment syntax with ' *' as a continuation marker is hideous... imho 😄

other than that, the output looks good. now to take a look at the code itself 😦 this is a big pull request

[sjorek]

to 1) … I don't get it; maybe my english is not good enough ?!? Hint: actually this line of code you quote is not new (hence it's just old code from previous commits, but I admit last changed by one of my commits - so blame me)

to 2) … yep it's ugly, but some projects use it (as a work-around). I thought it would be a good idea to enable it … but it's probably not the best idea I had. I don't insist in that line, and would certainly like to remove it again if the block-comment issue in coffee-script has been fixed. So I'll leave it as a comment, is that ok ?

… yeah and finally, it's hard to split that pull-request into smaller pieces, but not impossible. So if you get into trouble or insist, due to a lack of (review-)time or so, I would split it up.

[kmdavis]

ah... sorry on #1, I hadn't noticed that bug before.

on #2... well... yeah, I guess a workaround might be necessary... :(

[sjorek]

… continuation:
1.) I got it ! … you mean a folded-comment should never hide code (got confused as the word “obscure” means something completely different in german, the german “obskur” is more like “dubious”) … so back to the topic:

I thought hiding unimportant code is one of the initial ideas of the code-folding feature. And actually I didn't invent that; this behavior has been there since you merged it from @achingbrain … I use it quite often to hide node.js imports like in:

# ^ imports:
foo = require 'bar'
blah = require 'blub'

[kmdavis]

I could be convinced that it's a good thing... so... let's leave it for now, and I'll think about it 😄

My initial impression was that this was "comment folding" instead of "code folding"

[sjorek]

… continuation - part 2:

But actually I agree with your objection. Folded comments should not hide the code ! … In this case I need to rethink (and update) some parts of the pull-request … how about making it configurable ? (And getting rid of my bad habit to hide code from the readers eyes … 😏)

[kmdavis]

maybe 2 different folding prefixes, 1 for comment folding and 1 for code folding... hmm... but ppl could get confused about which is which... hrmm... difficult... very difficult :p

[sjorek]

… let's leave it for now, and incubate conceive a better solution later … as I (hopefully) didn't change any behavior, this could be a good way to go.

[sjorek]

I put some interesting comments in this pull-request's code about code-folding and how to enhance it … so we could start with it right away by raising a true issue and collect some thoughts of other people (@achingbrain) too … and maybe we/I should look into the original solution (@achingbrain mentioned something like that) to figure out how it was meant, and derive our ideas from that …

[kmdavis]

ok... code reviewed... looks good... though my eyes did start to glaze over towards the end.

creating an issue to explore the topic of code/comment folding sounds like a good idea

[sjorek]

Wow … that was a quick decision … 💫 … very cool. Do you open the issue ? …

[kmdavis]

you should do that

[sjorek]

glazed eyes ? 'cause you got sad 😫, confused 😕, overwhelmed 😀, had an information-overload or something completely different (🚬) ?

^^^^
sorry, didn't want to get personal … sometimes my horse bolts.

[sjorek]

Ok, I'll do so, I mean opening the issue …

[kmdavis]

because I haven't finished my first cup of ☕ yet

[sjorek]

phew … good to know. 😁