Add Multi Line Comments to SCSS

[killercup]

I like commenting my SCSS files. Multi-line style, as defined in the SCSS reference.

[killercup]

Hi @kmdavis, thanks for merging this. I just wanted to let you know that I forked groc to switch to highlight.js and marked.js (it's faster, doesn't depend on pygments and offers highlighting in markdown). If you are interested in merging this, let me know (or just grab my code).

[kmdavis]

I'd LOVE to get rid of pygments. Send us a pull request!

[sjorek]

@kmdavis … wow … I would not be happy with such a change. I'd love to see a modular approach, where you have the choice between pygments and other implementations, as highlight.js and marked.js or even https://github.com/jayferd/rouge. I experimented a lot with all of them, and I'd like to offer my skills, to ensure that this is possible. My reason(s): Have you ever thought about plugging a formatter-plugin into pygments, that eases the code-segmentation dramatically and spits out a JSON-file with fragments of HTML-formatted code seperated from their comments ? This approach is not only faster, but really precise in terms of finding comments. I started with this idea a few months ago (http://bitbucket.org/sjorek/pygments-json-formatter) and I even did more. I'd be glad to get your feedback …

[sjorek]

@killercup … would you like to join our forces in order to implement a modular approach, that allows switching between pygments, highlight.js and rouge ?

Grüße aus Berlin 😀

[sjorek]

@killercup … please take my last comment to @kmdavis into consideration. Thanks a lot !

[sjorek]

@kmdavis + @killercup : please read on here: #143 (comment)

[killercup]

Hi @kmdavis, guten Morgen @sjorek, thanks for your responses! And sorry for replying to this PR again…

I'll create a pull request that (for now) replaces pygments with highlight.js and showdown with marked.

Just so you know, switching away from pygments required me to adjust the stylesheet as well as add some properties to languages.coffee (where pygments and highlight use different names for languages). Also, most languages are untested.

To be honest, I'm also not quite sold on the modular approach @sjorek suggested. Personally, I'd like groc to be one npm dependency away from being used. IMHO, having to install pygments (and Python) or rouge (and Ruby) just to generate documentation (e.g. on a build server) is not the way to go. I'm usually not the kinda guy who likes to mix languages unless absolutely necessary.

That highlight-and-then-split approach sound like a really good idea, though. Actually, I'm surprised I couldn't find anything but HTML output in highlight's docs.

[sjorek]

Hi everybody,

I’ll just comment on your reply.

To be honest, I'm also not quite sold on the modular approach @sjorek suggested. Personally, I'd like groc to be one npm dependency away from being used. IMHO, having to install pygments (and Python) or rouge (and Ruby) just to generate documentation (e.g. on a build server) is not the way to go. I'm usually not the kinda guy who likes to mix languages unless absolutely necessary.

I’m sorry to here that, as some projects I take care of heavily depend on pygments - hence your change force us to take deal with different styles … (but not with rouge).
That highlight-and-then-split approach sound like a really good idea, though. Actually, I'm surprised I couldn't find anything but HTML output in highlight's docs.

I’m not sure if you got me right - my modular approach would be the following:

1. groc invokes new groc-syntax-highlighter-module for each sourcefile
2. groc-syntax-highlighter-module passes source file to real syntax-highlighter-implementation (ie. highlight.js, pygments, rouge, or even a webservice.)
3. syntax-highlighter-implementation parses source-file into a stream of tokens and code-fragments
4. syntax-highlighter-filter- and -formatter-plugin(s) separate comments-tokens from all other and spit out JSON with raw Comment-Tokens and formatted HTML-Codefragments.
   • The segmentation happens BEFORE the highlighting !
   • You can quite easily embed additional meta-information, like line-numbers or function/class-names, into the resulting stream …
   • I have some working implementations with different JSON-stream results. Please gimme some feedback if you wanna experiment with them.
   • I should be really easy to implement this in highlight.js.
   • Sample output:
     json [ {"Token.Comment": "/** A Comment **/"}, {"Token.Segment": "<pre><code><span …"}, {"Token.Comment": "// Another Comment"}, {"Token.Segment": "<pre><code><span …"} ]
5. groc consumes this JSON-output to produce its usual output

If you think this is too complicated, then ok, so shall it be …

And sorry for replying to this dead thread, too :-)

[killercup]

Hey @sjorek, thanks for the explanation, that's what I understood as well. With "highlight-and-then-split" I just meant that the highlighter-implementation determines what is code and what is comment ("split"). This is of course the technically best method I could imagine. I couldn't find any tokenized output for highlight.js in its documentation, though. Perhaps I'll look into its parser/lexer implemation later today.

Maybe we should move this specific discussion to #149.

As mentioned there, my suggestion for keeping pygments around is that you add a new option ('highlighter', e.g.) and the highlightCode method determines which highlighter to call based on that option. If you like that, I can try to implement that this weekend.

[sjorek]

@killercup 👍 +1 for the “highlighter”-option … If I can assist just ping me in #149 … I'll also dig into highlight.js a bit deeper.

[sjorek]

@killercup Btw.: thanks for your contributions and patience anyway 👍 …