postext 1.4.2 → 1.5.1

package/dist/bundle/configVersion.d.ts

@@ -0,0 +1,295 @@
+import type { PostextConfig } from '../types';
+/**
+ * The configuration rules this engine writes: 8 since postext 1.5. Thirteen
+ * rules changed in that release, and a configuration stored under an older
+ * number (or none) is read through {@link migrateConfig}:
+ * - 3: a heading level's `breakBefore` (and a heading style's) merges field
+ *   by field onto the level's default — H1's being `always-odd`
+ *   ({@link pinLegacyHeadingBreaks});
+ * - 4: one em of a formula is the surrounding text's size ×
+ *   `math.fontSizeScale`, where up to 1.4 formulas came out
+ *   {@link LEGACY_MATH_SIZE}× larger ({@link pinLegacyMathSize});
+ * - 5: an inline resource keeps the float gap below it as well as above
+ *   (`layout.inlineResourceGap: 'around'`), where up to 1.4 the text after
+ *   it resumed at the next grid line ({@link pinLegacyInlineGap});
+ * - 6, five rules:
+ *   - a heading reads its inline marks (`headings.inlineMarks: true`),
+ *     where up to 1.4 it printed them as plain text ({@link
+ *     pinLegacyHeadingMarks});
+ *   - a design text's drop cap that names no size is set at the size that
+ *     brings its top level with the first line's capitals, where up to 1.4
+ *     it was as tall as all the line boxes it spans ({@link
+ *     pinLegacyDropCapSize});
+ *   - `bodyText.keepColonWithList` leaves room under the colon line for
+ *     the list's first item to start by its orphan and widow rules
+ *     (`bodyText.colonListRoom: 'item'`), where up to 1.4 one line was
+ *     enough ({@link pinLegacyColonListRoom});
+ *   - an inline resource inside a box keeps the float gap too
+ *     (`layout.inlineResourceGapInBoxes`), where up to 1.4 it sat right
+ *     against the text around it ({@link pinLegacyBoxResourceGap});
+ *   - a box that splits inside a paragraph or list item leaves at least two
+ *     lines of it on each side (`layout.boxChildSplitMinLines: 2`), where
+ *     up to 1.4 a cut could leave one ({@link pinLegacyBoxChildCut});
+ * - 7, two rules:
+ *   - a line may end after an em or en dash set closed between words
+ *     (`bodyText.breakAfterDashes`), where up to 1.4 Knuth–Plass never
+ *     broke there ({@link pinLegacyDashBreaks});
+ *   - ragged running text is broken with Knuth–Plass too
+ *     (`bodyText.optimalRagged`), where up to 1.4 it was set line by line
+ *     ({@link pinLegacyRaggedBreaking});
+ * - 8, three rules:
+ *   - a paragraph kept with the heading above it at a column's foot
+ *     splits by the orphan rule too (`headings.keepWithNextSplit:
+ *     'rules'`), where up to 1.4 it kept as many lines as fit under the
+ *     heading ({@link pinLegacyHeadingSplit});
+ *   - the space under a `:::paragraphs` container merges with the next
+ *     block's own and is at least the paragraph spacing of the text around
+ *     it (`bodyText.paragraphContainerSpacing: 'collapse'`), where up to
+ *     1.4 the style's space was baked into the grid snap and the next
+ *     block's space above added under it ({@link
+ *     pinLegacyParagraphContainerSpacing});
+ *   - Knuth–Plass may end a line after the hyphen of a compound in every
+ *     paragraph (`bodyText.breakAfterHyphens`), where up to 1.4 a justified
+ *     paragraph with no inline formatting never broke there ({@link
+ *     pinLegacyHyphenBreaks}).
+ *
+ * A configuration stored without a version was written for postext 1.4 or
+ * earlier. One stored under 3 to 7 was written by a 1.5 prerelease, and
+ * gets the pins of the rules after its number: under 3 the maths,
+ * inline-gap, version-6, version-7 and version-8 pins, under 4 the
+ * inline-gap, version-6, version-7 and version-8 pins, under 5 the
+ * version-6, version-7 and version-8 pins, under 6 the version-7 and
+ * version-8 pins, under 7 the version-8 pins.
+ */
+export declare const CONFIG_VERSION = 8;
+/**
+ * How much larger postext 1.4 set maths than the size it documents:
+ * MathJax gives a formula's box in `ex`, one `ex` of its TeX font is
+ * 0.442 em (the font's `x_height`), and 1.4 took it as half an em. So
+ * 0.5 ÷ 0.442 ≈ 1.1312; a configuration whose `math.fontSizeScale` is
+ * multiplied by it sets every formula at the size 1.4 did.
+ */
+export declare const LEGACY_MATH_SIZE: number;
+/**
+ * A configuration written for postext 1.4 or earlier, pinned to the heading
+ * breaks it laid out then. Up to 1.4 a `headings` object turned the H1 page
+ * break off unless it set `levels[0].breakBefore.enabled` (and stripping the
+ * defaults dropped an H1 `enabled: false`, so saved and exported
+ * configurations never carried one), a partial H1 break took its missing
+ * field from the no-break default, and a heading style's `breakBefore`
+ * replaced its level's with the same fill. The engine now merges each onto
+ * the level's break — H1's being `always-odd` — so those breaks are written
+ * out: `enabled: false` on H1, or `parity: 'any'` beside an `enabled: true`.
+ * A configuration with no `headings` object, or one that spells every break
+ * out in full, is returned as it is (the same object).
+ */
+export declare function pinLegacyHeadingBreaks<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the maths size it
+ * laid out then: `math.fontSizeScale` (1 when unset) × {@link
+ * LEGACY_MATH_SIZE}. A display formula's margins in `em` or `rem` are
+ * lengths of the formula's own size, so they are divided by the same
+ * factor and keep the space 1.4 left around the formula. A value that
+ * lands on its default is left out (a scale of 0.884 becomes the default
+ * 1), and a configuration with maths switched off (`math.enabled: false`,
+ * whose formulas are set as their TeX source at the body size) is
+ * returned as it is (the same object).
+ */
+export declare function pinLegacyMathSize<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the space it left
+ * under an inline resource: `layout.inlineResourceGap: 'above'`, where 1.4
+ * kept the float gap above the resource only and set the text after it at
+ * the next grid line. A configuration that names a gap already is returned
+ * as it is (the same object).
+ */
+export declare function pinLegacyInlineGap<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the room it left
+ * for a list under the colon line that introduces it:
+ * `bodyText.colonListRoom: 'line'`, where 1.4 took one line of room as
+ * enough and a first item the orphan and widow rules keep whole went on
+ * to the next column without the colon line. A configuration that names a
+ * room already, or turns `keepColonWithList` off, is returned as it is
+ * (the same object).
+ */
+export declare function pinLegacyColonListRoom<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the space it left
+ * around an inline resource inside a box: `layout.inlineResourceGapInBoxes:
+ * false`, where 1.4 set the resource right under the text before it and
+ * the text after it right under the resource. A configuration that already
+ * says whether boxes keep the gap is returned as it is (the same object).
+ */
+export declare function pinLegacyBoxResourceGap<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the cuts it made in
+ * a box that splits: `layout.boxChildSplitMinLines: 1`, where 1.4 cut
+ * inside a paragraph or list item wherever each side of the box held its
+ * `splitMinLines` lines in all, even when that left one line of the
+ * paragraph or item on a side. A configuration that names the setting
+ * already is returned as it is (the same object).
+ */
+export declare function pinLegacyBoxChildCut<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the line breaks it
+ * made at a dash: `bodyText.breakAfterDashes: false`, where 1.4's
+ * Knuth–Plass never ended a line after an em or en dash set closed between
+ * words ("say—that’s"), and its line-by-line breaker for formatted text
+ * only between two letters. A configuration that names the setting already
+ * is returned as it is (the same object).
+ */
+export declare function pinLegacyDashBreaks<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the way it broke
+ * ragged text: `bodyText.optimalRagged: false`, where 1.4 set every ragged
+ * paragraph line by line, filling each line before the next, whatever
+ * `optimalLineBreaking` said. A configuration that names the setting
+ * already, that sets no running text ragged (the body, a paragraph style,
+ * a box body, the body of a part or of a section style, in the
+ * configuration or in its HTML viewer's overrides), or that turns
+ * `optimalLineBreaking` off (the setting then changes nothing) is returned
+ * as it is (the same object).
+ */
+export declare function pinLegacyRaggedBreaking<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the way it split a
+ * paragraph kept with the heading above it at a column's foot:
+ * `headings.keepWithNextSplit: 'fill'`, where 1.4 kept as many lines as fit
+ * under the heading (at least `bodyText.widowMinLines`) however few went on
+ * to the next column. A configuration that names the setting already, that
+ * turns `headings.keepWithNext` off, or that turns `bodyText.avoidOrphans`
+ * off (the setting then changes nothing) is returned as it is (the same
+ * object).
+ */
+export declare function pinLegacyHeadingSplit<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the space it left
+ * under a `:::paragraphs` container: `bodyText.paragraphContainerSpacing:
+ * 'add'`, where 1.4 set the style's space (the larger of `spaceBetween` and
+ * `marginBottom`) under the last paragraph before the grid snap, added the
+ * next block's own space above (a heading's `marginTop`, the next
+ * container's) under it, and left the paragraph spacing of the text around
+ * the container out. A configuration that names the setting already, or
+ * declares no paragraph style (in the configuration or in its HTML
+ * viewer's overrides; a container naming no style is set as body text), is
+ * returned as it is (the same object).
+ */
+export declare function pinLegacyParagraphContainerSpacing<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the line breaks it
+ * made at the hyphen of a compound: `bodyText.breakAfterHyphens: false`,
+ * where 1.4's Knuth–Plass ended a justified line after a hyphen between two
+ * letters ("well-" | "known") only in a paragraph with inline formatting.
+ * A configuration that names the setting already, or turns
+ * `optimalLineBreaking` off (the setting then changes nothing), is returned
+ * as it is (the same object).
+ */
+export declare function pinLegacyHyphenBreaks<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the headings it
+ * laid out then: `headings.inlineMarks: false`, where 1.4 printed the text
+ * of a heading's `*italic*`, `**bold**` and other marks in the heading's
+ * plain style. A configuration that names the setting already is returned
+ * as it is (the same object).
+ */
+export declare function pinLegacyHeadingMarks<T extends Partial<PostextConfig>>(config: T): T;
+/**
+ * A configuration written before postext 1.5, pinned to the drop caps it
+ * laid out then. Up to 1.4 a design text's `dropCap` that named no
+ * `fontSize` was as tall as the line boxes it spans over 0.72 (the share of
+ * the size its capitals take), so its top stood above the capitals of the
+ * first line; today's default brings the two level. Every such drop cap,
+ * in whatever design it sits (running heads, heading designs and styles,
+ * part pages, the contents' part rows), gets that size written out: in the
+ * unit of the element's leading when that is a length, else in the unit of
+ * its font size, at the size 1.4 set at the document's `page.dpi` (to the
+ * last digit in most cases, and never more than a rounding step or two
+ * away). A configuration with none is returned as it is (the same object).
+ */
+export declare function pinLegacyDropCapSize<T extends Partial<PostextConfig>>(config: T): T;
+export interface MigrateConfigOptions {
+    /**
+     * The markdown the configuration lays out (a bundle's chapters, a book's),
+     * when the caller has it. Maths is written between `$` signs, so text with
+     * none sets no formula and its configuration is not given a maths size
+     * (see {@link pinLegacyMathSize}); an inline resource is embedded with a
+     * `::resource{id="…"}` line, so text with none (a mention in running text
+     * or in a code span does not count) is not given the inline gap either
+     * (see {@link pinLegacyInlineGap}), nor the box gap when no such line
+     * stands inside a `:::callout` (see {@link pinLegacyBoxResourceGap}); a
+     * list introduced by a line ending in a colon is what the colon-list room
+     * is for, so text with none is not given it (see {@link
+     * pinLegacyColonListRoom}); text with no heading whose title carries an
+     * inline mark (`*`, `_`, `^`, `~`, `:smallcaps[`, a link) is not given
+     * `headings.inlineMarks: false` (see {@link pinLegacyHeadingMarks});
+     * text with no `:::callout` is not given the box cut (see {@link
+     * pinLegacyBoxChildCut}); text with no em or en dash set closed between
+     * words is not given the 1.4 dash breaks (see {@link
+     * pinLegacyDashBreaks}); text with no heading is not given the 1.4 split
+     * under a heading (see {@link pinLegacyHeadingSplit}); text with no
+     * `:::paragraphs` container is not given the 1.4 space under containers
+     * (see {@link pinLegacyParagraphContainerSpacing}); and text with no
+     * hyphen between two letters is not given the 1.4 compound breaks (see
+     * {@link pinLegacyHyphenBreaks}). That keeps a stored configuration as
+     * short as it was. Without it the size is pinned whenever maths is on,
+     * and the gaps, the room, the heading marks, the box cut, the dash
+     * breaks, the split under a heading and the compound breaks always, and
+     * the container space always when the configuration declares a paragraph
+     * style.
+     * Any iterable of texts will do, a generator or a Map's `values()`
+     * included: it is read once.
+     */
+    content?: string | Iterable<string>;
+}
+/**
+ * A configuration stored under `configVersion` (see {@link CONFIG_VERSION}),
+ * in today's terms. One with no version (a number is expected; anything
+ * else counts as none) or one older than 3 has its heading breaks pinned by
+ * {@link pinLegacyHeadingBreaks}; one older than 4 has its maths size
+ * pinned by {@link pinLegacyMathSize}, unless `options.content` shows it
+ * sets no maths; one older than 5 has its inline gap pinned by {@link
+ * pinLegacyInlineGap}, unless `options.content` shows it embeds no
+ * resource; one older than 6 has its heading marks pinned by {@link
+ * pinLegacyHeadingMarks}, unless `options.content` shows no heading
+ * carries one, its drop caps by {@link pinLegacyDropCapSize}, its
+ * colon-list room by {@link pinLegacyColonListRoom}, unless
+ * `options.content` shows no list introduced by a colon, and its box gap
+ * by {@link pinLegacyBoxResourceGap}, unless `options.content` shows it
+ * embeds no resource inside a box, and its box cut by {@link
+ * pinLegacyBoxChildCut}, unless `options.content` shows it holds no box;
+ * one older than 7 has its dash breaks pinned by {@link
+ * pinLegacyDashBreaks}, unless `options.content` shows no closed dash, and
+ * its ragged breaking by {@link pinLegacyRaggedBreaking}, when it sets some
+ * running text ragged; one older than 8 has its split under a heading
+ * pinned by {@link pinLegacyHeadingSplit}, unless `options.content` shows
+ * no heading, the space under its `:::paragraphs` containers by {@link
+ * pinLegacyParagraphContainerSpacing}, when it declares a paragraph style,
+ * unless `options.content` shows no such container, and its compound
+ * breaks by {@link pinLegacyHyphenBreaks}, unless `options.content` shows
+ * no compound. A current one is returned as it is (the same object).
+ * Migrate a stored configuration once and store it again under
+ * `CONFIG_VERSION`: the maths pin multiplies a scale, so a configuration
+ * read twice under its old number would grow twice.
+ */
+export declare function migrateConfig<T extends Partial<PostextConfig>>(config: T, configVersion: unknown, options?: MigrateConfigOptions): T;
+/**
+ * A bundle's configuration in today's terms: `base` (the reader's own)
+ * under the manifest's `config` and the locale's overrides, both stored
+ * under `configVersion`. Top-level keys replace one another wholesale, so
+ * the heading breaks are pinned layer by layer (the base's are taken as
+ * they are) and the maths size once, on the `math` the layers leave in
+ * force — the size 1.4 set this bundle's formulas at, whichever layer
+ * named it, the base included when neither the manifest nor the locale
+ * names one. The inline gap, the box gap and the box cut are pinned the
+ * same way, on the `layout` in force, the colon-list room, the dash
+ * breaks, the compound breaks, the ragged breaking and the space under
+ * `:::paragraphs` containers on the `bodyText` in force (the ragged
+ * breaking when the merged configuration sets some running text ragged,
+ * the container space when it declares a paragraph style), the heading
+ * marks and the split under a heading on the `headings` in force, and the
+ * drop caps wherever they sit in the merged configuration.
+ * @internal `readBundle`'s; hosts call {@link migrateConfig}.
+ */
+export declare function migrateBundleConfig(base: PostextConfig, layers: readonly PostextConfig[], configVersion: unknown, options?: MigrateConfigOptions): PostextConfig;
+//# sourceMappingURL=configVersion.d.ts.map

package/dist/bundle/configVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configVersion.d.ts","sourceRoot":"","sources":["../../src/bundle/configVersion.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgH,aAAa,EAAE,MAAM,UAAU,CAAC;AAQ5J;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAqChC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,QAAc,CAAC;AAqB5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CA0BrF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAkBhF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIrF;AAOD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAItF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAInF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAKtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAKpF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kCAAkC,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAKjG;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIpF;AA4DD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIpF;AA8ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAKnF;AAoHD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,aAAa,CAAC,EAC5D,MAAM,EAAE,CAAC,EACT,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,oBAAyB,GACjC,CAAC,CAiBH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAoBf"}