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

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export { ditaTopicToDogsbayMd, type DitaMarkdownResult } from "./markdown.js";
 export { planConrefs, type ConrefCorpusFile, type ConrefPlan, type ConrefSnippet, } from "./conref.js";
 export { DB_QUALIFIERS } from "./blocks.js";
 export { checkWellFormed, type WellFormedProblem } from "./well-formed.js";
+export { DITA_CLASS_DEFAULTS, DITA_MAP_CLASS_DEFAULTS } from "./class-defaults.js";
+export { applyClassDefaults, classDefault } from "./class-defaults-apply.js";

package/dist/index.js

@@ -19,3 +19,5 @@ export { planConrefs, } from "./conref.js";
 // The closed db- qualifier vocabulary (tones, tab variants, scoped themes)
 export { DB_QUALIFIERS } from "./blocks.js";
 export { checkWellFormed } from "./well-formed.js";
+export { DITA_CLASS_DEFAULTS, DITA_MAP_CLASS_DEFAULTS } from "./class-defaults.js";
+export { applyClassDefaults, classDefault } from "./class-defaults-apply.js";

package/dist/inline.d.ts

@@ -9,6 +9,18 @@ export interface InlineContext {
     conref?: ConrefSiteContext;
     /** Publishing mode: DITA-OT preprocessed input (absent for migration). */
     publish?: PublishContext;
+    /** Every element carries @class (DTD defaults filled in): resolve unknown names by it, as publishing does. */
+    classes?: boolean;
+    /**
+     * The element being converted, shared by every context derived from the
+     * topic's (a note takes its line from it). Set by convertBlock and, for each
+     * element, convertInline.
+     */
+    position?: {
+        el?: Element;
+    };
+    /** ParseOptions.sourceLines: an element's 1-based source line. */
+    lineOf?: (el: Element) => number | undefined;
     /** Publishing: trademarks already marked in this topic (DITA-OT marks only the first). */
     trademarks?: Set<string>;
     /** Publishing: the number label of each titled table and figure ("Table 1. "). */

package/dist/inline.js

@@ -83,7 +83,7 @@ const BOLD_LIKE = new Set(["b", "strong", "uicontrol", "wintitle", "menucascade"
  */
 export const elementName = (el, ctx, known) => {
     const raw = el.name.toLowerCase();
-    if (!ctx.publish || known(raw))
+    if (!(ctx.publish || ctx.classes) || known(raw))
         return raw;
     const tokens = (el.attribs?.class ?? "").trim().split(/\s+/).slice(1).reverse();
     for (const token of tokens) {
@@ -216,6 +216,19 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
         }
         if (!isElement(node))
             continue;
+        const outer = ctx.position?.el;
+        if (ctx.position)
+            ctx.position.el = node;
+        try {
+            convertInlineElement(node);
+        }
+        finally {
+            if (ctx.position)
+                ctx.position.el = outer;
+        }
+    }
+    return mergeAdjacentText(out);
+    function convertInlineElement(node) {
         const name = elementName(node, ctx, isKnownInline);
         const children = node.children;
         // Publishing: an inline element with an @id gets an anchor, as DITA-OT's HTML keeps the id
@@ -238,7 +251,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             const defining = ctx.conref.definingSnippet(node.attribs.id);
             if (defining && inlineSafeSnippet(defining)) {
                 pushText(`{% include "${ctx.conref.includePath(defining)}" %}`);
-                continue;
+                return;
             }
         }
         // Inline conrefs (<ph conref="…"/>) are the standard DITA reused-text
@@ -254,7 +267,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 // Local children are the stale preview copy in DITA conref
                 // semantics — the include replaces the whole element
                 pushText(`{% include "${ctx.conref.includePath(snippet)}" %}`);
-                continue;
+                return;
             }
             ctx.note(node.attribs.conref ? "@conref" : "@conkeyref", `<${name}> pulls content from "${ref}" — ${conrefLedgerDetail(node.attribs, snippet, ctx.conref !== undefined)}`);
         }
@@ -275,7 +288,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         noteOnce(ctx, `db-badge ${t}`, `"${t}" is not a tone (${DB_QUALIFIERS.tones.join(", ")}) — default badge`);
                 }
                 out.push({ type: "badge", text, ...(variant ? { variant } : {}) });
