@optique/man 1.4.0-dev.2979 → 1.4.0-dev.2992

package/dist/cli.cjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 const require_chunk = require('./chunk-CUT6urMc.cjs');
 require('./roff-C8MvQ2tL.cjs');
-require('./man-ChbwsIhG.cjs');
-const require_generator = require('./generator-DYAqAqpo.cjs');
+require('./man-CHy1T6Mq.cjs');
+const require_generator = require('./generator-DnoyvwHV.cjs');
 const __optique_core_constructs = require_chunk.__toESM(require("@optique/core/constructs"));
 const __optique_core_primitives = require_chunk.__toESM(require("@optique/core/primitives"));
 const __optique_core_valueparser = require_chunk.__toESM(require("@optique/core/valueparser"));
@@ -18,7 +18,7 @@ const node_url = require_chunk.__toESM(require("node:url"));
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.4.0-dev.2979+a175cdb7";
+var version = "1.4.0-dev.2992+c4f1ddf9";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "./roff-Bh9bsH6u.js";
-import "./man-do5Ey935.js";
-import { generateManPageAsync } from "./generator-ChMzn8U9.js";
+import "./man-B8NXqGxL.js";
+import { generateManPageAsync } from "./generator-BP_7uXi7.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.4.0-dev.2979+a175cdb7";
+var version = "1.4.0-dev.2992+c4f1ddf9";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{generator-ChMzn8U9.js → generator-BP_7uXi7.js}

@@ -1,4 +1,4 @@
-import { formatDocPageAsMan } from "./man-do5Ey935.js";
+import { formatDocPageAsMan } from "./man-B8NXqGxL.js";
 import { getDocPageAsync, getDocPageSync } from "@optique/core/parser";
 
 //#region src/generator.ts
@@ -57,6 +57,8 @@ function extractParserAndOptions(parserOrProgram, options) {
 				environment: programOptions.environment,
 				showEnvironment: programOptions.showEnvironment,
 				showAliases: programOptions.showAliases,
+				showDefault: programOptions.showDefault,
+				showChoices: programOptions.showChoices,
 				files: programOptions.files,
 				exitStatus: programOptions.exitStatus
 			}

package/dist/{generator-BOtzZZU6.d.cts → generator-BVJg1ycJ.d.ts}

@@ -1,6 +1,6 @@
-import { ManPageOptions } from "./man-Czp4fceb.cjs";
-import { Mode, ModeValue, Parser } from "@optique/core/parser";
+import { ManPageOptions } from "./man-DTinCsVW.js";
 import { Program } from "@optique/core/program";
+import { Mode, ModeValue, Parser } from "@optique/core/parser";
 
 //#region src/generator.d.ts
 
@@ -51,6 +51,8 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * @param options The man page generation options.
  * @returns The complete man page in roff format.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -82,6 +84,8 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -150,6 +154,8 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @param options The man page generation options.
  * @returns The complete man page in roff format, or a Promise for async parsers.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;

package/dist/{generator-BZBZucRz.d.ts → generator-Cfh2NRJt.d.cts}

@@ -1,6 +1,6 @@
-import { ManPageOptions } from "./man-DgWDaZfO.js";
-import { Program } from "@optique/core/program";
+import { ManPageOptions } from "./man-CZ-4svg4.cjs";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
+import { Program } from "@optique/core/program";
 
 //#region src/generator.d.ts
 
@@ -51,6 +51,8 @@ interface GenerateManPageProgramOptions extends Partial<Omit<ManPageOptions, "se
  * @param options The man page generation options.
  * @returns The complete man page in roff format.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPageSync<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;
