@optique/man 0.10.7-dev.485 → 1.0.0-dev.1109

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

@@ -2,6 +2,20 @@ import { Message } from "@optique/core/message";
 
 //#region src/roff.d.ts
 
+/**
+ * Options for roff formatting of messages.
+ *
+ * @since 1.0.0
+ */
+interface RoffFormatOptions {
+  /**
+   * Whether to wrap `value` and `values` terms in double quotes.
+   * Defaults to `true`.
+   *
+   * @since 1.0.0
+   */
+  readonly quotes?: boolean;
+}
 /**
  * Escapes special roff characters in plain text.
  *
@@ -15,6 +29,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.
  *
@@ -57,9 +103,10 @@ declare function escapeHyphens(text: string): string;
  * ```
  *
  * @param msg The message to format.
+ * @param options Optional formatting options.
  * @returns The roff-formatted string.
  * @since 0.10.0
  */
-declare function formatMessageAsRoff(msg: Message): string;
+declare function formatMessageAsRoff(msg: Message, options?: RoffFormatOptions): string;
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

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

@@ -2,6 +2,20 @@ import { Message } from "@optique/core/message";
 
 //#region src/roff.d.ts
 
+/**
+ * Options for roff formatting of messages.
+ *
+ * @since 1.0.0
+ */
+interface RoffFormatOptions {
+  /**
+   * Whether to wrap `value` and `values` terms in double quotes.
+   * Defaults to `true`.
+   *
+   * @since 1.0.0
+   */
+  readonly quotes?: boolean;
+}
 /**
  * Escapes special roff characters in plain text.
  *
@@ -15,6 +29,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.
  *
@@ -57,9 +103,10 @@ declare function escapeHyphens(text: string): string;
  * ```
  *
  * @param msg The message to format.
+ * @param options Optional formatting options.
  * @returns The roff-formatted string.
  * @since 0.10.0
  */
-declare function formatMessageAsRoff(msg: Message): string;
+declare function formatMessageAsRoff(msg: Message, options?: RoffFormatOptions): string;
 //#endregion
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/dist/{roff-EpcecLXU.cjs → roff-DJ-LkRXl.cjs}

@@ -41,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.
@@ -61,18 +97,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";
@@ -113,11 +153,12 @@ 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");
 }
