@optique/man 1.4.0-dev.2633 → 1.4.0-dev.2636

package/dist/cli.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-const require_man = require('./man-DLcciZWq.cjs');
+const require_man = require('./man-BJ8K8qw-.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CUCPcKy-.cjs');
+const require_generator = require('./generator-DVBEnpDF.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.2633+ee18a31e";
+var version = "1.4.0-dev.2636+d5357098";
 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-CTCssitL.js";
-import { generateManPageAsync } from "./generator-IQLTxhd0.js";
+import "./man-Dq6PNLlO.js";
+import { generateManPageAsync } from "./generator-CavUoyIv.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.2633+ee18a31e";
+var version = "1.4.0-dev.2636+d5357098";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",

package/dist/{generator-IQLTxhd0.js → generator-CavUoyIv.js}

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

package/dist/{generator-CUCPcKy-.cjs → generator-DVBEnpDF.cjs}

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

package/dist/{generator-BK-jIonK.d.ts → generator-DgWHeZ4I.d.ts}

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

package/dist/{generator-stLqR1GX.d.cts → generator-vn382hBl.d.cts}

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

package/dist/generator.cjs

@@ -1,6 +1,6 @@
-require('./man-DLcciZWq.cjs');
+require('./man-BJ8K8qw-.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CUCPcKy-.cjs');
+const require_generator = require('./generator-DVBEnpDF.cjs');
 
 exports.generateManPage = require_generator.generateManPage;
 exports.generateManPageAsync = require_generator.generateManPageAsync;

package/dist/generator.d.cts

@@ -1,3 +1,3 @@
-import "./man-Yl3ZzrBK.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-stLqR1GX.cjs";
+import "./man-C--dNTRq.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-vn382hBl.cjs";
 export { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/generator.d.ts

@@ -1,3 +1,3 @@
-import "./man-B0OHE33m.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BK-jIonK.js";
+import "./man-D1GouPZ0.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DgWHeZ4I.js";
 export { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/generator.js

@@ -1,5 +1,5 @@
 import "./roff-Bh9bsH6u.js";
-import "./man-CTCssitL.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-IQLTxhd0.js";
+import "./man-Dq6PNLlO.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-CavUoyIv.js";
 
 export { generateManPage, generateManPageAsync, generateManPageSync };

package/dist/index.cjs

@@ -1,6 +1,6 @@
-const require_man = require('./man-DLcciZWq.cjs');
+const require_man = require('./man-BJ8K8qw-.cjs');
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CUCPcKy-.cjs');
+const require_generator = require('./generator-DVBEnpDF.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-Yl3ZzrBK.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-stLqR1GX.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-C--dNTRq.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-vn382hBl.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-B0OHE33m.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BK-jIonK.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-D1GouPZ0.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DgWHeZ4I.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-CTCssitL.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-IQLTxhd0.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Dq6PNLlO.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-CavUoyIv.js";
 
 export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

package/dist/{man-DLcciZWq.cjs → man-BJ8K8qw-.cjs}

@@ -249,7 +249,7 @@ function inferSectionTitle(entries) {
 * @param section The section to format.
 * @returns The roff-formatted section content.
 */
-function formatDocSectionEntries(section, showEnvironment = false) {
+function formatDocSectionEntries(section, showEnvironment = false, generatedEnvironment = false) {
 	const lines = [];
 	for (const entry of section.entries) {
 		const termStr = formatDocEntryTerm(entry.term);
@@ -262,18 +262,19 @@ function formatDocSectionEntries(section, showEnvironment = false) {
 			envVar: name
 		}])).join(", ")}]`;
 		if (entry.description) {
-			let desc = require_roff.formatMessageAsRoff(entry.description);
+			let desc = require_roff.formatMessageAsRoff(entry.description, generatedEnvironment ? { quotes: false } : {});
 			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") ? "" : " ";
-			lines.push(envAnnotation === "" ? desc : desc + separator + envAnnotation);
+			const body = envAnnotation === "" ? desc : desc + separator + envAnnotation;
+			lines.push(generatedEnvironment && body === "" ? "\\&" : body);
 		} else if (entry.default || entry.choices || envAnnotation !== "") {
 			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 })})`);
 			if (envAnnotation !== "") parts.push(envAnnotation);
 			lines.push(parts.join(" "));
-		}
+		} else if (generatedEnvironment) lines.push("\\&");
 	}
 	return lines.join("\n");
 }
