build: allow linting node.1

Signed-off-by: avivkeller <me@aviv.sh>
PR-URL: #64157
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: avivkeller

Makefile

@@ -932,6 +932,22 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
 		) \
 	fi
 
+doc/node.1:
+	$(error Please use 'make node.1' instead of 'make $@'.)
+
+.PHONY: node.1
+node.1: doc/api/cli.md tools/doc/node_modules
+	@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
+		echo "Skipping $@ (no crypto and/or no ICU)"; \
+	else \
+		$(call available-node, \
+			$(DOC_KIT) generate \
+			-v $(VERSION) \
+			--config-file tools/doc/man-page.doc-kit.config.mjs \
+			-o doc \
+		) \
+	fi
+
 .PHONY: docopen
 docopen: doc-only ## Open the documentation in a web browser.
 	@$(PYTHON) -mwebbrowser file://$(abspath $<)
@@ -1480,8 +1496,26 @@ tools/.mdlintstamp: tools/lint-md/node_modules/remark-parse/package.json $(LINT_
 	@$(call available-node,$(run-lint-md))
 	@touch $@
 
+tools/.manpagelintstamp: doc/node.1 doc/api/cli.md tools/doc/node_modules
+	$(info Verifying that $< is up to date...)
+	@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
+		echo "Skipping $< verification (no crypto and/or no ICU)"; \
+	else \
+		$(RM) -r tools/doc/.manpagecheck && \
+		$(call available-node, \
+			$(DOC_KIT) generate \
+			-v $(VERSION) \
+			--config-file tools/doc/man-page.doc-kit.config.mjs \
+		) \
+		if ! diff -u $< tools/doc/.manpagecheck/node.1; then \
+			echo '$< is out of date; run `make node.1` to regenerate it.' >&2; \
+			exit 1; \
+		fi; \
+	fi
+	@touch $@
+
 .PHONY: lint-md
-lint-md: lint-js-doc | tools/.mdlintstamp ## Lint the markdown documents maintained by us in the codebase.
+lint-md: lint-js-doc | tools/.mdlintstamp tools/.manpagelintstamp ## Lint the markdown documents maintained by us in the codebase.
 
 run-format-md = tools/lint-md/lint-md.mjs --format $(LINT_MD_FILES)
 .PHONY: format-md

doc/node.1

@@ -147,7 +147,7 @@ The valid arguments for the \fB--allow-fs-read\fR flag are:
 \fB*\fR - To allow all \fBFileSystemRead\fR operations.
 .It
 Multiple paths can be allowed using multiple \fB--allow-fs-read\fR flags.
-Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder1/\fR
+Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder2/\fR
 .El
 Examples can be found in the File System Permissions documentation.
 The initializer module and custom \fB--require\fR modules has a implicit
@@ -175,7 +175,7 @@ The valid arguments for the \fB--allow-fs-write\fR flag are:
 \fB*\fR - To allow all \fBFileSystemWrite\fR operations.
 .It
 Multiple paths can be allowed using multiple \fB--allow-fs-write\fR flags.
-Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder1/\fR
+Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder2/\fR
 .El
 Paths delimited by comma (\fB,\fR) are no longer allowed.
 When passing a single flag with a comma a warning will be displayed.
@@ -742,7 +742,8 @@ passing a second \fBparentURL\fR argument for contextual resolution.
 Previously gated the entire \fBimport.meta.resolve\fR feature.
 .
 .It Fl -experimental-import-text
-Enable experimental support for importing modules with \fBwith { type: 'text' }\fR.
+Enable experimental support for importing modules with
+\fBwith { type: 'text' }\fR.
 .
 .It Fl -experimental-inspector-network-resource
 Enable experimental support for inspector network resources.
@@ -767,9 +768,8 @@ See Package maps for details on the configuration file format and
 resolution algorithm.
 .
 .It Fl -experimental-print-required-tla
-If the ES module being \fBrequire()\fR'd contains top-level \fBawait\fR, this flag
-allows Node.js to evaluate the module, try to locate the
-top-level awaits, and print their location to help users find them.
+If the ES module graph cannot be \fBrequire()\fR'd because it contains any top-level \fBawait\fR,
+this flag allows Node.js to locate and print their locations.
 .
 .It Fl -experimental-quic
 Enable experimental support for the QUIC protocol.

tools/doc/man-page.doc-kit.config.mjs

@@ -0,0 +1,21 @@
+// @node-core/doc-kit configuration for generating and linting the Node.js
+// man-page (doc/node.1).
+
+import { fileURLToPath } from 'node:url';
+
+const root = new URL('../../', import.meta.url);
+
+const fromRoot = (path) => fileURLToPath(new URL(path, root));
+
+export default {
+  target: ['man-page'],
+
+  global: {
+    input: [fromRoot('doc/api/cli.md')],
+    output: fromRoot('tools/doc/.manpagecheck'),
+
+    // Point every loadable URL at its local file so no network request is made.
+    changelog: fromRoot('CHANGELOG.md'),
+    index: fromRoot('doc/api/index.md'),
+  },
+};