@dogsbay/format-dita 0.2.0-beta.123 → 0.2.0-beta.125

package/README.md

@@ -27,7 +27,7 @@ dogsbay import-dita   docs/            -o content    --report topics.md
 ```
 
 Tasks become native `:::steps`, notes become callouts, CALS and
-simpletables become tables, `<xref href="x.dita">` becomes `[…](x.md)`,
+simpletables (and a reference topic's `<properties>`) become tables, `<xref href="x.dita">` becomes `[…](x.md)`,
 and `keyref` links become `key:` links. Nested or sibling topics in
 multi-topic files are emitted inline as anchored sections.
 
@@ -38,6 +38,23 @@ emit `{% include %}` so one canonical copy of reused text survives. Use
 `dogsbay import-dita --no-conref-includes` to keep conrefs on the ledger
 instead.
 
+**Lines.** Every conversion note carries `line`, the source line of the
+element that raised it (or of the block being converted), so a host can point
+at it. `{ sourceLines: true }` also puts each block's line on `meta.line`, which
+`@dogsbay/render-html` writes as `data-line` when asked (`dataLines: true`).
+
+**Specializations in raw source:** a file as authored has no `@class`, so
+an element is known only by its name, and a specialization the converter
+does not know by name (a `<troubleshooting>` topic, a hazard statement's
+items) loses its markup. `{ classDefaults: true }` fills in each missing
+`@class` from the DITA 1.3 DTD defaults first (612 elements, the table
+`DITA_CLASS_DEFAULTS`, generated by `scripts/generate-class-defaults.mjs`
+from DITA-OT's `.mod` files), as parsing against the DTDs would; the
+element then converts as what it specializes. An existing `@class` is kept;
+a name the DTDs do not declare (custom or DITA 2.0) stays unclassed, with
+one note per topic. It is off by default for now because it changes the
+output for such elements.
+
 Everything that cannot map cleanly lands in the conversion ledger instead
 of disappearing: filter attributes, table spans, semantic-inline downgrades,
 `conkeyref`, conref ranges/pushes, whole-topic conrefs, unresolved targets,

package/dist/blocks.js

@@ -1,5 +1,5 @@
 import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
-import { convertInline, elementName, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
+import { convertInline, elementName, isKnownInline, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
 import { publishHref, publishLabel, publishLanguage, publishString } from "./types.js";
 import { anchorId } from "./anchors.js";
 import { DB_QUALIFIERS, outputTokens, youtubeId } from "./qualifiers.js";
@@ -52,6 +52,13 @@ const withProvenance = (node, el) => {
     }
     return node;
 };
+/** A list item or step: its source line (ParseOptions.sourceLines), as convertBlock gives a block. */
+const atLine = (node, el, ctx) => {
+    const line = ctx.lineOf?.(el);
+    if (line !== undefined && node.meta?.line === undefined)
+        node.meta = { ...node.meta, line };
+    return node;
+};
 const noteFilterAttrs = (el, ctx) => {
     for (const attr of ["audience", "platform", "product", "props", "otherprops", "rev"]) {
         if (el.attribs?.[attr]) {
@@ -77,8 +84,29 @@ const isBlockChild = (el, ctx) => {
     const name = blockName(el, ctx);
     if (ctx.publish && name === "image")
         return el.attribs?.placement === "break";
-    return BLOCK_ELEMENTS.has(name);
+    return BLOCK_ELEMENTS.has(name) || (isUnknownElement(el, ctx) && holdsBlocks(el, ctx));
 };
+/**
+ * An element the converter knows by neither a block nor an inline name (a
+ * custom specialization). Both resolutions count: with @class, a
+ * specialization of <fn> or <ph> resolves to an inline name, not a block one.
+ */
+const isUnknownElement = (el, ctx) => !isKnownBlock(elementName(el, ctx, isKnownBlock)) && !isKnownInline(elementName(el, ctx, isKnownInline));
+/**
+ * Whether an unknown element holds block content (a <p>, a list), directly or
+ * through other unknown wrappers. Such an element is a block wrapper: read as
+ * inline, its paragraphs and lists were flattened into one run of text, with
+ * an "unrecognized inline element" note for each of them. An image does not
+ * count: it sits in a sentence as often as not (an icon in a UI label).
+ */
+const holdsBlocks = (el, ctx) => el.children.some((c) => {
+    if (!isElement(c))
+        return false;
+    const name = blockName(c, ctx);
+    if (name === "image")
+        return false;
+    return BLOCK_ELEMENTS.has(name) || TRANSPARENT_CONTAINERS.has(name) || (isUnknownElement(c, ctx) && holdsBlocks(c, ctx));
+});
 const paragraphFrom = (nodes, ctx) => {
     const inline = trimInline(convertInline(nodes, ctx));
     if (inline.length === 0)
@@ -210,12 +238,18 @@ const definingItemNode = (el, ctx, type) => {
     ctx.note("@conref", `<${el.name.toLowerCase()} id="${el.attribs.id}"> is reused elsewhere via "${snippet.file}" but its content is multi-line — replace it with the include manually to keep one copy`);
     return null;
 };
+/**
+ * Whether an element is a `tag` by name or, with @class, by what it
+ * specializes: a hazard statement's <typeofhazard> is an <li>. Matching the
+ * name alone dropped such items, and their text, without a note.
+ */
+const isPart = (el, ctx, tag) => isElement(el) && elementName(el, ctx, (n) => n === tag) === tag;
 const convertListItems = (el, ctx, itemTag) => el.children
-    .filter((c) => isElement(c) && c.name.toLowerCase() === itemTag)
+    .filter((c) => isPart(c, ctx, itemTag))
     .map((li) => {
     const viaConref = itemConref(li, ctx, "list-item") ?? definingItemNode(li, ctx, "list-item");
     if (viaConref)
-        return withProvenance(viaConref, li);
+        return atLine(withProvenance(viaConref, li), li, ctx);
     const { inline: content, children: blocks } = mixedContent(li, { ...ctx, constrained: true });
     const { inline, children } = withItemAnchor(content, blocks, [li.attribs?.id], ctx);
     const item = { type: "list-item" };
@@ -223,7 +257,7 @@ const convertListItems = (el, ctx, itemTag) => el.children
         item.inline = inline;
     if (children.length > 0)
         item.children = children;
-    return withProvenance(item, li);
+    return atLine(withProvenance(item, li), li, ctx);
 });
 /** Components an `@outputclass` `db-*` token selects, per element. */
 const DB_COMPONENTS = {
@@ -529,7 +563,7 @@ const inlineLabel = (inline) => (inline ?? [])
 const dlComponentEntries = (el, ctx, component, keepEmpty = false, anchorsOut) => {
     const out = [];
     let pending = [];
-    const entries = el.children.filter((c) => isElement(c) && c.name.toLowerCase() === "dlentry");
+    const entries = el.children.filter((c) => isPart(c, ctx, "dlentry"));
     for (const entry of entries) {
         const items = convertDefList({ ...el, children: [entry] }, ctx).children ?? [];
         const terms = items.filter((n) => n.type === "dt");
@@ -637,7 +671,7 @@ const dlToCards = (el, ctx, anchors) => {
 const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd" }) => {
     const children = [];
     for (const entry of el.children.filter(isElement)) {
-        if (entry.name.toLowerCase() !== tags.entry)
+        if (!isPart(entry, ctx, tags.entry))
             continue;
         // Entry-level conref (<dlentry conref>): a term/definition pair can't
         // splice as an include — ledger it so the loss is never silent
@@ -647,8 +681,7 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
         }
         let entryAnchored = false;
         for (const part of entry.children.filter(isElement)) {
-            const name = part.name.toLowerCase();
-            if (name === tags.term) {
+            if (isPart(part, ctx, tags.term)) {
                 // Term-level conref (<dt conref>/<pt conref>): single-line
                 // include or ledger — never a silent empty term
                 const viaConref = constrainedConrefInline(part, ctx);
@@ -659,7 +692,7 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
                 });
                 entryAnchored = true;
             }
-            else if (name === tags.def) {
+            else if (isPart(part, ctx, tags.def)) {
                 const viaConref = constrainedConrefInline(part, ctx);
                 if (viaConref) {
                     children.push({ type: "dd", inline: viaConref });
@@ -719,12 +752,23 @@ const TABLE_PARTS = new Set([
 const hasClassToken = (el, token) => ` ${el.attribs?.class ?? ""} `.includes(` ${token} `);
 const elementChildren = (el) => el.children.filter(isElement);
 const PROPERTY_KINDS = ["proptype", "propvalue", "propdesc"];
+/**
+ * Whether an element is the reference domain's `local` (`properties`, `property`, …):
+ * by @class when DITA-OT has filled it in, else by name, as authored source has none.
+ */
+const isReference = (el, local) => hasClassToken(el, `reference/${local}`) || el.name.toLowerCase() === local;
 /** A properties table cell's column: `proptype`, or with suffix "hd" a header cell (`proptypehd`). */
-const propertyKind = (cell, suffix = "") => PROPERTY_KINDS.find((k) => hasClassToken(cell, `reference/${k}${suffix}`));
+const propertyKind = (cell, suffix = "") => PROPERTY_KINDS.find((k) => isReference(cell, `${k}${suffix}`));
+/**
+ * A properties table's cells. Exactly the cells `propertyKind` recognizes (a
+ * published cell's @class names its kind before the stentry it specializes),
+ * so a row's converted cells and its cell elements line up index for index.
+ */
+const PROPERTY_CELLS = new Set([...PROPERTY_KINDS, ...PROPERTY_KINDS.map((k) => `${k}hd`)]);
 /** A properties table's columns in use, its properties that have cells, and its header row. */
 const propertiesColumns = (el) => {
-    const header = elementChildren(el).find((c) => hasClassToken(c, "reference/prophead"));
-    const propertyRows = elementChildren(el).filter((c) => hasClassToken(c, "reference/property") && elementChildren(c).some((cell) => !!propertyKind(cell)));
+    const header = elementChildren(el).find((c) => isReference(c, "prophead"));
+    const propertyRows = elementChildren(el).filter((c) => isReference(c, "property") && elementChildren(c).some((cell) => !!propertyKind(cell)));
     const used = PROPERTY_KINDS.filter((k) => propertyRows.some((r) => elementChildren(r).some((c) => propertyKind(c) === k)) ||
         (header ? elementChildren(header).some((c) => propertyKind(c, "hd") === k) : false));
     return { used, propertyRows, ...(header ? { header } : {}) };
@@ -829,15 +873,24 @@ const convertTable = (el, ctx) => {
         }
     };
     walk(el);
-    // Publishing: a properties table's columns are the type, value and description columns
+    // A properties table's columns are the type, value and description columns
     // its header or any property uses (DITA-OT's hasType, hasValue, hasDesc); each row
     // aligns its cells to them, a property with no cells is dropped, and a header cell
-    // missing for a column in use is DITA-OT's generated label ("Type", "Value", "Description")
-    if (ctx.publish && hasClassToken(el, "reference/properties")) {
+    // missing for a column in use is DITA-OT's generated label ("Type", "Value",
+    // "Description"; localized when publishing). Authored source has no @class, so
+    // the parts are matched by name too (the walk above sees no sthead/strow then).
+    if (isReference(el, "properties")) {
         const { used, propertyRows, header } = propertiesColumns(el);
+        // A property with no cells has no row; one that reuses a row by conref is noted, not lost
+        for (const row of elementChildren(el)) {
+            if (isReference(row, "property") && !propertyRows.includes(row) && (row.attribs?.conref || row.attribs?.conkeyref)) {
+                const ref = row.attribs.conref ?? row.attribs.conkeyref;
+                ctx.note(row.attribs.conref ? "@conref" : "@conkeyref", `<property> pulls content from "${ref}" — ${conrefLedgerDetail(row.attribs, undefined, ctx.conref !== undefined)}`);
+            }
+        }
         rows.length = 0;
         for (const row of propertyRows) {
-            const converted = convertRow(row, SIMPLE_CELLS);
+            const converted = convertRow(row, PROPERTY_CELLS);
             const cellEls = elementChildren(row).filter((c) => !!propertyKind(c));
             rows.push({
                 type: "tr",
@@ -847,13 +900,10 @@ const convertTable = (el, ctx) => {
                 }),
             });
         }
-        const lang = publishLanguage(el, ctx.publish);
-        const label = {
-            proptype: publishString(ctx.publish, lang, "Type"),
-            propvalue: publishString(ctx.publish, lang, "Value"),
-            propdesc: publishString(ctx.publish, lang, "Description"),
-        };
-        const authored = header ? convertRow(header, SIMPLE_CELLS, true) : undefined;
+        const lang = ctx.publish ? publishLanguage(el, ctx.publish) : undefined;
+        const word = (w) => (ctx.publish ? publishString(ctx.publish, lang, w) : w);
+        const label = { proptype: word("Type"), propvalue: word("Value"), propdesc: word("Description") };
+        const authored = header ? convertRow(header, PROPERTY_CELLS, true) : undefined;
         const headerCells = header ? elementChildren(header).filter((c) => !!propertyKind(c, "hd")) : [];
         headRows.length = 0;
         headRows.push({
@@ -940,11 +990,11 @@ export const convertStepContent = (stepEl, ctx) => {
 const convertSteps = (el, ctx, type) => {
     const stepTag = type === "steps" ? "step" : "substep";
     const children = el.children
-        .filter((c) => isElement(c) && c.name.toLowerCase() === stepTag)
+        .filter((c) => isPart(c, ctx, stepTag))
         .map((stepEl) => {
         const viaConref = itemConref(stepEl, ctx, "step") ?? definingItemNode(stepEl, ctx, "step");
         if (viaConref)
-            return withProvenance(viaConref, stepEl);
+            return atLine(withProvenance(viaConref, stepEl), stepEl, ctx);
         const { inline: content, children: blocks } = convertStepContent(stepEl, { ...ctx, constrained: true });
         // Publishing: DITA-OT labels optional and required steps
         const importance = stepEl.attribs?.importance;
@@ -960,7 +1010,7 @@ const convertSteps = (el, ctx, type) => {
             step.inline = inline;
         if (children.length > 0)
             step.children = children;
-        return withProvenance(step, stepEl);
+        return atLine(withProvenance(step, stepEl), stepEl, ctx);
     });
     return { type, children };
 };
@@ -1012,7 +1062,7 @@ const publishTaskLabel = (name, ctx, el) => ctx.publish?.taskLabels && TASK_LABE
 /** Block-level DITA elements (used to split mixed content). */
 const BLOCK_ELEMENTS = new Set([
     "p", "shortdesc", "note", "codeblock", "pre", "screen", "msgblock", "ul", "ol", "sl", "dl", "parml", "table", "simpletable",
-    "fig", "image", "section", "example", "steps", "steps-unordered", "substeps", "lq", "object",
+    "properties", "fig", "image", "section", "example", "steps", "steps-unordered", "substeps", "lq", "object",
     "prereq", "context", "result", "postreq", "tasktroubleshooting", "choices", "choicetable", "syntaxdiagram",
 ]);
 const SYNTAX_GROUPS = new Set(["groupseq", "groupchoice", "groupcomp"]);
@@ -1119,6 +1169,27 @@ const ANCHORED_ELSEWHERE = new Set(["title", "related-links", "prolog", "data",
  * DITA-OT's pages. (Headings carry their own id.)
  */
 export function convertBlock(el, ctx) {
+    // A note raised while converting this element takes its line
+    const outer = ctx.position?.el;
+    if (ctx.position)
+        ctx.position.el = el;
+    try {
+        const out = convertBlockThemed(el, ctx);
+        // Source lines: each node this element became starts at its line
+        // (nested blocks came through here first and keep their own)
+        const line = ctx.lineOf?.(el);
+        if (line !== undefined)
+            for (const node of out)
+                if (node.meta?.line === undefined)
+                    node.meta = { ...node.meta, line };
+        return out;
+    }
+    finally {
+        if (ctx.position)
+            ctx.position.el = outer;
+    }
+}
+function convertBlockThemed(el, ctx) {
     const out = convertBlockAnchored(el, ctx);
     // A scoped theme wraps the element's whole output, its anchor included
     const theme = /(^|\s)db-theme-/i.test(el.attribs?.outputclass ?? "") ? themeOf(el, ctx) : undefined;
@@ -1364,7 +1435,7 @@ function convertBlockContent(el, ctx) {
             // as <li>: referencing items include or ledger, defining items
             // hand their text to the snippet)
             const items = el.children
-                .filter((c) => isElement(c) && c.name.toLowerCase() === "sli")
+                .filter((c) => isPart(c, ctx, "sli"))
                 .map((sli) => {
                 const viaConref = itemConref(sli, ctx, "list-item") ?? definingItemNode(sli, ctx, "list-item");
                 if (viaConref)
@@ -1400,9 +1471,17 @@ function convertBlockContent(el, ctx) {
             return [withProvenance(convertDefList(el, ctx, { entry: "plentry", term: "pt", def: "pd" }), el)];
         case "table":
         case "simpletable":
-            // Publishing: DITA-OT drops a properties table none of whose properties has a cell
-            if (ctx.publish && hasClassToken(el, "reference/properties") && propertiesColumns(el).propertyRows.length === 0)
+        case "properties":
+            // A properties table none of whose properties has a cell has no columns: DITA-OT drops it
+            if (isReference(el, "properties") && propertiesColumns(el).propertyRows.length === 0) {
+                if (!ctx.publish) {
+                    for (const row of elementChildren(el).filter((r) => r.attribs?.conref || r.attribs?.conkeyref)) {
+                        const ref = row.attribs.conref ?? row.attribs.conkeyref;
+                        ctx.note(row.attribs.conref ? "@conref" : "@conkeyref", `<${row.name.toLowerCase()}> pulls content from "${ref}" — ${conrefLedgerDetail(row.attribs, undefined, ctx.conref !== undefined)}`);
+                    }
+                }
                 return [];
+            }
             return [withProvenance(convertTable(el, ctx), el)];
         case "syntaxdiagram":
             if (ctx.publish)

package/dist/class-defaults-apply.d.ts

@@ -0,0 +1,15 @@
+import type { AnyNode, Element } from "domhandler";
+/** An element's DITA 1.3 default @class (`inMap`: inside a map document), or undefined for a name the DTDs do not declare. */
+export declare const classDefault: (name: string, inMap?: boolean) => string | undefined;
+/**
+ * Fill in the @class a DTD would have defaulted, on every element that has
+ * none, as parsing against the DTDs (or DITA-OT preprocessing) does. An
+ * existing @class is kept. Returns the element names the DITA 1.3 DTDs do not
+ * declare (custom specializations, DITA 2.0), in document order, each once;
+ * those stay unclassed. Not reported: the `<dita>` wrapper of a composite
+ * topic, which has no @class by design, and foreign vocabularies (a
+ * namespace prefix, or an undeclared name inside a `<foreign>`
+ * specialization: MathML, SVG), which are not DITA elements and are left
+ * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
+ */
+export declare function applyClassDefaults(nodes: AnyNode[], firstOf?: Map<string, Element>): string[];

package/dist/class-defaults-apply.js

@@ -0,0 +1,42 @@
+import { isTag } from "domhandler";
+import { DITA_CLASS_DEFAULTS, DITA_MAP_CLASS_DEFAULTS } from "./class-defaults.js";
+const own = (table, name) => Object.prototype.hasOwnProperty.call(table, name) ? table[name] : undefined;
+/** An element's DITA 1.3 default @class (`inMap`: inside a map document), or undefined for a name the DTDs do not declare. */
+export const classDefault = (name, inMap = false) => (inMap ? own(DITA_MAP_CLASS_DEFAULTS, name) : undefined) ?? own(DITA_CLASS_DEFAULTS, name);
+/**
+ * Fill in the @class a DTD would have defaulted, on every element that has
+ * none, as parsing against the DTDs (or DITA-OT preprocessing) does. An
+ * existing @class is kept. Returns the element names the DITA 1.3 DTDs do not
+ * declare (custom specializations, DITA 2.0), in document order, each once;
+ * those stay unclassed. Not reported: the `<dita>` wrapper of a composite
+ * topic, which has no @class by design, and foreign vocabularies (a
+ * namespace prefix, or an undeclared name inside a `<foreign>`
+ * specialization: MathML, SVG), which are not DITA elements and are left
+ * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
+ */
+export function applyClassDefaults(nodes, firstOf) {
+    const root = nodes.find(isTag);
+    const inMap = !!root && (["map", "bookmap", "subjectScheme"].includes(root.name) || ` ${root.attribs?.class ?? ""} `.includes(" map/map "));
+    const unknown = new Set();
+    const visit = (el, inForeign) => {
+        if (el.name.includes(":"))
+            return;
+        if (!el.attribs?.class?.trim()) {
+            const value = classDefault(el.name, inMap);
+            if (value)
+                el.attribs = { ...el.attribs, class: value };
+            else if (el.name !== "dita" && !inForeign && !unknown.has(el.name)) {
+                unknown.add(el.name);
+                firstOf?.set(el.name, el);
+            }
+        }
+        const foreign = inForeign || ` ${el.attribs?.class ?? ""} `.includes(" topic/foreign ");
+        for (const child of el.children)
+            if (isTag(child))
+                visit(child, foreign);
+    };
+    for (const node of nodes)
+        if (isTag(node))
+            visit(node, false);
+    return [...unknown];
+}

package/dist/class-defaults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Each DITA 1.3 element's default @class, as its DTD declares it. GENERATED by
+ * scripts/generate-class-defaults.mjs from the .mod files under dita-ot-4.3.5's
+ * plugins/org.oasis-open.dita.v1_3/dtd/ (612 elements); do not edit.
+ */
+export declare const DITA_CLASS_DEFAULTS: Readonly<Record<string, string>>;
+/** Elements whose class differs inside a map (map.mod declares them too). */
+export declare const DITA_MAP_CLASS_DEFAULTS: Readonly<Record<string, string>>;