bitmark++ text formatting

bitmark++ ("bitmark plus plus") makes a bit much more powerful: added to the bit type ([.article:bitmark++]), it enables everything from bitmark-- plus many additional inline tags (critic markup, links, source code, …), embedding of other text formats such as LaTeX for math formulas, and block tags like titles, lists and inline images.

bitmark-- tags are so basic that they can also be used within bitmark++ constructs like titles, highlighted text and bullet lists.

Titles

Two levels of body titles structure the content of a bit:

[.article:bitmark++]

# bitmark title level 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

## bitmark title level 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Styles

Text can be styled inline — **bold** and __italic__ directly, or any style through the ==text==|style| form:

[.article:bitmark++]

**bold**
__italic__

==bold alternative==|bold|
==italic alternative==|italic|
==light==|light|
==highlight==|highlight|
==strike==|strike|
==subscript==|subscript|
==superscript==|superscript|
==ins==|ins|
==del==|del|
==underline==|underline|
==doubleUnderline==|doubleUnderline|
==circle==|circle|
==languageEm==|languageEm|

# User Styles

==userUnderline==|userUnderline|
==userDoubleUnderline==|userDoubleUnderline|
==userStrike==|userStrike|
==userCircle==|userCircle|
==userHighlight==|userHighlight|

Lists

Lists work only with bitmark++. An empty line is needed after the list, a space is needed after the marker, and sublines are indented with a Tab (never spaces).

[.article:bitmark++]
• 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.

[.article:bitmark++]
•A First lettered item
•A Second lettered item

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

[.article:bitmark++]
•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:

[.article:bitmark++]
•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.

  • A plain URL (http://www.example.org) becomes a clickable link in every version of bitmark.
  • Links on text use the ==text==|link:url| form (bitmark++ only).

Text tags

The part after ==text== is a list of text tags: |bold|, |link:url|, |xref:id|. Some of them take extra parts that belong to the text tag before them — every part after a text tag belongs to it until the next text tag:

==ISO 9001==|xref:urn:iso:9001|►section-4|provider:iso|?Quality management|bold|

Here ►section-4, provider:iso and ?Quality management belong to the xref, and bold starts a second text tag. The parts may come in any order. A part the text tag does not take ends the list, and the rest of the line is plain text.

Hints

A hint is information that is not in the original text — the full title of a cited standard, say. It is written |?…| after a link, xref, extref or ► reference:

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

|?| is an empty hint, which is not the same as no hint. A hint given twice keeps the second one, with a warning.

Cross-reference providers

An xref can name the provider that builds the real link from its id, as an extref can:

==ISO 9001==|xref:urn:iso:9001:en,fr|provider:iso|

Inline images, figures and symbols

imageInline, figureInline and symbol take only their own parts (size, width, height, alignment, …); anything else after them ends the list. Each is always the first and only text tag. A symbol is an inline image under its own name — a small picture standing for a character — and sits in the middle of the line unless you say otherwise:

==Earth==|symbol:https://example.com/earth.svg|

A figureInline is an inline image under its own name that is a figure — numbered, captioned, and a link target — such as a figure inside a table cell:

==^==|figureInline:https://example.com/ohmmeter.svg|▼f1|%Figure 1|caption:Ohmmeter|

Toggle tags

A style can also be switched on and off instead of wrapped: (+bold) turns bold on, (-bold) turns it off. Toggles are switches, not brackets, so ranges may overlap — which **…** and ==…==|…| cannot express:

[.article:bitmark++]

(+bold)chlorophyll(+highlight:yellow) absorbs sunlight(-bold), and that energy drives the reaction(-highlight:yellow).

Here the bold ends inside the highlight. Toggles and the classic forms mix freely, and mean exactly the same marks.

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 |:

(+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, and has no classic form:

(+semantic:person|name:Albert Einstein|born:1879)Einstein(-semantic)

Where two toggles of the same name overlap, the text they share carries the most recent one — except semantic, which keeps every one:

(+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, heading or list item, with a notice.

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

(+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).