<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-abstraction-format/ssp-format-specification.org, branch claude-convert-md-to-org</title>
<subtitle>SiSU Spine: specs</subtitle>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/'/>
<entry>
<title>the specification uses org, rather than being markdown in org</title>
<updated>2026-10-01T23:06:40+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-10-01T23:06:40+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=9b9391327424febd5bd774d2ce35ecc137c79a58'/>
<id>9b9391327424febd5bd774d2ce35ecc137c79a58</id>
<content type='text'>
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 &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
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 &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
<entry>
<title>the specification in org: links to the section, not "see section 3"</title>
<updated>2026-10-01T17:12:04+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-10-01T17:12:04+00:00</published>
<link rel='alternate' type='text/html' href='https://git.sisudoc.org/sisudoc-abstraction-format/commit/?id=f160ec0b90aaacca2ab23a41f25c6e97bfb89ed3'/>
<id>f160ec0b90aaacca2ab23a41f25c6e97bfb89ed3</id>
<content type='text'>
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 &lt;noreply@anthropic.com&gt;
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
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 &lt;noreply@anthropic.com&gt;
</pre>
</div>
</content>
</entry>
</feed>
