@optique/man 1.4.0-dev.2683 → 1.4.0-dev.2709

package/dist/cli.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-const require_man = require('./man-BmoPyf06.cjs');
+const require_man = require('./man-DGAR8ct4.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-BOnOtkJo.cjs');
+const require_generator = require('./generator-BAYozOjf.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.4.0-dev.2683+bacbadf3";
+var version = "1.4.0-dev.2709+c0360f12";
 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-BS0Yx0Li.js";
-import { generateManPageAsync } from "./generator-DQzLiBjq.js";
+import "./man-fxL2soSJ.js";
+import { generateManPageAsync } from "./generator-D36bK8bw.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.2683+bacbadf3";
+var version = "1.4.0-dev.2709+c0360f12";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{generator-BOnOtkJo.cjs → generator-BAYozOjf.cjs}

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

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

@@ -1,4 +1,4 @@
-import { ManPageOptions } from "./man-BON751gT.cjs";
+import { ManPageOptions } from "./man-Czp4fceb.cjs";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 

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

@@ -1,4 +1,4 @@
-import { ManPageOptions } from "./man-CwjJZCko.js";
+import { ManPageOptions } from "./man-DgWDaZfO.js";
 import { Program } from "@optique/core/program";
 import { Mode, ModeValue, Parser } from "@optique/core/parser";
 

package/dist/{generator-DQzLiBjq.js → generator-D36bK8bw.js}

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

package/dist/generator.cjs

@@ -1,6 +1,6 @@
-require('./man-BmoPyf06.cjs');
+require('./man-DGAR8ct4.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-BOnOtkJo.cjs');
+const require_generator = require('./generator-BAYozOjf.cjs');
 
 exports.generateManPage = require_generator.generateManPage;
 exports.generateManPageAsync = require_generator.generateManPageAsync;

package/dist/generator.d.cts

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

package/dist/generator.d.ts

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

package/dist/generator.js

@@ -1,5 +1,5 @@
 import "./roff-Bh9bsH6u.js";
-import "./man-BS0Yx0Li.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DQzLiBjq.js";
+import "./man-fxL2soSJ.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-D36bK8bw.js";
 
 export { generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.cjs

@@ -1,6 +1,6 @@
-const require_man = require('./man-BmoPyf06.cjs');
+const require_man = require('./man-DGAR8ct4.cjs');
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-BOnOtkJo.cjs');
+const require_generator = require('./generator-BAYozOjf.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-BON751gT.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DpK0Sjwb.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Czp4fceb.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BOtzZZU6.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-CwjJZCko.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-l5JcmLW0.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DgWDaZfO.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BZBZucRz.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-BS0Yx0Li.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DQzLiBjq.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-fxL2soSJ.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-D36bK8bw.js";
 
 export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-BON751gT.d.cts → man-Czp4fceb.d.cts}

@@ -132,6 +132,9 @@ interface ManPageOptions {
 declare function formatDateForMan(date: string | Date | undefined): string | undefined;
 /**
  * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+ * Optionality follows the supplied usage wrappers, except that a group
+ * recording `acceptsEmpty` is drawn as omissible exactly when its parser
+ * accepts an empty argument list, as in `formatUsage()`.
  *
  * @param term The usage term to format.
  * @returns The roff-formatted string.

package/dist/{man-BmoPyf06.cjs → man-DGAR8ct4.cjs}

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 const require_roff = require('./roff-C8MvQ2tL.cjs');
 const __optique_core_doc = __toESM(require("@optique/core/doc"));
 const __optique_core_usage = __toESM(require("@optique/core/usage"));
+const __optique_core_internal_usage = __toESM(require("@optique/core/internal/usage"));
 
 //#region src/man.ts
 /**
@@ -65,6 +66,9 @@ function formatCommandNameAsRoff(name) {
 }
 /**
 * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+* Optionality follows the supplied usage wrappers, except that a group
+* recording `acceptsEmpty` is drawn as omissible exactly when its parser
+* accepts an empty argument list, as in `formatUsage()`.
 *
 * @param term The usage term to format.
 * @returns The roff-formatted string.
@@ -72,15 +76,15 @@ function formatCommandNameAsRoff(name) {
 * @since 0.10.0
 */
 function formatUsageTermAsRoff(term) {
-	return formatUsageTermAsRoffInternal(term, false);
+	return formatUsageAsRoff([term]);
 }
 /**
-* 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.
+* Returns whether a usage list contains exactly one visible term that can
+* share enclosing brackets.  Options need no brackets of their own, while
+* optional and repeated terms can elide redundant brackets.  Multiple
+* visible siblings must retain their individual grouping boundaries.
 */
-function hasSingleBracketedTerm(terms) {
+function hasSingleElidableTerm(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];
@@ -100,23 +104,23 @@ function formatUsageTermAsRoffInternal(term, insideBrackets) {
 		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}]`;
+			if (insideBrackets || term.names.length < 2) 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);
+			const childrenElidable = hasSingleElidableTerm(term.terms);
+			const childIsMultiple = childrenElidable && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const inner = formatUsageAsRoffInternal(term.terms, childrenElidable);
 			if (inner === "") return "";
-			if (insideBrackets && childrenBracketed && !childIsMultiple) return inner;
+			if (insideBrackets && childrenElidable && !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 childrenElidable = hasSingleElidableTerm(term.terms);
+			const childIsMultiple = childrenElidable && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const passInsideBrackets = wrapInBrackets && childrenElidable && !childIsMultiple;
 			const inner = formatUsageAsRoffInternal(term.terms, passInsideBrackets);
 			if (inner === "") return "";
 			if (wrapInBrackets) {
@@ -148,7 +152,7 @@ function formatUsageTermAsRoffInternal(term, insideBrackets) {
 * @returns The roff-formatted string.
 */
 function formatUsageAsRoff(usage) {
-	return formatUsageAsRoffInternal(usage, false);
+	return formatUsageAsRoffInternal((0, __optique_core_internal_usage.resolveUsageForDisplay)(usage, __optique_core_usage.isUsageHidden), false);
 }
 function formatUsageAsRoffInternal(usage, insideBrackets) {
 	return usage.map((term) => formatUsageTermAsRoffInternal(term, insideBrackets)).filter((s) => s !== "").join(" ");

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

@@ -132,6 +132,9 @@ interface ManPageOptions {
 declare function formatDateForMan(date: string | Date | undefined): string | undefined;
 /**
  * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+ * Optionality follows the supplied usage wrappers, except that a group
+ * recording `acceptsEmpty` is drawn as omissible exactly when its parser
+ * accepts an empty argument list, as in `formatUsage()`.
  *
  * @param term The usage term to format.
  * @returns The roff-formatted string.

package/dist/{man-BS0Yx0Li.js → man-fxL2soSJ.js}

@@ -1,6 +1,7 @@
 import { escapeHyphens, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-Bh9bsH6u.js";
 import { deriveEnvironmentSection } from "@optique/core/doc";
 import { isDocHidden, isUsageHidden } from "@optique/core/usage";
+import { resolveUsageForDisplay } from "@optique/core/internal/usage";
 
 //#region src/man.ts
 /**
@@ -42,6 +43,9 @@ function formatCommandNameAsRoff(name) {
 }
 /**
 * Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+* Optionality follows the supplied usage wrappers, except that a group
+* recording `acceptsEmpty` is drawn as omissible exactly when its parser
+* accepts an empty argument list, as in `formatUsage()`.
 *
 * @param term The usage term to format.
 * @returns The roff-formatted string.
@@ -49,15 +53,15 @@ function formatCommandNameAsRoff(name) {
 * @since 0.10.0
 */
 function formatUsageTermAsRoff(term) {
-	return formatUsageTermAsRoffInternal(term, false);
+	return formatUsageAsRoff([term]);
 }
 /**
-* 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.
+* Returns whether a usage list contains exactly one visible term that can
+* share enclosing brackets.  Options need no brackets of their own, while
+* optional and repeated terms can elide redundant brackets.  Multiple
+* visible siblings must retain their individual grouping boundaries.
 */
-function hasSingleBracketedTerm(terms) {
+function hasSingleElidableTerm(terms) {
 	const visible = terms.filter((t$1) => !("hidden" in t$1 && isUsageHidden(t$1.hidden)));
 	if (visible.length !== 1) return false;
 	const t = visible[0];
@@ -77,23 +81,23 @@ function formatUsageTermAsRoffInternal(term, insideBrackets) {
 		case "option": {
 			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(" | ");
 			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
-			if (insideBrackets) return `${names}${metavarPart}`;
-			return `[${names}${metavarPart}]`;
+			if (insideBrackets || term.names.length < 2) 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);
+			const childrenElidable = hasSingleElidableTerm(term.terms);
+			const childIsMultiple = childrenElidable && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const inner = formatUsageAsRoffInternal(term.terms, childrenElidable);
 			if (inner === "") return "";
-			if (insideBrackets && childrenBracketed && !childIsMultiple) return inner;
+			if (insideBrackets && childrenElidable && !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 childrenElidable = hasSingleElidableTerm(term.terms);
+			const childIsMultiple = childrenElidable && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const passInsideBrackets = wrapInBrackets && childrenElidable && !childIsMultiple;
 			const inner = formatUsageAsRoffInternal(term.terms, passInsideBrackets);
 			if (inner === "") return "";
 			if (wrapInBrackets) {
@@ -125,7 +129,7 @@ function formatUsageTermAsRoffInternal(term, insideBrackets) {
 * @returns The roff-formatted string.
 */
 function formatUsageAsRoff(usage) {
-	return formatUsageAsRoffInternal(usage, false);
+	return formatUsageAsRoffInternal(resolveUsageForDisplay(usage, isUsageHidden), false);
 }
 function formatUsageAsRoffInternal(usage, insideBrackets) {
 	return usage.map((term) => formatUsageTermAsRoffInternal(term, insideBrackets)).filter((s) => s !== "").join(" ");

package/dist/man.cjs

@@ -1,4 +1,4 @@
-const require_man = require('./man-BmoPyf06.cjs');
+const require_man = require('./man-DGAR8ct4.cjs');
 require('./roff-C8MvQ2tL.cjs');
 
 exports.formatDateForMan = require_man.formatDateForMan;

package/dist/man.d.cts

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

package/dist/man.d.ts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CwjJZCko.js";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-DgWDaZfO.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-BS0Yx0Li.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-fxL2soSJ.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.4.0-dev.2683",
+  "version": "1.4.0-dev.2709",
   "description": "Man page generator for Optique CLI parsers",
   "keywords": [
     "CLI",
@@ -90,11 +90,11 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2683+bacbadf3",
-    "@optique/run": "1.4.0-dev.2683+bacbadf3"
+    "@optique/core": "1.4.0-dev.2709+c0360f12",
+    "@optique/run": "1.4.0-dev.2709+c0360f12"
   },
   "devDependencies": {
-    "@optique/testing": "1.4.0-dev.2683+bacbadf3",
+    "@optique/testing": "1.4.0-dev.2709+c0360f12",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "tsx": "^4.21.0",