|There's more than one way to do things|
RFC: Highlighting portions of codeby martin (Friar)
|on Jun 26, 2007 at 17:54 UTC||Need Help??|
Esteemed fellow monks:
More often than not, a piece of Perl code can say more than so many words of prose. When discussing code, or concepts that can be illustrated with code, I sometimes wish I had a simple way of highlighting portions of that code, while still presenting it in typewriter style and offering the whole snippet for download.
This is not about syntax highlighting or fancy HTML. It would be sufficient to switch between two font weights or something, in order to draw attention to certain passages.
Such passages could be the corrections I made in somebody else's script, for example.
How could that be achieved?
We need to consider two aspects: How can we express this feature in our writeups? How could it work?
One way to express it might be some sort of minimal markup to toggle between normal and highlighted text. That markup would have to vanish in the downloaded source, of course (rule 1). It would be nice if it could be used anywhere within a line (rule 2). For the author or editor, it should not damage the readability of the source code too much (rule 3). Writeups written without this feature in mind should not change in appearance (rule 4).
To implement the feature, the PerlMonks engine would presumably need a new set of filters to render our highlightable code sections in the contexts that matter (viewing, editing, downloading). I won't go into details here, as I am just a happy user so far and ignorant of any internals.
As to a possible syntax, this could take us some consideration, but I have come up with a first draft. Please feel free to comment on either the request in general or the suggested syntax.
Unsurprisingly, maintaining source readability turns out to be a tough requirement. Perl has such a rich syntax by itself that hardly any in-line symbol can be added that would be clearly distinguishable as alien and at the same time not obscure anything.
In this example, only the word scalar would be highlighted -- rendered in boldface, say.
With respect to rule 3, I found it easier to mentally filter out funny looking lines than funny looking embedded character sequences from Perl source. I prefer dots to underscores to let those lines appear more as a unit.
The second best solution I considered allowed only complete lines to be highlighted. It would require the whole code block to be indented and reserve the first column to certain control markers, somewhat like unified diff output.
Anyway, I think such a feature could be quite useful. I hope it will neither be too difficult to get implemented nor the final solution too awkward to become popular. Have fun!