diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-08-26 20:07:13 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-08-26 20:07:13 -0400 |
| commit | 76c67a798d76186df081be59cefa0292f1cea569 (patch) | |
| tree | d3e75d7d05f2dc9af103a16851cea40be4c570e8 | |
| parent | docs: 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.md | 99 |
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 |
