Highlighting code within an example code block

[melissachen2000]

What are you trying to do that you can't?

When Adrienne writes tutorials in the how-to space, she teaches how to write the program incrementally, meaning that a few new lines of code are added with each code block. It would be useful to have some way of highlighting what code is new for that code block and what code is repeated from a previous code block.

What is your idea?

We can generalize this to the idea of highlighting a few lines of code within a code block. My suggestion is to have some way of annotating each line of code to determine if it is highlighted or not. Then, in the preview, there is a background for or a border around that line of code to help it stand out.

[melissachen2000]

While I am not sure about the technical feasibility of this, I would suggest the following as a design:

Taking influence from the design of #1061 , where \...\⭐ indicates a "highlighted" example in a doc, I would suggest using another emoji to indicate that a line is highlighted. Perhaps: 👀 to indicate "look at this"?

I think the rules for the syntax would be that the 👀 would need to be immediately followed by a newline or the closing \; this would be the way to determine that it is a highlighted line rather than the emoji being a part of the code.

So, something like

\Phrase('hello world')

Phrase('look at me!')👀\ 

Would render like something like

with the line of code that is annotated with 👀 given either a background or an underline with color --wordplay-highlight-color.

Thanks!

[amyjko]

I think this could be feasible. One possible technical constraint that we'd have to apply for parsing to be feasible would be to only permit 👀 between expressions in a Block. Allowing for it in arbitrary places would be difficult from a parsing perspective.

Another option would be to add it to the markup syntax, and then any expression that has an explanation above it with 👀 could be highlighted. That would require there to be an explanation of the line — which is probably a good idea anyway.

[melissachen2000]

Thanks Amy! Thanks for specifying that 👀 would need to be between expressions in a Block -- that makes sense.

I think I'm a bit confused about the second option. Wouldn't we need to add this to the markup syntax for it to work within an Example in an Explanation? Or is the suggestion to also allow Explanations outside of Examples to be highlighted as well? E.g.,

¶this is some explanation that i want highlighted 👀 ¶
Phrase("Hello world")

renders "this is some explanation that i want highlighted" with a background?

Thank you!!!

[amyjko]

For the second option, I (vaguely) meant that if an expression has explanation before it (in the parser, we parse these as DocumentedExpressions, and its explanation had 👀, then the expression would be highlighted (not the explanation). That would allow us just to annotate in the explanation, without having to mess with the rest of the language syntax. The 👀 could also go where the star goes, rather than placing it somewhere arbitrary in the markup.

[melissachen2000]

Oh, that's very cool! To make sure I'm understanding correctly, if someone wrote the following for their how-to (not in their project):

This how-to demonstrates how to use Phrase to display text:

\Phrase("hello world") ¶ 👀 ¶ \

(which is saved in the database as ¶This how-to demonstrates how to use Phrase to display text:\n\n\Phrase("hello world") ¶ 👀 ¶ \¶/en-us)

Then this would highlight the Phrase("hello world") in the how-to?

I think this would be much better, since I'm guessing it would be a cleaner implementation.

Thank you!

[amyjko]

The internal explanation by the Phrase would need to be before the phrase, but yes.

This how-to demonstrates how to use Phrase to display text:

\¶ 👀 ¶Phrase("hello world") \

[melissachen2000]

Ooh, very cool! I think this feels like the more robust implementation, since it will be less susceptible to edge cases when parsing. If you are okay with it, I can work on developing this feature.