@rse/specbook 1.3.2 → 1.4.1

package/dst/specbook-format.md

@@ -123,7 +123,7 @@ type SchemaDiagram = {
     config?:           Partial<GradiaConfig>
 }
 type SchemaFormat = {
-    type?:             "auto" | "complex" | "concise"
+    type?:             "auto" | "complex" | "compact" | "concise"
     maxTableColumns?:  number
     maxCellHeight?:    number
     withUnusedProps?:  boolean
@@ -323,7 +323,8 @@ type SchemaGradiaConfig = Partial<{
 -   `SchemaDiagram.center?: string | SchemaDiagramCenter`:
     object a `hub` diagram is projected onto (default: `self`), or a
     synthetic center node, labeled from a referenced `source` object (or
-    one of its properties, via `property`) or a literal `label`, typed
+    one of its properties, via `property`, falling back onto the `label`
+    or the object name while absent) or a literal `label`, typed
     (under `qualified`) by `kind`, and linked to the `source` object,
     BECAUSE the focus of a hub is not always a specification object --
     the solution itself, e.g., sits in the middle of a context diagram
@@ -429,8 +430,9 @@ type SchemaGradiaConfig = Partial<{
     HTML/PDF rendering of the objects of an object kind among their siblings,
     BECAUSE one uniform rendering fits neither rich nor numerous objects
 
--   `SchemaFormat.type?: "auto" | "complex" | "concise"`:
-    rendering: `complex` (sections), `concise` (tables), or `auto`,
+-   `SchemaFormat.type?: "auto" | "complex" | "compact" | "concise"`:
+    rendering: `complex` (sections), `concise` (tables), `compact`
+    (tables of section-like cells), or `auto`,
     BECAUSE sections bury small objects, tables truncate rich ones
 
 -   `SchemaFormat.maxTableColumns?: number`:
@@ -571,7 +573,8 @@ Instead of naming an existing object, `center` can also declare a
 *synthetic* center node, which represents something no specification
 object models -- like the solution itself in the middle of a context
 diagram. Such a center is labeled from a referenced `source` object (or
-one of its properties, via `property`) or a literal `label`, and links
+one of its properties, via `property`, falling back onto the `label` or
+the object name while the property is absent) or a literal `label`, and links
 to the `source` object. As the nodes carry no `[[xxx]]` reference to a
 synthetic center, `centerEdges` synthesizes the edges from a direction
 `property` of the node objects: its `inbound` value maps onto a
@@ -649,15 +652,20 @@ how the HTML/PDF export renders the objects of that kind among their
 siblings, so that the sibling kinds below one parent can render
 differently (e.g. one kind as a table, another as sections). Its `type`
 selects the rendering: `complex` (nested sections), `concise` (one
-compact table of all sibling objects of the kind), or the default
-`auto`, which collapses only the deepest level into tables.
+compact table of all sibling objects of the kind), `compact` (one
+table of the name and a single cell per object, which renders the
+object like `complex`, but without its heading: diagram, properties as
+key/value lines, and description, for a kind whose many properties a
+table row cannot hold), or the default `auto`, which collapses only the
+deepest level into tables.
 
 Inside a `concise` table, unconfigured child kinds implicitly stay
 `concise` and render as sub-tables inside the description cells, while
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), `maxCellHeight`
+its properties into embedded per-object tables, while a `compact`
+one ignores it), `maxCellHeight`
 (default: `40`) is the percentage a table cell of the kind may exceed
 the height of every other non-empty cell of its row before the HTML
 export folds its remaining text away, and `withUnusedProps`
