summaryrefslogtreecommitdiffhomepage
path: root/ocda-db-format-specification.org
AgeCommit message (Collapse)AuthorFilesLines
2026-10-01the specification uses org, rather than being markdown in orgclaude-convert-md-to-orgRalph Amissah1-139/+144
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>
2026-10-01the specification in org: links to the section, not "see section 3"Ralph Amissah1-0/+451
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>