-                continue;
+                return;
             }
             // A content-less keyref falls through to the key's text ({{ key }}): the badge look is what is lost
             if (node.attribs?.keyref)
@@ -309,7 +322,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         : [];
             // An unresolved key with no content renders nothing, as in DITA-OT's output
             if (content.length === 0)
-                continue;
+                return;
             const href = node.attribs?.href;
             if (href) {
                 // An external link keeps its href as written, even to a .dita file
@@ -319,14 +332,14 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             else {
                 out.push(...content);
             }
-            continue;
+            return;
         }
         if (!ctx.publish && node.attribs?.keyref && name !== "xref" && name !== "link" && name !== "image") {
             const hasFallback = children.some((c) => isElement(c) || (isText(c) && c.data.trim().length > 0));
             if (!hasFallback) {
                 noteOnce(ctx, "@keyref", "content-less keyref emitted as {{ key }} minja variable — resolves only for TEXT keys (keys.yaml entries with text:); href-only keys need manual attention");
                 pushText(`{{ ${node.attribs.keyref} }}`);
-                continue;
+                return;
             }
             // Fallback content present: note the dropped indirection, then fall
             // through so the element converts normally (term stays italic, …)
@@ -334,12 +347,12 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
         }
         if (TRANSPARENT.has(name) && !isCodeLike(name, ctx)) {
             out.push(...convertInline(children, ctx, formatting));
-            continue;
+            return;
         }
         // Publishing: content DITA-OT's HTML does not show (foreign content such as MathML without
         // a plugin, and required-cleanup without args.draft)
         if (ctx.publish && (name === "foreign" || name === "unknown" || name === "required-cleanup"))
-            continue;
+            return;
         if ((name === "fn" || name === "synnote") && ctx.publish && ctx.footnotes) {
             // Publishing: a numbered footnote, listed at the end of the page as DITA-OT does. Only
             // footnotes without @callout are numbered; a callout is the label when it is a valid,
@@ -351,14 +364,14 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             // Converted by parse.ts, which can convert block content (a list in a footnote)
             ctx.footnotes.push({ label, el: node, ...(callout ? { callout: true } : {}) });
             out.push({ type: "footnote-ref", label });
-            continue;
+            return;
         }
         if (name === "q" && ctx.publish) {
             // Publishing: a quotation in quotation marks, as a browser renders DITA-OT's <q>
             pushText("\u201C");
             out.push(...convertInline(children, ctx, formatting));
             pushText("\u201D");
-            continue;
+            return;
         }
         if (isCodeLike(name, ctx) && ctx.publish && children.some((c) => isElement(c) && ["xref", "link"].includes(c.name.toLowerCase()))) {
             // Publishing: a code phrase containing a link, as DITA-OT renders it: one code
@@ -374,7 +387,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             out.push({ type: "html-inline", html: `<code>${collapseWhitespace(html).trim()}</code>` });
             if (raw.endsWith(" "))
                 pushText(" ");
-            continue;
+            return;
         }
         if (isCodeLike(name, ctx)) {
             if (name !== "codeph" && name !== "tt") {
@@ -394,7 +407,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             });
             if (ctx.publish && raw.endsWith(" ") && raw.trim())
                 pushText(" ");
-            continue;
+            return;
         }
         if (name === "menucascade") {
             // "File > Save Project", as DITA-OT's HTML renders it: each step keeps
@@ -412,7 +425,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 out.push(...converted);
                 any = true;
             }
