summaryrefslogtreecommitdiffhomepage
path: root/org/ocda_specification.org
blob: 10fd6a42faba25c0f449015027256bd5d8778b1c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
-*- mode: org -*-
#+TITLE:       configuration git
#+DESCRIPTION: documents - structuring, various output representations & search
#+FILETAGS:    :spine:hub:
#+AUTHOR:      Ralph Amissah
#+EMAIL:       [[mailto:ralph.amissah@gmail.com][ralph.amissah@gmail.com]]
#+COPYRIGHT:   Copyright (C) 2015 (continuously updated, current 2026) Ralph Amissah
#+LANGUAGE:    en
#+STARTUP:     content hideblocks hidestars noindent entitiespretty
#+PROPERTY:    header-args+ :eval never-export :exports code
#+PROPERTY:    header-args+ :noweb yes :padline no
#+PROPERTY:    header-args+ :results silent :cache no
#+PROPERTY:    header-args+ :mkdirp yes
#+OPTIONS:     H:3 num:nil toc:t \n:t ::t |:t ^:nil -:t f:t *:t

* ./
** README.md

#+HEADER: :tangle ../README.md
#+HEADER: :noweb yes
#+BEGIN_SRC md
# sisudoc-abstraction-format

Specification of the **object-centric document abstraction** that
[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) builds from
SiSU markup, and of the two forms it is written in: **`.ssp`**, text and
PEG-parsable, and **`.ocda.db`**, sqlite.

The two carry one version number between them, because neither may express
what the other cannot.

## What this is

A specification, not a program. The repository ships:

- [`ocda-model.md`](ocda-model.md) - **the model**: what an object is,
  the citation number, structure, sections, segments, digests. The part
  both serialisations share, and the place the three terms *ocda*,
  *abstraction* and `.ssp` are told apart.
- [`ssp-format-specification.md`](ssp-format-specification.md) - **the
  `.ssp`**: the model written as text.
- [`ocda-db-format-specification.md`](ocda-db-format-specification.md) -
  **the `.ocda.db`**: the model written as sqlite.
- [`example-autonomous-contract.ssp`](example-autonomous-contract.ssp) -
  spine's output for that sample document, complete and unedited.
- [`example-wealth-of-networks.ssp`](example-wealth-of-networks.ssp) -
  an excerpt of spine's output for that sample document: verbatim
  lines, marked elisions, keeping the preamble, the `@head` section
  and a run of body objects that includes an object embedding an
  image. The whole file runs to 27,769 lines.

Both carry, in their opening comment lines, the command that
regenerates them, so they can be diffed against a run rather than
taken on trust. Both are output of **spine, format 2.1** (neither holds a
poem, so from 2.0 to 2.1 each changed by its version line alone).

## Version

The format is at **2.1**, and says so on the first line of every
file:

```
% SiSU Document Abstraction v2.1
```

The minor part is raised when a property is added, the major part
when one changes meaning or goes away, and a reader checks the major
part and refuses what it does not know. The history is in the
specification.

## What is `.ssp`?

Spine's processing pipeline goes
,**markup -> abstraction -> output**. The abstraction stage builds an
in-memory object model: every paragraph, heading, table, footnote
etc. is a numbered object with parent / sibling / type metadata
("OCN" - Object Citation Numbering). `.ssp` is a faithful text
serialisation of that object model.

It is designed for:

- Inspecting and debugging spine's abstraction stage.
- Diff-friendly version control of document structure (a `.ssp`
  diff between two markup edits shows exactly which objects
  changed).
- Round-trip experiments: markup -> spine -> `.ssp` -> alternative
  renderers (HTML, LLM-ready chunks, ...) without rerunning spine.
- A stable contract between spine and downstream consumers that do
  not want to link against spine's internal D types.

Line types (full grammar in
[`ssp-format-specification.md`](ssp-format-specification.md)):

```
@name {           section / block open
}                  section / block close
[N] type ...       object declaration (N = OCN, 0 if unnumbered)
.name: value       property of the preceding object
| text content     text line of the preceding object
                   blank line (object separator)
% comment          comment (ignored by parser)
```

## Audience

- Developers writing readers / converters for spine's abstraction
  (readers written from this specification alone:
  sisudoc-ssp-reader, sisudoc-ocda-db-reader, now frozen with current readers
  offered and maintained within sisudoc-ocda-lib).
- Anyone studying spine's internal document model without reading
  the D source.
- LLM / search / indexing tooling that consumes structured
  document data downstream of spine.

End-user document authors do not need to read this; they write
`.sst` / `.ssm` markup, which spine then turns into `.ssp` along
the way to the final output formats.

## Quickstart

Read the spec:

```sh
$EDITOR ssp-format-specification.md
```

Look at a real example:

```sh
$EDITOR example-wealth-of-networks.ssp
```

Generate your own `.ssp` from a sample document via spine:

```sh
# inside sisudoc-spine/
result/bin/spine --source --pod2 --output=/tmp/ssp path/to/pod
ls /tmp/ssp/pod/*/media/abstraction/*.ssp
```

