@optique/man 1.4.0-dev.2628 → 1.4.0-dev.2631

package/dist/cli.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-const require_man = require('./man-C44Q4VSc.cjs');
+const require_man = require('./man-DLcciZWq.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CtkCu_MS.cjs');
+const require_generator = require('./generator-CUCPcKy-.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.2628+867c4f91";
+var version = "1.4.0-dev.2631+0f2bd6a0";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",
@@ -88,6 +88,11 @@ a ${(0, __optique_core_message.metavar)("PROGRAM")} or ${(0, __optique_core_mess
   ${"1"}  User commands
   ${"5"}  File formats
   ${"8"}  System administration` }),
+		showEnvironment: (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)("--show-environment", (0, __optique_core_valueparser.choice)([
+			"inline",
+			"section",
+			"both"
+		], { metavar: "LAYOUT" }), { description: __optique_core_message.message`Document declared environment bindings inline, in a section, or both.` })),
 		exportName: (0, __optique_core_modifiers.withDefault)((0, __optique_core_primitives.option)("-e", "--export", (0, __optique_core_valueparser.string)({ metavar: "NAME" }), { description: __optique_core_message.message`JavaScript export name to use. The export must be
 a ${(0, __optique_core_message.metavar)("PROGRAM")} (from ${(0, __optique_core_message.commandLine)("defineProgram()")}) or
 a ${(0, __optique_core_message.metavar)("PARSER")}. If not specified, the default export is used.` }), "default"),
@@ -396,14 +401,16 @@ async function main() {
 			name: args.name,
 			date,
 			version: args.versionString,
-			manual: args.manual
+			manual: args.manual,
+			showEnvironment: args.showEnvironment == null ? void 0 : { placement: args.showEnvironment }
 		});
 		else manPage = await require_generator.generateManPageAsync(target, {
 			name: name$1,
 			section: args.section,
 			date,
 			version: args.versionString,
-			manual: args.manual
+			manual: args.manual,
+			showEnvironment: args.showEnvironment == null ? void 0 : { placement: args.showEnvironment }
 		});
 	} catch (error) {
 		generationError(error instanceof Error ? error : new Error(String(error)));

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import "./roff-Bh9bsH6u.js";
-import "./man-Cq0qfXg0.js";
-import { generateManPageAsync } from "./generator-DywTJCMH.js";
+import "./man-CTCssitL.js";
+import { generateManPageAsync } from "./generator-IQLTxhd0.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.2628+867c4f91";
+var version = "1.4.0-dev.2631+0f2bd6a0";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",
@@ -88,6 +88,11 @@ a ${metavar("PROGRAM")} or ${metavar("PARSER")} to generate a man page from.` })
   ${"1"}  User commands
   ${"5"}  File formats
   ${"8"}  System administration` }),
+		showEnvironment: optional(option("--show-environment", choice([
+			"inline",
+			"section",
+			"both"
+		], { metavar: "LAYOUT" }), { description: message`Document declared environment bindings inline, in a section, or both.` })),
 		exportName: withDefault(option("-e", "--export", string({ metavar: "NAME" }), { description: message`JavaScript export name to use. The export must be
 a ${metavar("PROGRAM")} (from ${commandLine("defineProgram()")}) or
 a ${metavar("PARSER")}. If not specified, the default export is used.` }), "default"),
@@ -396,14 +401,16 @@ async function main() {
 			name: args.name,
 			date,
 			version: args.versionString,
-			manual: args.manual
+			manual: args.manual,
+			showEnvironment: args.showEnvironment == null ? void 0 : { placement: args.showEnvironment }
 		});
 		else manPage = await generateManPageAsync(target, {
 			name: name$1,
 			section: args.section,
 			date,
 			version: args.versionString,
-			manual: args.manual
+			manual: args.manual,
+			showEnvironment: args.showEnvironment == null ? void 0 : { placement: args.showEnvironment }
 		});
 	} catch (error) {
 		generationError(error instanceof Error ? error : new Error(String(error)));

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

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

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

@@ -1,4 +1,4 @@
-const require_man = require('./man-C44Q4VSc.cjs');
+const require_man = require('./man-DLcciZWq.cjs');
 const __optique_core_parser = require_man.__toESM(require("@optique/core/parser"));
 
 //#region src/generator.ts
@@ -55,6 +55,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 				footer: programOptions.footer ?? metadata.footer,
 				seeAlso: programOptions.seeAlso,
 				environment: programOptions.environment,
+				showEnvironment: programOptions.showEnvironment,
 				files: programOptions.files,
 				exitStatus: programOptions.exitStatus
 			}

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

@@ -1,4 +1,4 @@
-import { formatDocPageAsMan } from "./man-Cq0qfXg0.js";
+import { formatDocPageAsMan } from "./man-CTCssitL.js";
 import { getDocPageAsync, getDocPageSync } from "@optique/core/parser";
 
 //#region src/generator.ts
@@ -55,6 +55,7 @@ function extractParserAndOptions(parserOrProgram, options) {
 				footer: programOptions.footer ?? metadata.footer,
 				seeAlso: programOptions.seeAlso,
 				environment: programOptions.environment,
+				showEnvironment: programOptions.showEnvironment,
 				files: programOptions.files,
 				exitStatus: programOptions.exitStatus
 			}

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

@@ -1,4 +1,4 @@
-import { ManPageOptions } from "./man-C3FUTPuQ.cjs";
+import { ManPageOptions } from "./man-Yl3ZzrBK.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-C44Q4VSc.cjs');
+require('./man-DLcciZWq.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CtkCu_MS.cjs');
+const require_generator = require('./generator-CUCPcKy-.cjs');
 
 exports.generateManPage = require_generator.generateManPage;
 exports.generateManPageAsync = require_generator.generateManPageAsync;

package/dist/generator.d.cts

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

package/dist/generator.d.ts

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

package/dist/generator.js

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

package/dist/index.cjs

@@ -1,6 +1,6 @@
-const require_man = require('./man-C44Q4VSc.cjs');
+const require_man = require('./man-DLcciZWq.cjs');
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-CtkCu_MS.cjs');
+const require_generator = require('./generator-CUCPcKy-.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-C3FUTPuQ.cjs";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-I9cXlw1Z.cjs";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-Yl3ZzrBK.cjs";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-stLqR1GX.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-CHYiSoI_.js";
-import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-MbR1I1SH.js";
+import { ManPageOptions, formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-B0OHE33m.js";
+import { GenerateManPageOptions, GenerateManPageProgramOptions, generateManPage, generateManPageAsync, generateManPageSync } from "./generator-BK-jIonK.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-Cq0qfXg0.js";
-import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-DywTJCMH.js";
+import { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff } from "./man-CTCssitL.js";
+import { generateManPage, generateManPageAsync, generateManPageSync } from "./generator-IQLTxhd0.js";
 
 export { escapeHyphens, escapeQuotedValue, escapeRequestArg, escapeRoff, formatDateForMan, formatDocPageAsMan, formatMessageAsRoff, formatUsageTermAsRoff, generateManPage, generateManPageAsync, generateManPageSync };

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

@@ -1,5 +1,5 @@
-import { DocPage, DocSection } 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
@@ -70,6 +70,15 @@ interface ManPageOptions {
    * Environment variables to document in the ENVIRONMENT section.
    */
   readonly environment?: DocSection;
+  /**
+   * Displays declared environment bindings. `true` selects inline annotations;
+   * an object can select a generated section or both. 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.
+   * @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * File paths to document in the FILES section.
    */
@@ -148,7 +157,8 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @param page The documentation page to format.
  * @param options The man page options.
  * @returns The complete man page in roff format.
- * @throws {TypeError} If the program name is empty.
+ * @throws {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).
  * @since 0.10.0

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

@@ -1,4 +1,5 @@
 import { escapeHyphens, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-Bh9bsH6u.js";
+import { deriveEnvironmentSection } from "@optique/core/doc";
 import { isDocHidden, isUsageHidden } from "@optique/core/usage";
 
 //#region src/man.ts
@@ -225,22 +226,29 @@ function inferSectionTitle(entries) {
 * @param section The section to format.
 * @returns The roff-formatted section content.
 */
-function formatDocSectionEntries(section) {
+function formatDocSectionEntries(section, showEnvironment = false) {
 	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 envAnnotation = envNames.length === 0 ? "" : `[env: ${envNames.map((name) => formatMessageAsRoff([{
+			type: "envVar",
+			envVar: name
+		}])).join(", ")}]`;
 		if (entry.description) {
 			let desc = formatMessageAsRoff(entry.description);
 			if (entry.default) desc += ` [${formatMessageAsRoff(entry.default)}]`;
 			if (entry.choices) desc += ` (choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`;
-			lines.push(desc);
-		} else if (entry.default || entry.choices) {
+			const separator = desc === "" || desc.endsWith("\n") ? "" : " ";
+			lines.push(envAnnotation === "" ? desc : desc + separator + envAnnotation);
+		} 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(" "));
 		}
 	}
@@ -273,7 +281,8 @@ function formatDocSectionEntries(section) {
 * @param page The documentation page to format.
 * @param options The man page options.
 * @returns The complete man page in roff format.
-* @throws {TypeError} If the program name is empty.
+* @throws {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).
 * @since 0.10.0
@@ -315,18 +324,23 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH DESCRIPTION");
 		lines.push(formatMessageAsRoff(description));
 	}
+	const placement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
+	const inlineEnvironment = placement === "inline" || placement === "both";
 	for (const section of page.sections) {
 		if (section.entries.length === 0) continue;
-		const content = formatDocSectionEntries(section);
+		const content = formatDocSectionEntries(section, inlineEnvironment);
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
 		lines.push(`.SH "${escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
-	if (options.environment && options.environment.entries.length > 0) {
-		const content = formatDocSectionEntries(options.environment);
+	const automaticEnvironment = options.environment == null && (placement === "section" || placement === "both") ? deriveEnvironmentSection(page, { 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);
 		if (content !== "") {
-			lines.push(".SH ENVIRONMENT");
+			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
+			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${escapeRequestArg(title)}"`);
 			lines.push(content);
 		}
 	}

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

@@ -22,6 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 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"));
 
 //#region src/man.ts
@@ -248,22 +249,29 @@ function inferSectionTitle(entries) {
 * @param section The section to format.
 * @returns The roff-formatted section content.
 */
-function formatDocSectionEntries(section) {
+function formatDocSectionEntries(section, showEnvironment = false) {
 	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 envAnnotation = envNames.length === 0 ? "" : `[env: ${envNames.map((name) => require_roff.formatMessageAsRoff([{
+			type: "envVar",
+			envVar: name
+		}])).join(", ")}]`;
 		if (entry.description) {
 			let desc = require_roff.formatMessageAsRoff(entry.description);
 			if (entry.default) desc += ` [${require_roff.formatMessageAsRoff(entry.default)}]`;
 			if (entry.choices) desc += ` (choices: ${require_roff.formatMessageAsRoff(entry.choices, { quotes: false })})`;
-			lines.push(desc);
-		} else if (entry.default || entry.choices) {
+			const separator = desc === "" || desc.endsWith("\n") ? "" : " ";
+			lines.push(envAnnotation === "" ? desc : desc + separator + envAnnotation);
+		} 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(" "));
 		}
 	}
@@ -296,7 +304,8 @@ function formatDocSectionEntries(section) {
 * @param page The documentation page to format.
 * @param options The man page options.
 * @returns The complete man page in roff format.
-* @throws {TypeError} If the program name is empty.
+* @throws {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).
 * @since 0.10.0
@@ -338,18 +347,23 @@ function formatDocPageAsMan(page, options) {
 		lines.push(".SH DESCRIPTION");
 		lines.push(require_roff.formatMessageAsRoff(description));
 	}
+	const placement = typeof options.showEnvironment === "object" ? options.showEnvironment.placement ?? "inline" : options.showEnvironment ? "inline" : void 0;
+	const inlineEnvironment = placement === "inline" || placement === "both";
 	for (const section of page.sections) {
 		if (section.entries.length === 0) continue;
-		const content = formatDocSectionEntries(section);
+		const content = formatDocSectionEntries(section, inlineEnvironment);
 		if (content === "") continue;
 		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
 		lines.push(`.SH "${require_roff.escapeRequestArg(title)}"`);
 		lines.push(content);
 	}
-	if (options.environment && options.environment.entries.length > 0) {
-		const content = formatDocSectionEntries(options.environment);
+	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 environment = options.environment ?? automaticEnvironment;
+	if (environment != null && environment.entries.length > 0) {
+		const content = formatDocSectionEntries(environment);
 		if (content !== "") {
-			lines.push(".SH ENVIRONMENT");
+			const title = automaticEnvironment == null ? "ENVIRONMENT" : automaticEnvironment.title?.toUpperCase() ?? "ENVIRONMENT";
+			lines.push(title === "ENVIRONMENT" ? ".SH ENVIRONMENT" : `.SH "${require_roff.escapeRequestArg(title)}"`);
 			lines.push(content);
 		}
 	}

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

@@ -1,6 +1,6 @@
+import { DocPage, DocSection, ShowEnvironmentOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
 import { UsageTerm } from "@optique/core/usage";
-import { DocPage, DocSection } from "@optique/core/doc";
 
 //#region src/man.d.ts
 
@@ -70,6 +70,15 @@ interface ManPageOptions {
    * Environment variables to document in the ENVIRONMENT section.
    */
   readonly environment?: DocSection;
+  /**
+   * Displays declared environment bindings. `true` selects inline annotations;
+   * an object can select a generated section or both. 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.
+   * @since 1.4.0
+   */
+  readonly showEnvironment?: boolean | ShowEnvironmentOptions;
   /**
    * File paths to document in the FILES section.
    */
@@ -148,7 +157,8 @@ declare function formatUsageTermAsRoff(term: UsageTerm): string;
  * @param page The documentation page to format.
  * @param options The man page options.
  * @returns The complete man page in roff format.
- * @throws {TypeError} If the program name is empty.
+ * @throws {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).
  * @since 0.10.0

package/dist/man.cjs

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

package/dist/man.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/man",
-  "version": "1.4.0-dev.2628",
+  "version": "1.4.0-dev.2631",
   "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.2628+867c4f91",
-    "@optique/run": "1.4.0-dev.2628+867c4f91"
+    "@optique/core": "1.4.0-dev.2631+0f2bd6a0",
+    "@optique/run": "1.4.0-dev.2631+0f2bd6a0"
   },
   "devDependencies": {
-    "@optique/testing": "1.4.0-dev.2628+867c4f91",
+    "@optique/testing": "1.4.0-dev.2631+0f2bd6a0",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "tsx": "^4.21.0",