Inspired by how GitHub documentation explains code by displaying inline comments side by side with code, and how useful that would be for some of my use cases, I did a quick rewrite of the the code to work in TiddlyWiki.
Sharing it here in case this is of interest to anyone else, though please keep in mind that this has barely been tested as of yet:
Excellent job. Reminds me of Docco. Quite remarkable.
This is gorgeous! And yes, @CodaCoder, it brings back the good old days of Docco.
The other thing this made me realize is that you have a highlighter for wikitext! I hadn’t realized that there was one available, and had searched casually for one without any luck. It was going to get on the queue for questions to ask. Nice to see that it does exist. The file doesn’t mention a license. Is it available under some free license?
I will take a look myself, but I do notice that it doesn’t recognize plain stand-alone filters. Would it be straightforward to alter it to allow them, or should I look to write my own from scratch? I could use it if I decide to extend my TW5-SQL_Playground wiki.
How long have they been doing that, I wonder? I’ve looked at plenty of GH documentation over the years, and don’t recall seeing the Docco style.
Me neither. But yeah, 1:1 docco with these tired old eyes.
Hi Scott, I am afraid that what you see there is a hodgepodge resulting from a half hour I spent yesterday cobbling together bits from the highlighters from XML, Markdown and a few other languages. It was a quick attempt whilst editing directly in the browser - as witnessed by the chaotic formatting and indentation - to see if I could wrap my head around what was needed to create a proper highlighting module for wikitext. It worked well enough for the code in the demo that I uploaded it, but it is otherwise not feature complete and probably rather brittle. As far as license goes, the original license
seems appropriate. If this is something you would like to work on, please do feel free.
The filter highlighting you see is a by-product of which characters the rules for conditional expressions are allowed to contain. Free form wikitext actually should not contain filters and as such they probably should not get syntax highlighting. The best approach for filters might be to write a separate language module or a mode, and then selectively import/allow that within other modes where appropriate.
I had a bit of a think about this yesterday and it would be very easy to highlight the different brackets and braces within filters. It would be nice to highlight all operator names in a different color by specifying them as reserved words, but that would require a list of all possible operator names, further complicated by the possibility of custom operators.
I first noticed it earlier this week. It is possible that this technique is not widely used across all of their documentation.
This is great @saqimtiaz and simple leveraging comment blocks.
It would be interesting to see what it would look like if you made comments visible in a rendered tiddler. Perhaps we may use <!--- comment with three hyphens ---> for that. Perhaps making this an editor preview as well or permitting it to be toggled on and off.
Nice find.