|
The first conversion carried markdown's forms across. This one uses the
structures org has for what the specification holds:
- each .ssp property is a heading of its own under section 6.3, its
order, value, condition and count in a property drawer, with an id
(prop-parent) that the database specification's column tables link
to. The table at the head of 6.3 is a column view of those headings,
regenerated from them, so it cannot drift from them;
- the @meta keys are a checklist, checked where the reference
collection uses them, and the counts (28 of 43, and each group's) are
org's own count of the checks rather than a number in the prose;
- tables whose cells were prose are definition lists: the version
history, with org dates, the note marks, the @source and @make keys,
the model's three terms and two serialisations;
- what is formal is a named source block: the grammar (ssp-grammar,
tangled to ssp.peg), the database queries (sqlite, tangled to
ocda-db-queries.sql, runnable in place given :db), and .ssp lines as
ssp blocks. Tangled files are generated and not tracked;
- inline code is ~code~ rather than =verbatim=: org reads a table cell
that begins with "=" as a formula once the table is edited, and two
tables had been rewritten to #ERROR that way;
- README: a section on reading it in org, and the pandoc filter that
makes a markdown copy for a forge, an export rather than a second
source, with every link between the documents and to a section kept.
Fixed in passing, both from the first conversion: the @meta table's
"exercised" marks had been read by pandoc as emphasis and lost, and a
code span after ".." had not rendered.
Checked: each document exports with org's broken-link check on; every
link into another document names an id it has; every table row has its
table's number of cells; every word of the markdown is in the org bar
table headings, titles and the rewording named above; the tangled
queries run against a format 2.1 database; every link in the markdown
copy resolves.
(assisted by Claude-Code)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
README, the model, and the two format specifications, from markdown to
org. pandoc made the first pass, the rest by hand and by a checked
script, to use what org has where markdown had to describe it:
- a title, description, author and export options in each header;
- every numbered section given a short, stable CUSTOM_ID (sec-3-1), so a
section can be linked by number;
- every "section N" in the prose a link to it: in the same document
([[#sec-6-3][section 6.3]]), in the model ("model section 9", and
"ocda-model.org section 3"), or in the document a "section N of ..."
names, including references that run across a line break;
- the links between the documents to the .org files, and to the
section where one is named;
- sql, sh and peg code as source blocks with their language;
- the one table that showed escapes as characters is an example block,
since an org table cannot hold a literal "|" in a cell; the two cells
that mention one use \vert.
Checked: each document exports with org's broken-link check on (every
internal link resolves), every link into another document names a
CUSTOM_ID that document has, and every table row has its table's
number of cells. The text is unchanged otherwise.
.gitignore admits *.org (the author's change, staged for this).
(assisted by Claude-Code)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|