# The Rosetta Map

A bit can carry two identities side by side, like the Rosetta Stone carries
one text in two scripts: the platform's and the customer's. That is what lets
content come in from the customer's own format without losing its identity,
or anything attached to it.

## Two identities

| | Platform side | Customer side |
| --- | --- | --- |
| Identity of a bit | `@id` | `@customerId` |
| Anchor (link target) | `▼` | `customer▼` (JSON `customerAnchor`) |
| Link to an anchor | `►` | `customer ref` (JSON `customerRef`) |

- **Import** writes only the customer side: the IDs, anchors and links the
  customer's file already has.
- **A platform** adds its own IDs and anchors on top, for its own use.
- **Export** reads only the customer side, so the customer's IDs and links
  go out as they came in and the platform's stay behind.
- A link into another document keeps its original address (an ISO URN, say)
  and never goes stale.

## What it gives you

- **Conversion that keeps identity.** Content comes in from the customer's
  XML with every ID, anchor and link, and keeps them on the way out.
- **Updates.** A new edition is matched bit by bit through the customer's
  IDs, so annotations, notes, translations and diff layers stay attached.
- **Nothing lost.** What was attached to the old version finds its place in
  the new one.

## From XML to bitmark

The parser imports standards documents in NISO STS XML. This section with a
table:

```xml
<sec id="sec_4">
  <label>4</label>
  <title>Rated values</title>
  <p id="p_4_1">The rated values are given in <xref ref-type="table" rid="tab_1">Table 1</xref>.</p>
  <table-wrap id="tab_1">
    <label>Table 1</label>
    <caption><title>Rated currents</title></caption>
    <table>
      <thead><tr><th>Type</th><th colspan="2">Rated current (A)</th></tr></thead>
      <tbody>
        <tr><td>A</td><td>10</td><td>16</td></tr>
        <tr><td>B</td><td>20</td><td>32</td></tr>
      </tbody>
    </table>
  </table-wrap>
</sec>
```

becomes these bits (shortened: the parser also writes a few display
properties):

```bitmark
[.chapter]
[@customerId: sec_4 ]
[% 4 ]
[customer▼ sec_4 ]
[# Rated values ]

[.smart-standard-article-normative]
[@customerId: p_4_1 ]
[customer▼ p_4_1 ]
The rated values are given in (+customer ref:tab_1)Table 1(-customer ref).

[.smart-standard-table-extended-normative]
[@customerId: tab_1 ]
[customer▼ tab_1 ]
[% Table 1 ]
[@caption: Rated currents ]
==== table-header ====
Type
--
[@tableColSpan: 2 ]
Rated current (A)
====
A
--
10
--
16
====
B
--
20
--
32
```

Each `id` became a customer ID and anchor, the cross-reference a customer
link, the paragraph a normative provision and the merged header cell a
column span.

## Commands

```bash
npx @gmb/bitmark-parser convert standard.xml --input-format xml-niso-iec --output-format bitmark --inline-style toggle
npx @gmb/bitmark-parser convert standard.xml --input-format xml-niso-iec --output-format jsonl
npx @gmb/bitmark-parser convert standard.xml --input-format xml-niso-iec --output-format bitmark --mapping-report
```

The mapping report lists what each XML element became, and every element it
did not map, instead of losing it silently. In JavaScript:

```js
import { convert } from "@gmb/bitmark-parser";

const jsonl = convert(xml, { inputFormat: "xml-niso-iec", outputFormat: "jsonl" });
```

Exporting the bitmark again (`--output-format xml-niso-iec`) keeps the
customer IDs and links, today in the parser's own bit XML. Writing a complete
NISO STS document back from the bits is planned.