Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

RFC: Highlighting portions of code

by martin (Pilgrim)
on Jun 26, 2007 at 17:54 UTC ( #623463=monkdiscuss: print w/ replies, xml ) 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.

  • Highlightable code blocks need a new set of enclosing tags to avoid any ambiguity. I suggest <hcode>.
  • Source lines are written as is, just as in ordinary code blocks.
  • Tab characters should be avoided and replaced by the appropriate number of blanks.
  • Our minimal markup -- turning highlighting on and off -- is achieved using extra lines.
  • A line containing at least two but none other than ^ (caret) and . (dot) characters modifies the appearance of the previous line: Each character above a caret will be highlighted, all others not.
  • A non-code line forces the next line to be treated as code, whatever ist is. That way a row of dots can be used to guard a similarly looking code line.

Example:

<hcode> use strict; use warnings; print the_time(), "\n"; sub the_time { return scalar localtime @_; ...........^^^^^^ } __END__ </hcode>
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!

Comment on RFC: Highlighting portions of code
Select or Download Code
Re: RFC: Highlighting portions of code
by hossman (Prior) on Jun 26, 2007 at 18:04 UTC

    I don't really have an opinion on wether a feature like this is needed, but if it's implemented, it might as well be implemented in a way that still leaves the raw code compilable...

    <hcode> sub the_time { return scalar localtime @_; #..........^^^^^^ } </hcode>

    ...now nothing special needs to be done with the d/l code links.

Re: RFC: Highlighting portions of code
by shmem (Canon) on Jun 26, 2007 at 21:21 UTC
    If it's code, it's code. To highlight any parts, just use whatever you would do with these doing a code revision, or writing code in a way readable to less informed programmers, that is: use comments.

    IMHO that's the better solution, since following your proposals, highlighting would be lost downloading code.

    --shmem

    _($_=" "x(1<<5)."?\n".q·/)Oo.  G°\        /
                                  /\_¯/(q    /
    ----------------------------  \__(m.====·.(_("always off the crowd"))."·
    ");sub _{s./.($e="'Itrs `mnsgdq Gdbj O`qkdq")=~y/"-y/#-z/;$e.e && print}
Re: RFC: Highlighting portions of code
by Anonymous Monk on Jun 26, 2007 at 23:06 UTC
    You need to research prior discussion
Re: RFC: Highlighting portions of code
by graff (Chancellor) on Jun 27, 2007 at 03:24 UTC
    I'll second shmem'e response: explanatory comments (or just clear code layout with well chosen names for vars and subs) are the best way to draw attention to specific details in code that you want others to read and understand.

    Puttering around with what amounts to ASCII-art will be tedious, and well beyond the patience, attention span or mental capacity of many who (try to) post code here. It'll get especially unwieldy when someone feels compelled to use fairly long lines of code with highlighted stuff at the end.

    Even though I kinda like dhoss's suggestion to make sure that "highlighting directives" are really nothing more than commented lines in the code, I have to ask: well then, why not just say a few words in those extra comment lines, instead of counting out periods and carets?

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://623463]
Approved by grep
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (10)
As of 2014-07-23 05:02 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (133 votes), past polls