@@ -702,6 +710,7 @@ type SpecObject = {
 type SpecDescription = {
     description:       string
     rationale?:        string
+    elaboration?:      string
     embedding?:        string[]
 }
 type SpecProperty = {
@@ -776,7 +785,7 @@ type SpecProperty = {
     BECAUSE a specification is a tree, not a flat list of statements
 
 -   `SpecDescription`:
-    description of an object: statement, rationale, and images,
+    description of an object: statement, rationale, elaboration, and images,
     BECAUSE the WHAT and the WHY are stored apart to be rendered apart
 
 -   `SpecDescription.description: string`:
@@ -785,11 +794,18 @@ type SpecProperty = {
 
 -   `SpecDescription.rationale?: string`:
     rationale text behind the `, BECAUSE ` split (the WHY),
+    up to the end of its paragraph,
     BECAUSE a statement without its WHY cannot be judged or revised
 
+-   `SpecDescription.elaboration?: string`:
+    blocks following the paragraph of the rationale (e.g. images or diagrams),
+    BECAUSE further content must not end up inside the WHY
+
 -   `SpecDescription.embedding?: string[]`:
-    image files embedded via `![xxx](yyy)`, inlined at parse time,
-    one entry per file in markup order (empty for an unreadable file),
+    image, diagram source, and source code files embedded via `![xxx](yyy)`,
+    inlined at parse time, one entry per file in markup order (those of
+    the statement first, those of the elaboration second, and empty for
+    an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
 -   `SpecProperty`:
@@ -805,7 +821,8 @@ type SpecProperty = {
     BECAUSE constraints and references are checked against this text
 
 -   `SpecProperty.embedding?: string[]`:
-    image files embedded in the value, inlined at parse time,
+    image, diagram source, and source code files embedded in the value,
+    inlined at parse time,
     one entry per file in markup order (empty for an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
@@ -992,10 +1009,15 @@ paragraphs, blockquotes, ordered lists (e.g. scenario steps or test
 case procedures), and fenced code blocks. A fenced code block of
 language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
-become authored content on a re-parse. In the Concise Format, the
-description is formed by the non-property segments of the item, so a
-description carrying a `;` cannot be a segment either and forces its
-object into the Complex Format.
+become authored content on a re-parse. A fenced code block of language
+`mermaid` (alias `mmd`) or `d2` is a [Mermaid](https://mermaid.js.org/)
+or [D2](https://d2lang.com/) diagram, which the HTML/PDF export renders
+as a diagram instead of as code (see "Diagram Embeddings" below). A
+fenced code block of any other known language is a syntax-highlighted
+code listing (see "Code Listings" below). In
+the Concise Format, the description is formed by the non-property
+segments of the item, so a description carrying a `;` cannot be a
+segment either and forces its object into the Complex Format.
 
 A description is split into its *statement* and *rationale* at the first
 `, BECAUSE ` (or `, **BECAUSE** `) occurrence:
@@ -1005,10 +1027,25 @@ The event is created and configured but not visible to attendees,
 BECAUSE an event needs a private setup phase.
 ```
 
+The rationale ends with its paragraph: all blocks following it (further
+paragraphs, embedded images, and diagrams) form the *elaboration*, which
+is rendered below the statement and its rationale, so the description
+of a Complex Format object can state its WHAT and WHY first and
+illustrate them afterwards:
+
+````
+The event is created and configured but not visible to attendees,
+BECAUSE an event needs a private setup phase.
+
+![Event Lifecycle](event-lifecycle.mmd)
+````
+
 ### Wiki-Style References
 
 A `[[<reference/>]]` anywhere in a name, property value, description, or
-rationale is a Wiki-style reference to another object, which is checked
+rationale (except inside a fenced code block, whose code stays verbatim,
+so e.g. a shell test `[[ -f x ]]` is no reference) is a Wiki-style
+reference to another object, which is checked
 for unique resolvability and rendered as a hyperlink in the HTML/PDF
 exports. A reference is a `.`-separated path of segments, where each
 segment matches a single object as:
@@ -1046,7 +1083,21 @@ SVG files are inlined as-is; PNG/JPEG/WebP files are embedded as base64
 `data:` URLs. URLs and other file types are left untouched. The
 HTML/PDF export optimizes the embedded images on its own (downscaled
 and re-encoded PNG/JPEG/WebP, minified SVG), so the files can stay in their
-original resolution.
+original resolution. Like a diagram, an embedded image (except the logo
+of the title page) folds, maximizes, and is omitted (`-O diagram:image`,
+or by nesting level) in the HTML/PDF export, while the AST exports keep
+it.
+
+A page of a PDF document is embedded like an image --
+`![<alt/>](<file/>.pdf)` for the first page, or
+`![<alt/>](<file/>.pdf#page=<n/>)` for the 1-based page number `<n/>` --
+where the document is inlined at parse time. The exports convert the
+page through `pdfjs-dist` into a vector SVG with its texts as glyph
+outlines and then treat it exactly like an embedded SVG image, while a
+page failing to render (e.g. an absent page number) is omitted with a
+notice. A presentation (e.g. PowerPoint), a spreadsheet (e.g. Excel), or
+any other office document is embedded through its PDF export, which
+carries its exact rendering and fonts.
 
 A reference carrying the `{theme}` placeholder -- e.g.
 `![Logo](logo-{theme}.svg)` -- is a *theme-aware* embedding: it expands
@@ -1056,10 +1107,113 @@ HTML export shows just the variant matching the color theme currently
 active in the document, while the PDF export (like print in general)
 always uses the `light` variant.
 
+An image without a dark variant is treated on the dark theme of the HTML
+export as its `dark` fragment parameter says (see "Fragment Parameters"
+below), while print always keeps it as it is. An image defaults to
+`dark=auto`, which inverts it (with its hues rotated back) if it most
+likely draws dark lines onto a transparent or light canvas: an SVG if it
+neither adapts itself (via `light-dark()` colors, `prefers-color-scheme`
+rules, or a `color-scheme` declaration, which follows the color theme of
+the document anyway), nor embeds a raster image, nor paints a background
+which is not light, and a raster image (PNG/JPEG/WebP) if at least 60%
+of its pixels are transparent or near-white and the others are dark on
+average and of a few colors only (unlike a photo or a colorful
+screenshot). As the detection cannot tell a logo or illustration with
+brand colors from a line drawing, `#dark=none` keeps such an image as it
+is, while `#dark=invert` forces the inversion (e.g.
+`![Overview](overview.svg#dark=invert)`). A
+[draw.io](https://www.drawio.com/) diagram is best embedded as its
+editable SVG (`.drawio.svg`, which draw.io keeps current on every save)
+with its "Adaptive Colors" page setting on "Automatic", as it then
+adapts all its colors itself. A theme-aware embedding ignores the
+fragment, as its `dark` variant already serves the dark theme.
+
 The reference-style image `![<alt/>][<label/>]` embeds the image of its
 definition `[<label/>]: data:image/<type/>;base64,<data/>` (SVG, PNG,
-JPEG, or WebP) in the same file, the only supported link definition.
+JPEG, or WebP, where a `;dark=invert` or `;dark=none` parameter behind
+the type carries the treatment on the dark theme, which the export
+always resolves for an SVG) in the same file, the only supported link
+definition.
 This is the form the normalized Markdown export emits for every embedded
 image (a theme-aware one by its `light` variant), with the definitions
 at the end of the document, so it stands alone without the image files.
 Author the inline form; the reference-style one is for re-parsing only.
+
+### Diagram Embeddings
+
+A [Mermaid](https://mermaid.js.org/) or [D2](https://d2lang.com/)
+diagram is either written inline into a description as a fenced code
+block of language `mermaid` (alias `mmd`) or `d2`, or kept in a file of
+its own and embedded like an image -- `![<alt/>](<file/>.mmd)`,
+`![<alt/>](<file/>.mermaid)`, or `![<alt/>](<file/>.d2)` -- inside a
+description or property value, where its source is inlined at parse time.
+The HTML/PDF export renders every such diagram (Mermaid through
+`beautiful-mermaid`, D2 through `@terrastruct/d2`) in the theme colors of
+the document, once per color theme, like a theme-aware image. It folds,
+maximizes, and is omitted (`-O diagram:code`, for diagrams as code, or
+by nesting level) like a derived Gradia diagram. A diagram failing to render
+is omitted with a notice. The normalized Markdown and the AST exports
+carry the source of a fenced diagram as part of the description, and an
+embedded diagram file as its rendered SVG (the `light` variant).
+
+### Code Listings
+
+A code snippet is either written inline into a description as a fenced
+code block of a known language (any language id or alias of
+[Shiki](https://shiki.style/), like `ts`, `java`, `css`, or `html`), or
+kept in a source code file of its own and embedded like an image --
+`![<alt/>](<file/>.<ext/>)`, where `<ext/>` is such a language id or
+alias (e.g. `.ts`, `.java`, `.css`, `.html`) -- inside a description or
+property value, where its source is inlined at parse time. A fenced code
+block of no or an unknown language stays plain preformatted text.
+
+The HTML/PDF export renders every such snippet as a *code listing* in
+DejaVu Sans Mono, with line numbers and with its keywords, operators,
+and punctuation in the accent color and bold, its literals in the signal
+color, and its comments in the dim color and italic. A code listing
+folds, maximizes, and is omitted (`-O diagram:listing`, or by nesting
+level) like a diagram.
+
+A fenced code listing takes whitespace-separated parameters behind its
+language, and an embedded one takes them as its fragment (see "Fragment
+Parameters" below):
+
+-   `start=<n/>` (fenced only): the number of the first line (default `1`).
+-   `lines=<a/>-<b/>` or `lines=<a/>` (embedded only): the excerpt of the
+    1-based lines `<a/>` to `<b/>` (or line `<a/>` alone), numbered from
+    `<a/>`, where an empty range is reported as an error.
+-   `mark=<a/>[-<b/>][,...]`: the lines or line ranges to mark (in the
+    shown line numbers) on a very light signal background.
+
+````
+```ts start=10 mark=12-13
+const greeter = new Greeter("World")
+```
+
+![Greeter Class](greeter.ts#lines=5-20&mark=8,12-14)
+````
+
+The AST exports carry an embedded source code file as its
+`data:text/x-code;lang=<lang/>;start=<n/>[;mark=<hunks/>];base64,<data/>`
+URL, while the normalized Markdown export turns one of a description into
+a fenced code block (with its `start` and `mark` parameters) at the end
+of the elaboration, and keeps one of a property value as a
+reference-style image definition of that URL.
+
+#### Fragment Parameters
+
+The fragment of an embedding reference is a list of `<key/>=<value/>`
+parameters joined by `&`, in any order and each at most once, with the
+values optionally URI-encoded (e.g. `%20` for a space): `page`
+(documents), `dark` (documents and images), and `lines` and `mark`
+(source code files, see "Code Listings" above). A fragment carrying any
+other key or an invalid value is reported as an error. The `dark`
+parameter selects the treatment on the dark theme of the HTML export,
+while print always shows the original: `dark=invert` inverts the
+embedding with its hues rotated back, `dark=none` shows it as it is, and
+`dark=auto` (the default) decides by the content of the image or the
+rendered document page (inverting a light canvas with dark ink, but
+neither a dark one nor one carrying a photo), as an image and a document
+page can be anything (line drawings, photos, logos); e.g.
+`![<alt/>](<file/>.pdf#page=3&dark=none)` keeps a page which the
+detection would invert, but whose colors have to stay.