@optique/man 1.0.0-dev.783 → 1.0.0-dev.885

package/dist/cli.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-const require_man = require('./man-CT30XV48.cjs');
-require('./roff-EpcecLXU.cjs');
-const require_generator = require('./generator-BDKtMiuq.cjs');
+const require_man = require('./man-DFKETOWN.cjs');
+require('./roff-Cl0vekdg.cjs');
+const require_generator = require('./generator-Bal_ioLr.cjs');
 const __optique_core_constructs = require_man.__toESM(require("@optique/core/constructs"));
 const __optique_core_primitives = require_man.__toESM(require("@optique/core/primitives"));
 const __optique_core_valueparser = require_man.__toESM(require("@optique/core/valueparser"));
@@ -17,7 +17,7 @@ const node_url = require_man.__toESM(require("node:url"));
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.0.0-dev.783+64de3665";
+var version = "1.0.0-dev.885+3300ebe1";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",
@@ -330,13 +330,21 @@ async function tryRegisterTsx() {
 * Checks if a value is a Program object.
 */
 function isProgram(value) {
-	return value != null && typeof value === "object" && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata != null;
+	try {
+		return value != null && typeof value === "object" && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata != null && typeof value.metadata.name === "string" && isParser(value.parser);
+	} catch {
+		return false;
+	}
 }
 /**
 * Checks if a value is a Parser object.
 */
 function isParser(value) {
-	return value != null && typeof value === "object" && "parse" in value && typeof value.parse === "function" && "$mode" in value && "usage" in value;
+	try {
+		return value != null && typeof value === "object" && "parse" in value && typeof value.parse === "function" && "$mode" in value && "usage" in value && "getDocFragments" in value && typeof value.getDocFragments === "function";
+	} catch {
+		return false;
+	}
 }
 /**
 * Infers the program name from a file path.
@@ -344,7 +352,7 @@ function isParser(value) {
 function inferNameFromPath(filePath) {
 	const base = (0, node_path.basename)(filePath);
 	const ext = (0, node_path.extname)(base);
-	return base.slice(0, -ext.length);
+	return ext.length > 0 ? base.slice(0, -ext.length) : base;
 }
 /**
 * Gets available exports from a module.
@@ -377,19 +385,20 @@ async function main() {
 	if (target === void 0) exportNotFoundError(args.file, args.exportName, getAvailableExports(mod));
 	if (!isProgram(target) && !isParser(target)) notProgramOrParserError(args.file, args.exportName, describeType(target));
 	const name$1 = args.name ?? (isProgram(target) ? target.metadata.name : null) ?? inferNameFromPath(args.file);
+	const date = args.date ?? /* @__PURE__ */ new Date();
 	let manPage;
 	try {
 		if (isProgram(target)) manPage = await require_generator.generateManPageAsync(target, {
 			section: args.section,
 			name: args.name,
-			date: args.date,
+			date,
 			version: args.versionString,
 			manual: args.manual
 		});
 		else manPage = await require_generator.generateManPageAsync(target, {
 			name: name$1,
 			section: args.section,
-			date: args.date,
+			date,
 			version: args.versionString,
 			manual: args.manual
 		});

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import "./roff-C_MiRXVS.js";
-import "./man-CAYHrsaf.js";
-import { generateManPageAsync } from "./generator-DGiXLyTu.js";
+import "./roff-CwBRpWCo.js";
+import "./man-BBDifH_Y.js";
+import { generateManPageAsync } from "./generator-CdDVvD4r.js";
 import { object } from "@optique/core/constructs";
 import { argument, option } from "@optique/core/primitives";
 import { choice, string } from "@optique/core/valueparser";
@@ -17,7 +17,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.0.0-dev.783+64de3665";
+var version = "1.0.0-dev.885+3300ebe1";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",
@@ -330,13 +330,21 @@ async function tryRegisterTsx() {
 * Checks if a value is a Program object.
 */
 function isProgram(value) {
-	return value != null && typeof value === "object" && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata != null;
+	try {
+		return value != null && typeof value === "object" && "parser" in value && "metadata" in value && typeof value.metadata === "object" && value.metadata != null && typeof value.metadata.name === "string" && isParser(value.parser);
+	} catch {
+		return false;
+	}
 }
 /**
 * Checks if a value is a Parser object.
 */
 function isParser(value) {
-	return value != null && typeof value === "object" && "parse" in value && typeof value.parse === "function" && "$mode" in value && "usage" in value;
+	try {
+		return value != null && typeof value === "object" && "parse" in value && typeof value.parse === "function" && "$mode" in value && "usage" in value && "getDocFragments" in value && typeof value.getDocFragments === "function";
+	} catch {
+		return false;
+	}
 }
 /**
 * Infers the program name from a file path.
@@ -344,7 +352,7 @@ function isParser(value) {
 function inferNameFromPath(filePath) {
 	const base = basename(filePath);
 	const ext = extname(base);
-	return base.slice(0, -ext.length);
+	return ext.length > 0 ? base.slice(0, -ext.length) : base;
 }
 /**
 * Gets available exports from a module.
@@ -377,19 +385,20 @@ async function main() {
 	if (target === void 0) exportNotFoundError(args.file, args.exportName, getAvailableExports(mod));
 	if (!isProgram(target) && !isParser(target)) notProgramOrParserError(args.file, args.exportName, describeType(target));
 	const name$1 = args.name ?? (isProgram(target) ? target.metadata.name : null) ?? inferNameFromPath(args.file);
+	const date = args.date ?? /* @__PURE__ */ new Date();
 	let manPage;
 	try {
 		if (isProgram(target)) manPage = await generateManPageAsync(target, {
 			section: args.section,
 			name: args.name,
-			date: args.date,
+			date,
 			version: args.versionString,
 			manual: args.manual
 		});
 		else manPage = await generateManPageAsync(target, {
 			name: name$1,
 			section: args.section,
-			date: args.date,
+			date,
 			version: args.versionString,
 			manual: args.manual
 		});

package/dist/{generator-BDKtMiuq.cjs → generator-Bal_ioLr.cjs}

@@ -1,4 +1,4 @@
-const require_man = require('./man-CT30XV48.cjs');
+const require_man = require('./man-DFKETOWN.cjs');
 const __optique_core_parser = require_man.__toESM(require("@optique/core/parser"));
 
 //#region src/generator.ts

package/dist/{generator-DGiXLyTu.js → generator-CdDVvD4r.js}

@@ -1,4 +1,4 @@
-import { formatDocPageAsMan } from "./man-CAYHrsaf.js";
+import { formatDocPageAsMan } from "./man-BBDifH_Y.js";
 import { getDocPageAsync, getDocPageSync } from "@optique/core/parser";
 
 //#region src/generator.ts

package/dist/index.cjs

@@ -1,8 +1,10 @@
-const require_man = require('./man-CT30XV48.cjs');
-const require_roff = require('./roff-EpcecLXU.cjs');
-const require_generator = require('./generator-BDKtMiuq.cjs');
+const require_man = require('./man-DFKETOWN.cjs');
+const require_roff = require('./roff-Cl0vekdg.cjs');
+const require_generator = require('./generator-Bal_ioLr.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
+exports.escapeQuotedValue = require_roff.escapeQuotedValue;
+exports.escapeRequestArg = require_roff.escapeRequestArg;
 exports.escapeRoff = require_roff.escapeRoff;
 exports.formatDateForMan = require_man.formatDateForMan;
 exports.formatDocPageAsMan = require_man.formatDocPageAsMan;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-72Am6STB.cjs";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Dh4GLG_Q.cjs";
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-C_87xXP6.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-xPX8GhXq.cjs";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 
@@ -156,4 +156,4 @@ declare function generateManPage(parser: Parser<"sync", unknown, unknown>, optio
 declare function generateManPage(parser: Parser<"async", unknown, unknown>, options: GenerateManPageOptions): Promise<string>;
 declare function generateManPage<M extends Mode>(parser: Parser<M, unknown, unknown>, options: GenerateManPageOptions): ModeValue<M, string>;
 //#endregion
-export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };
+export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-B36zMxYc.js";
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DrdGbys8.js";
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-DlmeL3KB.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CGKLHWkS.js";
 import { Program } from "@optique/core/program";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 
@@ -156,4 +156,4 @@ declare function generateManPage(parser: Parser<"sync", unknown, unknown>, optio
 declare function generateManPage(parser: Parser<"async", unknown, unknown>, options: GenerateManPageOptions): Promise<string>;
 declare function generateManPage<M extends Mode>(parser: Parser<M, unknown, unknown>, options: GenerateManPageOptions): ModeValue<M, string>;
 //#endregion
-export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };
+export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-C_MiRXVS.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CAYHrsaf.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DGiXLyTu.js";
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CwBRpWCo.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BBDifH_Y.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-CdDVvD4r.js";
 
-export { escapeHyphens, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-CAYHrsaf.js → man-BBDifH_Y.js}

@@ -1,4 +1,4 @@
-import { escapeHyphens, formatMessageAsRoff } from "./roff-C_MiRXVS.js";
+import { escapeHyphens, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CwBRpWCo.js";
 import { isDocHidden, isUsageHidden } from "@optique/core/usage";
 
 //#region src/man.ts
@@ -31,6 +31,9 @@ function formatDateForMan(date) {
 function escapeThField(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
+function formatCommandNameAsRoff(name) {
+	return `\\fB${escapeHyphens(escapeRoff(name))}\\fR`;
+}
 /**
 * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
 *
@@ -42,13 +45,13 @@ function escapeThField(value) {
 function formatUsageTermAsRoff(term) {
 	if ("hidden" in term && isUsageHidden(term.hidden)) return "";
 	switch (term.type) {
-		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
 		case "option": {
 			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(" | ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
 			return `[${names}${metavarPart}]`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
+		case "command": return formatCommandNameAsRoff(term.name);
 		case "optional": {
 			const inner = formatUsageAsRoff(term.terms);
 			if (inner === "") return "";
@@ -66,7 +69,7 @@ function formatUsageTermAsRoff(term) {
 			if (alternatives.length === 1) return alternatives[0];
 			return `(${alternatives.join(" | ")})`;
 		}
-		case "literal": return term.value;
+		case "literal": return escapeRoff(term.value);
 		case "passthrough": return "[...]";
 		case "ellipsis": return "...";
 		default: {
@@ -95,12 +98,12 @@ function formatDocEntryTerm(term) {
 	switch (term.type) {
 		case "option": {
 			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
 			return `${names}${metavarPart}`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "argument": return `\\fI${term.metavar}\\fR`;
-		case "literal": return term.value;
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
+		case "literal": return escapeRoff(term.value);
 		default: return formatDocUsageTermAsRoff(term);
 	}
 }
@@ -130,14 +133,14 @@ function formatDocUsageTermAsRoff(term) {
 			if (alternatives.length === 1) return alternatives[0];
 			return `(${alternatives.join(" | ")})`;
 		}
-		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
 		case "option": {
 			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
 			return `${names}${metavarPart}`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "literal": return term.value;
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "literal": return escapeRoff(term.value);
 		case "passthrough": return "[...]";
 		case "ellipsis": return "...";
 		default: {
@@ -201,26 +204,39 @@ function formatDocSectionEntries(section) {
 * @param page The documentation page to format.
 * @param options The man page options.
 * @returns The complete man page in roff format.
+* @throws {TypeError} If the program name is empty.
+* @throws {RangeError} If the section number is not a valid man page section
+* (1–8).
 * @since 0.10.0
 */
 function formatDocPageAsMan(page, options) {
+	if (options.name === "") throw new TypeError("Program name must not be empty.");
+	if (!Number.isInteger(options.section) || options.section < 1 || options.section > 8) {
+		let repr;
+		try {
+			repr = JSON.stringify(options.section);
+		} catch {
+			repr = String(typeof options.section);
+		}
+		throw new RangeError(`Invalid man page section number (must be 1–8): ${repr}`);
+	}
 	const lines = [];
-	const thParts = [escapeThField(options.name.toUpperCase()), options.section.toString()];
-	const hasDate = options.date != null;
-	const hasVersion = options.version != null;
-	const hasManual = options.manual != null;
+	const thParts = [escapeHyphens(escapeThField(options.name).toUpperCase()), options.section.toString()];
+	const hasDate = options.date != null && options.date !== "";
+	const hasVersion = options.version != null && options.version !== "";
+	const hasManual = options.manual != null && options.manual !== "";
 	if (hasDate) thParts.push(`"${escapeThField(formatDateForMan(options.date))}"`);
 	else if (hasVersion || hasManual) thParts.push("\"\"");
-	if (hasVersion) thParts.push(`"${escapeThField(`${options.name} ${options.version}`)}"`);
+	if (hasVersion) thParts.push(`"${escapeHyphens(escapeThField(options.name))} ${escapeThField(options.version)}"`);
 	else if (hasManual) thParts.push("\"\"");
 	if (hasManual) thParts.push(`"${escapeThField(options.manual)}"`);
 	lines.push(`.TH ${thParts.join(" ")}`);
 	lines.push(".SH NAME");
-	if (page.brief) lines.push(`${options.name} \\- ${formatMessageAsRoff(page.brief)}`);
-	else lines.push(options.name);
+	if (page.brief) lines.push(`${escapeHyphens(escapeRoff(options.name))} \\- ${formatMessageAsRoff(page.brief)}`);
+	else lines.push(escapeHyphens(escapeRoff(options.name)));
 	if (page.usage) {
 		lines.push(".SH SYNOPSIS");
-		lines.push(`.B ${options.name}`);
+		lines.push(`.B ${escapeHyphens(escapeRoff(options.name))}`);
 		const usageStr = formatUsageAsRoff(page.usage);
 		if (usageStr) lines.push(usageStr);
 	}
@@ -233,7 +249,7 @@ function formatDocPageAsMan(page, options) {
 		const content = formatDocSectionEntries(section);
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? "OPTIONS";
-		lines.push(`.SH ${title}`);
+		lines.push(`.SH "${escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
 	if (options.environment && options.environment.entries.length > 0) {
@@ -269,7 +285,7 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH SEE ALSO");
 		const refs = options.seeAlso.map((ref, i) => {
 			const suffix = i < options.seeAlso.length - 1 ? "," : "";
-			return `.BR ${ref.name} (${ref.section})${suffix}`;
+			return `.BR ${escapeHyphens(escapeRoff(ref.name))} (${ref.section})${suffix}`;
 		});
 		lines.push(refs.join("\n"));
 	}

package/dist/{man-Dh4GLG_Q.d.cts → man-CGKLHWkS.d.ts}

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
-import { DocPage, DocSection } from "@optique/core/doc";
 import { UsageTerm } from "@optique/core/usage";
+import { DocPage, DocSection } from "@optique/core/doc";
 
 //#region src/man.d.ts
 
@@ -121,6 +121,9 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @param page The documentation page to format.
  * @param options The man page options.
  * @returns The complete man page in roff format.
+ * @throws {TypeError} If the program name is empty.
+ * @throws {RangeError} If the section number is not a valid man page section
+ * (1–8).
  * @since 0.10.0
  */
 declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;

package/dist/{man-CT30XV48.cjs → man-DFKETOWN.cjs}

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_roff = require('./roff-EpcecLXU.cjs');
+const require_roff = require('./roff-Cl0vekdg.cjs');
 const __optique_core_usage = __toESM(require("@optique/core/usage"));
 
 //#region src/man.ts
@@ -54,6 +54,9 @@ function formatDateForMan(date) {
 function escapeThField(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
+function formatCommandNameAsRoff(name) {
+	return `\\fB${require_roff.escapeHyphens(require_roff.escapeRoff(name))}\\fR`;
+}
 /**
 * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
 *
@@ -65,13 +68,13 @@ function escapeThField(value) {
 function formatUsageTermAsRoff(term) {
 	if ("hidden" in term && (0, __optique_core_usage.isUsageHidden)(term.hidden)) return "";
 	switch (term.type) {
-		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "argument": return `\\fI${require_roff.escapeRoff(term.metavar)}\\fR`;
 		case "option": {
 			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(" | ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${require_roff.escapeRoff(term.metavar)}\\fR` : "";
 			return `[${names}${metavarPart}]`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
+		case "command": return formatCommandNameAsRoff(term.name);
 		case "optional": {
 			const inner = formatUsageAsRoff(term.terms);
 			if (inner === "") return "";
@@ -89,7 +92,7 @@ function formatUsageTermAsRoff(term) {
 			if (alternatives.length === 1) return alternatives[0];
 			return `(${alternatives.join(" | ")})`;
 		}
-		case "literal": return term.value;
+		case "literal": return require_roff.escapeRoff(term.value);
 		case "passthrough": return "[...]";
 		case "ellipsis": return "...";
 		default: {
@@ -118,12 +121,12 @@ function formatDocEntryTerm(term) {
 	switch (term.type) {
 		case "option": {
 			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(", ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${require_roff.escapeRoff(term.metavar)}\\fR` : "";
 			return `${names}${metavarPart}`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "argument": return `\\fI${term.metavar}\\fR`;
-		case "literal": return term.value;
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "argument": return `\\fI${require_roff.escapeRoff(term.metavar)}\\fR`;
+		case "literal": return require_roff.escapeRoff(term.value);
 		default: return formatDocUsageTermAsRoff(term);
 	}
 }
@@ -153,14 +156,14 @@ function formatDocUsageTermAsRoff(term) {
 			if (alternatives.length === 1) return alternatives[0];
 			return `(${alternatives.join(" | ")})`;
 		}
-		case "argument": return `\\fI${term.metavar}\\fR`;
+		case "argument": return `\\fI${require_roff.escapeRoff(term.metavar)}\\fR`;
 		case "option": {
 			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(", ");
-			const metavarPart = term.metavar ? ` \\fI${term.metavar}\\fR` : "";
+			const metavarPart = term.metavar ? ` \\fI${require_roff.escapeRoff(term.metavar)}\\fR` : "";
 			return `${names}${metavarPart}`;
 		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "literal": return term.value;
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "literal": return require_roff.escapeRoff(term.value);
 		case "passthrough": return "[...]";
 		case "ellipsis": return "...";
 		default: {
@@ -224,26 +227,39 @@ function formatDocSectionEntries(section) {
 * @param page The documentation page to format.
 * @param options The man page options.
 * @returns The complete man page in roff format.
+* @throws {TypeError} If the program name is empty.
+* @throws {RangeError} If the section number is not a valid man page section
+* (1–8).
 * @since 0.10.0
 */
 function formatDocPageAsMan(page, options) {
+	if (options.name === "") throw new TypeError("Program name must not be empty.");
+	if (!Number.isInteger(options.section) || options.section < 1 || options.section > 8) {
+		let repr;
+		try {
+			repr = JSON.stringify(options.section);
+		} catch {
+			repr = String(typeof options.section);
+		}
+		throw new RangeError(`Invalid man page section number (must be 1–8): ${repr}`);
+	}
 	const lines = [];
-	const thParts = [escapeThField(options.name.toUpperCase()), options.section.toString()];
-	const hasDate = options.date != null;
-	const hasVersion = options.version != null;
-	const hasManual = options.manual != null;
+	const thParts = [require_roff.escapeHyphens(escapeThField(options.name).toUpperCase()), options.section.toString()];
+	const hasDate = options.date != null && options.date !== "";
+	const hasVersion = options.version != null && options.version !== "";
+	const hasManual = options.manual != null && options.manual !== "";
 	if (hasDate) thParts.push(`"${escapeThField(formatDateForMan(options.date))}"`);
 	else if (hasVersion || hasManual) thParts.push("\"\"");
-	if (hasVersion) thParts.push(`"${escapeThField(`${options.name} ${options.version}`)}"`);
+	if (hasVersion) thParts.push(`"${require_roff.escapeHyphens(escapeThField(options.name))} ${escapeThField(options.version)}"`);
 	else if (hasManual) thParts.push("\"\"");
 	if (hasManual) thParts.push(`"${escapeThField(options.manual)}"`);
 	lines.push(`.TH ${thParts.join(" ")}`);
 	lines.push(".SH NAME");
-	if (page.brief) lines.push(`${options.name} \\- ${require_roff.formatMessageAsRoff(page.brief)}`);
-	else lines.push(options.name);
+	if (page.brief) lines.push(`${require_roff.escapeHyphens(require_roff.escapeRoff(options.name))} \\- ${require_roff.formatMessageAsRoff(page.brief)}`);
+	else lines.push(require_roff.escapeHyphens(require_roff.escapeRoff(options.name)));
 	if (page.usage) {
 		lines.push(".SH SYNOPSIS");
-		lines.push(`.B ${options.name}`);
+		lines.push(`.B ${require_roff.escapeHyphens(require_roff.escapeRoff(options.name))}`);
 		const usageStr = formatUsageAsRoff(page.usage);
 		if (usageStr) lines.push(usageStr);
 	}
@@ -256,7 +272,7 @@ function formatDocPageAsMan(page, options) {
 		const content = formatDocSectionEntries(section);
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? "OPTIONS";
-		lines.push(`.SH ${title}`);
+		lines.push(`.SH "${require_roff.escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
 	if (options.environment && options.environment.entries.length > 0) {
@@ -292,7 +308,7 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH SEE ALSO");
 		const refs = options.seeAlso.map((ref, i) => {
 			const suffix = i < options.seeAlso.length - 1 ? "," : "";
-			return `.BR ${ref.name} (${ref.section})${suffix}`;
+			return `.BR ${require_roff.escapeHyphens(require_roff.escapeRoff(ref.name))} (${ref.section})${suffix}`;
 		});
 		lines.push(refs.join("\n"));
 	}

package/dist/{man-DrdGbys8.d.ts → man-xPX8GhXq.d.cts}

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
-import { UsageTerm } from "@optique/core/usage";
 import { DocPage, DocSection } from "@optique/core/doc";
+import { UsageTerm } from "@optique/core/usage";
 
 //#region src/man.d.ts
 
@@ -121,6 +121,9 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @param page The documentation page to format.
  * @param options The man page options.
  * @returns The complete man page in roff format.
+ * @throws {TypeError} If the program name is empty.
+ * @throws {RangeError} If the section number is not a valid man page section
+ * (1–8).
  * @since 0.10.0
  */
 declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;

package/dist/man.cjs

@@ -1,5 +1,5 @@
-const require_man = require('./man-CT30XV48.cjs');
-require('./roff-EpcecLXU.cjs');
+const require_man = require('./man-DFKETOWN.cjs');
+require('./roff-Cl0vekdg.cjs');
 
 exports.formatDateForMan = require_man.formatDateForMan;
 exports.formatDocPageAsMan = require_man.formatDocPageAsMan;

package/dist/man.d.cts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Dh4GLG_Q.cjs";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-xPX8GhXq.cjs";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DrdGbys8.js";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CGKLHWkS.js";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.js

@@ -1,4 +1,4 @@
-import "./roff-C_MiRXVS.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CAYHrsaf.js";
+import "./roff-CwBRpWCo.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BBDifH_Y.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/{roff-72Am6STB.d.cts → roff-C_87xXP6.d.cts}

@@ -15,6 +15,38 @@ import { Message } from "@optique/core/message";
  * @since 0.10.0
  */
 declare function escapeRoff(text: string): string;
+/**
+ * Escapes roff-sensitive characters inside a quoted value in body text.
+ * Handles backslashes and double quotes so the value can be safely
+ * placed between literal `"` delimiters in roff text output (e.g.,
+ * `value()` / `values()` message terms).
+ *
+ * This function is *not* safe for roff request arguments such as
+ * `.SH "..."`, where groff performs an extra level of escape
+ * interpretation.  Use {@link escapeRequestArg} for that purpose.
+ *
+ * @param text The raw value text.
+ * @returns The escaped text safe for use inside roff double quotes
+ *   in body text.
+ * @since 1.0.0
+ */
+declare function escapeQuotedValue(text: string): string;
+/**
+ * Escapes roff-sensitive characters inside a quoted roff request argument
+ * (e.g., `.SH "..."`).  Unlike {@link escapeQuotedValue}, this function
+ * replaces backslashes with the `\(rs` glyph instead of `\\`, because
+ * groff performs an extra level of escape interpretation on request
+ * arguments — `\\` would still be parsed as an escape prefix.
+ *
+ * Line breaks (`\r\n`, `\r`, `\n`) are normalized to spaces because a
+ * raw newline would split the request line and cause the remainder to be
+ * parsed as new roff input.
+ *
+ * @param text The raw argument text.
+ * @returns The escaped text safe for use inside a quoted roff request.
+ * @since 1.0.0
+ */
+declare function escapeRequestArg(text: string): string;
 /**
  * Escapes hyphens in option names to prevent line breaks.
  *
@@ -62,4 +94,4 @@ declare function escapeHyphens(text: string): string;
  */
 declare function formatMessageAsRoff(msg: Message): string;
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/{roff-C_MiRXVS.js → roff-Cl0vekdg.cjs}

@@ -1,3 +1,4 @@
+
 //#region src/roff.ts
 /**
 * Escapes backslashes in text for roff.
@@ -40,6 +41,42 @@ function escapeRoff(text) {
 	return escapeLineStarts(escapeBackslashes(text));
 }
 /**
+* Escapes roff-sensitive characters inside a quoted value in body text.
+* Handles backslashes and double quotes so the value can be safely
+* placed between literal `"` delimiters in roff text output (e.g.,
+* `value()` / `values()` message terms).
+*
+* This function is *not* safe for roff request arguments such as
+* `.SH "..."`, where groff performs an extra level of escape
+* interpretation.  Use {@link escapeRequestArg} for that purpose.
+*
+* @param text The raw value text.
+* @returns The escaped text safe for use inside roff double quotes
+*   in body text.
+* @since 1.0.0
+*/
+function escapeQuotedValue(text) {
+	return escapeBackslashes(text).replace(/"/g, "\\(dq");
+}
+/**
+* Escapes roff-sensitive characters inside a quoted roff request argument
+* (e.g., `.SH "..."`).  Unlike {@link escapeQuotedValue}, this function
+* replaces backslashes with the `\(rs` glyph instead of `\\`, because
+* groff performs an extra level of escape interpretation on request
+* arguments — `\\` would still be parsed as an escape prefix.
+*
+* Line breaks (`\r\n`, `\r`, `\n`) are normalized to spaces because a
+* raw newline would split the request line and cause the remainder to be
+* parsed as new roff input.
+*
+* @param text The raw argument text.
+* @returns The escaped text safe for use inside a quoted roff request.
+* @since 1.0.0
+*/
+function escapeRequestArg(text) {
+	return text.replace(/\r\n|\r|\n/g, " ").replace(/\\/g, "\\(rs").replace(/"/g, "\\(dq");
+}
+/**
 * Escapes hyphens in option names to prevent line breaks.
 *
 * In roff, a regular hyphen (`-`) can be used as a line break point.
@@ -68,10 +105,10 @@ function formatTermAsRoff(term) {
 		case "optionName": return `\\fB${escapeHyphens(term.optionName)}\\fR`;
 		case "optionNames": return term.optionNames.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
 		case "metavar": return `\\fI${escapeBackslashes(term.metavar)}\\fR`;
-		case "value": return `"${escapeBackslashes(term.value)}"`;
+		case "value": return `"${escapeQuotedValue(term.value)}"`;
 		case "values":
 			if (term.values.length === 0) return "";
-			return term.values.map((v) => `"${escapeBackslashes(v)}"`).join(" ");
+			return term.values.map((v) => `"${escapeQuotedValue(v)}"`).join(" ");
 		case "envVar": return `\\fB${escapeBackslashes(term.envVar)}\\fR`;
 		case "commandLine": return `\\fB${escapeHyphens(escapeBackslashes(term.commandLine))}\\fR`;
 		case "lineBreak": return "\n";
@@ -122,4 +159,33 @@ function formatMessageAsRoff(msg) {
 }
 
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+Object.defineProperty(exports, 'escapeHyphens', {
+  enumerable: true,
+  get: function () {
+    return escapeHyphens;
+  }
+});
+Object.defineProperty(exports, 'escapeQuotedValue', {
+  enumerable: true,
+  get: function () {
+    return escapeQuotedValue;
+  }
+});
+Object.defineProperty(exports, 'escapeRequestArg', {
+  enumerable: true,
+  get: function () {
+    return escapeRequestArg;
+  }
+});
+Object.defineProperty(exports, 'escapeRoff', {
+  enumerable: true,
+  get: function () {
+    return escapeRoff;
+  }
+});
+Object.defineProperty(exports, 'formatMessageAsRoff', {
+  enumerable: true,
+  get: function () {
+    return formatMessageAsRoff;
+  }
+});

package/dist/{roff-EpcecLXU.cjs → roff-CwBRpWCo.js}

@@ -1,4 +1,3 @@
-
 //#region src/roff.ts
 /**
 * Escapes backslashes in text for roff.
@@ -41,6 +40,42 @@ function escapeRoff(text) {
 	return escapeLineStarts(escapeBackslashes(text));
 }
 /**
+* Escapes roff-sensitive characters inside a quoted value in body text.
+* Handles backslashes and double quotes so the value can be safely
+* placed between literal `"` delimiters in roff text output (e.g.,
+* `value()` / `values()` message terms).
+*
+* This function is *not* safe for roff request arguments such as
+* `.SH "..."`, where groff performs an extra level of escape
+* interpretation.  Use {@link escapeRequestArg} for that purpose.
+*
+* @param text The raw value text.
+* @returns The escaped text safe for use inside roff double quotes
+*   in body text.
+* @since 1.0.0
+*/
+function escapeQuotedValue(text) {
+	return escapeBackslashes(text).replace(/"/g, "\\(dq");
+}
+/**
+* Escapes roff-sensitive characters inside a quoted roff request argument
+* (e.g., `.SH "..."`).  Unlike {@link escapeQuotedValue}, this function
+* replaces backslashes with the `\(rs` glyph instead of `\\`, because
+* groff performs an extra level of escape interpretation on request
+* arguments — `\\` would still be parsed as an escape prefix.
+*
+* Line breaks (`\r\n`, `\r`, `\n`) are normalized to spaces because a
+* raw newline would split the request line and cause the remainder to be
+* parsed as new roff input.
+*
+* @param text The raw argument text.
+* @returns The escaped text safe for use inside a quoted roff request.
+* @since 1.0.0
+*/
+function escapeRequestArg(text) {
+	return text.replace(/\r\n|\r|\n/g, " ").replace(/\\/g, "\\(rs").replace(/"/g, "\\(dq");
+}
+/**
 * Escapes hyphens in option names to prevent line breaks.
 *
 * In roff, a regular hyphen (`-`) can be used as a line break point.
@@ -69,10 +104,10 @@ function formatTermAsRoff(term) {
 		case "optionName": return `\\fB${escapeHyphens(term.optionName)}\\fR`;
 		case "optionNames": return term.optionNames.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
 		case "metavar": return `\\fI${escapeBackslashes(term.metavar)}\\fR`;
-		case "value": return `"${escapeBackslashes(term.value)}"`;
+		case "value": return `"${escapeQuotedValue(term.value)}"`;
 		case "values":
 			if (term.values.length === 0) return "";
-			return term.values.map((v) => `"${escapeBackslashes(v)}"`).join(" ");
+			return term.values.map((v) => `"${escapeQuotedValue(v)}"`).join(" ");
 		case "envVar": return `\\fB${escapeBackslashes(term.envVar)}\\fR`;
 		case "commandLine": return `\\fB${escapeHyphens(escapeBackslashes(term.commandLine))}\\fR`;
 		case "lineBreak": return "\n";
@@ -123,21 +158,4 @@ function formatMessageAsRoff(msg) {
 }
 
 //#endregion
-Object.defineProperty(exports, 'escapeHyphens', {
-  enumerable: true,
-  get: function () {
-    return escapeHyphens;
-  }
-});
-Object.defineProperty(exports, 'escapeRoff', {
-  enumerable: true,
-  get: function () {
-    return escapeRoff;
-  }
-});
-Object.defineProperty(exports, 'formatMessageAsRoff', {
-  enumerable: true,
-  get: function () {
-    return formatMessageAsRoff;
-  }
-});
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/{roff-B36zMxYc.d.ts → roff-DlmeL3KB.d.ts}

@@ -15,6 +15,38 @@ import { Message } from "@optique/core/message";
  * @since 0.10.0
  */
 declare function escapeRoff(text: string): string;
+/**
+ * Escapes roff-sensitive characters inside a quoted value in body text.
+ * Handles backslashes and double quotes so the value can be safely
+ * placed between literal `"` delimiters in roff text output (e.g.,
+ * `value()` / `values()` message terms).
+ *
+ * This function is *not* safe for roff request arguments such as
+ * `.SH "..."`, where groff performs an extra level of escape
+ * interpretation.  Use {@link escapeRequestArg} for that purpose.
+ *
+ * @param text The raw value text.
+ * @returns The escaped text safe for use inside roff double quotes
+ *   in body text.
+ * @since 1.0.0
+ */
+declare function escapeQuotedValue(text: string): string;
+/**
+ * Escapes roff-sensitive characters inside a quoted roff request argument
+ * (e.g., `.SH "..."`).  Unlike {@link escapeQuotedValue}, this function
+ * replaces backslashes with the `\(rs` glyph instead of `\\`, because
+ * groff performs an extra level of escape interpretation on request
+ * arguments — `\\` would still be parsed as an escape prefix.
+ *
+ * Line breaks (`\r\n`, `\r`, `\n`) are normalized to spaces because a
+ * raw newline would split the request line and cause the remainder to be
+ * parsed as new roff input.
+ *
+ * @param text The raw argument text.
+ * @returns The escaped text safe for use inside a quoted roff request.
+ * @since 1.0.0
+ */
+declare function escapeRequestArg(text: string): string;
 /**
  * Escapes hyphens in option names to prevent line breaks.
  *
@@ -62,4 +94,4 @@ declare function escapeHyphens(text: string): string;
  */
 declare function formatMessageAsRoff(msg: Message): string;
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/roff.cjs

@@ -1,5 +1,7 @@
-const require_roff = require('./roff-EpcecLXU.cjs');
+const require_roff = require('./roff-Cl0vekdg.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
+exports.escapeQuotedValue = require_roff.escapeQuotedValue;
+exports.escapeRequestArg = require_roff.escapeRequestArg;
 exports.escapeRoff = require_roff.escapeRoff;
 exports.formatMessageAsRoff = require_roff.formatMessageAsRoff;

package/dist/roff.d.cts

@@ -1,2 +1,2 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-72Am6STB.cjs";
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-C_87xXP6.cjs";
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/roff.d.ts

@@ -1,2 +1,2 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-B36zMxYc.js";
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-DlmeL3KB.js";
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/roff.js

@@ -1,3 +1,3 @@
-import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-C_MiRXVS.js";
+import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CwBRpWCo.js";
 
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.0.0-dev.783+64de3665",
+  "version": "1.0.0-dev.885+3300ebe1",
   "description": "Man page generator for Optique CLI parsers",
   "keywords": [
     "CLI",
@@ -84,8 +84,8 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.783+64de3665",
-    "@optique/run": "1.0.0-dev.783+64de3665"
+    "@optique/core": "1.0.0-dev.885+3300ebe1",
+    "@optique/run": "1.0.0-dev.885+3300ebe1"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",