`--pod2` writes the abstraction as `.ssp` and bundles it into the
source pod. (See sisudoc-spine's CLI help for the current flags.)

## License

AGPL-3.0-or-later, matching the parent
[sisudoc-spine](https://git.sisudoc.org/sisudoc-spine)
project.

## Repository

- **Canonical URL:** https://git.sisudoc.org/sisudoc-abstraction-format
- **Clone:** `git clone --depth=1 git://git.sisudoc.org/specs/sisudoc-abstraction-format`

## Related projects

- [sisudoc-spine](https://git.sisudoc.org/sisudoc-spine) - the document
  engine that writes `.ssp` and `.ocda.db` files.
- [sisudoc-ocda-lib](https://git.sisudoc.org/sisudoc-ocda-lib) - the
  abstraction read as a library, from a .ssp, a .ocda.db or a
  .sisupod (D and Gleam). To be published.
- [sisudoc-ocda-writer](https://git.sisudoc.org/sisudoc-ocda-writer) -
  sample writers over that library (text, markdown, html, epub, typst),
  each checked against spine. To be published.
- [tree-sitter-sisu](https://git.sisudoc.org/tree-sitter-sisu) - grammar
  for the .sst / .ssm markup spine reads before writing a .ssp.
#+END_SRC

** git .gitignore :gitignore:

#+HEADER: :tangle "../.gitignore"
#+BEGIN_SRC gitignore
,*
!.gitignore
!*.nix
!flake.lock
!*.md
!*.ssp
!org/
!**/*.org
!**/COPYRIGHT
#+END_SRC

** ocda-model.md

#+HEADER: :tangle ../ocda-model.md
#+BEGIN_SRC md
# The object-centric document abstraction (OCDA)

,**The model.** What a document *is* once spine has parsed it, independent
of any file it is written to.

Two serialisations carry this model, and they carry **one version number
between them**, because neither may express what the other cannot:

|                                                                      |                                |
|----------------------------------------------------------------------|--------------------------------|
| [`ssp-format-specification.md`](ssp-format-specification.md)         | the OCDA as text, `.ssp`       |
| [`ocda-db-format-specification.md`](ocda-db-format-specification.md) | the OCDA as sqlite, `.ocda.db` |

This document is what they share. It describes objects; they describe
writing objects down.

## 1. Three words, and what each names

The terms are used precisely in this repository and in spine, and the
distinction is worth holding:

| level              | term                       | names                                                                                                                                                  |
|--------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| the model          | **OCDA**                   | what a document is once parsed: numbered objects with structure, identity and digests. Independent of any file, any stage, any tool                    |
| the stage          | **abstraction**            | the middle of spine's **markup -> abstraction -> output**: the act of building the model, and the point at which a document may now enter the pipeline |
| the serialisations | **`.ssp`**, **`.ocda.db`** | the model written down, as text and as sqlite                                                                                                          |

A thing is named for the level it belongs to. Something true of the model
whatever file it is in takes *ocda*; something about the pipeline stage
takes *abstraction*; something that reads or writes one file form takes
that form's name.

## 2. The object

A document is a sequence of **objects**, grouped into sections. An object
is a paragraph, a heading, a table, an endnote, a line of verse: the unit
the document is made of and the unit it is cited by.

Every object carries:

- an **object citation number** (OCN), section 3;
- an **identifier**, section 3.1;
- a **kind** and a **type**, section 2.1;
- its **place in the structure**: parent, ancestors, and for a heading its
  children and its last descendant, section 4;
- the **segment** it is in, and for a heading an **anchor**, sections 7
  and 7.1;
- its **text**, in spine's internal representation;
- a **digest** of that text.

### 2.1 Kind and type: two axes, not one

An object is classified twice, and the two answer different questions.

,**Kind** (`is_a`) says *what the object is*, one of sixteen. Each kind
belongs to one section, except `heading`, which appears in all nine:

| kind           | section      | what it is                                                                     | count  |
|----------------|--------------|--------------------------------------------------------------------------------|--------|
| `para`         | body         | a paragraph, the ordinary unit of a document                                   | 41,885 |
| `heading`      | *all nine*   | a heading at one of the eight levels                                           | 3,503  |
| `toc`          | toc          | an entry in the generated table of contents                                    | 3,215  |
| `bookindex`    | bookindex    | an entry in the generated book index                                           | 3,034  |
| `endnote`      | endnotes     | a note, gathered from where it was called                                      | 2,294  |
| `code`         | body         | a code block                                                                   | 1,623  |
| `bibliography` | bibliography | a bibliography entry                                                           | 585    |
| `comment`      | body         | markup comment, carried and not rendered                                       | 450    |
| `verse`        | body         | one verse of a poem                                                            | 151    |
| `glossary`     | glossary     | a glossary entry                                                               | 56     |
| `quote`        | body         | a block quotation                                                              | 53     |
| `poem`         | body         | a poem: the container of its verses, OCN `0`, cited as their range (section 5) | 48     |
| `block`        | body         | a block of grouped text                                                        | 45     |
| `table`        | body         | a table, with its columns described                                            | 32     |
| `blurb`        | blurb        | a blurb entry                                                                  | 28     |
| `group`        | body         | a group block                                                                  | 16     |

,**Type** (`is_of_type`) says *how the object's text behaves*, and takes
only three values:

| type      | means                                                   | kinds                                                                                 |
|-----------|---------------------------------------------------------|---------------------------------------------------------------------------------------|
| `para`    | flowing text, wrapped as the output sees fit            | `para`, `heading`, `toc`, `bookindex`, `endnote`, `bibliography`, `glossary`, `blurb` |
| `block`   | text whose line breaks are significant and must be kept | `code`, `verse`, `quote`, `poem`, `block`, `table`, `group`                           |
| `comment` | not rendered                                            | `comment`                                                                             |

The mapping from kind to type is fixed: every `code` object is of type
`block`, every `para` object of type `para`. **A renderer that has the type
does not need to know all sixteen kinds** to decide whether it may reflow
the text, which is what the second axis is for.

## 3. The object citation number

The OCN is the heart of the model and the reason for it.

,**An object's OCN is the same in every format spine writes.** A paragraph
that is object 42 in the HTML is object 42 in the EPUB, in the PDF, in the
plain text, in the search database and in both serialisations of the
abstraction. A citation to object 42 of a document is therefore a citation
to a fixed piece of text, not to a page in one edition or a scroll position
in one rendering.

Three properties follow, and each is a trap for a reader that assumes
otherwise:

- **Not every object has one.** Generated furniture, and objects the markup
  has suppressed, carry `0`. There are many of them: 7,543 across the 36
  document reference collection.
- **`0` is therefore not an identity.** Objects sharing `0` are not the
  same object, and `0` must never be used as a key.
- **A non-zero OCN is unique within a document**, from format 2.1: checked
  over the reference collection, no non-zero OCN occurs twice in any of the
  36 document-languages. **Before 2.1 it was not**: a poem carried the OCN of
  its last verse, so the same number named two objects (48 such pairs in the
  collection, 21 in `through_the_looking_glass`). A reader of an older
  artefact keys on position within a section when one row is wanted.

### 3.1 The identifier

Every object also carries an **identifier**: the name by which an output
refers to it. An HTML anchor, a LaTeX `\hypertarget`, a link from a book
index entry to the object it indexes, are all written from the identifier.

,**The identifier of an object with a non-zero OCN is its OCN**, written as
text. That is the ordinary case and it is the reason a citation to object
42 can be turned into a link without consulting anything.

An object with OCN `0` has no OCN to take an identifier from, so one is
assigned: `a1`, `a2`, `a3`, ... in document order over the objects that
need one. There are few of them, eleven in a book, and they are the
generated furniture of section 3.

,**A reader must arrive at the identifier whether or not the serialisation
wrote it down**; see section 9.

## 4. Levels

A document has **eight heading levels**, in two groups of four:

| level | index | what it is                                   |
|-------|-------|----------------------------------------------|
| `A`   | 0     | the document title. Exactly one per document |
| `B`   | 1     |                                              |
| `C`   | 2     | the title matter below it                    |
| `D`   | 3     |                                              |
| `1`   | 4     | the top level of the document body           |
| `2`   | 5     |                                              |
| `3`   | 6     | below that                                   |
| `4`   | 7     |                                              |

`A` to `D` are the title levels, `1` to `4` the body levels, and the index
is what the eight-slot arrays of section 5 are indexed by. A heading that
claims no level has 9, which is the "not a heading level" value and is why
`.heading_lev_collapsed` is emitted only when it is below 9.

,**Collapsed levels.** A document that uses `A` and then `1`, skipping `B`,
`C` and `D`, has a gap in its levels that is an artefact of the markup
rather than of the document. Every level-indexed array therefore comes in
two forms: as marked up, and **collapsed**, with the unused levels removed
so that the remaining ones are contiguous. Outputs that care about nesting
depth use the collapsed form; anything tracing back to the markup uses the
other.

## 5. Structure

Structure is carried by number, not by nesting: an object names its parent
rather than containing its children. This is what lets the serialisations
be flat and the model be walked in either direction.

- **`parent`** - the OCN of the object this one hangs from.
  **A parent of `0` is not "no parent"**: it is a parent heading the author
  has made non-substantive, its OCN suppressed or a dummy heading
  introduced to segment an output. The distinction is preserved
  deliberately, and a reader walking upward must stop at `0` rather than
  treat it as missing, or the walk will not terminate.
- **`ancestors`** - **eight slots, indexed by level** (section 4): the OCN
  of the heading at each level above this object, `0` where there is none,
  so the path to the root is available without walking it.
  **A heading's own OCN sits in its own level's slot**: checked over the
  reference collection, 3,432 headings of 3,432. So for a heading the array
  is its path including itself, and for any other object it is the path to
  the heading above it.
- **`ancestors_collapsed`** - the same, in collapsed levels.
- **`children`** - a heading's child headings.
- **`last_descendant`** - the last OCN under a heading, which makes a
  subtree a **range** rather than a traversal: everything from the
  heading's OCN to its last descendant is inside it.
- **`ocn_range`** - for a **container**, the first and last OCN of what it
  holds (2.1). A poem is the one container: its verses are the citable
  units, one object each, and the poem is not; it carries OCN `0` and no
  identifier, **comes immediately before its first verse**, and is cited as
  the range of them (`173-180`). So a writer that meets a poem knows what
  follows and where it ends, and can wrap the verses in one pass. The poem
  has no text of its own. `0 0`, or absent, where the object is not a
  container.
  **Before 2.1** the poem came *after* its last verse, carried that verse's
  OCN and identifier, and stated no range.

## 6. Sections

Objects are grouped into nine sections, in this order:

```
head  toc  body  endnotes  glossary  bibliography  bookindex  blurb  tail
```

`head` is the document's title matter, `body` the document proper, and the
rest are generated or gathered. `tail` is the end of document some output
writers use. A section with no objects is not carried.

## 7. Segments

An output may be one file or many. A **segment** is one of the many: a
chapter-sized piece of HTML or EPUB with its own name and its own
navigation.

Two different questions are asked about segments, and the model answers
both separately because the answers differ:

- **which segment does this heading open?** Set on headings only.
- **which segment is this object in?** Set on nearly every object.

Without the second, a reader cannot say where a paragraph belongs. The
search database reads the second.

### 7.1 The anchor

A heading carries an **anchor**: the name an output links to in order to
arrive at that heading. It is what a table of contents entry and a
cross reference point at.

,**An object's anchor is its segment name**, in the ordinary case, because a
heading that opens a segment is arrived at by arriving at the segment. It
differs only where a heading is not the opening of the segment it sits in:
69 of the 72 anchors in one reference document equal their segment and 3 do
not.

,**A reader must arrive at the anchor whether or not the serialisation wrote
it down**; see section 9.

## 8. Digests

The model is checkable at four levels, and the chain is what lets an
artefact be verified rather than trusted:

```
the markup files ──> a digest over every markup file of that language
the serialisation ──> a digest of the .ssp a database was built from
each object ──> a digest of the object's text
each image ──> a digest of the image file, with its size in bytes and pixels
```

An object's digest is over its text alone, so a change to one paragraph
moves one digest and no other.

## 9. Derived values, and why a reader must derive them

Two of the values above are **derived**: the identifier from the OCN
(section 3.1), and the anchor from the segment name (section 7.1). The
model holds them; a serialisation need not, and the text form does not.

,**A serialisation may omit a value it can compute.** The `.ssp` writes a
property only when it carries information, so it omits `.identifier` where
the identifier is the OCN and `.anchor` where the anchor is the segment
name. The `.ocda.db` is columns rather than lines and writes both
unconditionally.

Both are conforming. What is **not** conforming is a reader that takes the
text form literally and hands on a model with those fields empty, because
that model is not the same model the database gives, and a writer over it
will produce different output from the two serialisations of one document.

The size of the difference is easy to underestimate. In
`free_culture.lawrence_lessig` the `.ssp` omits **1,314 identifiers and 69
anchors** that the `.ocda.db` states, which is nearly every object in the
document.

So, on loading:

| field      | when absent              | take                                                             |
|------------|--------------------------|------------------------------------------------------------------|
| identifier | OCN is non-zero          | the OCN as text                                                  |
| identifier | OCN is `0`               | whatever the serialisation gave; there is nothing to derive from |
| anchor     | the object has a segment | the segment name                                                 |

,**This is a property of the model, not of either format**, which is why it
is stated here and not only in the two format specifications. It is stated
here *because* two readers written independently from these documents
disagreed for want of it: the rule was implied by the `.ssp`'s emission
conditions and nowhere asserted.

It is also what **spine's own reader** does, and always did, which is why
the `.ocda.db` carries the derived values: the database is written from the
`.ssp` read straight back, and the reading fills both in. So this section
documents existing behaviour rather than prescribing new. It should have
been written down first.

## 10. What the model does not hold

- **The markup.** The model is what the markup produced, not the markup
  itself. An artefact that carries both is the `.ocda.db`, which carries
  the markup alongside the model rather than within it.
- **The images.** The model *names* them, with digest, byte size and pixel
  size, and they must be found beside the file for a document to be
  complete.
- **Any output format.** No HTML, no page numbers, no typesetting.
#+END_SRC

** ssp-format-specification.md

#+HEADER: :tangle ../ssp-format-specification.md
#+BEGIN_SRC md
# The `.ssp` format

,**The object-centric document abstraction, written as text. Format version
2.1**, as spine emits and reads it after 0.25.1.

This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the sqlite
serialisation shares; read that first if the question is what an object
,*is* rather than how it is written down.

## The name

`.ssp` belongs to the family of SiSU markup extensions, `.sst` (sisu text),
`.ssm` (sisu master) and `.ssi` (sisu insert), and a short extension was
wanted that sat with them. It stands loosely for **sisu peg**, or **sisu
parsable**. `.ssa`, for sisu abstraction, was thought to be taken by other
projects.

So the extension names the *file family and its parsability*, where
`.ocda.db` names the *model and its container*. The two are not parallel in
construction and are not meant to be.

## Status

This specification is derived from the emitter
(`sisudoc/ocda/abstraction/ssp.d` in sisudoc-spine, whose `sspObjectRecord`
is "the single definition of what an object looks like in a `.ssp` file"),
and every claim in it is checked against the project's 36 document
reference set. Where the two could differ, the emitter is normative and
this document is wrong.

## 1. What a `.ssp` is

A `.ssp` file is the serialisation, as text, of one language of one
document after spine has parsed it: the object model, not the markup and
not any output format.

Spine's pipeline is **markup -> abstraction -> output**. A `.ssp` is the
middle stage written down. Since spine 0.25.0 it is also read back, so a
document may enter the pipeline at the abstraction stage instead of being
parsed, and the output writers cannot tell which happened.

The format is:

- **line oriented.** Every construct is a whole line. No line continuations.
- **order significant.** Sections appear in a fixed order, objects in
  document order, and an object's properties in a fixed order (section 6.3).
- **UTF-8**, without a byte order mark.
- **lossless for the abstraction**, not for the markup: a `.ssp` read back
  and re-emitted is byte identical, which the project's test suite asserts
  over the whole reference set.

### 1.1 What it is not

It does not carry the markup it was made from, and it does not carry its
images: it *names* them, with their digests and pixel sizes, and they must
be found beside it (`../image/` within a pod) for the document to be
complete. An artefact that carries both is the `.ocda.db`, which is built
by reading a `.ssp` back, so it can hold nothing this format cannot express.

## 2. Version and compatibility

The version is declared **in band**, on the first line of every file:

```
% SiSU Document Abstraction v2.1
```

and by the sibling sqlite serialisation in its `schema.version` metadata
row, so that one bump moves both.

### 2.1 The rule

- The **minor** part is raised when a property is **added**. A reader of the
  newer format still reads the older one.
- The **major** part is raised when a property **changes meaning or goes
  away**.
- A reader **checks the major part and refuses what it does not know**,
  rather than loading an unfamiliar artefact half populated in silence.

### 2.2 History

| version | date       | what moved                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|---------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2.1     | 2026-09-29 | `.ocn_range`, the first and last ocn of what a container holds. A poem is a container of verses and is cited as their range: it now comes before its first verse, carries ocn `0` and no identifier, and states the range, where it had come after its last verse carrying that verse's ocn and identifier, so that one number named two objects. A minor bump: the property is an addition, the poem was never rendered and has no text, the verses are unchanged, and a 2.0 reader reads a 2.1 file. The same run gathers a note in a poem's last verse into the endnotes, which it had not been: one more endnote in the reference collection. And the editor's notes, `~[* ]~` and `~[+ ]~`, which spine had not recognised and passed through as text, are notes: a third form of note mark, a symbol and a number (`*1`, `+1`), each series numbered through the document; 135 more endnotes, 2,294 in all (section 3.2, "A note begins with its mark"). |
| 2.0     | 2026-09-18 | `source.digest` changes meaning: it covers every markup file the document is made of, where it had been the digest of the master file alone. A change of meaning, so the major part.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 1.1     | 2026-09-10 | The `@source` block; the document metadata the output writers read, carried in full (14 `@meta` and 3 `@make` properties added); `.segment_lv4_is`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 0.1     |            | The first form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## 3. Lexical structure

Six line types, distinguished by their first character. Nothing else is a
valid line.

| line               | form            | meaning                                       |
|--------------------|-----------------|-----------------------------------------------|
| comment            | `% ...`         | file header only (section 4)                  |
| block open         | `@name {`       | opens a preamble block or a section           |
| block close        | `}`             | closes it                                     |
| key                | `  key: value`  | inside a preamble block, two spaces of indent |
| object declaration | `[ocn] kind...` | opens an object record (section 6.1)          |
| property           | `.name: value`  | a property of the object just declared        |
| text               | `\| text`       | a line of the object's text                   |
| blank              |                 | separates records; carries no meaning         |

A value runs to the **end of the line**. It is not quoted, and it is not
trimmed beyond the single space after the colon. A value may therefore
contain `:`, spaces, and any UTF-8 character except a line break.

### 3.1 Escaping

Only one value is escaped, because only one value is a **joined list**:
`.heading_ancestors_text` joins eight slots with `|`. A slot that itself
contains `|`, a backslash, or a line break would otherwise be unreadable.

| in the value    | written as |
|-----------------|------------|
| `\`             | `\\`       |
| `\|`            | `\\|`      |
| newline         | `\n`       |
| carriage return | `\r`       |

Unescaping reads left to right: a backslash escapes the next character,
`\n` and `\r` become the control characters, any other escaped character
stands for itself, and an unescaped `|` ends the slot.

,**No other value is escaped**, and text lines are not escaped at all: a
text line is the object's text verbatim after the two-character `| `
prefix.

### 3.2 Object text is internal markup

The text on `|` lines is spine's **internal** representation, neither the
author's markup nor any output. It carries the markers spine uses to hold
inline structure:

The full set is defined in spine's `InlineMarkup` (`ocda/meta/defaults.d`).
Counts are occurrences in object text across the 36 document reference
collection, which distinguishes what a reader will certainly meet from what
it may not.

| marker      | means                                       | count  | where                |
|-------------|---------------------------------------------|--------|----------------------|
| `░`         | non-breaking space                          | 23,048 |                      |
| `┥` `┝`     | link text, open and close                   | 20,290 |                      |
| `┤` `├`     | link target, open and close                 | 20,290 |                      |
| `⑆`         | a page number of the source edition follows | 19,099 |                      |
| `┨` `┣`     | that page number, open and close            | 19,099 |                      |
| `■`         | monospace                                   | 10,688 |                      |
| `【` `】`   | an inline note, its mark first (below)      | 2,294  |                      |
| `¤`         | an internal site link                       | 2,157  |                      |
| `┊`         | table cell separator                        | 695    | `table` objects only |
| `┙`         | line break, inline                          | 184    |                      |
| `☼`         | an image, in a link's text slot             | 63     |                      |
| `┚`         | line break, spaced                          | 50     | `group` objects only |
| `〖` `〗`   | a starred note                              | 0      |                      |
| `‖`         | a citation                                  | 0      |                      |
| `┘`         | line break, plain                           | 0      |                      |
| `┼` `┿` `╂` | page break: line, page, new page            | 0      |                      |
| `┏` `┆`     | table open, table paragraph                 | 0      |                      |
| `␣`         | separator                                   | 0      |                      |

,**A count of 0 means the reference collection does not exercise it, not
that it cannot appear.** All of these are defined by the emitter and a
reader must be prepared for them.

,**A note begins with its mark**, then whitespace, then the note: `【12 text】`.
The mark is one of three forms, and a reader must take all three:

| mark                    | what                                                                                                                          | example                    |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| digits                  | the author's notes, numbered through the document                                                                             | `【12 ...】`               |
| `*` or `+`, repeated    | a special note, marked by the symbols alone                                                                                   | `【** ...】`               |
| `*` or `+`, then digits | an editor's note (2.1): the markup's `~[* ]~` and `~[+ ]~`, each series numbered through the document apart from the author's | `【*3 ...】`, `【+1 ...】` |

So the pattern is `【(\d+|[*+]+[0-9]*)\s`. Before 2.1 the third form did not
occur: spine did not recognise the editor's-note markup, and it came through
as text, `~[* ...]~` and all. Each note of every form is gathered into the
`endnotes` section, where its `.anchor_tag` is `note_` and the mark
(`note_12`, `note_*3`).

Two traps in this table, both found by counting rather than by reading:

,**`┚` is defined twice**, as the spaced line break and as the table close.
In object text it occurs only in `group` objects, never in a `table`, so
the object's kind resolves it. A reader should decide by kind rather than
by character.

,**`「` and `」` are not markers here.** They are defined in `InlineMarkup`
as the wrapper spine's ODT writer puts around an object number, but that
happens at output, after the abstraction. Their 67 occurrences in the
reference collection are **Japanese corner brackets in the document's own
text**, being quotation marks in Japanese. In a `.ssp` they are always
content.

Some markers are the ASCII characters `*`, `!`, `/`, `_`, `^` and `,` for
emphasis, bold, italic, underscore, superscript and subscript. These are
,**not distinguishable from ordinary text by inspection**, and a reader that
needs them must follow spine's rules for where they apply rather than
searching for the characters.

A reader that renders text must decode all of this; a reader that only
searches or counts need not, and one that wants plain text may strip the
non-ASCII markers and take the ASCII ones as text. They are stable and they
are part of the format.

## 4. File shape

In order, and this order is fixed:

```
% SiSU Document Abstraction v2.1
% Source: <markup filename>

@source { ... }

@meta { ... }

@make { ... }

@doc_has { ... }

@head { ... }
@toc { ... }
@body { ... }
@endnotes { ... }
@glossary { ... }
@bibliography { ... }
@bookindex { ... }
@blurb { ... }
@tail { ... }
```

The two `%` lines are the only comments in the file and appear only here.
The four preamble blocks are always present and always in that order. The
nine section blocks appear in that order. **A section is omitted entirely
when the document has no objects for it**, though in practice that is rare:
all 36 documents of the reference collection carry all nine, several of
them holding a single generated object.

## 5. The preamble blocks

Inside a block, every line is `  key: value` with exactly two spaces of
indent. Keys are unique within a block. **A key whose value is empty is
omitted**, so the set of keys present varies by document; the exceptions
are noted below.

### 5.1 `@source` - what this abstraction was made from

| key         | always?                    | meaning                                                                     |
|-------------|----------------------------|-----------------------------------------------------------------------------|
| `language`  | yes                        | the language of *this* file                                                 |
| `languages` | when the pod declares them | every language of the document, space separated                             |
| `digest`    | yes                        | sha256 over **every markup file the document is made of**, in a fixed order |

The source *filename* is not repeated here; it is on the `% Source:` line.

`digest` is what changed in 2.0. It had been the digest of the master file
alone, which for a single file document was right and for a multi-file one
was close to meaningless: any chapter could be edited without the digest
moving.

### 5.2 `@meta` - the document's own metadata

Dublin-Core shaped, `group.name`. **43 keys are defined**; a given document
carries only those it has. The 28 the reference collection exercises are
marked; the remainder are defined and simply unused by these documents.

| group         | keys                                                                                                                                                                             |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `title.`      | `main`*, `subtitle`*, `full`*, `language`*, `edition`*                                                                                                                           |
| `creator.`    | `author`*, `author_surname`*, `author_surname_fn`*, `author_email`*, `illustrator`*, `translator`*                                                                               |
| `date.`       | `published`*, `created`*, `issued`*, `available`*, `modified`*, `valid`*, `added_to_site`*                                                                                       |
| `rights.`     | `copyright`*, `license`*, `copyright_text`, `copyright_translation`, `copyright_illustrations`, `copyright_photographs`, `copyright_cover`, `copyright_audio`, `copyright_video` |
| `classify.`   | `topic_register`*, `subject`, `keywords`, `loc`*, `dewey`*                                                                                                                       |
| `identifier.` | `isbn`, `oclc`                                                                                                                                                                   |
| `notes.`      | `summary`*, `abstract`*, `description`*                                                                                                                                          |
| `original.`   | `source`*, `title`, `language`, `language_char`                                                                                                                                  |
| `language.`   | `document_char`*, `document`                                                                                                                                                     |

`classify.topic_register` is structured within its value: topics separated
by `;`, levels within a topic by `:`, and alternatives at a level by `|`.

### 5.3 `@make` - how the document is to be built

| key                     | value                    | meaning                                                                                                |
|-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------|
| `doc_type`              | `article`, `book`        | what kind of document this is                                                                          |
| `auto_num_top_at_level` | a level, e.g. `1`        | the heading level automatic numbering starts at, **as written in the markup**                          |
| `auto_num_top_lv`       | that level's index, 0..8 | the same level as a number (section 4 of [`ocda-model.md`](ocda-model.md)); `9` where numbering is off |
| `auto_num_depth`        | e.g. `2`                 | how many levels down numbering continues                                                               |
| `breaks`                | see below                | where the output starts a new page, and where it breaks one                                            |
| `footer`                | slots joined with `\|`   | the footer, each slot carrying link markup                                                             |
| `home_button_text`      | link markup              | the home link, as internal markup                                                                      |

`auto_num_top_at_level` and `auto_num_top_lv` are **the same value twice**,
as the markup wrote it and as an index: `1` and `4`, since the body levels
begin at index 4.

`breaks` is a small language of its own, `new=` for a new page and
`break=` for a page break, each taking a comma separated list of levels,
the two separated by `;`:

```
breaks: new=:A,:B; break=:C,1
breaks: new=:B; break=1
breaks: break=1
```

The level names here are written as they are in the markup, so with or
without the leading colon as the document wrote them; a reader should not
assume either form.

### 5.4 `@doc_has` - what the document contains, by count

Ten keys, **all ten always emitted**, zero included. This block is a
summary a reader can use without walking the objects.

```
inline_links  inline_notes_reg  inline_notes_star  tables  codeblocks
images  poems  groups  blocks  quotes
```

## 6. Objects

The nine section blocks hold object records, in document order. An object
record is an object declaration line, then its properties, then its text
lines, then a blank line.

### 6.1 The declaration line

```
[<ocn>] <kind>
[<ocn>] heading :<level>
[<ocn>] heading :<level> <identifier>
```

`<ocn>` is the **object citation number** (see
[`ocda-model.md`](ocda-model.md) section 3). `[0]` means the object has
none, is shared by many objects, and must never be used as a key; key on
position within a section instead.

`<kind>` is one of sixteen:

```
para  heading  toc  bookindex  endnote  code  bibliography  comment
verse  glossary  quote  poem  block  table  blurb  group
```

A **heading** is the one kind whose declaration line carries more: its
markup level after a colon (`:A` `:B` `:C` `:D` for the title levels,
`:1`..`:4` for the body levels; `:D` is defined and unexercised by the
reference collection), and then its identifier, when it has one
that is not simply the ocn. Every other kind carries an identifier, on the
same condition, as the `.identifier` property.

> **A reader must derive the identifier where it is absent, and the anchor
> likewise.** "when it has one that is not simply the ocn" means the
> identifier *is* the ocn in every other case, and a reader that leaves the
> field empty gives a different model from the one the `.ocda.db` gives, on
> nearly every object. Section 9 of [`ocda-model.md`](ocda-model.md) states
> both derivations and why they belong to the model rather than to either
> format. Two readers written independently from these documents disagreed
> for want of it.

### 6.2 Text lines

```
| <text>
```

One line per line of the object's text, in order, each prefixed with
`| ` (pipe, space). An object with no text has no text lines. The text is
internal markup (section 3.2) and is not escaped.

### 6.3 Properties

,**Properties appear in a fixed order**, the order of the table below, and a
reader may rely on it: checked over the reference set, no object among
56,882 emits a property out of this order.

,**A property is omitted when it holds its default**, so absence is
meaningful and is defined per property in the table. Four properties
repeat, appearing once per value rather than carrying a list: `.image`,
`.stow_link`, `.lev4_subtoc` and `.anchor_tag`.

Two consequences of the order, which a validator needs stated and which
hold over the whole reference collection:

- **a repeated property's occurrences are consecutive.** They share one
  position in the order, and nothing is written between them. Checked: no
  repeat in the collection is separated by another property.
- **no property follows the text.** The record is declaration, then
  properties, then text lines, and once a `|` line has been written no
  further property appears. Checked: 0 occurrences in the collection.

In the table, "emitted when" is the condition under which the property
appears at all. Counts are occurrences across the 36 document reference
set, as a guide to which parts of the format are load bearing.

| #  | property                  | value                         | emitted when                                                                                       | count  |
|----|---------------------------|-------------------------------|----------------------------------------------------------------------------------------------------|--------|
| 1  | `.identifier`             | string                        | a non-heading has an identifier that is not its ocn (**otherwise it is the ocn**: model section 9) | 353    |
| 2  | `.part`                   | string                        | the object belongs to a part (`frontmatter`, `body`, ...)                                          | 57,018 |
| 3  | `.section`                | string                        | the object's own section differs from the block it sits in                                         | 605    |
| 4  | `.parent`                 | int                           | **every object except** the document root and `toc` entries                                        | 53,767 |
| 5  | `.last_descendant`        | int                           | non-zero: the last ocn under this heading                                                          | 3,202  |
| 6  | `.ocn_range`              | 2 ints                        | the object is a container: the first and last ocn of what it holds (2.1; a poem, model section 5)  | 48     |
| 7  | `.children`               | ints                          | the heading has child headings                                                                     | 827    |
| 8  | `.ancestors`              | 8 ints                        | any is non-zero                                                                                    | 53,731 |
| 9  | `.ancestors_collapsed`    | 8 ints                        | any is non-zero                                                                                    | 53,731 |
| 10 | `.dom_status`             | 8 ints                        | any is non-zero                                                                                    | 3,319  |
| 11 | `.dom_status_collapsed`   | 8 ints                        | any is non-zero                                                                                    | 3,319  |
| 12 | `.heading_lev_collapsed`  | int                           | it is below 9                                                                                      | 3,503  |
| 13 | `.parent_lev`             | int                           | non-zero                                                                                           | 52,984 |
| 14 | `.dummy`                  | `true`                        | the heading was introduced to segment an output                                                    | 183    |
| 15 | `.ocn_off`                | `true`                        | the object has no citation number                                                                  | 7,543  |
| 16 | `.is_of_type`             | string                        | always, in practice                                                                                | 57,018 |
| 17 | `.attrib`                 | string                        | set                                                                                                | 1      |
| 18 | `.meta_lang`              | string                        | the object carries its own language                                                                | 0      |
| 19 | `.meta_syntax`            | string                        | the object carries its own markup syntax                                                           | 0      |
| 20 | `.sha256`                 | hex                           | the object's text digest is non-zero                                                               | 51,253 |
| 21 | `.image`                  | record                        | once **per image**, in order of appearance                                                         | 63     |
| 22 | `.indent`                 | 2 ints                        | either indent is non-zero: `base hang`                                                             | 7,583  |
| 23 | `.bullet`                 | `true`                        | the object is a bullet item                                                                        | 1,903  |
| 24 | `.lang`                   | string                        | the text attributes carry a language                                                               | 0      |
| 25 | `.has`                    | flags                         | any is set                                                                                         | 11,384 |
| 26 | `.table_cols`             | int                           | the object is a table with columns                                                                 | 32     |
| 27 | `.table_widths`           | ints                          | the table has column widths                                                                        | 32     |
| 28 | `.table_aligns`           | letters                       | the table has alignments (`l` `c` `r`)                                                             | 32     |
| 29 | `.table_header`           | `true`                        | the table has a header row                                                                         | 29     |
| 30 | `.code_linenumbers`       | `true`                        | the code block is numbered                                                                         | 1      |
| 31 | `.stow_link`              | url                           | once **per extracted link**                                                                        | 1,014  |
| 32 | `.segment`                | string                        | the heading opens a segment                                                                        | 3,355  |
| 33 | `.anchor`                 | string                        | the anchor differs from the segment name (**otherwise it is the segment name**: model section 9)   | 68     |
| 34 | `.segment_prev`           | string                        | there is a previous segment                                                                        | 1,022  |
| 35 | `.segment_next`           | string                        | there is a next segment                                                                            | 1,022  |
| 36 | `.heading_lev_anchor`     | string                        | the heading has a level anchor tag                                                                 | 1,854  |
| 37 | `.segment_epub`           | string                        | the heading opens an epub segment                                                                  | 3,355  |
| 38 | `.segment_html_is`        | string                        | the object is inside an html segment                                                               | 47,072 |
| 39 | `.segment_epub_is`        | string                        | the object is inside an epub segment                                                               | 47,072 |
| 40 | `.segment_lv4_is`         | string                        | **and** it differs from `.segment_html_is`                                                         | 342    |
| 41 | `.heading_ancestors_text` | 8 slots, `\|` joined, escaped | any slot is non-empty                                                                              | 3,319  |
| 42 | `.lev4_subtoc`            | string                        | once **per sub-table-of-contents entry**                                                           | 1,887  |
| 43 | `.anchor_tag`             | string                        | once **per anchor tag**                                                                            | 8,019  |

Three of these need a word here, the first two because the model behind
them is easy to misread (see [`ocda-model.md`](ocda-model.md) sections 5
and 7), the third because it is a property of this table rather than of the
format.

,**`.parent: 0` is emitted, not omitted.** A parent of 0 is a real,
non-substantive parent and not a missing value, so the property is written
out rather than defaulted away: omitting it would make the two cases
indistinguishable in the file. A reader walking upward stops at 0.

,**`.segment` and `.segment_html_is` are different questions**, and both are
carried: what a heading opens, and what an object sits in. A reader wanting
to know where a paragraph belongs needs the second.

,**Count 0 does not mean "not in the format".** `.meta_lang`, `.meta_syntax`
and `.lang` are emitted by spine under the conditions given, and no
document in the reference collection meets them. A reader must handle them;
a test corpus does not exercise them.

### 6.4 The `.image` record

```
.image: <filename> sha256:<HEX> bytes:<n> px:<width>x<height>
.image: <filename> missing:true
```

Filename first, as the object's handle on the image. The remaining fields
are self describing `key:value` tokens, **so that further fields may be
added without invalidating existing readers**; `px:` is omitted when the
pixel size is unknown. `px:` is the file's own size, not the display size,
which the object's text already carries.

### 6.5 The `.has` flags

Space separated, in this order, each present only when set:

```
links  notes_reg  notes_star  images  images_no_dim
```

## 7. Grammar

,**This grammar is complete for the file shape and deliberately incomplete
for one thing: the order of properties.** A grammar that fixed the order
would have to enumerate 42 optional terms in sequence, would be unreadable,
and would need editing at every minor version, which is exactly when a
property is added. The order is a guarantee of the format (section 6.3) and
is stated there, where it can be read; a parser that wants to check it can
do so against the table.

So: **a file that this grammar accepts and section 6.3 rejects is a
malformed file, not an ambiguity in the format.** The grammar is the shape;
the table is the contract.

,**Checked**: every line of the 36 document reference collection matches one
of the eight line shapes below, 721,363 lines with none left over.

```peg
Document    <- Header Source Meta Make DocHas Section* EOF
Header      <- "% SiSU Document Abstraction v" Version EOL
               "% Source: " Value EOL Blank
Version     <- Digit+ "." Digit+

Source      <- "@source {" EOL Pair+ "}" EOL Blank
Meta        <- "@meta {"   EOL Pair* "}" EOL Blank
Make        <- "@make {"   EOL Pair* "}" EOL Blank
DocHas      <- "@doc_has {" EOL Pair+ "}" EOL Blank
Pair        <- "  " Key ": " Value EOL
Key         <- [a-z_]+ ("." [a-z_]+)?

Section     <- "@" SectionName " {" EOL Blank Object* "}" EOL Blank
SectionName <- "head" / "toc" / "body" / "endnotes" / "glossary"
             / "bibliography" / "bookindex" / "blurb" / "tail"

Object      <- Decl Property* TextLine* Blank
Decl        <- "[" Digit+ "] " (Heading / Kind) EOL
Heading     <- "heading :" Level (" " Identifier)?
Level       <- [A-D] / [1-4]
Kind        <- [a-z]+
Property    <- "." Name ": " Value EOL
Name        <- [a-z_0-9]+
TextLine    <- "| " Value EOL

# a repeatable property appears once per value rather than carrying a list:
#   .image  .stow_link  .lev4_subtoc  .anchor_tag
# and .image has an inner shape of its own:
Image       <- ".image: " FileName (" " Field)* EOL
Field       <- Key ":" Value
FileName    <- (!" " !EOL .)+

Value       <- (!EOL .)*
Blank       <- EOL
EOL         <- "\n"
Digit       <- [0-9]
```

## 8. Conformance

### 8.1 A reader must

- **Check the major version** on the first line and refuse a major it does
  not know. Loading an unknown major half populated, in silence, is the
  failure this rule exists to prevent.
- **Tolerate unknown properties** within a known major version, since the
  minor part is raised precisely by adding them. Ignoring them is
  conforming behaviour.
- **Treat `[0]` as not an identity.** Objects with no citation number are
  numerous and share the number.
- **Stop at `.parent: 0`** when walking upward.

### 8.2 A reader should

- **Report what it ignored**, at least on request. A reader that silently
  drops what it does not understand cannot tell its user whether it
  understood the document, and cannot be used to check this specification
  against an implementation.

### 8.3 A writer must

- Emit the blocks and sections in the order of section 4, an object's
  properties in the order of section 6.3, and objects in document order.
- Omit a property holding its default, per section 6.3.
- Escape only what section 3.1 requires, and only where it requires it.

## 9. Relationship to the model, and to the sqlite serialisation

The model this format writes down is specified in
[`ocda-model.md`](ocda-model.md): objects, citation numbers, structure,
sections, segments and digests. This document adds nothing to the model and
subtracts nothing from it; it says how the model is written as text.

The `.ocda.db` is the same abstraction as sqlite, and is **built by reading
a `.ssp` back**: the document is emitted as `.ssp`, read straight in, and
what comes back is written. So the database cannot carry an object property
this format cannot express, and the two cannot drift. They share the
version, which is why a bump moves both.

The database is not a competitor to this format. It carries every language
of a document in one file, and the markup, images and configuration as
well, which this format does not.

## 10. Worked examples

- `example-autonomous-contract.ssp` - one document, complete and unedited.
- `example-wealth-of-networks.ssp` - an excerpt of a large one: verbatim
  lines with marked elisions, keeping the preamble, the `@head` section,
  and a run of body objects including one that embeds an image.

Each carries, in its opening comments, the command that regenerates it.
#+END_SRC

** ocda-db-format-specification.md

#+HEADER: :tangle ../ocda-db-format-specification.md
#+BEGIN_SRC md
# The `.ocda.db` format

,**The object-centric document abstraction, written as sqlite. Format
version 2.1**, as spine emits and reads it after 0.25.1.

This document specifies *one serialisation*. The model it serialises is
specified in [`ocda-model.md`](ocda-model.md), which the text serialisation
shares; read that first if the question is what an object *is* rather than
how it is stored.

## Status

Derived from the writer, `sisudoc/outputs/io_out/sqlite_ocda_db.d`, and
checked against the 27 published databases of the project's reference
collection. Where the two could differ the writer is normative and this
document is wrong.

## 1. What it is, and what makes it different

One file per **document**, holding **every language of it**: a ten language
document is one database with ten rows in `documents`, written one language
at a time into the one file.

Two things distinguish it from the `.ssp`:

- **It carries its own source.** The markup, the images, `conf/document_make`,
  `pod.manifest` and the `tools/po4a` catalogues are all inside it, in the
  `files` table. A pod can be written back out of it, and spine does exactly
  that when asked for an artefact that needs markup. The `.ssp` names its
  images and carries none of them.
- **It is queryable without being parsed.** A question about the document is
  a SELECT, answered from the file with no spine and no reader.

### 1.1 It is built from the `.ssp`

The document is emitted as `.ssp`, **read straight back**, and what comes
back is what is written. So **the database cannot carry an object property
the `.ssp` cannot express**, and the two cannot drift. That is also why they
share one version number: a bump moves both.

The carried *files* are the deliberate exception. They come from the pod
rather than from the abstraction, each with its digest.

## 2. Version

Declared in band, in the `metadata` table:

```sql
SELECT key, value FROM metadata WHERE doc_id IS NULL;
--  build.spine_version | 0.25.0
--  schema.name         | sisu-abstraction-db
--  schema.version      | 2.1
```

The rule is the model's, and identical to the `.ssp`: the minor part is
raised when a property is added, the major when one changes meaning or goes
away, and **a reader checks the major part and refuses what it does not
know**. See [`ssp-format-specification.md`](ssp-format-specification.md)
section 2 for the history, which is shared.

## 3. The schema

Eight tables, one virtual table, three views.

```
   documents      id, lang, source_filename, ssp_digest        UNIQUE(lang)
     │ doc_id
     ├─ metadata  doc_id, key, value                     UNIQUE(doc_id, key)
     │
     └─ objects   id, doc_id, section, seq, ocn, ... 50 columns
                                                UNIQUE(doc_id, section, seq)
          ├─ object_images   object_id, seq, name, bytes, sha256,
          │                  width, height, missing
          ├─ object_links    object_id, seq, url
          ├─ object_anchors  object_id, seq, anchor
          └─ object_subtoc   object_id, seq, entry

   files          id, role, name, bytes, sha256, width, height,
                  compression, data                      UNIQUE(role, name)

   objects_fts    fts5 over objects.text, external content over objects.id
```

### 3.1 `doc_id` is the language key

`documents.id`, referred to as `doc_id` everywhere else, is **what tells one
language's rows from another's**. It is the key to reach for in every query.

`objects.lang` and `objects.meta_lang` are **properties of the object** and
are not it. They are almost always empty (section 6).

### 3.2 The file-level metadata rows

`metadata` is keyed `UNIQUE(doc_id, key)` and not on key alone, because
every language has a title and a creator and a key-only key would refuse the
second.

Three rows describe **the file** rather than a document in it, and are
written with `doc_id` null: `schema.name`, `schema.version` and
`build.spine_version`. In SQL no null equals another null, so
`UNIQUE(doc_id, key)` does not constrain them, and a partial unique index
over `key` alone `WHERE doc_id IS NULL` is what makes them singular.

#### 3.2.1 The key prefix carries what the `.ssp` puts in blocks

The `.ssp` has four preamble blocks, `@source`, `@meta`, `@make` and
`@doc_has`. The database has **one** `metadata` table, and tells them apart
by a **prefix on the key**:

| `.ssp` block | database key                                              |
|--------------|-----------------------------------------------------------|
| `@meta`      | the key as it stands: `title.main`, `creator.author`, ... |
| `@make`      | `make.` + the key: `make.footer`, `make.doc_type`         |
| `@doc_has`   | `doc_has.` + the key: `doc_has.images`, `doc_has.tables`  |
| `@source`    | `source.` + the key: `source.language`, `source.digest`   |

,**A reader must strip the prefix and restore the grouping**, or a writer
over it has to ask `metadata["make.footer"]` from a database and
`make["footer"]` from a `.ssp`, which is exactly the difference the two
serialisations exist not to make.

`source.` also carries two keys with no `@source` counterpart,
`source.filename` and `source.ssp_digest`; the `.ssp` puts the first in its
`% Source:` comment and cannot hold the second, which is a digest *of* it.

Values may carry leading or trailing whitespace here where the `.ssp`
cannot represent it, its `key: value` line being unable to distinguish a
value that begins with a space from the separator. **Strip on load**, as a
reader of the text form necessarily does.

### 3.3 Fixed-width arrays are JSON

`children`, `ancestors`, `ancestors_collapsed`, `dom_status`,
`dom_status_collapsed`, `heading_ancestors_text`, `table_widths` and
`table_aligns` are stored as **JSON arrays**, with validity checks, so that
`json_extract`, `json_each` and `json_array_length` reach inside them.

> **Parse them as JSON.** A scan that strips `[`, `]`, `,` and `"` looks
> adequate and is wrong on the first escape: the encoder writes `/` as
> `\/`, so `FREE/OPEN-SOURCE SOFTWARE` comes back as
> `FREE\/OPEN-SOURCE SOFTWARE`. All 36 document-languages of the reference
> collection contain at least one, and the defect is invisible to any check
> that does not compare the field itself.
>
> Note also that `table_widths` is an array of **integers except where the
> columns divide evenly**, when it is `[33.3333,33.3333,33.3333]`. A decoder
> that accepts strings and integers and then falls back to a default turns
> a value it could not read into one that looks read.

The **element types**, so that a decoder can be written to accept exactly
what occurs:

| column                                                                               | elements                                                          |
|--------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `children`, `ancestors`, `ancestors_collapsed`, `dom_status`, `dom_status_collapsed` | integers                                                          |
| `table_widths`                                                                       | integers, or floats where the columns divide evenly               |
| `table_aligns`                                                                       | strings, one of `l` `c` `r`                                       |
| `heading_ancestors_text`                                                             | strings, eight of them, empty where that level is not an ancestor |

The `.ssp` writes the first three groups **space separated** and
`heading_ancestors_text` **`|` separated**. The empty slots of the last are
significant: they say which levels a heading sits under, so the separators
carry as much as the text does.

The open-ended lists are **rows in the four child tables** instead of
columns: images, links, anchor tags and sub-table-of-contents entries. Each
child table carries `seq`, which preserves the order they appeared in.

### 3.4 Indexes

`objects(doc_id, section)`, `objects(ocn)`, `objects(parent_ocn)`,
`objects(is_a)`, `objects(heading_level)` where it is a heading, and
`files(role)`, `object_images(name)`.

## 4. The relationship to the `.ssp`, column by column

,**Nothing is lost in either direction.** Every `.ssp` property is a column
or a child table; every column is a property, a value from the object
declaration line, or a database key.

Where the names differ they differ for a reason, the `.ssp` preferring the
short form and the database the explicit one:

| `.ssp` property    | database              |
|--------------------|-----------------------|
| `.parent`          | `parent_ocn`          |
| `.last_descendant` | `last_descendant_ocn` |
| `.dummy`           | `dummy_heading`       |
| `.ocn_off`         | `object_number_off`   |
| `.part`            | `is_of_part`          |
| `.section`         | `is_of_section`       |

Three are **expanded**, the `.ssp` folding what the database spreads:

| `.ssp` property                                         | database                                                                                                                                     |
|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `.indent: <base> <hang>`                                | `indent_base`, `indent_hang`                                                                                                                 |
| `.ocn_range: <first> <last>`                            | `ocn_range_first`, `ocn_range_last` (2.1: `0` where the object is not a container; a 2.0 database has neither column, and reads as no range) |
| `.has: links notes_reg notes_star images images_no_dim` | `has_links`, `has_notes_reg`, `has_notes_star`, `has_images`, `has_images_no_dim`                                                            |

The four **repeatable** properties become the four child tables:

| `.ssp` property | database         |
|-----------------|------------------|
| `.image`        | `object_images`  |
| `.stow_link`    | `object_links`   |
| `.anchor_tag`   | `object_anchors` |
| `.lev4_subtoc`  | `object_subtoc`  |

And four columns come from outside the property list: `ocn`, `is_a` and
`heading_level` from the object declaration line, and `text` from its `|`
lines. `id`, `doc_id` and `seq` are the database's own keys; `seq` is the
object's position within its section, and `(doc_id, section, seq)` is what
identifies an object when `ocn` will not: `0`, or, before 2.1, a poem
sharing its last verse's number (see [`ocda-model.md`](ocda-model.md)
section 3).

### 4.1 Where the two are not symmetric

"Nothing is lost in either direction" is true of the model, and there are
three places where the *files* nonetheless differ. A reader must know all
three, because each of them made two independently written readers disagree.

,**1. The database states what the `.ssp` derives.** `identifier` and
`anchor` are written on every row. The `.ssp` omits each where it can be
worked out, the identifier being the ocn and the anchor the segment name
(sections 6.1 and 6.3 of
[`ssp-format-specification.md`](ssp-format-specification.md), section 9 of
[`ocda-model.md`](ocda-model.md)). In `free_culture.lawrence_lessig` that is
,**1,314 identifiers and 69 anchors** stated here and absent there. Neither
file is the poorer; a reader that does not derive is.

,**2. `translation.ocn_aligned` is here and cannot be in a `.ssp`.** It says
whether the languages of a document share one numbering, and a `.ssp` is one
language. It is therefore a fact about **the file**, not about the document
in it, and it is the one such fact either serialisation carries.

A reader should **keep it out of the document model**, for the same reason
the `schema.*` and `build.*` rows are kept out: a writer over the model must
not be able to tell which serialisation it was handed, and a field that
exists only when the input was a database is exactly that tell. The model
has no place for collection-wide facts yet; when it grows one, this belongs
there.

,**3. Whitespace and grouping**, as section 3.2.1 gives them.

## 5. The `files` table: what it carries, and how

| role       | named by                   | `compression` | `data` holds     |
|------------|----------------------------|---------------|------------------|
| `image`    | its bare filename          | `none`        | the file as read |
| `source`   | `media/text/<lang>/<file>` | `zstd`        | a zstd frame     |
| `conf`     | `conf/document_make`       | `zstd`        | a zstd frame     |
| `manifest` | `pod.manifest`             | `zstd`        | a zstd frame     |
| `tools`    | `tools/po4a/...`           | `zstd`        | a zstd frame     |

The `compression` column carries the literal `none` or `zstd`, so a reader
need not infer it from the role.

Three rules make the file predictable:

1. **Compression is decided by role, never by size.** The same kind of file
   always stores the same way, so nobody need measure a document to know
   what its database will look like. A very small file can come out a few
   bytes larger inside a zstd frame; that is accepted rather than fixed with
   a threshold, which would make two documents of the same kind store
   differently for no reason a reader could see.
2. **Images are not compressed.** png and jpeg are compressed already; zstd
   gains nothing and costs a decompression on every read.
3. **`objects.text` is never compressed.** The full text index reads that
   column directly, and compressing it would stop search working completely
   rather than subtly.

,**`bytes` and `sha256` are always those of the original file**, whatever
`compression` says. So a digest check, a `digests.txt` line and a rebuilt
`source.digest` all keep working, and a reader that does not decompress can
still say what it is looking at.

## 6. Querying it

`sqlite3` is all that is needed. The recipes below were run against the
published databases.

### 6.1 What is this file

```sql
SELECT key, value FROM metadata WHERE doc_id IS NULL;
SELECT id, lang, source_filename FROM documents ORDER BY id;
SELECT role, count(*), sum(bytes) FROM files GROUP BY role;
```

### 6.2 The views

| view             | gives                                                                                       |
|------------------|---------------------------------------------------------------------------------------------|
| `outline`        | the headings: lang, section, seq, ocn, both levels, `last_descendant_ocn`, identifier, text |
| `citable`        | every object with an ocn, ordered by ocn, language named                                    |
| `document_files` | what the file carries: role, name, bytes, sha256, pixel size                                |

,**`outline` and `citable` name the language and order by it first.** A view
over a file that may hold ten languages and does not say which would read as
one document and be several.

,**A trap in `citable`:** it is `SELECT d.lang AS lang, o.*`, and `objects`
has a `lang` column of its own, so sqlite renames the second one. The view
has **`lang`, the document's language, and `lang:1`, the object's own**.
Quote the second if you want it: `SELECT "lang:1" FROM citable`.

### 6.3 Structure

A heading's subtree is a **range**, not a traversal, because every heading
carries `last_descendant_ocn`:

```sql
SELECT count(*) FROM objects o,
  (SELECT doc_id, ocn, last_descendant_ocn FROM objects
    WHERE is_a='heading' AND ocn=66) h
 WHERE o.doc_id = h.doc_id
   AND o.ocn BETWEEN h.ocn AND h.last_descendant_ocn;
```

And the path back up, on `parent_ocn`:

```sql
WITH RECURSIVE up(ocn, parent_ocn, text) AS (
  SELECT ocn, parent_ocn, text FROM objects WHERE doc_id=1 AND ocn=345
  UNION ALL
  SELECT o.ocn, o.parent_ocn, o.text FROM objects o
    JOIN up ON o.ocn = up.parent_ocn AND o.doc_id=1 AND o.is_a='heading'
   WHERE up.parent_ocn > 0)
SELECT ocn, substr(text,1,44) FROM up;
```

,**Keep the `parent_ocn > 0` guard.** A parent of 0 is a real,
non-substantive parent and not a missing value, and without the guard the
recursion does not terminate.

### 6.4 Full text

```sql
SELECT o.ocn, substr(o.text,1,44) FROM objects_fts f
  JOIN objects o ON o.id = f.rowid
  JOIN documents d ON d.id = o.doc_id
 WHERE f.text MATCH 'commons' AND d.lang='en' AND o.ocn > 0
 ORDER BY rank LIMIT 3;
```

fts5 syntax is available in full: `MATCH 'peer AND production'`,
`MATCH '"peer production"'`, `MATCH 'peer NEAR production'`.

The index is **external content** over `objects.id`: the text is indexed,
not stored twice.

### 6.5 Three things to know before trusting a query

1. **An ocn is not unique within a document**, and `0` is shared by many
   objects. Key on `objects.id`, or on `(doc_id, section, seq)`.
2. **`objects.text` is internal markup**, neither the author's markup nor
   any output. Fine for search and for reading structure, not for display
   without decoding. The markers are in
   [`ssp-format-specification.md`](ssp-format-specification.md) section 3.2.
3. **A multi-language file answers an unfiltered query with every language
   at once.** A single-language document has one `documents` row, so plain
   queries read naturally there; anything else wants `WHERE lang='..'` or a
   join to `documents`.

## 7. Digests, and verifying a file

```
the markup files ──> metadata source.digest   sha256 over every markup file
                                              of that language
the .ssp         ──> documents.ssp_digest     of the .ssp it was built from
each object      ──> objects.sha256           over the object's text
each carried file──> files.sha256             over the original bytes
the spine used   ──> metadata build.spine_version
```

So `.sst -> .ssp -> .ocda.db` is checkable end to end, and
`spine --ocda-verify=<file>` closes the loop by writing the carried markup
back out and re-parsing it: **does this spine still make this abstraction
from the markup this file carries?** It writes nothing and the exit status
is the answer.

,**Only this artefact can answer that from itself alone**, which is the
strongest sense in which it is the one to work with.

The database's own digest is taken once, when the last language has been
written, and appears in `digests.txt`. The metadata page links the database
and claims no hash for it, deliberately: the page is written per language
while the database is added to per language, so a digest taken there would
be of a file that no longer exists by the end of the run.

## 8. Conformance

A reader **must** check `schema.version`'s major part and refuse a major it
does not know; **must** treat `ocn` as not an identity; **must** stop at
`parent_ocn = 0` when walking upward; and **should** say what it did not
understand, for the reason given in
[`ssp-format-specification.md`](ssp-format-specification.md) section 8.2.

A writer **must** keep `bytes` and `sha256` those of the original file
whatever `compression` says, and **must not** compress `objects.text`.
#+END_SRC

* COPYRIGHT & LICENSE
** notices
*** project (project root) ./

#+HEADER: :tangle "../COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC org
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>
#+END_SRC

*** code org ./org

- .org literate programming:
  - copyright asserted
  - omitted
    - license
    - dependency information

#+HEADER: :tangle "../org/COPYRIGHT"
#+HEADER: :noweb yes
#+BEGIN_SRC text
- Name: spine - SiSU Spine, Doc Reform
  <<sisudoc_spine_copyright>>

  <<sisudoc_spine_license_agpl3>>

  <<sisudoc_spine_summary>>

<<sisudoc_spine_markup_samples>>
#+END_SRC

** incorporate
*** copyright

#+NAME: sisudoc_spine_copyright
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_copyright()>>
#+END_SRC

*** agpl3

#+NAME: sisudoc_spine_license_agpl3
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_license_agpl3()>>
#+END_SRC

*** spine_summary

#+NAME: sisudoc_spine_summary
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_summary()>>
#+END_SRC

*** markup_samples

#+NAME: sisudoc_spine_markup_samples
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:sisudoc_spine_markup_samples()>>
#+END_SRC

* org includes
** project version

#+NAME: spine_version
#+HEADER: :noweb yes
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_project_version()>>
#+END_SRC

** year

#+NAME: year
#+HEADER: :noweb yes
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:year()>>
#+END_SRC

** document header including copyright & license

#+NAME: doc_header_including_copyright_and_license
#+HEADER: :noweb yes
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:spine_doc_header_including_copyright_and_license()>>
#+END_SRC

* nixpkgs source

#+NAME: nixpkgs_unstable
#+HEADER: :noweb yes
#+BEGIN_SRC emacs-lisp
<<./sisudoc_spine_version_info_and_doc_header_including_copyright_and_license.org:nixpkgs_unstable()>>
#+END_SRC

* __END__