@jti/adoc2typst2pdf 1.0.0

package/docbook2typst.js

@@ -0,0 +1,1195 @@
+#!/usr/bin/env node
+
+/**
+ * docbook2typst.js
+ *
+ * Converts DocBook XML (as produced by asciidoctor -b docbook) to Typst markup.
+ *
+ * Usage:
+ *   node docbook2typst.js [options] <input.xml>
+ *
+ * Options:
+ *   -o <file>   Output Typst path (default: <input>.typ)
+ *   -h, --help  Show this help and exit
+ */
+
+'use strict';
+
+const fs   = require('fs')
+const path = require('path')
+
+
+// ── CLI ────────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2)
+
+if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+  console.log(`
+Usage: node docbook-typst.js [options] <input.xml>
+
+Converts DocBook XML to Typst markup.
+
+Options:
+  -o <file>   Output Typst file (default: <input>.typ)
+  -h, --help  Show this help and exit
+`)
+  process.exit(0)
+}
+
+let inputFile  = null
+let outputFile = null
+let useTheme   = true
+
+for (let i = 0; i < argv.length; i++) {
+  if ((argv[i] === '-o' || argv[i] === '--out-file') && argv[i + 1]) {
+    outputFile = argv[++i]
+  } else if (argv[i] === '--no-theme') {
+    useTheme = false
+  } else if (!argv[i].startsWith('-')) {
+    inputFile = argv[i]
+  }
+}
+
+if (!inputFile) {
+  console.error('Error: no input file specified.')
+  console.error('Run with --help for usage information.')
+  process.exit(1)
+}
+
+if (!fs.existsSync(inputFile)) {
+  console.error(`Error: file not found: ${inputFile}`)
+  process.exit(1)
+}
+
+outputFile = outputFile || inputFile.replace(/\.[^.]+$/, '.typ')
+
+// The assembled AsciiDoc source sits alongside the XML with the same basename.
+const adocSourceFile = inputFile.replace(/\.xml$/i, '.adoc')
+
+// ── XML Parser ────────────────────────────────────────────────────────────────
+//
+// Minimal recursive-descent parser for well-formed XML (as asciidoctor produces).
+// Returns a tree of { type, name, attrs, children } or { type: 'text', text }.
+
+function parseXml(src) {
+  let pos = 0
+
+  function skipWs() {
+    while (pos < src.length && /\s/.test(src[pos])) pos++
+  }
+
+  function readUntil(end) {
+    const i = src.indexOf(end, pos)
+    if (i === -1) throw new Error(`Unclosed: looking for ${JSON.stringify(end)} near pos ${pos}`)
+    const s = src.slice(pos, i)
+    pos = i + end.length
+    return s
+  }
+
+  function readName() {
+    const start = pos
+    while (pos < src.length && /[\w:.-]/.test(src[pos])) pos++
+    return src.slice(start, pos)
+  }
+
+  function decodeEntity() {
+    // Called when src[pos] === '&'
+    pos++ // consume '&'
+    const semi = src.indexOf(';', pos)
+    if (semi === -1) return '&'
+    const ref = src.slice(pos, semi)
+    pos = semi + 1
+    const named = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" }
+    if (ref in named) return named[ref]
+    if (ref.startsWith('#x') || ref.startsWith('#X'))
+      return String.fromCodePoint(parseInt(ref.slice(2), 16))
+    if (ref.startsWith('#'))
+      return String.fromCodePoint(parseInt(ref.slice(1), 10))
+    return `&${ref};` // unknown entity — keep as-is
+  }
+
+  function readAttrValue() {
+    const quote = src[pos]
+    if (quote !== '"' && quote !== "'")
+      throw new Error(`Expected quote at pos ${pos}, got ${JSON.stringify(src[pos])}`)
+    pos++
+    let val = ''
+    while (pos < src.length && src[pos] !== quote) {
+      val += src[pos] === '&' ? decodeEntity() : src[pos++]
+    }
+    pos++ // closing quote
+    return val
+  }
+
+  function readAttrs() {
+    const attrs = {}
+    while (pos < src.length) {
+      skipWs()
+      if (src[pos] === '>' || src[pos] === '/') break
+      const name = readName()
+      if (!name) break
+      skipWs()
+      if (src[pos] === '=') {
+        pos++
+        skipWs()
+        attrs[name] = readAttrValue()
+      } else {
+        attrs[name] = true // valueless boolean attribute
+      }
+    }
+    return attrs
+  }
+
+  function parseNode() {
+    if (pos >= src.length) return null
+
+    // Text node
+    if (src[pos] !== '<') {
+      let text = ''
+      while (pos < src.length && src[pos] !== '<') {
+        text += src[pos] === '&' ? decodeEntity() : src[pos++]
+      }
+      return { type: 'text', text }
+    }
+
+    pos++ // consume '<'
+
+    // Processing instruction: <?target data?>
+    if (src[pos] === '?') {
+      pos++
+      const piContent = readUntil('?>').trim()
+      const spaceIdx = piContent.search(/\s/)
+      const target = spaceIdx === -1 ? piContent : piContent.slice(0, spaceIdx)
+      return { type: 'pi', target }
+    }
+
+    // Comments, CDATA, DOCTYPE
+    if (src[pos] === '!') {
+      pos++
+      if (src.slice(pos, pos + 2) === '--') {
+        pos += 2
+        readUntil('-->')
+        return null
+      }
+      if (src.slice(pos, pos + 7) === '[CDATA[') {
+        pos += 7
+        const text = readUntil(']]>')
+        return { type: 'text', text }
+      }
+      readUntil('>') // DOCTYPE or other
+      return null
+    }
+
+    // Closing tag — caller will handle
+    if (src[pos] === '/') return null
+
+    // Opening element
+    const name = readName()
+    const attrs = readAttrs()
+    skipWs()
+
+    if (src[pos] === '/') {
+      pos++ // self-closing />
+      if (src[pos] === '>') pos++
+      return { type: 'element', name, attrs, children: [] }
+    }
+
+    if (src[pos] === '>') pos++
+
+    const children = []
+    while (pos < src.length) {
+      // Closing tag for this element?
+      if (src[pos] === '<' && src[pos + 1] === '/') {
+        pos += 2
+        const closeName = readName()
+        skipWs()
+        if (src[pos] === '>') pos++
+        if (closeName !== name) {
+          // Mismatched tag — tolerate and rewind (best-effort)
+          console.warn(`Warning: mismatched </${closeName}>, expected </${name}> — skipping`)
+        }
+        break
+      }
+      const child = parseNode()
+      if (child) children.push(child)
+    }
+
+    return { type: 'element', name, attrs, children }
+  }
+
+  // Parse the full document
+  const nodes = []
+  while (pos < src.length) {
+    skipWs()
+    if (pos >= src.length) break
+    const node = parseNode()
+    if (node) nodes.push(node)
+  }
+
+  return nodes.find(n => n.type === 'element') || null
+}
+
+// ── DOM Helpers ───────────────────────────────────────────────────────────────
+
+// Read an attribute, trying plain name, then xl: and xml: prefixed variants.
+function attr(node, name) {
+  if (!node || !node.attrs) return null
+  return node.attrs[name]
+    ?? node.attrs['xl:' + name]
+    ?? node.attrs['xml:' + name]
+    ?? null
+}
+
+function childElements(node, ...tags) {
+  if (!node || !node.children) return []
+  const kids = node.children.filter(c => c.type === 'element')
+  return tags.length ? kids.filter(c => tags.includes(c.name)) : kids
+}
+
+function firstChild(node, ...tags) {
+  return childElements(node, ...tags)[0] ?? null
+}
+
+// Recursively extract all text content.
+function textContent(node) {
+  if (!node) return ''
+  if (node.type === 'text') return node.text
+  return (node.children ?? []).map(textContent).join('')
+}
+
+// ── Typst Escaping ────────────────────────────────────────────────────────────
+
+// Escape special Typst markup characters in normal text context.
+function esc(s) {
+  if (!s) return ''
+  return s
+    .replace(/\\/g, '\\\\')
+    .replace(/#/g,  '\\#')
+    .replace(/\$/g, '\\$')
+    .replace(/@/g,  '\\@')
+    .replace(/</g,  '\\<')
+    .replace(/>/g,  '\\>')
+    .replace(/\[/g, '\\[')
+    .replace(/\]/g, '\\]')
+    .replace(/\*/g, '\\*')
+    .replace(/_/g,  '\\_')
+    .replace(/`/g,  '\\`')
+}
+
+// Escape inside a Typst double-quoted string literal.
+function escStr(s) {
+  if (!s) return ''
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+// Decode percent-encoded characters in an image fileref so Typst receives a
+// plain filesystem path (e.g. "foo%20bar.png" → "foo bar.png").
+function decodeFileref(s) {
+  if (!s) return ''
+  try { return decodeURIComponent(s) }
+  catch { return s }
+}
+
+// Convert a DocBook contentwidth/contentdepth value to a Typst length string.
+// Values may be bare integers (pixels), floats with a trailing dot (e.g. "96."),
+// or numbers with an explicit unit suffix (px, pt, mm, cm, in, em, pc, %).
+// Returns null when the value is non-numeric or otherwise unusable.
+function parseImageDim(value) {
+  if (!value) return null
+  const m = String(value).match(/^(\d+(?:\.\d*)?)(\s*(%|px|pt|mm|cm|in|em|pc))?$/i)
+  if (!m) return null
+  const num = parseFloat(m[1])
+  if (!isFinite(num) || num <= 0) return null
+  const unit = (m[3] || '').toLowerCase()
+  switch (unit) {
+    case '%':  return `${num}%`
+    case 'pt': return `${num}pt`
+    case 'mm': return `${num}mm`
+    case 'cm': return `${num}cm`
+    case 'in': return `${num}in`
+    case 'em': return `${num}em`
+    case 'pc': return `${num * 12}pt` // 1 pica = 12 points
+    case 'px':
+    case '':   return `${(num * 0.75).toFixed(2)}pt` // px → pt at 96 dpi
+    default:   return null
+  }
+}
+
+// Search the assembled AsciiDoc source for the first line that references the
+// given image filename, returning a human-readable "line N: <text>" string, or
+// null when the source file is absent or the image is not found there.
+let _adocLines = null
+function findAdocImageLine(fileref) {
+  if (!fileref) return null
+  try {
+    if (!_adocLines) {
+      _adocLines = fs.readFileSync(adocSourceFile, 'utf-8').split('\n')
+    }
+  } catch { return null }
+  const base = path.basename(fileref)
+  for (let i = 0; i < _adocLines.length; i++) {
+    if (_adocLines[i].includes(base)) {
+      return `line ${i + 1}: ${_adocLines[i].trim()}`
+    }
+  }
+  return null
+}
+
+// Build the Typst image() argument string for a given <imagedata> element,
+// appending width: and/or height: when contentwidth/contentdepth are present.
+// Throws when contentwidth contains a non-numeric value that cannot be parsed
+// as a dimension, reporting the offending image and its AsciiDoc source line.
+function imageDataArgs(imgdata) {
+  const rawW    = attr(imgdata, 'contentwidth')
+  const rawH    = attr(imgdata, 'contentdepth')
+  const fileref = decodeFileref(attr(imgdata, 'fileref') || '')
+
+  if (rawW) {
+    const w = parseImageDim(rawW)
+    if (w === null) {
+      const loc = findAdocImageLine(fileref)
+      const where = loc ? `\n  ${adocSourceFile} ${loc}` : `\n  image: ${fileref}`
+      throw new Error(`Invalid contentwidth value "${rawW}"${where}`)
+    }
+  }
+
+  const w = parseImageDim(rawW)
+  const h = parseImageDim(rawH)
+  const parts = []
+  if (w) parts.push(`width: ${w}`)
+  if (h) parts.push(`height: ${h}`)
+  return parts.length ? ', ' + parts.join(', ') : ''
+}
+
+// Sanitize a DocBook xml:id into a valid Typst label (letters, digits, - _ . : /).
+function sanitizeLabel(id) {
+  if (!id) return ''
+  return id.replace(/[^a-zA-Z0-9\-_.:/]/g, '-')
+}
+
+// ── ID → title index ──────────────────────────────────────────────────────────
+
+// Maps xml:id values to their section/element title text, built before conversion.
+const idTitles = new Map()
+
+function buildIdIndex(node) {
+  if (!node || node.type !== 'element') return
+  const id = attr(node, 'id')
+  if (id) {
+    const titleNode = firstChild(node, 'title')
+    if (titleNode) {
+      // Section/figure/table: title is a child element.
+      idTitles.set(id, textContent(titleNode).trim())
+    } else if (node.name === 'bridgehead') {
+      // Bridgehead: the element's own text content is the title.
+      const t = textContent(node).trim()
+      if (t) idTitles.set(id, t)
+    }
+  }
+  for (const child of (node.children ?? [])) buildIdIndex(child)
+}
+
+// ── Converter ─────────────────────────────────────────────────────────────────
+
+function convert(root) {
+  buildIdIndex(root)
+  const parts = []
+
+  // Skip <info> — title is provided by the preamble in asciidoc-typst-pdf.js.
+  for (const child of (root.children ?? [])) {
+    if (child.type !== 'element') continue
+    if (child.name === 'info') continue
+    emitBlock(child, parts, 0)
+  }
+
+  return parts.join('').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+}
+
+// ── Block emitter ─────────────────────────────────────────────────────────────
+
+function emitBlock(node, out, depth) {
+  if (!node) return
+
+  if (node.type === 'text') {
+    const t = node.text.trim()
+    if (t) out.push(esc(t) + '\n\n')
+    return
+  }
+
+  const tag = node.name
+
+  switch (tag) {
+    case 'book':
+    case 'article':
+      for (const c of childElements(node)) {
+        if (c.name === 'info') continue
+        emitBlock(c, out, depth)
+      }
+      break
+
+    case 'chapter':
+    case 'part':
+      emitSection(node, out, 2)
+      break
+
+    case 'section':
+    case 'appendix':
+    case 'preface':
+      emitSection(node, out, depth + 1)
+      break
+
+    case 'simpara':
+    case 'para': {
+      // A <simpara> or <para> containing only <?asciidoc-pagebreak?> emits a page break.
+      if ((node.children ?? []).some(c => c.type === 'pi' && c.target === 'asciidoc-pagebreak')) {
+        out.push('#pagebreak()\n\n')
+        break
+      }
+      // A para may wrap block-level elements (e.g. <informaltable>, <figure>).
+      // When it does, emit each block child as a block and collect inline runs
+      // as separate paragraphs, rather than calling emitInline() on the whole node.
+      const BLOCK_TAGS = new Set([
+        'table', 'informaltable', 'figure', 'informalfigure',
+        'itemizedlist', 'orderedlist', 'variablelist',
+        'programlisting', 'screen', 'literallayout',
+        'note', 'tip', 'important', 'caution', 'warning',
+      ])
+      const children = node.children ?? []
+      const hasBlock = children.some(c => c.type === 'element' && BLOCK_TAGS.has(c.name))
+      if (hasBlock) {
+        let inlineRun = []
+        const flushInline = () => {
+          const t = inlineRun.join('').trim()
+          if (t) out.push(t + '\n\n')
+          inlineRun = []
+        }
+        for (const c of children) {
+          if (c.type === 'element' && BLOCK_TAGS.has(c.name)) {
+            flushInline()
+            emitBlock(c, out, depth)
+          } else {
+            inlineRun.push(emitInline(c))
+          }
+        }
+        flushInline()
+      } else {
+        out.push(emitInline(node).trim() + '\n\n')
+      }
+      break
+    }
+
+    case 'formalpara': {
+      const t    = firstChild(node, 'title')
+      const body = firstChild(node, 'para', 'simpara')
+      const titleStr = t    ? `#strong[${emitInline(t).trim()}]` : ''
+      const bodyStr  = body ? emitInline(body).trim()     : ''
+      out.push([titleStr, bodyStr].filter(Boolean).join('\n\n') + '\n\n')
+      break
+    }
+
+    case 'itemizedlist':
+      emitItemizedList(node, out, 0)
+      out.push('\n')
+      break
+
+    case 'orderedlist':
+      emitOrderedList(node, out, 0)
+      out.push('\n')
+      break
+
+    case 'variablelist':
+      emitVariableList(node, out)
+      break
+
+    case 'note':
+    case 'tip':
+    case 'important':
+    case 'caution':
+    case 'warning': {
+      emitAdmonition(node, out, admonitionKind(tag))
+      break
+    }
+
+    case 'figure':
+      emitFigure(node, out)
+      break
+
+    case 'informalfigure':
+      emitFigure(node, out)
+      break
+
+    case 'informaltable':
+    case 'table':
+      emitTable(node, out)
+      break
+
+    case 'programlisting':
+    case 'screen':
+    case 'literallayout':
+      emitListing(node, out)
+      break
+
+    case 'calloutlist':
+      emitCalloutList(node, out)
+      break
+
+    case 'informalexample':
+    case 'example':
+      for (const c of childElements(node)) emitBlock(c, out, depth)
+      break
+
+    case 'bridgehead': {
+      const renderas = attr(node, 'renderas') || 'sect3'
+      const level    = parseInt(renderas.replace(/\D+/, ''), 10) || 3
+      const xmlId    = attr(node, 'id')
+      const labelPart = xmlId ? ` <${sanitizeLabel(xmlId)}>` : ''
+      // Use #heading() to suppress TOC entry
+      const title = emitInline(node).trim()
+      out.push(`#heading(level: ${level}, outlined: false)[${title}]${labelPart}\n\n`)
+      break
+    }
+
+    case 'anchor': {
+      const xmlId = attr(node, 'id')
+      if (xmlId) out.push(`#[#metadata("") <${sanitizeLabel(xmlId)}>]\n\n`)
+      break
+    }
+
+    case 'blockquote':
+    case 'quote': {
+      const content = childElements(node, 'para', 'simpara')
+        .map(c => emitInline(c).trim())
+        .join('\n\n')
+      out.push(`#quote(block: true)[\n${content}\n]\n\n`)
+      break
+    }
+
+    case 'sidebar':
+    case 'abstract': {
+      const title = firstChild(node, 'title')
+      const inner = []
+      for (const c of childElements(node)) {
+        if (c.name === 'title') continue
+        emitBlock(c, inner, depth)
+      }
+      const titleStr = title ? `#strong[${emitInline(title).trim()}]\n\n` : ''
+      out.push(`#block(stroke: 0.5pt + gray, inset: 1em, radius: 4pt, width: 100%)[\n${titleStr}${inner.join('')}]\n\n`)
+      break
+    }
+
+    // Elements that appear in block context but are really inline wrappers
+    case 'title':
+    case 'info':
+    case 'date':
+      break // handled by their parent
+
+    default:
+      // Fallback: recurse into children
+      for (const c of (node.children ?? [])) {
+        if (c.type === 'element') emitBlock(c, out, depth)
+        else if (c.type === 'text' && c.text.trim()) {
+          out.push(esc(c.text.trim()) + '\n\n')
+        }
+      }
+  }
+}
+
+// ── Section emitter ───────────────────────────────────────────────────────────
+
+function emitSection(node, out, level) {
+  const titleNode = firstChild(node, 'title')
+  const xmlId     = attr(node, 'id')
+
+  if (titleNode) {
+    const effectiveLevel = useTheme ? level : Math.max(1, level - 1)
+    const hashes    = '='.repeat(Math.min(effectiveLevel, 6))
+    const titleText = emitInline(titleNode).trim()
+    out.push(`${hashes} ${titleText}\n`)
+    if (xmlId) out.push(`<${sanitizeLabel(xmlId)}>\n`)
+    out.push('\n')
+  }
+
+  for (const child of childElements(node)) {
+    if (child.name === 'title') continue
+    if (child.name === 'section' || child.name === 'appendix') {
+      emitSection(child, out, level + 1)
+    } else {
+      emitBlock(child, out, level)
+    }
+  }
+}
+
+// ── List emitters ─────────────────────────────────────────────────────────────
+
+function emitItemizedList(node, out, indent) {
+  for (const item of childElements(node, 'listitem')) {
+    const lines = emitListItem(item, '-', indent)
+    out.push(lines + '\n')
+  }
+}
+
+function emitOrderedList(node, out, indent) {
+  for (const item of childElements(node, 'listitem')) {
+    const lines = emitListItem(item, '+', indent)
+    out.push(lines + '\n')
+  }
+}
+
+function emitListItem(item, marker, indent) {
+  const pad    = '  '.repeat(indent)
+  const subpad = '  '.repeat(indent + 1)
+  const parts  = []
+
+  for (const c of childElements(item)) {
+    if (c.name === 'simpara' || c.name === 'para') {
+      parts.push(emitInline(c).trim())
+    } else if (c.name === 'itemizedlist') {
+      const sub = []
+      for (const si of childElements(c, 'listitem')) {
+        sub.push(subpad + emitListItem(si, '-', indent + 1))
+      }
+      parts.push(sub.join('\n'))
+    } else if (c.name === 'orderedlist') {
+      const sub = []
+      for (const si of childElements(c, 'listitem')) {
+        sub.push(subpad + emitListItem(si, '+', indent + 1))
+      }
+      parts.push(sub.join('\n'))
+    } else if (c.name === 'programlisting' || c.name === 'screen') {
+      const lang = attr(c, 'language') || ''
+      parts.push(`\`\`\`${lang}\n${listingText(c)}\n\`\`\``)
+    } else if (c.name === 'figure' || c.name === 'informalfigure') {
+      const s = figureString(c)
+      if (s) parts.push(s)
+    } else if (c.name === 'table' || c.name === 'informaltable') {
+      parts.push(tableString(c))
+    } else {
+      const adm = admonitionKind(c.name)
+      if (adm) {
+        parts.push(admonitionBlock(c, adm))
+      } else {
+        const t = textContent(c).trim()
+        if (t) parts.push(esc(t))
+      }
+    }
+  }
+
+  if (!parts.length) return `${pad}${marker} `
+
+  const first = (parts.shift() || '').replace(/\n/g, '\n' + subpad)
+  const rest  = parts.map(p => subpad + p.replace(/\n/g, '\n' + subpad)).join('\n')
+  return `${pad}${marker} ${first}${rest ? '\n' + rest : ''}`
+}
+
+function emitVariableList(node, out) {
+  for (const entry of childElements(node, 'varlistentry')) {
+    const termNode  = firstChild(entry, 'term')
+    const itemNode  = firstChild(entry, 'listitem')
+    const term      = termNode ? emitInline(termNode).trim() : ''
+    const def       = itemNode
+      ? childElements(itemNode, 'simpara', 'para')
+          .map(c => emitInline(c).trim())
+          .join(' ')
+      : ''
+    out.push(`/ ${term}: ${def}\n\n`)
+  }
+}
+
+// ── Admonition emitter ────────────────────────────────────────────────────────
+
+// Returns the Typst block string for an admonition node (without trailing newlines).
+function admonitionBlock(node, kind) {
+  const inner = []
+
+  for (const c of childElements(node)) {
+    if (c.name === 'title') continue // styling handled by theme
+    if (c.name === 'simpara' || c.name === 'para') {
+      inner.push(emitInline(c).trim())
+    } else if (c.name === 'itemizedlist') {
+      for (const item of childElements(c, 'listitem')) {
+        inner.push(emitListItem(item, '-', 0))
+      }
+    } else if (c.name === 'orderedlist') {
+      for (const item of childElements(c, 'listitem')) {
+        inner.push(emitListItem(item, '+', 0))
+      }
+    } else if (c.name === 'figure' || c.name === 'informalfigure') {
+      const s = figureString(c)
+      if (s) inner.push(s)
+    } else {
+      const t = textContent(c).trim()
+      if (t) inner.push(esc(t))
+    }
+  }
+
+  const body = inner.join('\n\n')
+  if (useTheme) return `#admonition("${kind}")[\n${body}\n]`
+  const label = kind.charAt(0).toUpperCase() + kind.slice(1)
+  return `#block(stroke: 0.5pt, inset: 8pt)[#strong[${esc(label)}:] ${body}]`
+}
+
+function emitAdmonition(node, out, kind) {
+  out.push(admonitionBlock(node, kind) + '\n\n')
+}
+
+// Return the admonition kind string for a given tag name, or null if not an admonition.
+function admonitionKind(tag) {
+  switch (tag) {
+    case 'note':      return 'note'
+    case 'tip':       return 'tip'
+    case 'important': return 'important'
+    case 'caution':   return 'caution'
+    case 'warning':   return 'warning'
+    default:          return null
+  }
+}
+
+// ── Figure / image emitter ────────────────────────────────────────────────────
+
+// Extract the plain-text alt string from <mediaobject><textobject><phrase>.
+function figureAlt(mo) {
+  if (!mo) return ''
+  const to = firstChild(mo, 'textobject')
+  if (!to) return ''
+  const phrase = firstChild(to, 'phrase')
+  return (phrase ? textContent(phrase) : textContent(to)).trim()
+}
+
+// Return the alt: named argument for image(), or empty string when none.
+function imageAltArg(alt) {
+  return alt ? `, alt: "${escStr(alt)}"` : ''
+}
+
+// Return the Typst caption/alt arguments for #figure().
+// captionText is the figure title (formal) or phrase alt text (informal).
+// alt is the image accessibility text.
+function figureAttrs(captionText, alt, formal) {
+  const cap = captionText ? esc(captionText) : ''
+  return `  caption: [${cap}],\n` +
+         (alt ? `  alt: "${escStr(alt)}",\n` : '')
+}
+
+// Return the Typst #figure(...) string for a <figure> or <informalfigure>
+// node, or null if the node lacks a usable image reference.
+function figureString(node) {
+  const formal = node.name === 'figure'
+  const mo     = firstChild(node, 'mediaobject', 'inlinemediaobject')
+  if (!mo) return null
+
+  const io      = firstChild(mo, 'imageobject')
+  if (!io) return null
+
+  const imgdata = firstChild(io, 'imagedata')
+  if (!imgdata) return null
+
+  const fileref = decodeFileref(attr(imgdata, 'fileref'))
+  if (!fileref) return null
+
+  const alt = figureAlt(mo)
+  // Prefer the figure's <title> element as the caption; fall back to alt text.
+  const titleNode = formal ? firstChild(node, 'title') : null
+  const captionText = (titleNode ? textContent(titleNode).trim() : null) || alt
+
+  return (
+    `#figure(\n` +
+    `  image("${escStr(fileref)}"${imageDataArgs(imgdata)}${imageAltArg(alt)}),\n` +
+    figureAttrs(captionText, alt, formal) +
+    `)`
+  )
+}
+
+function emitFigure(node, out) {
+  const s = figureString(node)
+  if (s) out.push(s + '\n\n')
+}
+
+// ── Table emitter ─────────────────────────────────────────────────────────────
+
+function tableString(node) {
+  const titleNode = firstChild(node, 'title')
+  const tgroup    = firstChild(node, 'tgroup')
+  if (!tgroup) return
+
+  const colspecs  = childElements(tgroup, 'colspec')
+  const thead     = firstChild(tgroup, 'thead')
+  const tbody     = firstChild(tgroup, 'tbody')
+
+  // Build column widths from colspec/@colwidth, e.g. "50*" → "1fr"
+  const numCols   = parseInt(attr(tgroup, 'cols') || '0', 10) || colspecs.length || 2
+  const widths    = colspecs.map(c => {
+    const w = attr(c, 'colwidth') || '1*'
+    // proportional widths ("50*") → fractional
+    const match = w.match(/^([\d.]+)\*/)
+    return match ? `${match[1]}fr` : w
+  })
+  while (widths.length < numCols) widths.push('1fr')
+
+  const colsExpr = '(' + widths.join(', ') + ')'
+  const cells    = []
+
+  if (thead) {
+    const headerRow = firstChild(thead, 'row')
+    if (headerRow) {
+      cells.push('  table.header(')
+      for (const e of childElements(headerRow, 'entry')) {
+        const align   = attr(e, 'align') || 'left'
+        const content = emitCellContent(e)
+        cells.push(`    table.cell(align: ${align})[${content}],`)
+      }
+      cells.push('  ),')
+    }
+  }
+
+  if (tbody) {
+    for (const row of childElements(tbody, 'row')) {
+      for (const e of childElements(row, 'entry')) {
+        const align   = attr(e, 'align') || 'left'
+        const content = emitCellContent(e)
+        cells.push(`  table.cell(align: ${align})[${content}],`)
+      }
+    }
+  }
+
+  // Build the table call without a leading `#` so it can be used either as a
+  // standalone statement (#table(...)) or as an argument to #figure() where
+  // the `#` is not valid (Typst code mode).
+  const tableCall =
+    `table(\n` +
+    `  columns: ${colsExpr},\n` +
+    `  stroke: (_, y) => (bottom: if y == 0 { 0.5pt + black } else { 0.5pt + luma(200) }),\n` +
+    cells.join('\n') + '\n' +
+    `)`
+
+  const xmlId   = attr(node, 'id')
+  const labelSuffix = xmlId ? ` <${sanitizeLabel(xmlId)}>` : ''
+
+  if (titleNode) {
+    const cap = emitInline(titleNode).trim()
+    return `#figure(\n  ${tableCall},\n  caption: [${cap}],\n  kind: table,\n)${labelSuffix}`
+  } else {
+    return `#figure(\n  ${tableCall},\n  caption: none,\n  kind: table,\n  numbering: none,\n)${labelSuffix}`
+  }
+}
+
+function emitTable(node, out) {
+  out.push(tableString(node) + '\n\n')
+}
+
+// Render the content of a table cell. Cells can hold simpara, itemizedlist,
+// informalfigure, and other block elements.
+function emitCellContent(entry) {
+  const parts = []
+
+  for (const c of (entry.children ?? [])) {
+    if (c.type === 'text') {
+      const t = c.text.trim()
+      if (t) parts.push(esc(t))
+    } else if (c.type === 'element') {
+      switch (c.name) {
+        case 'simpara':
+        case 'para':
+          parts.push(emitInline(c).trim())
+          break
+        case 'itemizedlist':
+          for (const item of childElements(c, 'listitem')) {
+            parts.push(emitListItem(item, '-', 0))
+          }
+          break
+        case 'orderedlist':
+          for (const item of childElements(c, 'listitem')) {
+            parts.push(emitListItem(item, '+', 0))
+          }
+          break
+        case 'figure':
+        case 'informalfigure': {
+          const s = figureString(c)
+          if (s) parts.push(s)
+          break
+        }
+        case 'programlisting':
+        case 'screen': {
+          const lang = attr(c, 'language') || ''
+          parts.push(`\`\`\`${lang}\n${listingText(c)}\n\`\`\``)
+          break
+        }
+        case 'table':
+        case 'informaltable':
+          parts.push(tableString(c))
+          break
+        default: {
+          const adm = admonitionKind(c.name)
+          if (adm) {
+            parts.push(admonitionBlock(c, adm))
+          } else {
+            const t = textContent(c).trim()
+            if (t) parts.push(esc(t))
+          }
+        }
+      }
+    }
+  }
+
+  return parts.join('\n\n')
+}
+
+// ── Listing emitter ───────────────────────────────────────────────────────────
+
+// Returns the Unicode circled-number character for n (1–20), used as callout
+// markers in code blocks. The Typst template replaces these with SVG circles.
+function circledNumber(n) {
+  if (n >= 1 && n <= 20) return String.fromCodePoint(0x245F + n) // ①=U+2460 … ⑳=U+2473
+  return `(${n})` // fallback for n > 20
+}
+
+// Build the code string for a <programlisting> or <screen> node, substituting
+// any inline <co> child elements with Unicode circled-number callout markers.
+function listingText(node) {
+  let code = ''
+  for (const child of (node.children ?? [])) {
+    if (child.type === 'text') {
+      code += child.text
+    } else if (child.type === 'element' && child.name === 'co') {
+      const xmlId = attr(child, 'id')
+      const match = xmlId && xmlId.match(/(\d+)$/)
+      const n = match ? parseInt(match[1], 10) : 0
+      if (n >= 1) code += circledNumber(n)
+    }
+    // Other element children within programlisting are ignored.
+  }
+  return code
+}
+
+function emitListing(node, out) {
+  const lang = attr(node, 'language') || ''
+  out.push(`\`\`\`${lang}\n${listingText(node)}\n\`\`\`\n\n`)
+}
+
+// ── Callout list emitter ──────────────────────────────────────────────────────
+
+function emitCalloutList(node, out) {
+  const callouts = childElements(node, 'callout')
+  if (!callouts.length) return
+
+  for (const callout of callouts) {
+    const arearefs = attr(callout, 'arearefs') || ''
+    const match = arearefs.match(/(\d+)$/)
+    const n = match ? parseInt(match[1], 10) : 0
+    if (!n) continue
+
+    const descParts = []
+    for (const c of childElements(callout)) {
+      if (c.name === 'para' || c.name === 'simpara') {
+        descParts.push(emitInline(c).trim())
+      } else if (c.name === 'itemizedlist') {
+        const sub = []
+        emitItemizedList(c, sub, 0)
+        descParts.push(sub.join(''))
+      } else if (c.name === 'orderedlist') {
+        const sub = []
+        emitOrderedList(c, sub, 0)
+        descParts.push(sub.join(''))
+      }
+    }
+
+    const desc = descParts.join('\n\n').trim()
+    if (useTheme) {
+      out.push(`#callout-item(${n})[\n${desc}\n]\n`)
+    } else {
+      out.push(`${n}. ${desc}\n\n`)
+    }
+  }
+  out.push('\n')
+}
+
+// ── Inline emitter ────────────────────────────────────────────────────────────
+//
+// Processes a node and returns a Typst inline string.
+
+function emitInline(node) {
+  if (!node) return ''
+  if (node.type === 'text') return esc(node.text)
+
+  const tag  = node.name
+  const kids = () => (node.children ?? []).map(emitInline).join('')
+
+  switch (tag) {
+    // Pass-through wrappers
+    case 'title':
+    case 'simpara':
+    case 'para':
+    case 'phrase':
+    case 'term':
+      return kids()
+
+    // Emphasis / strong
+    case 'emphasis': {
+      const role = attr(node, 'role') || ''
+      const content = kids()
+      if (role.includes('strong')) return `#strong[${content}]`
+      return `#emph[${content}]`
+    }
+
+    // UI element — <literal role="ui ui-xxxx">
+    case 'literal': {
+      const role = attr(node, 'role') || ''
+      if (role.startsWith('ui ui-')) {
+        if (useTheme) {
+          const kind = escStr(role.slice('ui ui-'.length))
+          return `#ui("${kind}")[${kids()}]`
+        }
+        return `#strong[${kids()}]`
+      }
+      // Not a UI element — fall through to inline-code rendering
+      const rawLit = textContent(node)
+      if (rawLit.includes('`')) return `#raw("${escStr(rawLit)}")`
+      return `\`${rawLit}\``
+    }
+
+    // Inline code — strip role attributes, just render as code
+    case 'code':
+    case 'computeroutput':
+    case 'filename':
+    case 'systemitem':
+    case 'classname':
+    case 'methodname':
+    case 'varname':
+    case 'constant': {
+      const raw = textContent(node)
+      // Avoid nested backticks
+      if (raw.includes('`')) return `#raw("${escStr(raw)}")`
+      return `\`${raw}\``
+    }
+
+    // Hyperlink
+    case 'link':
+    case 'ulink': {
+      const href = attr(node, 'href') ?? ''
+      const text = kids()
+      if (!href) return text
+      if (text.trim() === href) return `#link("${escStr(href)}")`
+      return `#link("${escStr(href)}")[${text}]`
+    }
+
+    // Cross-reference — use #link(<label>)[title] because @label requires heading numbering
+    case 'xref': {
+      const linkend = attr(node, 'linkend') ?? ''
+      if (!linkend) return ''
+      const label = sanitizeLabel(linkend)
+      // Look up the section title; fall back to a humanised version of the id.
+      const title = idTitles.get(linkend)
+        ?? linkend.replace(/.*[-_]([^-_]+)$/, '$1').replace(/[-_]/g, ' ')
+      return `#link(<${label}>)[${esc(title)}]`
+    }
+
+    // UI button — bold with square brackets via theme function
+    case 'guibutton':
+      if (useTheme) return `#guibutton("${escStr(textContent(node))}")`
+      return `#strong[${kids()}]`
+
+    // UI label/icon — render as bold
+    case 'guilabel':
+    case 'guiicon':
+      return `#strong[${kids()}]`
+
+    // Menu navigation elements — menuchoice wraps all items in bold,
+    // joining guimenu/guisubmenu/guimenuitem with a filled right-pointing triangle.
+    case 'guimenu':
+    case 'guisubmenu':
+    case 'guimenuitem':
+      return kids()
+
+    case 'menuchoice': {
+      const items = childElements(node)
+        .filter(c => ['guimenu','guisubmenu','guimenuitem','shortcut'].includes(c.name))
+        .map(emitInline)
+      const sep = ' #text(size: 0.75em)[\u25b6] '
+      return `#strong[${items.join(sep)}]`
+    }
+
+    // Keyboard keys
+    case 'keycap': {
+      const raw = textContent(node)
+      if (useTheme) return `#keycap("${escStr(raw)}")`
+      return raw.includes('`') ? `#raw("${escStr(raw)}")` : `\`${raw}\``
+    }
+
+    case 'keycombo': {
+      const keys = childElements(node, 'keycap').map(c => {
+        const raw = textContent(c)
+        if (useTheme) return `#keycap("${escStr(raw)}")`
+        return raw.includes('`') ? `#raw("${escStr(raw)}")` : `\`${raw}\``
+      })
+      return keys.join('+')
+    }
+
+    // Inline quotation
+    case 'quote':
+      return `"${kids()}"`
+
+    // Footnote
+    case 'footnote': {
+      const content = childElements(node, 'para', 'simpara')
+        .map(c => emitInline(c).trim())
+        .join(' ')
+      return `#footnote[${content}]`
+    }
+
+    // Superscript / subscript
+    case 'superscript':
+      return `#super[${kids()}]`
+    case 'subscript':
+      return `#sub[${kids()}]`
+
+    // Inline image
+    case 'inlinemediaobject': {
+      const imobj   = firstChild(node, 'imageobject')
+      const imdata  = imobj ? firstChild(imobj, 'imagedata') : null
+      const fileref = decodeFileref(imdata ? attr(imdata, 'fileref') : null)
+      if (fileref) {
+        const alt = figureAlt(node)
+        return `#box(image("${escStr(fileref)}", height: 1em${imageAltArg(alt)}))`
+      }
+      return ''
+    }
+
+    // Ignored inline wrappers
+    case 'anchor':
+    case 'textobject':
+    case 'imageobject':
+    case 'mediaobject':
+      return ''
+
+    // Inline URI
+    case 'uri':
+      return `#link("${escStr(textContent(node))}")`
+
+    // Definition-list term (when nested inline)
+    case 'varlistentry':
+      return kids()
+
+    // Generic fallback — pass children through
+    default:
+      return kids()
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const src = fs.readFileSync(inputFile, 'utf-8')
+
+let root
+try {
+  root = parseXml(src)
+} catch (err) {
+  console.error(`XML parse error: ${err.message}`)
+  process.exit(1)
+}
+
+if (!root) {
+  console.error('Error: no root element found in XML.')
+  process.exit(1)
+}
+
+const typst = convert(root)
+fs.writeFileSync(outputFile, typst, 'utf-8')
+console.log(`Wrote ${outputFile}`)