@optique/man 0.10.7 → 1.0.0-dev.1109

package/dist/man-CkvscTlM.cjs

@@ -0,0 +1,432 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const require_roff = require('./roff-DJ-LkRXl.cjs');
+const __optique_core_usage = __toESM(require("@optique/core/usage"));
+
+//#region src/man.ts
+/**
+* Formats a date for use in man pages.
+*
+* When a `Date` object is given, the month and year are extracted using
+* the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+* the same `Date` instant may produce different output on machines in
+* different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+* if you need timezone-independent output.
+*
+* @param date The date to format, or undefined.
+* @returns The formatted date string, or undefined.
+* @throws {RangeError} If the given `Date` object is invalid.
+* @since 0.10.0
+*/
+function formatDateForMan(date) {
+	if (date === void 0) return void 0;
+	if (typeof date === "string") return date;
+	if (Number.isNaN(date.getTime())) throw new RangeError("Invalid Date object.");
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December"
+	];
+	return `${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+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.
+*
+* @param term The usage term to format.
+* @returns The roff-formatted string.
+* @throws {TypeError} If the term has an unknown type.
+* @since 0.10.0
+*/
+function formatUsageTermAsRoff(term) {
+	return formatUsageTermAsRoffInternal(term, false);
+}
+/**
+* Returns whether a usage list contains exactly one visible term that
+* produces its own brackets.  When true, a parent wrapper can safely elide
+* its own brackets to avoid redundant nesting.  Multiple bracket-producing
+* siblings must keep their individual brackets for disambiguation.
+*/
+function hasSingleBracketedTerm(terms) {
+	const visible = terms.filter((t$1) => !("hidden" in t$1 && (0, __optique_core_usage.isUsageHidden)(t$1.hidden)));
+	if (visible.length !== 1) return false;
+	const t = visible[0];
+	return t.type === "option" || t.type === "optional" || t.type === "multiple" && t.min < 1 || t.type === "passthrough";
+}
+/**
+* Returns whether a usage list's single visible term has the given type.
+*/
+function hasSingleVisibleTermOfType(terms, type) {
+	const visible = terms.filter((t) => !("hidden" in t && (0, __optique_core_usage.isUsageHidden)(t.hidden)));
+	return visible.length === 1 && visible[0].type === type;
+}
+function formatUsageTermAsRoffInternal(term, insideBrackets) {
+	if ("hidden" in term && (0, __optique_core_usage.isUsageHidden)(term.hidden)) return "";
+	switch (term.type) {
+		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${require_roff.escapeRoff(term.metavar)}\\fR` : "";
+			if (insideBrackets) return `${names}${metavarPart}`;
+			return `[${names}${metavarPart}]`;
+		}
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "optional": {
+			const childrenBracketed = hasSingleBracketedTerm(term.terms);
+			const childIsMultiple = childrenBracketed && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const inner = formatUsageAsRoffInternal(term.terms, childrenBracketed);
+			if (inner === "") return "";
+			if (insideBrackets && childrenBracketed && !childIsMultiple) return inner;
+			return `[${inner}]`;
+		}
+		case "multiple": {
+			const wrapInBrackets = term.min < 1;
+			const childrenBracketed = hasSingleBracketedTerm(term.terms);
+			const childIsMultiple = childrenBracketed && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const passInsideBrackets = wrapInBrackets && childrenBracketed && !childIsMultiple;
+			const inner = formatUsageAsRoffInternal(term.terms, passInsideBrackets);
+			if (inner === "") return "";
+			if (wrapInBrackets) {
+				if (insideBrackets && passInsideBrackets) return `${inner} ...`;
+				return `[${inner} ...]`;
+			}
+			return `${inner} ...`;
+		}
+		case "exclusive": {
+			const alternatives = term.terms.map((t) => formatUsageAsRoffInternal(t, false)).filter((s) => s !== "");
+			if (alternatives.length === 0) return "";
+			if (alternatives.length === 1) return alternatives[0];
+			return `(${alternatives.join(" | ")})`;
+		}
+		case "literal": return require_roff.escapeRoff(term.value);
+		case "passthrough": return "[...]";
+		case "ellipsis": return "...";
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown usage term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Usage} array as roff markup.
+*
+* @param usage The usage terms to format.
+* @returns The roff-formatted string.
+*/
+function formatUsageAsRoff(usage) {
+	return formatUsageAsRoffInternal(usage, false);
+}
+function formatUsageAsRoffInternal(usage, insideBrackets) {
+	return usage.map((term) => formatUsageTermAsRoffInternal(term, insideBrackets)).filter((s) => s !== "").join(" ");
+}
+/**
+* Formats a {@link DocEntry}'s term for man page output.
+*
+* @param term The usage term from the entry.
+* @returns The roff-formatted term string.
+*/
+function formatDocEntryTerm(term) {
+	if ("hidden" in term && (0, __optique_core_usage.isDocHidden)(term.hidden)) return "";
+	switch (term.type) {
+		case "option": {
+			const names = term.names.map((name) => `\\fB${require_roff.escapeHyphens(name)}\\fR`).join(", ");
+			const metavarPart = term.metavar ? ` \\fI${require_roff.escapeRoff(term.metavar)}\\fR` : "";
+			return `${names}${metavarPart}`;
+		}
+		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);
+	}
+}
+/**
+* Formats a {@link UsageTerm} as roff markup for doc rendering, filtering
+* doc-hidden terms instead of usage-hidden terms.
+*
+* @throws {TypeError} If the term has an unknown type.
+*/
+function formatDocUsageTermAsRoff(term) {
+	if ("hidden" in term && (0, __optique_core_usage.isDocHidden)(term.hidden)) return "";
+	switch (term.type) {
+		case "optional": {
+			const inner = formatDocUsageAsRoff(term.terms);
+			if (inner === "") return "";
+			return `[${inner}]`;
+		}
+		case "multiple": {
+			const inner = formatDocUsageAsRoff(term.terms);
+			if (inner === "") return "";
+			if (term.min < 1) return `[${inner} ...]`;
+			return `${inner} ...`;
+		}
+		case "exclusive": {
+			const alternatives = term.terms.map((t) => formatDocUsageAsRoff(t)).filter((s) => s !== "");
+			if (alternatives.length === 0) return "";
+			if (alternatives.length === 1) return alternatives[0];
+			return `(${alternatives.join(" | ")})`;
+		}
+		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${require_roff.escapeRoff(term.metavar)}\\fR` : "";
+			return `${names}${metavarPart}`;
+		}
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "literal": return require_roff.escapeRoff(term.value);
+		case "passthrough": return "[...]";
+		case "ellipsis": return "...";
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown usage term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Usage} array as roff markup for doc rendering,
+* filtering doc-hidden terms.
+*/
+function formatDocUsageAsRoff(usage) {
+	return usage.map(formatDocUsageTermAsRoff).filter((s) => s !== "").join(" ");
+}
+/**
+* Infers the section title from entry kinds when no explicit title is given.
+* Returns `"COMMANDS"` for command-only sections, `"ARGUMENTS"` for
+* argument-only sections, and `"OPTIONS"` otherwise.
+*
+* @param entries The entries in the section.
+* @returns The inferred section title in uppercase.
+*/
+function inferSectionTitle(entries) {
+	const kinds = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if ("hidden" in entry.term && (0, __optique_core_usage.isDocHidden)(entry.term.hidden)) continue;
+		kinds.add(entry.term.type);
+	}
+	if (kinds.size === 1) {
+		if (kinds.has("command")) return "COMMANDS";
+		if (kinds.has("argument")) return "ARGUMENTS";
+	}
+	return "OPTIONS";
+}
+/**
+* Formats a {@link DocSection} as roff markup with .TP macros.
+*
+* @param section The section to format.
+* @returns The roff-formatted section content.
+*/
+function formatDocSectionEntries(section) {
+	const lines = [];
+	for (const entry of section.entries) {
+		const termStr = formatDocEntryTerm(entry.term);
+		if (termStr === "") continue;
+		lines.push(".TP");
+		lines.push(termStr);
+		if (entry.description) {
+			let desc = require_roff.formatMessageAsRoff(entry.description);
+			if (entry.default) desc += ` [${require_roff.formatMessageAsRoff(entry.default)}]`;
+			if (entry.choices) desc += ` (choices: ${require_roff.formatMessageAsRoff(entry.choices, { quotes: false })})`;
+			lines.push(desc);
+		} else if (entry.default || entry.choices) {
+			const parts = [];
+			if (entry.default) parts.push(`[${require_roff.formatMessageAsRoff(entry.default)}]`);
+			if (entry.choices) parts.push(`(choices: ${require_roff.formatMessageAsRoff(entry.choices, { quotes: false })})`);
+			lines.push(parts.join(" "));
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Formats a {@link DocPage} as a complete man page in roff format.
+*
+* This function generates a man page following the standard man(7) format,
+* including sections for NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and more.
+*
+* @example
+* ```typescript
+* import { formatDocPageAsMan } from "@optique/man/man";
+* import type { DocPage } from "@optique/core/doc";
+*
+* const page: DocPage = {
+*   brief: message`A sample CLI application`,
+*   usage: [{ type: "argument", metavar: "FILE" }],
+*   sections: [],
+* };
+*
+* const manPage = formatDocPageAsMan(page, {
+*   name: "myapp",
+*   section: 1,
+*   version: "1.0.0",
+* });
+* ```
+*
+* @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 or any `seeAlso` entry's 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 = [`"${require_roff.escapeHyphens(require_roff.escapeRequestArg(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(`"${require_roff.escapeRequestArg(formatDateForMan(options.date))}"`);
+	else if (hasVersion || hasManual) thParts.push("\"\"");
+	if (hasVersion) thParts.push(`"${require_roff.escapeHyphens(require_roff.escapeRequestArg(options.name))} ${require_roff.escapeRequestArg(options.version)}"`);
+	else if (hasManual) thParts.push("\"\"");
+	if (hasManual) thParts.push(`"${require_roff.escapeRequestArg(options.manual)}"`);
+	lines.push(`.TH ${thParts.join(" ")}`);
+	lines.push(".SH NAME");
+	const brief = options.brief ?? page.brief;
+	if (brief) lines.push(`${require_roff.escapeHyphens(require_roff.escapeRoff(options.name))} \\- ${require_roff.formatMessageAsRoff(brief)}`);
+	else lines.push(require_roff.escapeHyphens(require_roff.escapeRoff(options.name)));
+	if (page.usage) {
+		lines.push(".SH SYNOPSIS");
+		lines.push(`.B "${require_roff.escapeHyphens(require_roff.escapeRequestArg(options.name))}"`);
+		const usageStr = formatUsageAsRoff(page.usage);
+		if (usageStr) lines.push(usageStr);
+	}
+	const description = options.description ?? page.description;
+	if (description) {
+		lines.push(".SH DESCRIPTION");
+		lines.push(require_roff.formatMessageAsRoff(description));
+	}
+	for (const section of page.sections) {
+		if (section.entries.length === 0) continue;
+		const content = formatDocSectionEntries(section);
+		if (content === "") continue;
+		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
+		lines.push(`.SH "${require_roff.escapeRequestArg(title)}"`);
+		lines.push(content);
+	}
+	if (options.environment && options.environment.entries.length > 0) {
+		const content = formatDocSectionEntries(options.environment);
+		if (content !== "") {
+			lines.push(".SH ENVIRONMENT");
+			lines.push(content);
+		}
+	}
+	if (options.files && options.files.entries.length > 0) {
+		const content = formatDocSectionEntries(options.files);
+		if (content !== "") {
+			lines.push(".SH FILES");
+			lines.push(content);
+		}
+	}
+	if (options.exitStatus && options.exitStatus.entries.length > 0) {
+		const content = formatDocSectionEntries(options.exitStatus);
+		if (content !== "") {
+			lines.push(".SH EXIT STATUS");
+			lines.push(content);
+		}
+	}
+	const examples = options.examples ?? page.examples;
+	if (examples) {
+		lines.push(".SH EXAMPLES");
+		lines.push(require_roff.formatMessageAsRoff(examples));
+	}
+	const bugs = options.bugs ?? page.bugs;
+	if (bugs) {
+		lines.push(".SH BUGS");
+		lines.push(require_roff.formatMessageAsRoff(bugs));
+	}
+	if (options.seeAlso && options.seeAlso.length > 0) {
+		for (const ref of options.seeAlso) if (!Number.isInteger(ref.section) || ref.section < 1 || ref.section > 8) {
+			let repr;
+			try {
+				repr = JSON.stringify(ref.section);
+			} catch {
+				repr = String(typeof ref.section);
+			}
+			throw new RangeError(`Invalid man page section number for seeAlso entry ${JSON.stringify(ref.name)} (must be 1–8): ${repr}`);
+		}
+		lines.push(".SH SEE ALSO");
+		const refs = options.seeAlso.map((ref, i) => {
+			const suffix = i < options.seeAlso.length - 1 ? "," : "";
+			return `.BR "${require_roff.escapeHyphens(require_roff.escapeRequestArg(ref.name))}" (${ref.section})${suffix}`;
+		});
+		lines.push(refs.join("\n"));
+	}
+	const author = options.author ?? page.author;
+	if (author) {
+		lines.push(".SH AUTHOR");
+		lines.push(require_roff.formatMessageAsRoff(author));
+	}
+	const footer = options.footer ?? page.footer;
+	if (footer) {
+		lines.push(".PP");
+		lines.push(require_roff.formatMessageAsRoff(footer));
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+Object.defineProperty(exports, 'formatDateForMan', {
+  enumerable: true,
+  get: function () {
+    return formatDateForMan;
+  }
+});
+Object.defineProperty(exports, 'formatDocPageAsMan', {
+  enumerable: true,
+  get: function () {
+    return formatDocPageAsMan;
+  }
+});
+Object.defineProperty(exports, 'formatUsageTermAsRoff', {
+  enumerable: true,
+  get: function () {
+    return formatUsageTermAsRoff;
+  }
+});

package/dist/{man-tclTvdWs.d.ts → man-DKwa47XV.d.cts}

@@ -32,7 +32,9 @@ interface ManPageOptions {
   readonly section: ManPageSection;
   /**
    * The date to display in the man page footer.
-   * If a Date object is provided, it will be formatted as "Month Year".
+   * If a `Date` object is provided, it will be formatted as `"Month Year"`
+   * using the host's local timezone.  For timezone-independent output (e.g.,
+   * in CI), pass a pre-formatted string instead.
    * If a string is provided, it will be used as-is.
    */
   readonly date?: string | Date;
@@ -62,7 +64,7 @@ interface ManPageOptions {
    */
   readonly seeAlso?: ReadonlyArray<{
     readonly name: string;
-    readonly section: number;
+    readonly section: ManPageSection;
   }>;
   /**
    * Environment variables to document in the ENVIRONMENT section.
@@ -76,12 +78,37 @@ interface ManPageOptions {
    * Exit status codes to document in the EXIT STATUS section.
    */
   readonly exitStatus?: DocSection;
+  /**
+   * A brief description of the program for the NAME section.
+   * Overrides the brief from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program for the DESCRIPTION section.
+   * Overrides the description from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly description?: Message;
+  /**
+   * Footer text appended at the end of the man page.
+   * Overrides the footer from the {@link DocPage} if both are present.
+   * @since 1.0.0
+   */
+  readonly footer?: Message;
 }
 /**
  * Formats a date for use in man pages.
  *
+ * When a `Date` object is given, the month and year are extracted using
+ * the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+ * the same `Date` instant may produce different output on machines in
+ * different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+ * if you need timezone-independent output.
+ *
  * @param date The date to format, or undefined.
  * @returns The formatted date string, or undefined.
+ * @throws {RangeError} If the given `Date` object is invalid.
  * @since 0.10.0
  */
 declare function formatDateForMan(date: string | Date | undefined): string | undefined;
@@ -90,6 +117,7 @@ declare function formatDateForMan(date: string | Date | undefined): string | und
  *
  * @param term The usage term to format.
  * @returns The roff-formatted string.
+ * @throws {TypeError} If the term has an unknown type.
  * @since 0.10.0
  */
 declare function formatUsageTermAsRoff(term: UsageTerm): string;
@@ -120,6 +148,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 or any `seeAlso` entry's 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 @@
-require('./roff-EpcecLXU.cjs');
-const require_man = require('./man-DGnow1Jr.cjs');
+const require_man = require('./man-CkvscTlM.cjs');
+require('./roff-DJ-LkRXl.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-BMb0Vyt9.cjs";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DKwa47XV.cjs";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-tclTvdWs.js";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B1Q2mhit.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-Leuf7kOn.js";
+import "./roff-CCdIQO7B.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-BE1OY_lJ.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/{roff-C_MiRXVS.js → roff-CCdIQO7B.js}

@@ -40,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.
@@ -60,18 +96,22 @@ function escapeHyphens(text) {
 * is done in formatMessageAsRoff after all terms are joined.
 *
 * @param term The message term to format.
+* @param options Optional formatting options.
 * @returns The roff-formatted string.
 */
-function formatTermAsRoff(term) {
+function formatTermAsRoff(term, options) {
 	switch (term.type) {
 		case "text": return escapeBackslashes(term.text);
 		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":
+			if (options?.quotes === false) return escapeBackslashes(term.value);
+			return `"${escapeQuotedValue(term.value)}"`;
 		case "values":
 			if (term.values.length === 0) return "";
-			return term.values.map((v) => `"${escapeBackslashes(v)}"`).join(" ");
+			if (options?.quotes === false) 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";
@@ -112,14 +152,15 @@ function formatTermAsRoff(term) {
 * ```
 *
 * @param msg The message to format.
+* @param options Optional formatting options.
 * @returns The roff-formatted string.
 * @since 0.10.0
 */
-function formatMessageAsRoff(msg) {
-	const joined = msg.map(formatTermAsRoff).join("");
+function formatMessageAsRoff(msg, options) {
+	const joined = msg.map((t) => formatTermAsRoff(t, options)).join("");
 	const escaped = escapeLineStarts(joined);
 	return escaped.replace(/\n\n+/g, "\n.PP\n");
 }
 
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };