/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
orcolor: #00ff00
- background: the text background colour (highlight), a named colour or hex code value, e.g.
background: #ffff00
orbackground: 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.