# Text formatting

The text of a bit is formatted by default: styles, links, references,
formulas, inline images and lists, all written inside the text. Only plain,
unformatted text is declared, with `:text` after the bit type:

```bitmark
[.article:text]
This text is shown exactly as written, **asterisks** included.
```

## Toggle tags

A style is switched **on** and **off**: `(+bold)` turns bold on, `(-bold)`
turns it off. Toggles are switches, not brackets, so ranges may overlap:

```bitmark
[.article]
(+bold)chlorophyll(+highlight:yellow) absorbs sunlight(-bold), and that energy drives the reaction(-highlight:yellow).
```

Here the bold ends inside the highlight.

## Styles

```bitmark
[.article]
(+bold)bold(-bold)
(+italic)italic(-italic)
(+light)light(-light)
(+highlight)highlight(-highlight)
(+strike)strike(-strike)
(+subscript)subscript(-subscript)
(+superscript)superscript(-superscript)
(+ins)inserted(-ins)
(+del)deleted(-del)
(+underline)underline(-underline)
(+underline double)double underline(-underline double)
(+circle)circle(-circle)
(+color language)language emphasis(-color language)
```

Styles a reader applies to their own copy carry `user`:

```bitmark
[.article]
(+underline user)underline(-underline user)
(+underline double user)double underline(-underline double user)
(+strike user)strike(-strike user)
(+circle user)circle(-circle user)
(+highlight user)highlight(-highlight user)
```

The legacy forms `**bold**`, `__italic__` and `==text==|bold|` are
deprecated: the parser still reads them, but new content uses toggles.

### Names and values

Every mark with a toggle spelling is listed on its mark page. A compound
name is the family first, with one space: `underline double`,
`highlight user`, `color language`. A value follows a colon, and further
properties follow `|`:

```bitmark
[.article]
(+link:https://example.com)the docs(-link)
(+highlight:yellow)highlighted(-highlight)
(+timer:egg|duration:PT3M)soft boiled(-timer)
(+xref:entropy|reference:chapter 3)entropy(-xref)
```

A value ends at the tag's `)` — parentheses inside it are fine as long as they
balance (`(+link:https://en.wikipedia.org/wiki/HTTP_(protocol))HTTP(-link)`) —
or at a `|`. A `^` escapes the character after it: `^)` and `^|` inside a value.

`(+semantic:…)` attaches a named object of key/value pairs to a span:

```bitmark
[.article]
(+semantic:person|name:Albert Einstein|born:1879)Einstein(-semantic)
```

Where two toggles of the same name but different values overlap, the text
they share carries the most recent value — except `semantic`, which keeps
every one. Opening a toggle that is already open, with the same value or
none, changes nothing:

```bitmark
[.article]
(+semantic:person)Marie Curie(+semantic:award) won the Nobel Prize(-semantic:person) in 1903(-semantic:award)
```

Here " won the Nobel Prize" is both a person and an award.

### Closing

`(-name)` closes the most recently opened toggle of that name;
`(-name:value)` closes the one opened with that value, wherever it is. A
toggle left open closes at the end of its paragraph or list item, with a
notice.

A footnote, a formula and an inline image or figure wrap their content and
are written whole:

```bitmark
[.article]
(+footnote:1)So long, and thanks for all the fish(-footnote)
(+latex)E = mc^2(-latex)
(+image:https://example.com/power.svg)power symbol(-image)
(+figure:https://example.com/ohmmeter.svg|item:Figure 1)ohmmeter(-figure)
```

### What is not a tag

Anything that is not a known toggle name stays text, untouched — `(+1)`,
`Na(+)`, `(+)-camphor`, `(+ bold)`. To write a toggle literally, break it
with a caret: `(^+bold)` is the text `(+bold)`.

## Links

- A plain URL (`http://www.example.org`) becomes a clickable link.
- A link on words is a toggle: `(+link:https://example.com)the docs(-link)`.
- A reference to another document names its address and, optionally, the
  provider that builds the real link from it:

```bitmark
[.article]
(+xref:urn:iso:9001:en,fr|provider:iso)ISO 9001(-xref)
```

## Inline images, figures and symbols

A `symbol` is an inline image standing for a character, and sits in the
middle of the line:

```bitmark
[.article]
(+symbol:https://example.com/earth.svg)Earth(-symbol)
```

