Dave Jarvis' Repositories

# Captions and cross-references

Users may define captions and cross-references to tables, figures,
and equations. Unfortunately, at time of writing, the CommonMark
specification is frozen. This means cross-references must be implemented
as an extension to the Markdown specification, leaving the door open for
differing Markdown rendering libraries and applications to diverge with
respect to syntax.

# Syntax

This section describes how to use captions and cross-references within
Markdown documents. The CommonMark standard details different ways to
add captions to tables and figures. While those are supported, a more
consistent syntax has been implemented.

## Captions

Tables, figures, and equations are captioned using the same syntax. In
general, a line that starts with a double colon after a blank line will
result in a caption added to the item immediately preceding it. The
remainder of this section provides examples.

### Images

An image caption:

```
![image title](https://loremflickr.com/600/350)

:: Figure caption text
```

### Table

A table caption:

```
| a | b | c |
|---|---|---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |

:: Table caption text
```

### Equation

An equation caption:

```
$$E = mc^2$$

:: Equation caption
```

# Cross-references

There are two parts to a cross-reference: the anchor name and its references.
An anchor name must be uniquely defined. Any number of references may refer
to an anchor name. Anchor names can be associated with any item in the
document, and are primarily added to captions.

The general syntax for anchor names and references is:

* `{#type-name:label}` (anchor name)
* `[@type-name:label]` (reference)

The `type-name` can be any alphanumeric value, starting with a letter or
ideogram. Type names are user-defined categories for the item type. Labels
are user-defined identifiers that must be unique per item.

Consider the following example:

```
In [@fig:animal], a cute animal is shown.

![image title](https://loremflickr.com/600/350)

:: World's cutest animal {#fig:animal}

There is no cuter animal than the one in [@fig:animal].
```

The anchor name uniquely defines where an item in a document is located. Any
number of references, anywhere in the document, may reference an anchor name.
There are few restrictions placed on the possible type names and labels. Here
are a few more anchor name examples:

```
{#fig:cats}
{#図版:猫}
{#eq:mass-energy}
{#eqn:laplace}
```

## Type names

To avoid duplicating writing the label each time (e.g., Figure, Table,
Equation), there are a number of predefined labels associated with
type names. The following table lists the type names and the label
generated by the typesetting system:

| Type name | English name |
|-----------|--------------|
| algorithm | Algorithm    |
| alg       | Algorithm    |
| equation  | Equation     |
| eqn       | Equation     |
| eq        | Equation     |
| figure    | Figure       |
| fig       | Figure       |
| formula   | Formula      |
| listing   | Listing      |
| list      | Listing      |
| lst       | Listing      |
| lyric     | Lyrics       |
| music     | Score        |
| score     | Score        |
| source    | Listing      |
| src       | Listing      |
| tab       | Table        |
| table     | Table        |
| tbl       | Table        |

These values are defined in the theme's `xhtml/xml-references.tex` file.