summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-08-26 20:07:13 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-08-26 20:07:13 -0400
commit76c67a798d76186df081be59cefa0292f1cea569 (patch)
treed3e75d7d05f2dc9af103a16851cea40be4c570e8
parentdocs: add README under git.sisudoc.org/tools/ namespace (diff)
spec: image records, .image property
Documents the per-object image record that spine now emits, one repeatable .image line per image, filename first then self-describing key:value fields: .image: won_benkler_2_1.png sha256:5BA4...D128 bytes:93861 px:420x342 .image: ffa.png missing:true Covers the four fields (sha256, bytes, px, missing), the reader requirements (repeatable, order-independent fields, ignore what is not recognised, do not assume a field count), the distinction between px (the file's own pixel size) and the w##h## display dimensions carried in the object text, and the PEG rules for the record. Notes why the pod digests.txt keeps its own flat form. (assisted by Claude-Code)
-rw-r--r--format-specification.md99
1 files changed, 97 insertions, 2 deletions
diff --git a/format-specification.md b/format-specification.md
index 2814e33..837f0e6 100644
--- a/format-specification.md
+++ b/format-specification.md
@@ -284,9 +284,92 @@ with empty strings between consecutive `|` markers.
**Digest** (from `metainfo`):
```
-.sha256: 7a3b9f... % hex-encoded
+.sha256: 7A3B9F... % hex-encoded (uppercase), of object text
```
+The digest covers the object's `text` field only (including inline notes),
+not any file the text references.
+
+**Images** (from `metainfo.sha256.images`):
+
+An object that embeds one or more images carries one `.image` line per
+image, in order of appearance within the object text:
+
+```
+.image: won_benkler_2_1.png sha256:5BA492C2C040C179FF8E46FC800B5B3AE6F7F082D9532F877141F44A366DD128 bytes:93861 px:420x342
+```
+
+The value is a record: the image filename first (the object's handle on
+the image, as it appears after the `☼` marker in the text and as the file
+is named in the pod's `media/image/` directory), followed by
+whitespace-separated `key:value` fields:
+
+| Field | Meaning |
+|---|---|
+| `sha256:` | SHA256 digest of the image file, hex-encoded, uppercase |
+| `bytes:` | image file size in bytes |
+| `px:` | the file's own pixel dimensions, `<width>x<height>` |
+| `missing:` | `true` when the referenced file was absent or unreadable |
+
+`px:` is the image as stored, read from the file header. It is *not* the
+same thing as the `w##h##` dimensions carried in the object's text
+(`☼won_benkler_2_1.png,w420h342`), which are display dimensions: author
+set in the markup, or where the markup gave `w0h0` derived from the file
+and capped to a maximum display width. The two commonly differ, e.g.
+
+```
+% display 640x323, file 831x420 (capped)
+.image: di_evh_f10-1.png sha256:... bytes:... px:831x420
+% display 82x128, file 328x512 (author set)
+.image: sm_d_image.jpg sha256:... bytes:... px:328x512
+```
+
+Display dimensions are therefore not duplicated in the record: they are
+already present, verbatim, in the object's text lines, and they describe
+the rendering rather than the file. `px:` records what the text cannot,
+and completes the file's identity alongside `sha256:` and `bytes:`.
+It is omitted when the dimensions could not be read.
+
+An image the abstraction referenced but could not read is recorded as
+such, rather than being omitted:
+
+```
+.image: ffa.png missing:true
+```
+
+`missing:true` and `sha256:`/`bytes:` are mutually exclusive: no digest
+or size could be taken, so neither field is written. The record still
+tells a reader that the object embeds an image and names it, and tells a
+verifier that this `.ssp` was produced from an incomplete pod.
+
+Rules:
+
+- The property is **repeatable**. An object with two images emits two
+ `.image` lines; readers accumulate them into a list. Objects without
+ images emit none.
+- The filename is a single token (image names match
+ `[a-zA-Z0-9._-]+\.(jpg|gif|png)`, so it cannot contain whitespace, `:`
+ or `\n`) and is always the first field.
+- Fields after the filename are **order-independent and extensible**.
+ A reader MUST ignore a `key:value` field it does not recognise, and
+ MUST NOT assume a fixed field count. This reserves room for later
+ additions (e.g. `mime:image/png`) without a format break.
+- Values are the file's own properties, so two objects embedding the same
+ image emit identical `sha256:`/`bytes:`/`px:` values. Display
+ dimensions, which can differ between two such objects, are a property
+ of the reference and stay in the object's text.
+
+Rationale: this is verification data (is the image shipped in this pod the
+image the abstraction was built from?), so the digest of the referenced
+file belongs with the object that references it, and remains valid when
+the `.ssp` file travels alone. Packing filename, size and digest into the
+property *name* (as `.imageSha256_filesize_filename:`) would put the
+schema in the key, forcing a new property name on every added field; a
+positional `::`-separated value would fix the arity for the same reason.
+The pod-level `digests.txt` manifest keeps its own flat
+`HEX::bytes - filename` convention: that file is a verification report,
+not a grammar-bound serialisation.
+
**Extracted links** (from `stow`):
```
@@ -311,6 +394,7 @@ Properties with default values are omitted to reduce verbosity:
| .ocn_off | false | false |
| .code_syntax | "" | empty |
| .code_linenumbers | false | false |
+| .image | (none) | object embeds no image (repeatable, so no default) |
### What is NOT serialized
@@ -347,10 +431,21 @@ SiSUAbstraction:
/ 'blurb'
ObjExtra <- sp ~(!nl .)+
- Property <- '.' ~PropName ':' sp ~PropValue nl
+ Property <- ImageProperty / GenericProperty
+ GenericProperty
+ <- '.' ~PropName ':' sp ~PropValue nl
PropName <- Identifier
PropValue <- (!nl .)+
+ ImageProperty
+ <- '.image' ':' sp ~ImageFile ImageField* nl
+ ImageFile <- [a-zA-Z0-9._-]+ '.' ('jpg' / 'gif' / 'png')
+ ImageField <- sp ~ImageFieldName ':' ~ImageFieldValue
+ ImageFieldName
+ <- Identifier
+ ImageFieldValue
+ <- (![ \t\n] .)+
+
TextLine <- '|' sp? ~(!nl .)* nl
Comment <- '%' (!nl .)* nl