@entropicwarrior/sdoc 0.2.20 → 0.2.21

package/docs/reference/slide-authoring.sdoc

@@ -107,6 +107,18 @@
             reserved. \`--pptx\` runs the same check for free, because it has
             already measured the deck.
 
+            To override what a format does with the optional slides:
+
+            ```
+            node tools/build-slides.js deck.sdoc --pdf --with-optional
+            node tools/build-slides.js deck.sdoc --no-optional
+            ```
+
+            A slide marked \`optional: true\` is kept in the HTML build and
+            left out of \`--pdf\` and \`--pptx\`. Either default can be
+            overridden in any format: \`--with-optional\` keeps them,
+            \`--no-optional\` drops them. See [Optional Slides](#optional).
+
             To use a custom theme:
 
             ```
@@ -138,6 +150,7 @@
                 \`footnote:\` | Small print pinned under the body: provenance, caveats, sources.
                 \`status:\` | A second line under the kicker on a title slide, for a distribution notice.
                 \`accent:\` | \`primary\`, \`secondary\`, \`tertiary\` or \`neutral\`. An accent names a role; the theme chooses the colour.
+                \`optional:\` | \`true\` holds the slide back from the exports, and from any build passed \`--no-optional\`. See [Optional Slides](#optional).
                 \`numbered:\` | \`columns\` and \`rows\`. \`true\` numbers the children 01, 02, 03.
                 \`variant:\` | \`columns\` and \`rows\`. A named treatment, such as \`panel\` or \`mono\`.
                 \`weights:\` | \`split\` only. The ratio between panes, as in \`48 52\`.
@@ -150,11 +163,11 @@
             }
 
             A key is only configuration where it means something. \`config:\`,
-            \`kicker:\`, \`lede:\`, \`footnote:\`, \`accent:\` and \`status:\` are
-            understood by every scope; the rest are understood only by the
-            layout named against them above. Anywhere else they are ordinary
-            text — a slide opening "Value: the customer keeps their data."
-            renders that sentence, it does not silently swallow it. A
+            \`kicker:\`, \`lede:\`, \`footnote:\`, \`accent:\`, \`status:\` and
+            \`optional:\` are understood by every scope; the rest are understood
+            only by the layout named against them above. Anywhere else they are
+            ordinary text — a slide opening "Value: the customer keeps their
+            data." renders that sentence, it does not silently swallow it. A
             paragraph spanning more than one source line is never
             configuration.
 
@@ -526,6 +539,114 @@
             spine 2, its details in order, and so on. This is the same order
             slides appear in the HTML, so PDF export needs no special case —
             every slide is just one page.
+
+            Every detail is a page, then, including the ones the audience
+            never saw. Mark a detail `optional: true` to keep it out of the
+            exported file — see [Optional Slides](#optional).
+        }
+    }
+
+    # Optional Slides @optional
+    {
+        Some slides exist for the room and not for the file that gets sent
+        on: the answer to a question that may not be asked, the figure
+        behind a figure, the rebuttal you hope to leave unused. Set
+        \`optional: true\` on the slide and it stays in the HTML build, which
+        is what you present from, and leaves the PDF and the PPTX, which are
+        what you send.
+
+        # Syntax @optional-syntax
+        {
+            ```
+            # Unit economics @unit-economics {
+                Headline numbers.
+
+                # Gross margin by cohort @margin :detail {
+                    optional: true
+
+                    The cohort table, if anyone asks for it.
+                }
+            }
+
+            # Pricing objections @objections {
+                optional: true
+
+                Held back unless pricing comes up.
+            }
+            ```
+
+            \`optional:\` is a slide property, not a scope annotation, and that
+            is deliberate: a heading carries one \`:type\`, and a drilldown has
+            already spent it on \`:detail\`. Reading optional-ness off the
+            configuration run keeps the two independent, so all four
+            combinations are available — a required spine, an optional spine,
+            a required detail, an optional detail.
+
+            A slide is the unit. Setting it on a cell inside a structured
+            layout — a column, a pipeline row, a pane of a \`split\` — has no
+            effect: the whole slide travels or none of it does. Mark the slide
+            that holds the cell.
+
+            It is set the way the other boolean properties are: \`true\`,
+            \`yes\`, \`on\` or \`1\` mark the slide; \`false\`, \`no\`, \`off\` or \`0\`
+            leave it alone. Like every slide property it must come before any
+            content.
+
+            A value that is none of those words is not configuration at all.
+            A slide whose first line is "Optional: a second seat costs
+            nothing" renders that sentence — a boolean key discards what it
+            cannot read, so it declines the line rather than swallowing it.
+        }
+
+        # What each format does @optional-formats
+        {
+            {[table]
+                Format | Default | Why
+                HTML | Included | It is the format you present from, and an optional slide is one you may want in the room.
+                PDF | Excluded | It is a format you send on.
+                PPTX | Excluded | The same.
+            }
+
+            The default is a guess about intent, not a property of the format,
+            so either can be overridden anywhere. An HTML deck is also
+            something you send someone:
+
+            ```
+            node tools/build-slides.js deck.sdoc --pdf --with-optional
+            node tools/build-slides.js deck.sdoc --no-optional
+            ```
+
+            When both are given the last one wins, as with \`--fit\`.
+
+            An optional spine takes its details with it. A detail belongs to
+            its spine, and there is nowhere for it to stand once the spine is
+            gone, so it goes whether or not it is marked itself.
+        }
+
+        # Numbering @optional-numbering
+        {
+            Optional slides are dropped before the deck is numbered, not
+            hidden afterwards, so the slide indicator counts what the reader
+            actually holds. A deck of four spines with one of them optional
+            reads \`3 / 3\` on its last page in the exported file and \`4 / 4\`
+            in the HTML build. The pages are consecutive either way; there is
+            no gap where a slide was removed.
+
+            A spine whose only details are optional loses its
+            \`slide-has-details\` class in the export too, so no theme draws a
+            drilldown chevron pointing at nothing.
+        }
+
+        # Themes @optional-theme
+        {
+            An optional slide carries the \`slide-optional\` class wherever it
+            is kept. A theme can use it to mark the slide on screen — a corner
+            tab, a tinted rule — so the presenter can see which slides are off
+            the main path. The built-in theme does not style it, so an optional
+            slide looks like any other until a theme says otherwise.
+
+            Nothing marked optional reaches a build it was excluded from, so
+            the class cannot appear in one.
         }
     }
 
@@ -768,6 +889,10 @@
             rather than an outlined box, so a hairline under a heading is a
             hairline rather than a rectangle with three invisible edges.
 
+            What is not in the file at all: slides marked \`optional: true\`,
+            unless \`--with-optional\` was passed. See
+            [Optional Slides](#optional).
+
             What does not carry: web fonts are named, not embedded, so the
             fonts a theme uses must be available to the viewer. Choosing faces
             that are on Google Fonts is the reliable route, because Slides

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/slide-layouts.js

@@ -32,6 +32,7 @@ const COMMON_KEYS = new Set([
   "footnote",
   "accent",
   "status",
+  "optional",
 ]);
 
 const LAYOUT_KEYS = {
@@ -53,6 +54,17 @@ const CELL_KEYS = {
   bars: ["value", "fill"],
 };
 
+// Keys whose value is a boolean. Every other key renders the text it is given,
+// so consuming the line is visible in the output; a boolean key discards
+// anything it does not recognise, which would make an opening sentence
+// disappear. These therefore only take the line when the value is a word they
+// actually understand — "Optional: a second seat costs nothing" is prose.
+const BOOLEAN_KEYS = new Set(["optional", "numbered", "rule"]);
+const BOOLEAN_WORDS = new Set([
+  "true", "yes", "on", "1",
+  "false", "no", "off", "0",
+]);
+
 // Every key any scope might understand. A leading paragraph opening with one
 // of these is a configuration *candidate*; whether it is kept depends on the
 // context resolved below.
@@ -136,6 +148,13 @@ function extractConfig(children, parentLayout) {
       rejected.push(candidate.node);
       continue;
     }
+    if (
+      BOOLEAN_KEYS.has(candidate.key) &&
+      !BOOLEAN_WORDS.has(candidate.value.trim().toLowerCase())
+    ) {
+      rejected.push(candidate.node);
+      continue;
+    }
     if (candidate.key === "config" || candidate.key === "layout") {
       config.layout = candidate.value.toLowerCase();
     } else {
@@ -505,10 +524,12 @@ function buildBody(layout, cell, ctx) {
 }
 
 module.exports = {
+  BOOLEAN_KEYS,
   CONFIG_KEYS,
   STRUCTURED_LAYOUTS,
   extractConfig,
   buildBody,
   accentClass,
   slug,
+  truthy,
 };

package/src/slide-renderer.js

@@ -8,7 +8,7 @@
 //   const html = renderSlides(nodes, { meta, themeCss, themeJs });
 
 const { parseInline, renderKatex, escapeHtml, escapeAttr, sanitizeSvg, colorSwatchHtml } = require("./sdoc");
-const { extractConfig, buildBody, accentClass, slug } = require("./slide-layouts");
+const { extractConfig, buildBody, accentClass, slug, truthy } = require("./slide-layouts");
 
 // ---------------------------------------------------------------------------
 // Inline rendering — produces clean HTML without sdoc-* classes
@@ -211,6 +211,23 @@ function extractDetails(children) {
   return { details, contentNodes: rest };
 }
 
+// Whether a slide scope carries `optional: true`.
+//
+// Optional-ness is a slide *property*, not a scope type: a heading carries one
+// `:type` annotation and a drilldown has already spent it on `:detail`, so a
+// detail slide could not also be annotated optional. Reading it off the
+// configuration run keeps the two orthogonal — every combination of
+// spine/detail and required/optional is expressible.
+//
+// The details are pulled out first and the config read without a parent
+// layout, exactly as renderSlide() does it, so this answer and the one the
+// slide renders under can never disagree.
+function isOptionalSlide(scope) {
+  const { contentNodes } = extractDetails(scope.children || []);
+  const { config } = extractConfig(contentNodes);
+  return truthy(config.optional);
+}
+
 // ---------------------------------------------------------------------------
 // Slide rendering
 // ---------------------------------------------------------------------------
@@ -246,6 +263,11 @@ function renderSlide(scope, slideIndex, overlayHtml, position) {
   if (position && position.detail > 0) {
     classes.push("slide-detail");
   }
+  // Present in the HTML build, which is the presenting format; dropped before
+  // this point when the deck is rendered for PDF or PPTX export.
+  if (truthy(config.optional)) {
+    classes.push("slide-optional");
+  }
 
   // On a title slide the kicker sits beneath the statement rather than above
   // it, so the eye lands on the name first.
@@ -312,7 +334,8 @@ function renderSlides(nodes, options = {}) {
     themeJs = "",
     darkMode = false,
     themeConfig = {},
-    fit = null
+    fit = null,
+    includeOptional = true
   } = options;
 
   // The design box and print page come from the theme (themes/<name>/theme.json).
@@ -373,14 +396,28 @@ function renderSlides(nodes, options = {}) {
   footerParts.push(`<span class="nav-next">&rsaquo;</span>`);
   const overlayHtml = `\n<div class="slide-footer">${footerParts.join("")}</div>`;
 
+  // Optional slides are for the room, not the file that gets sent on. They are
+  // kept in the HTML build (includeOptional defaults to true, so every existing
+  // caller sees the deck it saw before) and dropped here when a deck is
+  // rendered for export. Dropping them before numbering — rather than hiding
+  // them later in print CSS — is what keeps the indicator honest: the
+  // denominator counts the spine slides the reader actually has.
+  //
+  // An optional spine takes its details with it. A detail belongs to its spine;
+  // there is nowhere for it to go once the spine is gone.
+  const kept = includeOptional ? slides : slides.filter((s) => !isOptionalSlide(s));
+
   // Build a flat emission order: each spine slide, followed immediately by its
   // :detail children in source order. The flat order matches what we want for
   // PDF export, so PDF needs no special case.
-  const totalSpines = slides.length;
+  const totalSpines = kept.length;
   const emitted = [];
-  slides.forEach((scope, i) => {
+  kept.forEach((scope, i) => {
     const spineIndex = i + 1; // 1-based
-    const { details } = extractDetails(scope.children);
+    const { details: allDetails } = extractDetails(scope.children);
+    const details = includeOptional
+      ? allDetails
+      : allDetails.filter((d) => !isOptionalSlide(d));
     emitted.push({
       scope,
       position: {
@@ -573,4 +610,4 @@ ${jsTag}${mermaidTag}
 </html>`;
 }
 
-module.exports = { renderSlides, renderSlide, renderNode, renderInline };
+module.exports = { renderSlides, renderSlide, renderNode, renderInline, isOptionalSlide };