@@ -357,10 +358,13 @@ function formatDocPageAsMan(page, options) {
 		lines.push(`.SH "${require_roff.escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
-	const automaticEnvironment = options.environment == null && (placement === "section" || placement === "both") ? (0, __optique_core_doc.deriveEnvironmentSection)(page, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	const automaticEnvironment = options.environment == null && placement != null ? (0, __optique_core_doc.deriveEnvironmentSection)(page, {
+		onlyUnreferenced: placement === "inline",
+		title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0
+	}) : void 0;
 	const environment = options.environment ?? automaticEnvironment;
 	if (environment != null && environment.entries.length > 0) {
-		const content = formatDocSectionEntries(environment);
+		const content = formatDocSectionEntries(environment, false, automaticEnvironment != null);
 		if (content !== "") {
 			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
 			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${require_roff.escapeRequestArg(title)}"`);

package/dist/{man-B0OHE33m.d.ts → man-C--dNTRq.d.cts}

@@ -1,5 +1,5 @@
-import { Message } from "@optique/core/message";
 import { DocPage, DocSection, ShowEnvironmentOptions } from "@optique/core/doc";
+import { Message } from "@optique/core/message";
 import { UsageTerm } from "@optique/core/usage";
 
 //#region src/man.d.ts
@@ -72,7 +72,8 @@ interface ManPageOptions {
   readonly environment?: DocSection;
   /**
    * Displays declared environment bindings. `true` selects inline annotations;
-   * an object can select a generated section or both. Defaults to `false`.
+   * an object can select a generated section or both. Names without visible
+   * CLI references get a fallback section in inline mode. Defaults to `false`.
    * A supplied `environment` section overrides the generated section, including
    * an empty section. Inline annotations are independent of that override.
    * `sectionTitle` only affects generated sections and is uppercased.

package/dist/{man-Yl3ZzrBK.d.cts → man-D1GouPZ0.d.ts}

@@ -1,5 +1,5 @@
-import { DocPage, DocSection, ShowEnvironmentOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
+import { DocPage, DocSection, ShowEnvironmentOptions } from "@optique/core/doc";
 import { UsageTerm } from "@optique/core/usage";
 
 //#region src/man.d.ts
@@ -72,7 +72,8 @@ interface ManPageOptions {
   readonly environment?: DocSection;
   /**
    * Displays declared environment bindings. `true` selects inline annotations;
-   * an object can select a generated section or both. Defaults to `false`.
+   * an object can select a generated section or both. Names without visible
+   * CLI references get a fallback section in inline mode. Defaults to `false`.
    * A supplied `environment` section overrides the generated section, including
    * an empty section. Inline annotations are independent of that override.
    * `sectionTitle` only affects generated sections and is uppercased.

package/dist/{man-CTCssitL.js → man-Dq6PNLlO.js}

@@ -226,7 +226,7 @@ function inferSectionTitle(entries) {
 * @param section The section to format.
 * @returns The roff-formatted section content.
 */
-function formatDocSectionEntries(section, showEnvironment = false) {
+function formatDocSectionEntries(section, showEnvironment = false, generatedEnvironment = false) {
 	const lines = [];
 	for (const entry of section.entries) {
 		const termStr = formatDocEntryTerm(entry.term);
@@ -239,18 +239,19 @@ function formatDocSectionEntries(section, showEnvironment = false) {
 			envVar: name
 		}])).join(", ")}]`;
 		if (entry.description) {
-			let desc = formatMessageAsRoff(entry.description);
+			let desc = formatMessageAsRoff(entry.description, generatedEnvironment ? { quotes: false } : {});
 			if (entry.default) desc += ` [${formatMessageAsRoff(entry.default)}]`;
 			if (entry.choices) desc += ` (choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`;
 			const separator = desc === "" || desc.endsWith("\n") ? "" : " ";
-			lines.push(envAnnotation === "" ? desc : desc + separator + envAnnotation);
+			const body = envAnnotation === "" ? desc : desc + separator + envAnnotation;
+			lines.push(generatedEnvironment && body === "" ? "\\&" : body);
 		} else if (entry.default || entry.choices || envAnnotation !== "") {
 			const parts = [];
 			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("\\&");
 	}
 	return lines.join("\n");
 }
@@ -334,10 +335,13 @@ function formatDocPageAsMan(page, options) {
 		lines.push(`.SH "${escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
-	const automaticEnvironment = options.environment == null && (placement === "section" || placement === "both") ? deriveEnvironmentSection(page, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	const automaticEnvironment = options.environment == null && placement != null ? deriveEnvironmentSection(page, {
+		onlyUnreferenced: placement === "inline",
+		title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0
+	}) : void 0;
 	const environment = options.environment ?? automaticEnvironment;
 	if (environment != null && environment.entries.length > 0) {
-		const content = formatDocSectionEntries(environment);
+		const content = formatDocSectionEntries(environment, false, automaticEnvironment != null);
 		if (content !== "") {
 			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
 			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${escapeRequestArg(title)}"`);

package/dist/man.cjs

@@ -1,4 +1,4 @@
-const require_man = require('./man-DLcciZWq.cjs');
+const require_man = require('./man-BJ8K8qw-.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-Yl3ZzrBK.cjs";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-C--dNTRq.cjs";
 export { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/dist/man.d.ts

@@ -1,2 +1,2 @@
-import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B0OHE33m.js";
+import { ManPageOptions, ManPageSection, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-D1GouPZ0.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-CTCssitL.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Dq6PNLlO.js";
 
 export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.4.0-dev.2633",
+  "version": "1.4.0-dev.2636",
   "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.2633+ee18a31e",
-    "@optique/run": "1.4.0-dev.2633+ee18a31e"
+    "@optique/core": "1.4.0-dev.2636+d5357098",
+    "@optique/run": "1.4.0-dev.2636+d5357098"
   },
   "devDependencies": {
-    "@optique/testing": "1.4.0-dev.2633+ee18a31e",
+    "@optique/testing": "1.4.0-dev.2636+d5357098",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "tsx": "^4.21.0",