A `figure` is an inline image that is a figure — numbered, captioned, and a
link target — such as a figure inside a table cell:

```bitmark
[.article]
(+figure:https://example.com/ohmmeter.svg|anchor:f1|item:Figure 1|caption:Ohmmeter)(-figure)
```

## References inside a document

A reference to a place inside the same document names the anchor it points
to:

```bitmark
[.article]
See (+ref:chapter-3)section 3(-ref).
```

## Hints

A **hint** is information that is not in the original text, such as the full
title of a cited standard. It belongs to a link, a reference or a
cross-reference, and has no toggle spelling yet. A link or reference with a
hint keeps the legacy form: the text in `==…==`, then its parts, each
between `|`:

```bitmark
[.article]
See ==ISO==|link:https://iso.org|?Official site| and ==section 3==|►chapter-3|?Chapter 3: Results|.
```

`|?…|` is the hint, `|►chapter-3|` the reference to the anchor `chapter-3`.
`|?|` is an empty hint, which is not the same as no hint; a hint given twice
keeps the second one, with a warning.

## Lists

Lists are the only blocks inside a bit's text. An empty line is needed after
the list, a space is needed after the marker, and sublines are indented
with a Tab (never spaces).

```bitmark
[.article]
• Bullet Line
• Second Bullet Line
	•1 Numbered Subline One
	•1 Numbered Subline Two
```

| Marker | List |
| --- | --- |
| `•` | Bullet list |
| `•_` | List without bullets |
| `•+` / `•-` | Checklist: checked / unchecked |
| `•1` | Numbered list (1, 2, 3) |
| `•1I` / `•1i` | Roman numerals (I, II, III / i, ii, iii) |
| `•A` / `•a` | Letters (A, B, C / a, b, c) |

Every item uses the same marker, and the items count on by themselves:
to insert an item, add a line — no other line changes.

```bitmark
[.article]
•A First lettered item
•A Second lettered item
```

A marker of a different type starts a new list, at every level:

```bitmark
[.article]
•1 First
•1 Second
• An aside: a new bullet list
•1 A new numbered list, starting at 1
```

### Setting a number

Put the number in the marker. On the first item it sets where the list
starts — handy when a list is spread over several bits. On a later item,
add a `!` to fix that item's number; the items after it count on from
there:

```bitmark
[.article]
•4I Fourth (the list starts at IV)
•1I Fifth
•9!I Ninth (fixed)
•1I Tenth
```

The number goes first, in digits, then the `!`, then the list type: `•4`,
`•10!` (numbered), `•4a`, `•10!A` (lettered), `•4i`, `•10!I` (Roman). This is
the form regenerated bitmark always uses. When typing you may also write the
`!` after the type (`•10I!`), and lettered numbers as letters, any number of
them (`•d`, `•j!`, `•aaa`). A single letter is always a letter, even `•i` and
`•I` (both 9): Roman lists always have a number before the `i` or `I`. On a
later item a number without `!` is ignored, so hand-numbered lists (`•1`,
`•2`, `•3`) still count 1, 2, 3.

### The colon form

A colon and a value also state a number, on any item, with or without `!`:
`•I:IV` or `•I:4` (Roman IV), `•a:j` or `•a:10` (the letter j), `•1:5`. The
value may be digits or in the list's own style, in any case (`•1I:iV`).
Before the colon only the list type counts, so `•4:3` is the same as `•1:3`
and `•c:3` the same as `•a:3` — except that `i:` and `I:` are Roman.
Regenerated bitmark never uses the colon form: it writes the digits form of
the previous section.

A marker whose number is not valid for its list — `•I:IIII`, `•a:0` — is
not a marker: the line stays text. A numbered list may start at 0 (`•0`);
Roman numerals run from 1 to 3999.

## Headings

Headings are bits of their own, not part of a bit's text; see
[Headings and paragraphs](https://docs.bitmark-association.org/concepts/headings-and-paragraphs.md).

> [!NOTE]
> **Older bitmark.** You may find `:bitmark--`, `:bitmark+` or `:bitmark++`
> after a bit type, as in `[.article:bitmark++]`. They named text formats of
> earlier versions. Today a bit's text is formatted by default and only
> `:text` is ever declared. The parser warns on `bitmark--` and `bitmark+`
> and uses the default instead; `bitmark++` is accepted as the default.