# 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
