Snippet Markup

[Pavel Rappo]

# Snippet Markup

One of the major challenges of the "Snippets" project is to design markup. Although we've made good progress there, we are still exploring the respective design space. This note provides some background and summarizes the current state of that exploration at a very high level.

## Background

Snippet markup comprises constructs in snippet source that together with the `{@snippet}` tag control the output of a snippet. In the early stages of the project we identified qualities that we wanted markup to have. The top three most wanted qualities were: relevance, noninterference, and invariance. I'm now going to briefly describe these qualities and their implications below.

### Relevance

Instead of general-purpose markup snippets need domain-specific markup: markup designed to express composition and typography transformations typically found in snippets.

To gain insights for such markup we've surveyed hundreds of snippets in JDK as well as outside of it. By doing so we wanted to capture the intent and best practices of the authors of those snippets. The survey allowed us to extract building blocks of markup that would be tailored to snippets, and thus relevant.

We found that there are only two types of building blocks such markup would have: (1) define a region of a snippet source and (2) specify an action on a region. Authors would combine those blocks to form a list of instructions for this highly-specific text processor (snippet).

### Nonintenference

We recognized that it should be possible to mark up snippet source regardless of whether it is modifiable or not. If source is not modifiable, it is unable to accommodate internal markup and thus, external markup must be used. If source is modifiable, internal markup can be used; however, such markup should not obfuscate, invalidate, or otherwise negatively interfere with source.

To fulfill these requirements, markup has to be able to specify regions in the snippet source from a distance. How big this distance is depends on a particular source. If a snippet is to be derived from unmodifiable source, then the markup has to be put as far from that source as the `{@snippet}` tag, perhaps into that tag attributes. If a snippet is to be derived from modifiable source code, the markup can be put as close to that source as the bottom and right margins of the same source file: code comments put there do not interfere with compilation, line and column numbers. 

In both internal and external markup, a region in the snippet source can be specified using line numbers and string matching. In addition to that, in internal markup a line can be specified implicitly by putting markup instructions on that line in the snippet source.

### Invariance

Translating markup from internal to external or vice versa may require changes (for example, external markup cannot implicitly specify lines). However, translating a snippet from inline to external or vice versa should not require any changes to that snippet's internal markup. 

Not only is that quality convenient when moving snippets around, it also simplifies management of hybrid snippets. That is, snippets that have two equivalent parts: inline and external.

## Summary

We are still designing markup as we haven't yet convinced ourselves that we have found the sweet spot. Currently, the exploration is focusing on three particular directions: (1) potential uses of footnotes, (2) dealing with excessively long lines of markup and markup that spans multiple lines, and (3) rules and syntax for compound actions.

Any feedback to this note is welcome,
-Pavel