@@ -129,6 +170,18 @@ Object.defineProperty(exports, 'escapeHyphens', {
     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 () {

package/dist/roff.cjs

@@ -1,5 +1,7 @@
-const require_roff = require('./roff-EpcecLXU.cjs');
+const require_roff = require('./roff-DJ-LkRXl.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 { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-COeDIWWF.cjs";
+export { RoffFormatOptions, 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 { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CgYQDHBN.js";
+export { RoffFormatOptions, 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-CCdIQO7B.js";
 
-export { escapeHyphens, escapeRoff, formatMessageAsRoff };
+export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "0.10.7-dev.485+0a30b635",
+  "version": "1.0.0-dev.1109+fa132665",
   "description": "Man page generator for Optique CLI parsers",
   "keywords": [
     "CLI",
@@ -84,8 +84,8 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "0.10.7-dev.485+0a30b635",
-    "@optique/run": "0.10.7-dev.485+0a30b635"
+    "@optique/core": "1.0.0-dev.1109+fa132665",
+    "@optique/run": "1.0.0-dev.1109+fa132665"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",

package/dist/man-DGnow1Jr.cjs

@@ -1,235 +0,0 @@
-const require_roff = require('./roff-EpcecLXU.cjs');
-
-//#region src/man.ts
-/**
-* Formats a date for use in man pages.
-*
-* @param date The date to format, or undefined.
-* @returns The formatted date string, or undefined.
-* @since 0.10.0
-*/
-function formatDateForMan(date) {
-	if (date === void 0) return void 0;
-	if (typeof date === "string") return date;
-	const months = [
-		"January",
-		"February",
-		"March",
-		"April",
-		"May",
-		"June",
-		"July",
-		"August",
-		"September",
-		"October",
-		"November",
-		"December"
-	];
-	return `${months[date.getMonth()]} ${date.getFullYear()}`;
-}
-function escapeThField(value) {
-	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
-}
-/**
-* Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
-*
-* @param term The usage term to format.
-* @returns The roff-formatted string.
-* @since 0.10.0
-*/
-function formatUsageTermAsRoff(term) {
-	if ("hidden" in term && term.hidden) return "";
-	switch (term.type) {
-		case "argument": return `\\fI${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` : "";
-			return `[${names}${metavarPart}]`;
-		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "optional": {
-			const inner = formatUsageAsRoff(term.terms);
-			return `[${inner}]`;
-		}
-		case "multiple": {
-			const inner = formatUsageAsRoff(term.terms);
-			if (term.min < 1) return `[${inner} ...]`;
-			return `${inner} ...`;
-		}
-		case "exclusive": {
-			const alternatives = term.terms.map((t) => formatUsageAsRoff(t)).join(" | ");
-			return `(${alternatives})`;
-		}
-		case "literal": return term.value;
-		case "passthrough": 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 usage.map(formatUsageTermAsRoff).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) {
-	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` : "";
-			return `${names}${metavarPart}`;
-		}
-		case "command": return `\\fB${term.name}\\fR`;
-		case "argument": return `\\fI${term.metavar}\\fR`;
-		case "literal": return term.value;
-		default: return formatUsageTermAsRoff(term);
-	}
-}
-/**
-* 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) {
-		lines.push(".TP");
-		lines.push(formatDocEntryTerm(entry.term));
-		if (entry.description) {
-			let desc = require_roff.formatMessageAsRoff(entry.description);
-			if (entry.default) desc += ` [${require_roff.formatMessageAsRoff(entry.default)}]`;
-			lines.push(desc);
-		} else if (entry.default) lines.push(`[${require_roff.formatMessageAsRoff(entry.default)}]`);
-	}
-	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.
-* @since 0.10.0
-*/
-function formatDocPageAsMan(page, options) {
-	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;
-	if (hasDate) thParts.push(`"${escapeThField(formatDateForMan(options.date))}"`);
-	else if (hasVersion || hasManual) thParts.push("\"\"");
-	if (hasVersion) thParts.push(`"${escapeThField(`${options.name} ${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.usage) {
-		lines.push(".SH SYNOPSIS");
-		lines.push(`.B ${options.name}`);
-		const usageStr = formatUsageAsRoff(page.usage);
-		if (usageStr) lines.push(usageStr);
-	}
-	if (page.description) {
-		lines.push(".SH DESCRIPTION");
-		lines.push(require_roff.formatMessageAsRoff(page.description));
-	}
-	for (const section of page.sections) {
-		if (section.entries.length === 0) continue;
-		const title = section.title?.toUpperCase() ?? "OPTIONS";
-		lines.push(`.SH ${title}`);
-		lines.push(formatDocSectionEntries(section));
-	}
-	if (options.environment && options.environment.entries.length > 0) {
-		lines.push(".SH ENVIRONMENT");
-		lines.push(formatDocSectionEntries(options.environment));
-	}
-	if (options.files && options.files.entries.length > 0) {
-		lines.push(".SH FILES");
-		lines.push(formatDocSectionEntries(options.files));
-	}
-	if (options.exitStatus && options.exitStatus.entries.length > 0) {
-		lines.push(".SH EXIT STATUS");
-		lines.push(formatDocSectionEntries(options.exitStatus));
-	}
-	if (options.examples) {
-		lines.push(".SH EXAMPLES");
-		lines.push(require_roff.formatMessageAsRoff(options.examples));
-	}
-	if (options.bugs) {
-		lines.push(".SH BUGS");
-		lines.push(require_roff.formatMessageAsRoff(options.bugs));
-	}
-	if (options.seeAlso && options.seeAlso.length > 0) {
-		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}`;
-		});
-		lines.push(refs.join("\n"));
-	}
-	if (options.author) {
-		lines.push(".SH AUTHOR");
-		lines.push(require_roff.formatMessageAsRoff(options.author));
-	}
-	if (page.footer) {
-		lines.push(".PP");
-		lines.push(require_roff.formatMessageAsRoff(page.footer));
-	}
-	return lines.join("\n");
-}
-
-//#endregion
-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;
-  }
-});