Text formatting

Text is stored exactly as you type it. A little notation is drawn as formatting when the text is shown: bold, italic, code, maths, links, and cites of other things in the workspace. A requirement's body can also hold headings, lists, quotes, code blocks and display maths (see Blocks in a body). Each form with a formatted field has a one-line reminder under it.

Where it applies

Bold, italic and code

• Only * marks emphasis. _ is an ordinary character, so PWR_EN_N needs no escaping.
• Inside backticks everything is literal: no emphasis, maths, links or cites. Use code for register names, pin names and values copied from a datasheet.
• Formatting does not carry across a blank line. An unclosed ** before a blank line is shown as typed.

Maths

Text between single dollar signs is typeset as TeX, using KaTeX.

The workspace draws these with KaTeX's own fonts, so they look a little different there from this page.

• The opening $ must be followed by something other than a space, and the closing one must follow something other than a space and must not be followed by a digit. So costs $5 and $10 stays as text.
• Two dollar signs together are never maths on a line with other text: $$x$$ is shown as typed. In a body, a line holding only $$ starts display maths.
• \$ is a literal dollar sign.
• Inside maths, a backslash is TeX's: $\{a\}$ shows braces.
• An expression may run over a line break, but not over a blank line.
• An expression KaTeX cannot read is shown as a small red LaTeX error. Hover over it for KaTeX's message.
• In the tree's filter, an expression is matched as its TeX source, so frac finds $\frac{a}{b}$.

Links

A URL starting with http:// or https:// becomes a link that opens in a new tab. Punctuation at the end, such as a full stop, is left out of the link, and so is a closing bracket that has no opening bracket inside the URL:

See the regulator datasheet (https://example.com/datasheets/tps62133.pdf).

Cites

A cite of something in the workspace becomes a link to it, drawn with its current status:

• A cite is a run of capital letters, digits and hyphens, optionally followed by :RUN- and a number, with no letter, digit or hyphen directly before or after it. A hyphen at the end is ignored.
• It becomes a link only if it names a list, requirement, verification or run that exists now. Anything else, such as ISO-9001, a deleted requirement, or a lower-case hw-3, stays as text.
• If a requirement and a verification have the same id, the requirement wins.
• The cite always shows the current status, so a cite written months ago reads correctly today. A run's cite in text is not faded when a later run has replaced it.

Backslash escapes

A backslash before punctuation shows that character as typed. Before a cite or URL, the backslash is hidden and the cite or URL is not linked. Any other backslash is shown.

Blocks in a body

A requirement's body is read as a series of blocks. A block starts at the beginning of a line, and indentation before it is allowed. Everything above still works inside paragraphs, headings, list items and quotes. A line ending inside a paragraph is shown as a line break, and a blank line starts a new paragraph.

• In the requirement pane every heading is the size of the body's text. Levels are told apart by weight, colour and a rule under #, so a heading never looks like the requirement's own title.
• A list item's marker needs a space after it and text on the same line. A line indented past the marker belongs to the item: indent a - under it to nest a list.
• Every line of a quote starts with >. A blank line ends it.
• There are no headings made by underlining with ===. A line of --- under text is a rule.
• A link goes to an http:// or https:// address. An image may also give a path on this site, such as /files/pins.png, and a title in double quotes after it.
• Tables are not drawn yet. Their text is shown as written.

Code blocks

Three backticks on their own line start a code block, and three more end it. A word after the opening backticks names the language, shown in the block's corner. Nothing inside is formatted, and nothing inside is a cite.

```c
#define PWR_EN_N  (1u << 3)
```

A mermaid, plantuml or wavedrom block is kept for diagrams. For now it is shown as code, and in the tree's tooltip as one line, such as Mermaid diagram. A line such as +------+------+ starts a block that is shown exactly as typed, up to the next blank line. These lines are kept for tables with merged cells.

Display maths

A line holding only $$ starts an expression shown on its own lines, and the next such line ends it. A code block with the language math does the same.

$$
V_{out} = V_{ref}\left(1 + \frac{R_1}{R_2}\right)
$$

In the tree

Hovering a row's body mark shows the first ten lines of the body that are not blank, with every block at one size and headings in bold. When there is more, the last line says how many lines were left out.

Cited in

When a requirement, verification or run is cited in written text, its page lists where under Cited in, with a count. A requirement's pane shows it after Verifications; a verification's page shows it at the end; a run's page shows it below the rows. When nothing cites it, the section is not shown.

Each place that cites it is one block, headed by that requirement, verification or run. Under the heading, each field that cites it is labelled the way the workspace labels it elsewhere, with the words around each mention:

The heading opens that page. The cited field is briefly highlighted when it opens, and scrolled into view if needed. When the cite is in a mapping's notes or a run row's notes, the link's address names that row (ending #map-VERIF-PWR or #row-HW-4), so a copy of it, a reload, or Back and Forward open the page at the same row. The first 10 places are shown; Show all, with the total, shows the rest.

What counts

Only text in its current form counts. These are the places a cite is collected from:

• Not counted: drafts, older versions, notes on closed mappings, run notes, and list descriptions (which draw no cites).
• In a body, a cite inside a code block, a diagram block, display maths, a link's label or an image's text does not count.
• Lists are never shown as cited, though a list's code in text still links to it.
• A page does not list itself. A requirement whose statement or body mentions its own cite, or a mapping's notes citing either end of that mapping, do not appear under Cited in.
• A run's page shows the description of the version it used and the notes of every mapping it included, with working links. If that version is no longer the latest, or the mapping is closed, those cites do not count: otherwise one sentence would be listed once for every run that used it.
• Creating a requirement makes earlier text that already cites its id count straight away.