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

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

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

[.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

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:

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.