clyops-doc 0.0.0-stage → 0.7.0

package/src/render.ts

@@ -0,0 +1,187 @@
+// The document (model.ts) as a man page, Markdown or HTML.
+import type { Block, Doc } from './model.js';
+
+/** Output formats. */
+export type Format = 'man' | 'markdown' | 'html';
+
+// ---------------------------------------------------------------------------
+// man(7): plain .TH .SH .SS .PP .TP .nf/.fi macros, which groff and mandoc both render.
+// ---------------------------------------------------------------------------
+
+/** Text for a troff line: backslashes and dashes escaped, a leading `.` or `'` made literal. */
+export function troff(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => {
+      const escaped = line.replace(/\\/g, '\\e').replace(/-/g, '\\-');
+      return /^[.']/.test(escaped) ? `\\&${escaped}` : escaped;
+    })
+    .join('\n');
+}
+
+/** A macro argument: escaped, and quoted so spaces stay in it. */
+function arg(text: string): string {
+  return `"${troff(text).replace(/"/g, '\\(dq')}"`;
+}
+
+function manBlock(b: Block): string[] {
+  switch (b.kind) {
+    case 'p':
+      return ['.PP', troff(b.text)];
+    case 'h':
+      return [`.SS ${arg(b.text)}`];
+    case 'pre':
+      return ['.PP', '.nf', '.RS 4', troff(b.text), '.RE', '.fi'];
+    case 'dl':
+      return b.items.flatMap((i) => ['.TP', `\\fB${troff(i.term)}\\fR`, troff(i.text)]);
+    case 'refs':
+      return ['.PP', ...b.items.map((r, n) => `.BR ${arg(r.page)} ${arg(`(${r.section})${n < b.items.length - 1 ? ',' : ''}`)}`)];
+  }
+}
+
+/** The document as a man(7) page. */
+export function renderMan(doc: Doc): string {
+  const title = doc.page.toUpperCase().replace(/\s+/g, '-');
+  const lines = [
+    `.\\" Generated by clyops-doc from ${doc.name} --help-json-schema.`,
+    `.TH ${arg(title)} ${arg(doc.section)} ${arg(doc.date)} ${arg([doc.name, doc.version].filter(Boolean).join(' '))} ${arg('User Commands')}`,
+  ];
+  for (const s of doc.sections) {
+    lines.push(`.SH ${arg(s.title)}`);
+    // NAME is one line, "name \- summary", without a paragraph macro (man(7)).
+    if (s.title === 'NAME') {
+      lines.push(troff(`${doc.page}${doc.summary ? ` - ${doc.summary}` : ''}`));
+      continue;
+    }
+    for (const b of s.blocks) lines.push(...manBlock(b));
+  }
+  return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Markdown (CommonMark)
+// ---------------------------------------------------------------------------
+
+/**
+ * Text that renders as itself in CommonMark: characters that can start markup escaped, and nothing
+ * else, so the Markdown stays readable (`DRY_RUN`, `(default: 1)`).
+ */
+export function markdownText(text: string): string {
+  return text
+    .split('\n')
+    .map((line) =>
+      line
+        .replace(/[\\`*[\]<>|]/g, '\\$&')
+        // _ only emphasises at a word boundary.
+        .replace(/(^|[^A-Za-z0-9])_|_(?=[^A-Za-z0-9]|$)/g, (m) => m.replace('_', '\\_'))
+        // A block marker at the start of a line: a heading, quote, list item or rule.
+        .replace(/^(\s*)([#>+=-]|\d+[.)])/, '$1\\$2'))
+    .join('\n');
+}
+
+/** Inline code that may itself contain backticks. */
+function code(text: string): string {
+  const run = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+  const fence = '`'.repeat(run);
+  return run > 1 ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
+}
+
+function fenced(text: string): string[] {
+  const run = Math.max(2, ...(text.match(/`+/g) ?? []).map((m) => m.length)) + 1;
+  const fence = '`'.repeat(run);
+  return [fence, text, fence];
+}
+
+function markdownBlock(b: Block): string[] {
+  switch (b.kind) {
+    case 'p':
+      return [markdownText(b.text), ''];
+    case 'h':
+      return [`### ${code(b.text)}`, ''];
+    case 'pre':
+      return [...fenced(b.text), ''];
+    case 'dl':
+      return [...b.items.map((i) => `- ${code(i.term)}: ${markdownText(i.text)}`), ''];
+    case 'refs':
+      return [b.items.map((r) => `[${markdownText(`${r.page}(${r.section})`)}](${encodeURI(r.page)}.md)`).join(', '), ''];
+  }
+}
+
+/** The first line of a Markdown page: a comment, invisible when rendered, saying it is generated. */
+export const MARKDOWN_MARKER = '<!-- Generated by clyops-doc from --help-json-schema. Do not edit; regenerate instead. -->';
+
+/** The document as Markdown. */
+export function renderMarkdown(doc: Doc): string {
+  const lines = [MARKDOWN_MARKER, '', `# ${code(doc.name)}`, ''];
+  const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+  if (header) lines.push(`_${markdownText(header)}_`, '');
+  for (const s of doc.sections) {
+    lines.push(`## ${s.title}`, '');
+    for (const b of s.blocks) lines.push(...markdownBlock(b));
+  }
+  return lines.join('\n').replace(/\n+$/, '\n');
+}
+
+// ---------------------------------------------------------------------------
+// HTML: one standalone page, everything escaped.
+// ---------------------------------------------------------------------------
+
+/** Text with HTML's special characters escaped. */
+export function htmlText(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string);
+}
+
+const slug = (text: string) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+function htmlBlock(b: Block): string {
+  switch (b.kind) {
+    case 'p':
+      return `<p>${htmlText(b.text)}</p>`;
+    case 'h':
+      return `<h3 id="${slug(b.text)}"><code>${htmlText(b.text)}</code></h3>`;
+    case 'pre':
+      return `<pre><code>${htmlText(b.text)}</code></pre>`;
+    case 'dl':
+      return `<dl>\n${b.items.map((i) => `<dt><code>${htmlText(i.term)}</code></dt>\n<dd>${htmlText(i.text)}</dd>`).join('\n')}\n</dl>`;
+    case 'refs':
+      return `<p>${b.items.map((r) => `<a href="${htmlText(encodeURI(r.page))}.html"><code>${htmlText(r.page)}</code>(${htmlText(r.section)})</a>`).join(', ')}</p>`;
+  }
+}
+
+const STYLE = `body{font:16px/1.55 system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;color:#1d1f21;background:#fff}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em}
+pre{background:#f4f5f6;padding:.8rem 1rem;overflow-x:auto;border-radius:4px}
+h2{margin-top:2rem;font-size:1.05rem;letter-spacing:.04em}
+dt{margin-top:.6rem;font-weight:600}dd{margin:.2rem 0 0 1.5rem}
+.meta{color:#5b6168}
+@media (prefers-color-scheme:dark){body{color:#e3e5e8;background:#17191c}pre{background:#23262a}.meta{color:#9aa1a9}}`;
+
+/** The document as a standalone HTML page. */
+export function renderHtml(doc: Doc): string {
+  const header = [doc.version && `Version ${doc.version}`, doc.date].filter(Boolean).join(' · ');
+  const body = doc.sections
+    .map((s) => `<section id="${slug(s.title)}">\n<h2>${htmlText(s.title)}</h2>\n${s.blocks.map(htmlBlock).join('\n')}\n</section>`)
+    .join('\n');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="clyops-doc">
+<title>${htmlText(doc.page)}(${htmlText(doc.section)})</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header><h1><code>${htmlText(doc.name)}</code></h1>${header ? `<p class="meta">${htmlText(header)}</p>` : ''}</header>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+/** The document in `format`. */
+export function render(doc: Doc, format: Format): string {
+  return format === 'man' ? renderMan(doc) : format === 'markdown' ? renderMarkdown(doc) : renderHtml(doc);
+}