Adding highlight annotation to example markup syntax

[melissachen2000]

Context

The preview for the how-to is currently calculated based on the first glyph of the first example of the program or the first glyph of the how-to if no examples exist. This is functional, but perhaps not ideal for all use cases of how-tos. For example, if a how-to author writes a how-to where the examples build off each other towards a final product, then perhaps the final example should be the preview. Since this is something that a how-to author should get to decide, this PR implements a "highlight" annotation to examples, denoted with the syntax \Phrase("hello")\highlight or \Phrase("hello")\⭐.

Related issues

• Related Issue #
• Closes Code preview for how-tos in the Guide #976

Verification

Create a new how-to.

Verify that existing functionality still works

1. Add a few examples with no highlights. Verify that the first example defines the preview glyph. (E.g., \Phrase("hello")\ \Phrase("world")\ --> preview = h)
2. Create a how-to with no examples. Verify that the preview is the first glyph of the how-to. (E.g., hello world --> preview = h)

Verify that highlight editor works

1. Create an empty example by using the button in FormattedEditor or by typing \\. The button for highlighting the example should activate. Either pressing it, using the shortcut (ctrl + shift + 8), or manually typing the annotation should add it.
2. Verify that preview mode can be activated and deactivated

Verify that highlighted example defines the preview

1. Add two examples to a how-to. Highlight the second one. Verify that the highlighted example defines the preview glyph. (E.g., \Phrase("hello")\ \Phrase("world")\⭐ --> preview = w)
2. Add multiple examples to a how-to. Highlight two of the examples. Verify that the first highlighted example defines the preview glyph. (E.g., \Phrase("hello")\ \Phrase("world")\⭐ \Phrase("abcde")\⭐ --> preview = w)

Checklist

[amyjko]

Nice work! I reviewed everything, and it is very complete, consistent with the architecture, and meets all of the requirements.

There is one potential missing requirement, which is whether the highlight marker should be visible to viewers of the example code. Does knowing that a how to author intended for one to be a highlight example matter? Probably not, so I think this behavior is fine.

Finally, there is the learnability dimension of this. I think this is mostly as learnable as the other formatting, but it hinges on the tooltip. We could probably do more here, but I think it would be fine to open that as a new issue, since that would require some more design work to nail down, and should probably be done with other learnability issues with the markup syntax.

[melissachen2000]

Thanks Amy! I filed an issue about learnability at #1062 . Regarding if the marker should be visible to a viewer, I agree that it may not need to be visible, although I will ask Adrienne when I mention that this feature has been implemented.