<feed xmlns='http://www.w3.org/2005/Atom'>
<title>sisudoc-spine/src/sisudoc/ocda/meta, branch main</title>
<subtitle>SiSU Spine: document publishing and search (in D) 2015</subtitle>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/'/>
<entry>
<title>org files mostly headers</title>
<updated>2026-10-25T00:45:37+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-10-24T22:41:41+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=2a55a61d10739e782a82fcb438607e552148fbd9'/>
<id>2a55a61d10739e782a82fcb438607e552148fbd9</id>
<content type='text'>
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
</pre>
</div>
</content>
</entry>
<entry>
<title>abstraction 2.1: a poem states its object range</title>
<updated>2026-10-01T03:14:23+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-30T20:18:59+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=993a3f655359f98dc26d3d3222e07792e2ccddf7'/>
<id>993a3f655359f98dc26d3d3222e07792e2ccddf7</id>
<content type='text'>
- A poem is a container of verse, and stores its range of verse ocn,
  - its verse are the citable units with ocn.

- A note in the last verse of a poem previously was not gathered into
  the endnotes section, this now is fixed

Format 2.0 -&gt; 2.1: the property is an addition, the poem is not a
citable object (but contans a range of objects), its verse are
(individual citable objects), and every reader checks the major version.
A 2.0 database reads as having no ranges.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
- A poem is a container of verse, and stores its range of verse ocn,
  - its verse are the citable units with ocn.

- A note in the last verse of a poem previously was not gathered into
  the endnotes section, this now is fixed

Format 2.0 -&gt; 2.1: the property is an addition, the poem is not a
citable object (but contans a range of objects), its verse are
(individual citable objects), and every reader checks the major version.
A 2.0 database reads as having no ranges.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>notes: editor's notes, ~[* ]~ &amp; ~[+ ]~, as series</title>
<updated>2026-10-01T02:31:56+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-30T18:32:03+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=36d0935c9a7521a87929d676a6b657fb033c44eb'/>
<id>36d0935c9a7521a87929d676a6b657fb033c44eb</id>
<content type='text'>
The markup documents ~[* note ]~ and ~[+ note ]~ as editor's notes, each
a separately numbered series, and a bare ~[ note ]~ which sisu put in
the asterisk series. They are included as notes. Each series is numbered
through the document, *1, *2 ... and +1, +2 ..., apart from the author's
notes.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
The markup documents ~[* note ]~ and ~[+ note ]~ as editor's notes, each
a separately numbered series, and a bare ~[ note ]~ which sisu put in
the asterisk series. They are included as notes. Each series is numbered
through the document, *1, *2 ... and +1, +2 ..., apart from the author's
notes.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>unused function removed</title>
<updated>2026-10-01T00:06:54+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-30T15:17:30+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=18bc4f4640171dd2bd439a087ec31ccda35a52ef'/>
<id>18bc4f4640171dd2bd439a087ec31ccda35a52ef</id>
<content type='text'>
- meta_processing_general() in spine.d replaced by per-stage predicates.
- doc_matters.generated_time() commented out, unused since the odt and
  epub clock stamps were removed.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
- meta_processing_general() in spine.d replaced by per-stage predicates.
- doc_matters.generated_time() commented out, unused since the odt and
  epub clock stamps were removed.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>markdown output, --markdown (--md)</title>
<updated>2026-09-28T17:12:20+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-28T15:43:54+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=af9f8677ff80287a0c83319258261d2368e14294'/>
<id>af9f8677ff80287a0c83319258261d2368e14294</id>
<content type='text'>
A plain-text output that keeps the object numbers, written as CommonMark
with GFM pipe tables, one .md per document-language in &lt;lang&gt;/markdown/,
(linked from the metadata page) with images into that shared directory
itself, skipping any already there, so --markdown alone still gives a complete tree.

provided as an alternative to --text rather than a replacement