-            continue;
+            return;
         }
         if (name === "shortcut") {
             // A keystroke (`<shortcut>Ctrl+S</shortcut>`) is a keycap. Inside a
@@ -424,21 +437,21 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 out.push({ type: "kbd", keys });
             else
                 out.push(...convertInline(children, ctx, formatting));
-            continue;
+            return;
         }
         if (BOLD_LIKE.has(name)) {
             if (name !== "b" && name !== "strong") {
                 noteOnce(ctx, `<${name}>`, `rendered as bold — semantic identity not preserved`);
             }
             out.push(...convertInline(children, ctx, { ...formatting, bold: true }));
-            continue;
+            return;
         }
         if (ITALIC_LIKE.has(name)) {
             if (name !== "i" && name !== "em") {
                 noteOnce(ctx, `<${name}>`, `rendered as italic — semantic identity not preserved`);
             }
             out.push(...convertInline(children, ctx, { ...formatting, italic: true }));
-            continue;
+            return;
         }
         if (name === "tm" && ctx.publish) {
             // Publishing: the trademark symbol DITA-OT's HTML adds, on a trademark's first use in the topic
@@ -448,18 +461,18 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             if (symbol && !ctx.trademarks?.has(trademark))
                 pushText(symbol);
             ctx.trademarks?.add(trademark);
-            continue;
+            return;
         }
         // Highlighting Markdown has no syntax for: inline HTML around the converted content
         if (name === "u" || name === "sub" || name === "sup" || name === "overline") {
             const open = name === "overline" ? '<span style="text-decoration: overline">' : `<${name}>`;
             const close = name === "overline" ? "</span>" : `</${name}>`;
             out.push({ type: "html-inline", html: open }, ...convertInline(children, ctx, formatting), { type: "html-inline", html: close });
-            continue;
+            return;
         }
         if (name === "line-through") {
             out.push(...convertInline(children, ctx, { ...formatting, strikethrough: true }));
-            continue;
+            return;
         }
         if (name === "xref" || name === "link") {
             const href = node.attribs?.href;
@@ -476,7 +489,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                     out.push(...linkChildren);
                 else if (text)
                     pushText(text);
-                continue;
+                return;
             }
             if (keyref && !ctx.publish) {
                 // Key-based links keep their indirection via the key: scheme
@@ -486,7 +499,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                     href: `key:${keyref}`,
                     children: linkChildren.length > 0 ? linkChildren : [{ type: "text", text: keyref }],
                 });
-                continue;
+                return;
             }
             if (href) {
                 // An external link keeps its href as written, even to a .dita file
@@ -498,11 +511,11 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         ? linkChildren
                         : [{ type: "text", text: fallbackText || (ctx.publish ? ditaOtHrefText(href) : href) }],
                 });
-                continue;
+                return;
             }
             noteOnce(ctx, `<${name}>`, "xref without href/keyref — emitted as plain text");
             pushText(fallbackText);
-            continue;
+            return;
         }
         if (name === "image") {
             const imgHref = node.attribs?.href;
@@ -513,13 +526,13 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 else {
                     noteOnce(ctx, "<image>", "image without href dropped");
                 }
-                continue;
+                return;
             }
             if (ctx.publish) {
                 // Publishing: size, alignment and the <alt> element, as DITA-OT's HTML renders them
                 const { alt, attrs } = publishImage(node, ctx.publish);
                 out.push({ type: "image", src: imgHref, ...(alt ? { alt } : {}), ...(attrs ? { attrs } : {}) });
-                continue;
+                return;
             }
             // The <alt> element (DITA 1.1+) wins over the deprecated @alt, as in publishing.
             const altEl = (children).find((c) => isElement(c) && c.name.toLowerCase() === "alt");
@@ -529,17 +542,16 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 src: imgHref,
                 ...(alt ? { alt } : {}),
             });
-            continue;
+            return;
         }
         if (name === "indexterm" || name === "draft-comment" || name === "data") {
             noteOnce(ctx, `<${name}>`, "metadata element dropped from output");
-            continue;
+            return;
         }
         // Unknown inline element: keep the text, note the loss
         noteOnce(ctx, `<${name}>`, "unrecognized inline element — text kept, markup dropped");
         out.push(...convertInline(children, ctx, formatting));
     }
-    return mergeAdjacentText(out);
 };
 /** Merge neighbouring text spans with identical formatting (recursive calls
  * push whole runs, so pushText's local merging alone is not enough). */

package/dist/lines.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Offsets → 1-based line numbers, counting lines as checkWellFormed does:
+ * `\n`, `\r\n` and a lone `\r` each end one.
+ */
+export declare function lineLocator(text: string): (offset: number) => number;

package/dist/lines.js