@@ -82,6 +84,8 @@ declare function generateManPageSync(parser: Parser<"sync", unknown, unknown>, o
  * @param options The man page generation options.
  * @returns A promise that resolves to the complete man page in roff format.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPageAsync<M extends Mode, T>(program: Program<M, T>, options: GenerateManPageProgramOptions): Promise<string>;
@@ -150,6 +154,8 @@ declare function generateManPageAsync<M extends Mode>(parser: Parser<M, unknown,
  * @param options The man page generation options.
  * @returns The complete man page in roff format, or a Promise for async parsers.
  * @throws {TypeError} If the input is not a valid Parser or Program.
+ * @throws {RangeError} If `showChoices.maxItems` is less than `1` or a man
+ * page section number is invalid.
  * @since 0.10.0
  */
 declare function generateManPage<T>(program: Program<"sync", T>, options: GenerateManPageProgramOptions): string;

package/dist/{generator-DYAqAqpo.cjs → generator-DnoyvwHV.cjs}

@@ -1,5 +1,5 @@
 const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_man = require('./man-ChbwsIhG.cjs');
+const require_man = require('./man-CHy1T6Mq.cjs');
 const __optique_core_parser = require_chunk.__toESM(require("@optique/core/parser"));
 
 //#region src/generator.ts
@@ -58,6 +58,8 @@ function extractParserAndOptions(parserOrProgram, options) {
 				environment: programOptions.environment,
 				showEnvironment: programOptions.showEnvironment,
 				showAliases: programOptions.showAliases,
+				showDefault: programOptions.showDefault,
+				showChoices: programOptions.showChoices,
 				files: programOptions.files,
 				exitStatus: programOptions.exitStatus
 			}

package/dist/generator.cjs

@@ -1,6 +1,6 @@
 require('./roff-C8MvQ2tL.cjs');
-require('./man-ChbwsIhG.cjs');
-const require_generator = require('./generator-DYAqAqpo.cjs');
+require('./man-CHy1T6Mq.cjs');
+const require_generator = require('./generator-DnoyvwHV.cjs');
 
 exports.generateManPage = require_generator.generateManPage;
 exports.generateManPageAsync = require_generator.generateManPageAsync;

package/dist/generator.d.cts

@@ -1,3 +1,3 @@
-import "./man-Czp4fceb.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BOtzZZU6.cjs";
+import "./man-CZ-4svg4.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-Cfh2NRJt.cjs";
 export { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/generator.d.ts

@@ -1,3 +1,3 @@
-import "./man-DgWDaZfO.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BZBZucRz.js";
+import "./man-DTinCsVW.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BVJg1ycJ.js";
 export { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/generator.js

@@ -1,5 +1,5 @@
 import "./roff-Bh9bsH6u.js";
-import "./man-do5Ey935.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-ChMzn8U9.js";
+import "./man-B8NXqGxL.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BP_7uXi7.js";
 
 export { generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const require_man = require('./man-ChbwsIhG.cjs');
-const require_generator = require('./generator-DYAqAqpo.cjs');
+const require_man = require('./man-CHy1T6Mq.cjs');
+const require_generator = require('./generator-DnoyvwHV.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
 exports.escapeQuotedValue = require_roff.escapeQuotedValue;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Czp4fceb.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BOtzZZU6.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CZ-4svg4.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-Cfh2NRJt.cjs";
 import { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-Cpm_FJok.cjs";
 export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, type RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DgWDaZfO.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BZBZucRz.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DTinCsVW.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BVJg1ycJ.js";
 import { RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-DkJvVQ1o.js";
 export { type GenerateManPageOptions, type GenerateManPageProgramOptions, type ManPageOptions, type RoffFormatOptions, escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-Bh9bsH6u.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-do5Ey935.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-ChMzn8U9.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B8NXqGxL.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BP_7uXi7.js";
 
 export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-do5Ey935.js → man-B8NXqGxL.js}

@@ -241,40 +241,61 @@ function formatAliasesAnnotation(entry, showAliases) {
 	};
 }
 /**
-* Formats a {@link DocSection} as roff markup with .TP macros.
-*
-* @param section The section to format.
-* @returns The roff-formatted section content.
+* Limits choices by counting value terms, preserving structured messages and
+* removing the text separator immediately before the first omitted value.
 */
-function formatDocSectionEntries(section, showEnvironment = false, generatedEnvironment = false, showAliases = false) {
+function truncateChoices(choices, maxItems) {
+	if (maxItems < Infinity) {
+		let valueCount = 0;
+		for (let i = 0; i < choices.length; i++) if (choices[i].type === "value" && ++valueCount > maxItems) {
+			const cutIndex = i > 0 && choices[i - 1].type === "text" ? i - 1 : i;
+			return [...choices.slice(0, cutIndex), {
+				type: "text",
+				text: ", ..."
+			}];
+		}
+	}
+	return choices;
+}
+/**
+* Formats a {@link DocSection} as roff markup with .TP macros and the
+* requested annotations.
+*/
+function formatDocSectionEntries(section, options = {}) {
 	const lines = [];
 	for (const entry of section.entries) {
 		const termStr = formatDocEntryTerm(entry.term);
 		if (termStr === "") continue;
 		lines.push(".TP");
 		lines.push(termStr);
-		const envNames = showEnvironment ? [...new Set(entry.envVars ?? [])].filter((name) => name !== "") : [];
+		const envNames = options.showEnvironment ? [...new Set(entry.envVars ?? [])].filter((name) => name !== "") : [];
 		const envAnnotation = envNames.length === 0 ? "" : `[env: ${envNames.map((name) => formatMessageAsRoff([{
 			type: "envVar",
 			envVar: name
 		}])).join(", ")}]`;
-		const aliases = formatAliasesAnnotation(entry, showAliases);
-		if (entry.description) {
-			let desc = formatMessageAsRoff(entry.description, generatedEnvironment ? { quotes: false } : {});
-			if (aliases != null) desc += escapeHyphens(escapeRoff(aliases.prefix + aliases.body));
-			if (entry.default) desc += ` [${formatMessageAsRoff(entry.default)}]`;
-			if (entry.choices) desc += ` (choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`;
-			const separator = desc === "" || desc.endsWith("\n") ? "" : " ";
-			const body = envAnnotation === "" ? desc : desc + separator + envAnnotation;
-			lines.push(generatedEnvironment && body === "" ? "\\&" : body);
-		} else if (aliases != null || entry.default || entry.choices || envAnnotation !== "") {
-			const parts = [];
-			if (aliases != null) parts.push(escapeHyphens(escapeRoff(aliases.prefix.trimStart() + aliases.body)));
-			if (entry.default) parts.push(`[${formatMessageAsRoff(entry.default)}]`);
-			if (entry.choices) parts.push(`(choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`);
-			if (envAnnotation !== "") parts.push(envAnnotation);
-			lines.push(parts.join(" "));
-		} else if (generatedEnvironment) lines.push("\\&");
+		let body = entry.description == null ? "" : formatMessageAsRoff(entry.description, options.generatedEnvironment ? { quotes: false } : {});
+		const annotationPrefix = (prefix) => body === "" || body.endsWith("\n") ? prefix.replace(/^[^\S\r\n]+/, "") : prefix;
+		const aliases = formatAliasesAnnotation(entry, options.showAliases ?? false);
+		if (aliases != null) body += escapeHyphens(escapeRoff(annotationPrefix(aliases.prefix + aliases.body)));
+		if (options.showDefault !== false && entry.default?.length) {
+			const config = typeof options.showDefault === "object" ? options.showDefault : {};
+			body += escapeRoff(annotationPrefix(config.prefix ?? " (default: "));
+			body += formatMessageAsRoff(entry.default);
+			body += escapeRoff(config.suffix ?? ")");
+		}
+		if (options.showChoices !== false && entry.choices?.length) {
+			const config = typeof options.showChoices === "object" ? options.showChoices : {};
+			const maxItems = options.showChoices === void 0 ? Infinity : config.maxItems ?? 8;
+			body += escapeRoff(annotationPrefix((config.prefix ?? " (") + (config.label ?? "choices: ")));
+			body += formatMessageAsRoff(truncateChoices(entry.choices, maxItems), { quotes: false });
+			body += escapeRoff(config.suffix ?? ")");
+		}
+		if (envAnnotation !== "") {
+			const separator = body === "" || body.endsWith("\n") ? "" : " ";
+			body += separator + envAnnotation;
+		}
+		if (body !== "") lines.push(body);
+		else if (options.generatedEnvironment) lines.push("\\&");
 	}
 	return lines.join("\n");
 }
@@ -308,10 +329,12 @@ function formatDocSectionEntries(section, showEnvironment = false, generatedEnvi
 * @throws {TypeError} If the program name is empty or a generated environment
 * section title is empty, whitespace-only, or contains control characters.
 * @throws {RangeError} If the section number or any `seeAlso` entry's section
-* number is not a valid man page section (1–8).
+* number is not a valid man page section (1–8), or `showChoices.maxItems`
+* is less than `1`.
 * @since 0.10.0
 */
 function formatDocPageAsMan(page, options) {
+	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null && options.showChoices.maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${options.showChoices.maxItems}.`);
 	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;
@@ -352,7 +375,12 @@ function formatDocPageAsMan(page, options) {
 	const inlineEnvironment = placement === "inline" || placement === "both";
 	for (const section of page.sections) {
 		if (section.entries.length === 0) continue;
-		const content = formatDocSectionEntries(section, inlineEnvironment, false, options.showAliases ?? false);
+		const content = formatDocSectionEntries(section, {
+			showEnvironment: inlineEnvironment,
+			showAliases: options.showAliases,
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
 		lines.push(`.SH "${escapeRequestArg(title)}"`);
@@ -364,7 +392,11 @@ function formatDocPageAsMan(page, options) {
 	}) : void 0;
 	const environment = options.environment ?? automaticEnvironment;
 	if (environment != null && environment.entries.length > 0) {
-		const content = formatDocSectionEntries(environment, false, automaticEnvironment != null);
+		const content = formatDocSectionEntries(environment, {
+			generatedEnvironment: automaticEnvironment != null,
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
 			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${escapeRequestArg(title)}"`);
@@ -372,14 +404,20 @@ function formatDocPageAsMan(page, options) {
 		}
 	}
 	if (options.files && options.files.entries.length > 0) {
-		const content = formatDocSectionEntries(options.files);
+		const content = formatDocSectionEntries(options.files, {
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			lines.push(".SH FILES");
 			lines.push(content);
 		}
 	}
 	if (options.exitStatus && options.exitStatus.entries.length > 0) {
-		const content = formatDocSectionEntries(options.exitStatus);
+		const content = formatDocSectionEntries(options.exitStatus, {
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			lines.push(".SH EXIT STATUS");
 			lines.push(content);

package/dist/{man-ChbwsIhG.cjs → man-CHy1T6Mq.cjs}

@@ -242,40 +242,61 @@ function formatAliasesAnnotation(entry, showAliases) {
 	};
 }
 /**
-* Formats a {@link DocSection} as roff markup with .TP macros.
-*
-* @param section The section to format.
-* @returns The roff-formatted section content.
+* Limits choices by counting value terms, preserving structured messages and
+* removing the text separator immediately before the first omitted value.
 */
-function formatDocSectionEntries(section, showEnvironment = false, generatedEnvironment = false, showAliases = false) {
+function truncateChoices(choices, maxItems) {
+	if (maxItems < Infinity) {
+		let valueCount = 0;
+		for (let i = 0; i < choices.length; i++) if (choices[i].type === "value" && ++valueCount > maxItems) {
+			const cutIndex = i > 0 && choices[i - 1].type === "text" ? i - 1 : i;
+			return [...choices.slice(0, cutIndex), {
+				type: "text",
+				text: ", ..."
+			}];
+		}
+	}
+	return choices;
+}
+/**
+* Formats a {@link DocSection} as roff markup with .TP macros and the
+* requested annotations.
+*/
+function formatDocSectionEntries(section, options = {}) {
 	const lines = [];
 	for (const entry of section.entries) {
 		const termStr = formatDocEntryTerm(entry.term);
 		if (termStr === "") continue;
 		lines.push(".TP");
 		lines.push(termStr);
-		const envNames = showEnvironment ? [...new Set(entry.envVars ?? [])].filter((name) => name !== "") : [];
+		const envNames = options.showEnvironment ? [...new Set(entry.envVars ?? [])].filter((name) => name !== "") : [];
 		const envAnnotation = envNames.length === 0 ? "" : `[env: ${envNames.map((name) => require_roff.formatMessageAsRoff([{
 			type: "envVar",
 			envVar: name
 		}])).join(", ")}]`;
-		const aliases = formatAliasesAnnotation(entry, showAliases);
-		if (entry.description) {
-			let desc = require_roff.formatMessageAsRoff(entry.description, generatedEnvironment ? { quotes: false } : {});
-			if (aliases != null) desc += require_roff.escapeHyphens(require_roff.escapeRoff(aliases.prefix + aliases.body));
-			if (entry.default) desc += ` [${require_roff.formatMessageAsRoff(entry.default)}]`;
-			if (entry.choices) desc += ` (choices: ${require_roff.formatMessageAsRoff(entry.choices, { quotes: false })})`;
-			const separator = desc === "" || desc.endsWith("\n") ? "" : " ";
-			const body = envAnnotation === "" ? desc : desc + separator + envAnnotation;
-			lines.push(generatedEnvironment && body === "" ? "\\&" : body);
-		} else if (aliases != null || entry.default || entry.choices || envAnnotation !== "") {
-			const parts = [];
-			if (aliases != null) parts.push(require_roff.escapeHyphens(require_roff.escapeRoff(aliases.prefix.trimStart() + aliases.body)));
-			if (entry.default) parts.push(`[${require_roff.formatMessageAsRoff(entry.default)}]`);
-			if (entry.choices) parts.push(`(choices: ${require_roff.formatMessageAsRoff(entry.choices, { quotes: false })})`);
-			if (envAnnotation !== "") parts.push(envAnnotation);
-			lines.push(parts.join(" "));
-		} else if (generatedEnvironment) lines.push("\\&");
+		let body = entry.description == null ? "" : require_roff.formatMessageAsRoff(entry.description, options.generatedEnvironment ? { quotes: false } : {});
+		const annotationPrefix = (prefix) => body === "" || body.endsWith("\n") ? prefix.replace(/^[^\S\r\n]+/, "") : prefix;
+		const aliases = formatAliasesAnnotation(entry, options.showAliases ?? false);
+		if (aliases != null) body += require_roff.escapeHyphens(require_roff.escapeRoff(annotationPrefix(aliases.prefix + aliases.body)));
+		if (options.showDefault !== false && entry.default?.length) {
+			const config = typeof options.showDefault === "object" ? options.showDefault : {};
+			body += require_roff.escapeRoff(annotationPrefix(config.prefix ?? " (default: "));
+			body += require_roff.formatMessageAsRoff(entry.default);
+			body += require_roff.escapeRoff(config.suffix ?? ")");
+		}
+		if (options.showChoices !== false && entry.choices?.length) {
+			const config = typeof options.showChoices === "object" ? options.showChoices : {};
+			const maxItems = options.showChoices === void 0 ? Infinity : config.maxItems ?? 8;
+			body += require_roff.escapeRoff(annotationPrefix((config.prefix ?? " (") + (config.label ?? "choices: ")));
+			body += require_roff.formatMessageAsRoff(truncateChoices(entry.choices, maxItems), { quotes: false });
+			body += require_roff.escapeRoff(config.suffix ?? ")");
+		}
+		if (envAnnotation !== "") {
+			const separator = body === "" || body.endsWith("\n") ? "" : " ";
+			body += separator + envAnnotation;
+		}
+		if (body !== "") lines.push(body);
+		else if (options.generatedEnvironment) lines.push("\\&");
 	}
 	return lines.join("\n");
 }
@@ -309,10 +330,12 @@ function formatDocSectionEntries(section, showEnvironment = false, generatedEnvi
 * @throws {TypeError} If the program name is empty or a generated environment
 * section title is empty, whitespace-only, or contains control characters.
 * @throws {RangeError} If the section number or any `seeAlso` entry's section
-* number is not a valid man page section (1–8).
+* number is not a valid man page section (1–8), or `showChoices.maxItems`
+* is less than `1`.
 * @since 0.10.0
 */
 function formatDocPageAsMan(page, options) {
+	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null && options.showChoices.maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${options.showChoices.maxItems}.`);
 	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;
@@ -353,7 +376,12 @@ function formatDocPageAsMan(page, options) {
 	const inlineEnvironment = placement === "inline" || placement === "both";
 	for (const section of page.sections) {
 		if (section.entries.length === 0) continue;
-		const content = formatDocSectionEntries(section, inlineEnvironment, false, options.showAliases ?? false);
+		const content = formatDocSectionEntries(section, {
+			showEnvironment: inlineEnvironment,
+			showAliases: options.showAliases,
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
 		lines.push(`.SH "${require_roff.escapeRequestArg(title)}"`);
@@ -365,7 +393,11 @@ function formatDocPageAsMan(page, options) {
 	}) : void 0;
 	const environment = options.environment ?? automaticEnvironment;
 	if (environment != null && environment.entries.length > 0) {
-		const content = formatDocSectionEntries(environment, false, automaticEnvironment != null);
+		const content = formatDocSectionEntries(environment, {
+			generatedEnvironment: automaticEnvironment != null,
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
 			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${require_roff.escapeRequestArg(title)}"`);
@@ -373,14 +405,20 @@ function formatDocPageAsMan(page, options) {
 		}
 	}
 	if (options.files && options.files.entries.length > 0) {
-		const content = formatDocSectionEntries(options.files);
+		const content = formatDocSectionEntries(options.files, {
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			lines.push(".SH FILES");
 			lines.push(content);
 		}
 	}
 	if (options.exitStatus && options.exitStatus.entries.length > 0) {
-		const content = formatDocSectionEntries(options.exitStatus);
+		const content = formatDocSectionEntries(options.exitStatus, {
+			showDefault: options.showDefault,
+			showChoices: options.showChoices
+		});
 		if (content !== "") {
 			lines.push(".SH EXIT STATUS");
 			lines.push(content);

package/dist/{man-Czp4fceb.d.cts → man-CZ-4svg4.d.cts}

@@ -1,4 +1,4 @@
-import { DocPage, DocSection, ShowAliasesOptions, ShowEnvironmentOptions } from "@optique/core/doc";
+import { DocPage, DocSection, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
 import { UsageTerm } from "@optique/core/usage";
 
@@ -88,6 +88,25 @@ interface ManPageOptions {
    * @since 1.4.0
    */
   readonly showAliases?: boolean | ShowAliasesOptions;
+  /**
+   * Whether and how to display default values. Omitted, `true`, and `{}`
+   * display `(default: value)`, with prefix `" (default: "` and suffix `")"`.
+   * Unlike help output, man pages show defaults automatically. Set to `false`
+   * to hide them, or use `{ prefix: " [", suffix: "]" }` for the old format.
+   * Explicit empty prefixes and suffixes are preserved.
+   * @since 1.4.0
+   */
+  readonly showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display choices. When omitted, displays all choices.
+   * Explicit `true` or `{}` uses prefix `" ("`, label `"choices: "`, suffix
+   * `")"`, and a limit of eight value terms, followed by `...` if truncated.
+   * Set to `false` to hide choices or set `maxItems` to `Infinity` to show all.
+   * Explicit empty prefixes, labels, and suffixes are preserved.
+   * @throws {RangeError} If `maxItems` is less than `1`.
+   * @since 1.4.0
+   */
+  readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * File paths to document in the FILES section.
    */
@@ -172,7 +191,8 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @throws {TypeError} If the program name is empty or a generated environment
  * section title is empty, whitespace-only, or contains control characters.
  * @throws {RangeError} If the section number or any `seeAlso` entry's section
- * number is not a valid man page section (1–8).
+ * number is not a valid man page section (1–8), or `showChoices.maxItems`
+ * is less than `1`.
  * @since 0.10.0
  */
 declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;

package/dist/{man-DgWDaZfO.d.ts → man-DTinCsVW.d.ts}

@@ -1,5 +1,5 @@
 import { Message } from "@optique/core/message";
-import { DocPage, DocSection, ShowAliasesOptions, ShowEnvironmentOptions } from "@optique/core/doc";
+import { DocPage, DocSection, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions } from "@optique/core/doc";
 import { UsageTerm } from "@optique/core/usage";
 
 //#region src/man.d.ts
@@ -88,6 +88,25 @@ interface ManPageOptions {
    * @since 1.4.0
    */
   readonly showAliases?: boolean | ShowAliasesOptions;
+  /**
+   * Whether and how to display default values. Omitted, `true`, and `{}`
+   * display `(default: value)`, with prefix `" (default: "` and suffix `")"`.
+   * Unlike help output, man pages show defaults automatically. Set to `false`
+   * to hide them, or use `{ prefix: " [", suffix: "]" }` for the old format.
+   * Explicit empty prefixes and suffixes are preserved.
+   * @since 1.4.0
+   */
+  readonly showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display choices. When omitted, displays all choices.
+   * Explicit `true` or `{}` uses prefix `" ("`, label `"choices: "`, suffix
+   * `")"`, and a limit of eight value terms, followed by `...` if truncated.
+   * Set to `false` to hide choices or set `maxItems` to `Infinity` to show all.
+   * Explicit empty prefixes, labels, and suffixes are preserved.
+   * @throws {RangeError} If `maxItems` is less than `1`.
+   * @since 1.4.0
+   */
+  readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * File paths to document in the FILES section.
    */
@@ -172,7 +191,8 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @throws {TypeError} If the program name is empty or a generated environment
  * section title is empty, whitespace-only, or contains control characters.
  * @throws {RangeError} If the section number or any `seeAlso` entry's section
- * number is not a valid man page section (1–8).
+ * number is not a valid man page section (1–8), or `showChoices.maxItems`
+ * is less than `1`.
  * @since 0.10.0
  */
 declare function formatDocPageAsMan(page: DocPage, options: ManPageOptions): string;

package/dist/man.cjs

@@ -1,5 +1,5 @@
 require('./roff-C8MvQ2tL.cjs');
-const require_man = require('./man-ChbwsIhG.cjs');
+const require_man = require('./man-CHy1T6Mq.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-Czp4fceb.cjs";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CZ-4svg4.cjs";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

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

package/dist/man.js

@@ -1,4 +1,4 @@
 import "./roff-Bh9bsH6u.js";
-import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-do5Ey935.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B8NXqGxL.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.4.0-dev.2979",
+  "version": "1.4.0-dev.2992",
   "description": "Man pages and Markdown command references for Optique",
   "keywords": [
     "CLI",
@@ -98,11 +98,11 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2979+a175cdb7",
-    "@optique/run": "1.4.0-dev.2979+a175cdb7"
+    "@optique/core": "1.4.0-dev.2992+c4f1ddf9",
+    "@optique/run": "1.4.0-dev.2992+c4f1ddf9"
   },
   "devDependencies": {
-    "@optique/testing": "1.4.0-dev.2979+a175cdb7",
+    "@optique/testing": "1.4.0-dev.2992+c4f1ddf9",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "tsx": "^4.21.0",