--markdown  produces a document that renders, (both provide objext
  numbering survives both. Every object carries an anchor and a
  superscript number linking to itself, so a citation by object number
  is a link in any markdown renderer.
--text may still be of value to read in a terminal

A note is written where it is referenced, with a link back to the
object it came from, rather than gathered into an endnotes
section.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
A plain-text output that keeps the object numbers, written as CommonMark
with GFM pipe tables, one .md per document-language in &lt;lang&gt;/markdown/,
(linked from the metadata page) with images into that shared directory
itself, skipping any already there, so --markdown alone still gives a complete tree.

provided as an alternative to --text rather than a replacement

--markdown  produces a document that renders, (both provide objext
  numbering survives both. Every object carries an anchor and a
  superscript number linking to itself, so a citation by object number
  is a link in any markdown renderer.
--text may still be of value to read in a terminal

A note is written where it is referenced, with a link back to the
object it came from, rather than gathered into an endnotes
section.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>typst output --typist &amp; --pdf that makes the pdf</title>
<updated>2026-09-28T17:07:41+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-28T00:40:20+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=b254c23c56a113bdcdb89f1f7917352baaa1cf0a'/>
<id>b254c23c56a113bdcdb89f1f7917352baaa1cf0a</id>
<content type='text'>
typst provides a new pdf build path replacing latex as the primary pdf
builder.
  --typst (--typ) writes the .typ;
  --pdf writes the .typ and compiles it by spawning `typst compile`.
    (--pdf is redefined, being typst to pdf rather than latex).
  --latex is unchanged and writes the .tex;

One .typ per document-language (not one per paper size). The paper and
the orientation are read from sys.inputs with a default, so the same
file compiles to every paper --set-papersize asks for, the pdfs keep
their original names.

Spine's paper names (derived from what suited latex) and typst's are
different vocabularies and are mapped; a paper typst does not have is
named and skipped.

With the flag --pdf spine invokes a typesetter to generate the pdf
output directly, which is new (the latex path writes a .tex and leaves
xelatex to the caller). If typst is not available on the machine it is
reported absent, naming the binary and printing the command, and the run
continues, the .typ is written.

Several useful features of an object-centric pdf are easily met, usually
being a few lines each.
- The object number goes in the margin as one `place` at a coordinate
  inside the object's own block, carrying the label every citation
  points at.
- A note is a real footnote at the point of reference, with the
  document's own number and one link back to the object.
- The table of contents locates by object number rather than by page, so
  it holds true across every paper and every setting.

That typst compiles silently across the sample set means every internal
link in every document resolves (--pdf over the collection with two
paper sizes gives 144 pdfs, none skipped and none failed, each the page
size its name claims and each tagged).

paths: .typ, pdf named in same way as .tex based built pdfs so site
linkage works either way

flake.nix: added a typst dev shell, for .typ pdf typesetter
- dsh-typst-pdf providing a pdf typsetter for spine's .typ.
- dsh-latex-pdf provides xelatex for .tex which can still be written.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
typst provides a new pdf build path replacing latex as the primary pdf
builder.
  --typst (--typ) writes the .typ;
  --pdf writes the .typ and compiles it by spawning `typst compile`.
    (--pdf is redefined, being typst to pdf rather than latex).
  --latex is unchanged and writes the .tex;

One .typ per document-language (not one per paper size). The paper and
the orientation are read from sys.inputs with a default, so the same
file compiles to every paper --set-papersize asks for, the pdfs keep
their original names.

Spine's paper names (derived from what suited latex) and typst's are
different vocabularies and are mapped; a paper typst does not have is
named and skipped.

With the flag --pdf spine invokes a typesetter to generate the pdf
output directly, which is new (the latex path writes a .tex and leaves
xelatex to the caller). If typst is not available on the machine it is
reported absent, naming the binary and printing the command, and the run
continues, the .typ is written.

Several useful features of an object-centric pdf are easily met, usually
being a few lines each.
- The object number goes in the margin as one `place` at a coordinate
  inside the object's own block, carrying the label every citation
  points at.
- A note is a real footnote at the point of reference, with the
  document's own number and one link back to the object.
- The table of contents locates by object number rather than by page, so
  it holds true across every paper and every setting.

That typst compiles silently across the sample set means every internal
link in every document resolves (--pdf over the collection with two
paper sizes gives 144 pdfs, none skipped and none failed, each the page
size its name claims and each tagged).

paths: .typ, pdf named in same way as .tex based built pdfs so site
linkage works either way

flake.nix: added a typst dev shell, for .typ pdf typesetter
- dsh-typst-pdf providing a pdf typsetter for spine's .typ.
- dsh-latex-pdf provides xelatex for .tex which can still be written.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>ocda: warn if heading claims reserved segment name</title>
<updated>2026-09-23T12:22:15+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-21T20:12:56+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=8b81e9a11c7af642c4d0d8584a9cb348cc887d6e'/>
<id>8b81e9a11c7af642c4d0d8584a9cb348cc887d6e</id>
<content type='text'>
spine automatically builds some segments, including: (toc, endnotes,
glossary, bibliography, bookindex, blurb, _the_title) these are now
identified as reserved names and a user is now warned if any of these
names have been manually assigned to a heading by markup. A document
still builds but to disambiguate the ocn of the heading is attached to
the markup (reserved) name and this is seeded before a document not
after. It is read off the finished abstraction rather than reported by
the parser, and beside the ocn alignment check for the same reason: it
is a statement about a document rather than a step in building one.

  WARNING reserved segment name: the_autonomous_contract... [en]
    heading 1 at ocn 135 asks for "endnotes", which spine gives its
    own generated section
      it is named "endnotes-135" instead; ...

A warning: the document is correct and complete and the name it ends
up with works.

--strict makes it a failure for the run, as it does for ocn alignment,
and by the same reasoning: the outputs are written and can be looked at,
and the exit status is taken at the end.

Two of the thirty-six sample documents have reserved segment names,
"1~endnotes" heading. Output is unchanged: nothing here touches the
abstraction.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
spine automatically builds some segments, including: (toc, endnotes,
glossary, bibliography, bookindex, blurb, _the_title) these are now
identified as reserved names and a user is now warned if any of these
names have been manually assigned to a heading by markup. A document
still builds but to disambiguate the ocn of the heading is attached to
the markup (reserved) name and this is seeded before a document not
after. It is read off the finished abstraction rather than reported by
the parser, and beside the ocn alignment check for the same reason: it
is a statement about a document rather than a step in building one.

  WARNING reserved segment name: the_autonomous_contract... [en]
    heading 1 at ocn 135 asks for "endnotes", which spine gives its
    own generated section
      it is named "endnotes-135" instead; ...

A warning: the document is correct and complete and the name it ends
up with works.

--strict makes it a failure for the run, as it does for ocn alignment,
and by the same reasoning: the outputs are written and can be looked at,
and the exit status is taken at the end.

Two of the thirty-six sample documents have reserved segment names,
"1~endnotes" heading. Output is unchanged: nothing here touches the
abstraction.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>uid and paths separator "~" in place of ":"</title>
<updated>2026-09-23T12:19:53+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-23T11:18:52+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=26aba525c0c55cb0ec77cf3a788cb59de2683cee'/>
<id>26aba525c0c55cb0ec77cf3a788cb59de2683cee</id>
<content type='text'>
need a character to split filenames on in certain circumstances.
there problems with use of a colon in filenames, which is legal on posix
but not on Windows."~" fits the bill better being legal on every
filesystem of interest and is unreserved in rfc 3986, needing no escaping in a url.

The reference abstraction is renamed, its content unchanged. Over
the sample collection two filenames move and nothing else does: the
abstraction and database digests are identical, the archive's
members and their sizes are unchanged, and only the member order
shifts, "~" collating after letters where ":" sorted before them. The
document's epub dc:identifier is a v5 uuid derived from the uid, so it
changes for those filenames.

Every document's uid changes in the search database (spine.search.db).

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
need a character to split filenames on in certain circumstances.
there problems with use of a colon in filenames, which is legal on posix
but not on Windows."~" fits the bill better being legal on every
filesystem of interest and is unreserved in rfc 3986, needing no escaping in a url.

The reference abstraction is renamed, its content unchanged. Over
the sample collection two filenames move and nothing else does: the
abstraction and database digests are identical, the archive's
members and their sizes are unchanged, and only the member order
shifts, "~" collating after letters where ":" sorted before them. The
document's epub dc:identifier is a v5 uuid derived from the uid, so it
changes for those filenames.

Every document's uid changes in the search database (spine.search.db).

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>check: languages of a document, against each other</title>
<updated>2026-09-22T19:11:00+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-21T16:05:32+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=c7ce6760e78c33db52ba6fb8c61a2929b3c65117'/>
<id>c7ce6760e78c33db52ba6fb8c61a2929b3c65117</id>
<content type='text'>
Each language leaves a profile as it is abstracted: how many numbered
objects it has, and what kind of object each ocn is. The comparison is
against the language the manifest names first.

A count difference is reported alone. Past the first dropped or added
object every ocn names something else, and a kind comparison after it
would print hundreds of lines that are all the one fault.

The languages of a document share their object numbering, this being
the basis of ocn citation in a multi-language document: an ocn
names the same object in every language. Nothing enforces it.

It holds where translations follow the source object for object, and
stops holding otherwise (e.g. the moment a translator drops a paragraph,
merges two, or turns a heading into a sentence, at which point the
numbering no longer matches).

An ocn is not unique: a poem and its first verse share one, by design.
So the walk is in document order, the section order the .ssp is
written in rather than the abstraction's key order, which an
associative array does not promise, and the first object at an ocn is
the one recorded.

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
Each language leaves a profile as it is abstracted: how many numbered
objects it has, and what kind of object each ocn is. The comparison is
against the language the manifest names first.

A count difference is reported alone. Past the first dropped or added
object every ocn names something else, and a kind comparison after it
would print hundreds of lines that are all the one fault.

The languages of a document share their object numbering, this being
the basis of ocn citation in a multi-language document: an ocn
names the same object in every language. Nothing enforces it.

It holds where translations follow the source object for object, and
stops holding otherwise (e.g. the moment a translator drops a paragraph,
merges two, or turns a heading into a sentence, at which point the
numbering no longer matches).

An ocn is not unique: a poem and its first verse share one, by design.
So the walk is in document order, the section order the .ssp is
written in rather than the abstraction's key order, which an
associative array does not promise, and the first object at an ocn is
the one recorded.

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
<entry>
<title>pod: read when zstd-wrapped</title>
<updated>2026-09-22T17:46:31+00:00</updated>
<author>
<name>Ralph Amissah</name>
<email>ralph.amissah@gmail.com</email>
</author>
<published>2026-09-21T12:58:06+00:00</published>
<link rel='alternate' type='text/html' href='https://amissah.com/projects/sisudoc-spine/commit/?id=f89f0152a913cec14c6ee688a4f1b2ac7c4758ff'/>
<id>f89f0152a913cec14c6ee688a4f1b2ac7c4758ff</id>
<content type='text'>
sisupod using zstd compression recognised by first bytes.
&lt;doc&gt;.sisupod: spine reads one before it writes one, so when the name
changes (from .zip to .ssiupod) every pod already published stays
readable.

A .sisupod is one zstd frame wrapping the archive spine already builds.
The reader unwraps the bytes and hands the same archive to the same
parser, so every guard downstream is untouched: entry names, per-entry
and total size, path depth, escape and symlinks.

Which container it is comes from the first four bytes (rather than the
name). A pod published as a plain .zip reads as it always did, a
.sisupod reads, and either one renamed reads too. The suffix is still
recognised, both spellings, for the argument and for a url.

libzstd is declared rather than bound: provides the whole surface of
fifteen extern C prototypes (there is nothing to generate and no
upstream tree to track, which is the arrangement sqlite3 already has).
dub links it with "libs": [ "zstd" ]; nix needs zstd.out rather than
zstd, whose default output is the binaries and carries no library at
all.

A frame declares its uncompressed size in its own header, and for a pod
fetched over https that number is attacker controlled. The declared size
is checked against a ceiling before a buffer is asked for, a frame that
will not declare one is refused, and what comes out is checked against
what was promised. The ceiling is the extraction limit the archive
reader already applies, so the two bounds agree.

Measured: output built from a .sisupod is byte identical to output built
from the same pod's .zip, 359 files over text, html, epub, odt and .ssp
for three documents, live-manual's ten languages included. A truncated
frame is refused and the document skipped.

  free_culture           2863504 -&gt; 1099736   2.60x
  the_wealth_of_networks 4294022 -&gt; 1172649   3.66x
  live-manual            6972418 -&gt;  675970  10.31x

(assisted by Claude-Code)
</content>
<content type='xhtml'>
<div xmlns='http://www.w3.org/1999/xhtml'>
<pre>
sisupod using zstd compression recognised by first bytes.
&lt;doc&gt;.sisupod: spine reads one before it writes one, so when the name
changes (from .zip to .ssiupod) every pod already published stays
readable.

A .sisupod is one zstd frame wrapping the archive spine already builds.
The reader unwraps the bytes and hands the same archive to the same
parser, so every guard downstream is untouched: entry names, per-entry
and total size, path depth, escape and symlinks.

Which container it is comes from the first four bytes (rather than the
name). A pod published as a plain .zip reads as it always did, a
.sisupod reads, and either one renamed reads too. The suffix is still
recognised, both spellings, for the argument and for a url.

libzstd is declared rather than bound: provides the whole surface of
fifteen extern C prototypes (there is nothing to generate and no
upstream tree to track, which is the arrangement sqlite3 already has).
dub links it with "libs": [ "zstd" ]; nix needs zstd.out rather than
zstd, whose default output is the binaries and carries no library at
all.

A frame declares its uncompressed size in its own header, and for a pod
fetched over https that number is attacker controlled. The declared size
is checked against a ceiling before a buffer is asked for, a frame that
will not declare one is refused, and what comes out is checked against
what was promised. The ceiling is the extraction limit the archive
reader already applies, so the two bounds agree.

Measured: output built from a .sisupod is byte identical to output built
from the same pod's .zip, 359 files over text, html, epub, odt and .ssp
for three documents, live-manual's ten languages included. A truncated
frame is refused and the document skipped.

  free_culture           2863504 -&gt; 1099736   2.60x
  the_wealth_of_networks 4294022 -&gt; 1172649   3.66x
  live-manual            6972418 -&gt;  675970  10.31x

(assisted by Claude-Code)
</pre>
</div>
</content>
</entry>
</feed>