@@ -0,0 +1,24 @@
+/**
+ * Offsets → 1-based line numbers, counting lines as checkWellFormed does:
+ * `\n`, `\r\n` and a lone `\r` each end one.
+ */
+export function lineLocator(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c === 10 || (c === 13 && text.charCodeAt(i + 1) !== 10))
+            starts.push(i + 1);
+    }
+    return (offset) => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+}

package/dist/parse.js

@@ -1,4 +1,6 @@
 import { checkWellFormed } from "./well-formed.js";
+import { applyClassDefaults } from "./class-defaults-apply.js";
+import { lineLocator } from "./lines.js";
 import { parseDocument } from "htmlparser2";
 import { convertChildren, convertItemContent } from "./blocks.js";
 import { textOf, convertInline, trimInline, collapseWhitespace } from "./inline.js";
@@ -88,6 +90,8 @@ const convertSecondaryTopic = (el, ctx, level, bindConrefSite) => {
     for (const child of el.children) {
         if (!isElement(child))
             continue;
+        if (ctx.position)
+            ctx.position.el = child;
         const name = child.name.toLowerCase();
         if (name === "title" || name === "glossterm") {
             out.push({
@@ -97,14 +101,16 @@ const convertSecondaryTopic = (el, ctx, level, bindConrefSite) => {
                     ...(el.attribs?.id ? { id: el.attribs.id } : {}),
                 },
                 inline: trimInline(convertInline(child.children, inner)),
-                ...(el.attribs?.id ? { meta: { dita: { id: el.attribs.id } } } : {}),
+                ...(el.attribs?.id || ctx.lineOf?.(child) !== undefined
+                    ? { meta: { ...(el.attribs?.id ? { dita: { id: el.attribs.id } } : {}), ...(ctx.lineOf?.(child) !== undefined ? { line: ctx.lineOf(child) } : {}) } }
+                    : {}),
             });
             headingEmitted = true;
             continue;
         }
         if (name === "titlealts")
             continue;
-        if (isTopicElement(child, !!ctx.publish)) {
+        if (isTopicElement(child, !!ctx.publish || !!ctx.classes)) {
             out.push(...convertSecondaryTopic(child, ctx, bodyLevel, bindConrefSite));
             continue;
         }
@@ -219,13 +225,27 @@ const extractProlog = (el, meta, ctx) => {
 export function ditaTopicToTree(xml, options = {}) {
     const topicPath = options.topicPath ?? "";
     const notes = [];
-    const note = (construct, detail) => notes.push({ topicPath, construct, detail });
+    // Every note carries the line of the element converting when it was raised
+    // (a shared holder: contexts are copied, the holder is not)
+    const lineOf = lineLocator(xml);
+    const position = {};
+    const lineAt = (el) => el?.startIndex != null ? lineOf(el.startIndex) : undefined;
+    const note = (construct, detail, line = lineAt(position.el)) => notes.push({ topicPath, construct, detail, ...(line ? { line } : {}) });
     // The parser repairs malformed XML silently: say so, with a line
     const malformed = checkWellFormed(xml);
     if (malformed)
-        note("<xml>", `not well-formed XML, line ${malformed.line}: ${malformed.message} — the converted content may be incomplete`);
-    const doc = parseDocument(xml, { xmlMode: true });
-    const roots = findTopicRoots(doc.children, !!options.publish);
+        note("<xml>", `not well-formed XML, line ${malformed.line}: ${malformed.message} — the converted content may be incomplete`, malformed.line);
+    const doc = parseDocument(xml, { xmlMode: true, withStartIndices: true });
+    // Raw source: fill in the @class the DTDs default, so specializations convert as their base
+    if (options.classDefaults) {
+        const firstOf = new Map();
+        const undeclared = applyClassDefaults(doc.children, firstOf);
+        if (undeclared.length) {
+            note("@class", `no DITA 1.3 class default for ${undeclared.map((n) => `<${n}>`).join(", ")} — converted by name only`, lineAt(firstOf.get(undeclared[0])));
+        }
+    }
+    const byClass = !!options.publish || !!options.classDefaults;
+    const roots = findTopicRoots(doc.children, byClass);
     const root = roots[0] ?? null;
     if (!root) {
         note("<topic>", "no DITA topic root element found (concept/task/reference/topic/glossentry)");
@@ -274,6 +294,9 @@ export function ditaTopicToTree(xml, options = {}) {
         note,
         seenConstructs: new Set(),
         headingLevel: 2,
+        position,
+        ...(options.classDefaults ? { classes: true } : {}),
+        ...(options.sourceLines ? { lineOf: lineAt } : {}),
         ...(bindConrefSite ? { conref: bindConrefSite(root.attribs?.id) } : {}),
         ...(options.publish
             ? { publish: options.publish, trademarks: new Set(), footnotes: [], topicId: root.attribs?.id, anchorIds: renamedElementIds(doc.children) }
@@ -287,6 +310,7 @@ export function ditaTopicToTree(xml, options = {}) {
     for (const child of root.children) {
         if (!isElement(child))
             continue;
+        position.el = child;
         const name = child.name.toLowerCase();
         if (name === "title" || name === "glossterm") {
             // The page title is plain text: a badge in it keeps only its words
@@ -332,7 +356,7 @@ export function ditaTopicToTree(xml, options = {}) {
             extractProlog(child, meta, ctx);
             continue;
         }
-        if (isTopicElement(child, !!options.publish)) {
+        if (isTopicElement(child, byClass)) {
             // Nested topic: convert inline as a section (chunked authoring)
             tree.push(...convertSecondaryTopic(child, ctx, 2, bindConrefSite));
             continue;
@@ -341,9 +365,12 @@ export function ditaTopicToTree(xml, options = {}) {
     }
     // Sibling topics under a composite wrapper convert the same way
     for (const sibling of roots.slice(1)) {
+        position.el = sibling;
         // Publishing: DITA-OT titles sibling topics in one file like the first (h1)
         tree.push(...convertSecondaryTopic(sibling, ctx, options.publish ? 1 : 2, bindConrefSite));
     }
+    // Notes about the whole file (duplicate ids) are about no one element
+    position.el = undefined;
     // DITA element ids are unique per TOPIC, not per file — after inlining
     // multiple topics, colliding ids mean fragment links can mis-target.
     // Known loss, never silent loss: report every duplicate anchor.

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface DitaConversionNote {
     /** Construct that triggered the note (element/attribute name). */
     construct: string;
     detail: string;
+    /**
+     * The 1-based source line the note is about: the element that raised it, or
+     * failing that the block being converted (absent when there is none, as for
+     * "no topic root").
+     */
+    line?: number;
 }
 /** Topic-level metadata extracted alongside the block tree. */
 export interface DitaTopicMeta {
@@ -152,6 +158,22 @@ export interface DitaParseOptions {
      * its behavior unchanged.
      */
     publish?: PublishContext;
+    /**
+     * Fill in each missing @class from the DITA 1.3 DTD defaults (612 elements,
+     * see class-defaults.ts) before converting, as parsing against the DTDs
+     * would. Raw source has no @class, so without it an element is known only by
+     * its name, and a specialization the converter does not know by name loses
+     * its markup; with it, it converts as what it specializes. An existing
+     * @class is kept; a name the DTDs do not declare stays unclassed and is
+     * noted once. Off by default (it changes the output for such elements).
+     */
+    classDefaults?: boolean;
+    /**
+     * Put each block node's 1-based source line on `meta.line` (the line of the
+     * element it came from), so a host can map the rendered page back to the
+     * source; render-html writes it as `data-line` when asked. Off by default.
+     */
+    sourceLines?: boolean;
 }
 /** DITA topic root elements this importer understands. */
 export declare const DITA_TOPIC_TYPES: readonly ["concept", "task", "reference", "topic", "glossentry"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dita",
-  "version": "0.2.0-beta.123",
+  "version": "0.2.0-beta.125",
   "description": "DITA topic XML → TreeNode importer with conversion-note ledger; composes with format-dogsbay-md for .dita → .md migration. Browser-safe: no Node built-ins",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
   "dependencies": {
     "domhandler": "^5.0.3",
     "htmlparser2": "^10.1.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.123",
-    "@dogsbay/types": "0.2.0-beta.123"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.125",
+    "@dogsbay/types": "0.2.0-beta.125"
   },
   "license": "MIT",
   "repository": {