Highlighters

/Hints/Highlighters

This container holds notes that describe ways to highlight the text of a note. A highlighter note may contain multiple style declarations reflecting the fact that any given note can only apply a single highlighter.

Adding the built-in Hints container to a document, generates two specimen highlighter notes in the /Hints/Highlighters container:

Markdown. This is intended for users of Markdown.
Syntax. A specimen file to show syntax styling in action, rather than represent any particular syntax.

Any note can opt in to highlighting by setting the $SyntaxHighlighting value to the $Name of a highlighter note. For example, setting $SyntaxHighlighting to markdown would tell Tinderbox to use the highlight methods found in /Hints/Highlighters/markdown.

The highlighting methods are a list of regular expressions and formats and are described below.

Defining a highlighter rule

Each rule is defined by a line starting with the word pattern:. The first line of a highlighting rule must not be indented. For example:

pattern:parent|grandparent|nextSibling|previousSibling

Each highlighter note can contain one or more rules. A subsequent line starting pattern: is sufficient to start a new rule within the same note (i.e. its $Text), e.g.

pattern:parent|grandparent|nextSibling|previousSibling

pattern:project x

… but for ease of reading/maintenance of the rule's source code, it is sensible to place a blank line in $Text between each new highlighter rule.

The pattern statement tells the rule what $Text to match and 'highlight'. The colouring/styling of the rule's matches are defined in by lines following the rule.

Defining a rule's style

Any rule can have one or more visual styling codes; allowed codes are listed in the syntax section below. Each styling code for a rule must be on a discrete new line immediately following the rule's pattern: declaration and must be indented using at least one space or tab characters. The amount of indentation is a user choice, as long as the styling code does not start the line.

For example:

pattern:parent|grandparent|nextSibling|previousSibling

color: red

would locate any of the four defined words and colour them red.

Comments

Action code style comments are allowed. Comments are preceded by // and continue for the rest of the line, thus:

// this rule colours the word 'parent' to red.


pattern:parent

color: red // perhaps dark red is better?

Highlighter styling syntax

Highlighter rule codes are all-lowercase and should be treated as case sensitive.

Highlighters allow setting of line-spacing as a multiple of the normal line spacing (see line-spacing below).

Highlighters allow setting the indenting of the paragraph, as well as the indentation of the paragraph's first line (see indent and first-indent below).

Highlighters can use any of the following styling codes:

color: the text colour, a named colour or hex code value, e.g. color: green or color: #00ff00
background: the text background colour (highlight), a named colour or hex code value, e.g. background: #ffff00 or background: yellow
size: text size in points, e.g. size: 14
line-spacing: line-spacing as a multiple of the normal line spacing, e.g. line-spacing 2
indent: indent the paragraph in points, e.g. indent: 32
first-indent: indent the first line of a paragraph in points, e.g. first-indent: 16
bold: text bolded as a yes/no boolean, e.g. bold: yes

italic: text italicised as a yes/no boolean, e.g. italic: yes

strike: text struck-through as a yes/no boolean, e.g. strike: yes

underline: text underlined as a yes/no boolean, e.g. underline: yes

wildcards: yes/no boolean instructs the pattern to ignore regular expression meta-characters such as "*" and "+", e.g. wildcards: no

case-sensitive: yes/no boolean instructs the pattern to regard upper- and lower-case letters as equivalent, e.g. case-sensitive: no

Highlighter style changes alter $Text

Highlighters set the base colour of notes to their $TextColor rather than to "black" (#000000). Any styling is applied to RTF layer $Text (i.e the XML data and not its data). This is of note as not all (RTF) styling, e.g. text colour, can be exported via (HTML) Export.

Highlighting is NOT a toggle

Styling is not a toggle effect. Rules affect the stored style of any matched text.

Deleting a rule does not 'un-set' the visual style previously set by that rule.

Combining rules

Although a note can only apply one highlighter, that later can contain multiple rules. If multiple rules potentially match the same text, be aware the styling rules are applied in the order defined in the highlighter note's $Text. Thus, so styles written by the earliest rules may be overwritten by styles set by subsequent rules if both use differing values of the same styling code (e.g. different values of color).

Possible conflicts with other features

Do not use this feature on notes using the built-in 'Action' prototype for action code syntax highlighting. Use one or the other.

As highlighters alter the styling of $Text, existing styling including highlighted passages, may be altered (see above). Combine the two with care.

See also—notes linking to here: