From ef7f5a11e8d859fa959552676f7f7f241a78c5c6 Mon Sep 17 00:00:00 2001 From: Alhadis Date: Sun, 4 Feb 2018 00:16:50 +1100 Subject: doc: refactor manpage to use mdoc(7) macros Like man(7), mdoc(7) is a macro package for marking up computer manuals. The main difference is that mdoc is semantic rather than presentational, providing authors with a full DSL to abstract page markup from low-level Roff commands. By contrast, `man` is minimalist and leaves formatting to the author, who is expected to have a working amount of Roff knowledge. Therefore the use of `mdoc` for marking up Node's manpage is a decidedly better choice than bare `man`. Less room is left for error and mandoc(1) offers very robust error-checking and linting. PR-URL: https://github.com/nodejs/node/pull/18559 Reviewed-By: Roman Reiss Reviewed-By: James M Snell Reviewed-By: Gibson Fahnestock --- doc/node.1 | 694 +++++++++++++++++++++++++++++++------------------------------ 1 file changed, 353 insertions(+), 341 deletions(-) (limited to 'doc/node.1') diff --git a/doc/node.1 b/doc/node.1 index 836b901bea..26092d2652 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1,368 +1,380 @@ -.TH NODE 1 2016 Node.js Node.js - -.\" This is a man page comment. - -.\" Man page syntax (actually roff syntax) is somewhat obscure, but the -.\" important part is is that . specifies 's syntax for that -.\" line, and \f specifies it for the characters that follow. - -.\" .B Bold line -.\" .I Italic line (Rendered as underlined text in terminals) -.\" .BI Alternating bold/italics without spaces between arguments. -.\" Use `\ ` to include an "unpaddable" (literal) space in the output. -.\" .RI Alternating roman/italic - -.\" See http://liw.fi/manpages/ for an overview, or http://www.troff.org/54.pdf -.\" for detailed language reference. - -.\" Macro to display an underlined URL in bold -.de ur -.nr CF \\n(.f -.ft 4 -\\$1 -.ft \\n(CF -.. - - -.SH NAME - -node \- Server-side JavaScript runtime - - -.SH SYNOPSIS - -.B node -.RI [ options ] -.RI [ v8\ options ] -.RI [ script.js \ | -.B -e -.RI \&" script \&" -.RI | -.B - -.RI ] -.B [--] -.RI [ arguments ] -.br -.B node debug -.RI [ script.js " | " -.B \-e -.RI \&" script \&"\ | -.IR : ] -.I ... -.br -.B node -.RB [ \-\-v8-options ] - -Execute without arguments to start the REPL. - - -.SH DESCRIPTION - -Node.js is a set of libraries for JavaScript which allows it to be used outside -of the browser. It is primarily focused on creating simple, easy to build -network clients and servers. - - -.SH OPTIONS - -.TP -.BR \-v ", " \-\-version +.\" +.\" This manpage is written in mdoc(7). +.\" +.\" * Language reference: +.\" https://man.openbsd.org/mdoc.7 +.\" +.\" * Atom editor support: +.\" https://atom.io/packages/language-roff +.\" +.\" * Linting changes: +.\" mandoc -Wall -Tlint /path/to/this.file # BSD +.\" groff -w all -z /path/to/this.file # GNU/Linux, macOS +.\" +.\" +.\" Before making changes, please note the following: +.\" +.\" * In Roff, each new sentence should begin on a new line. This gives +.\" the Roff formatter better control over text-spacing, line-wrapping, +.\" and paragraph justification. +.\" +.\" * Do not leave blank lines in the markup. If whitespace is desired +.\" for readability, put a dot in the first column to indicate a null/empty +.\" command. Comments and horizontal whitespace may optionally follow: each +.\" of these lines are an example of a null command immediately followed by +.\" a comment. +.\" +.\"====================================================================== +. +.Dd 2018 +.Dt NODE 1 +. +.Sh NAME +.Nm node +.Nd server-side JavaScript runtime +. +.\"====================================================================== +.Sh SYNOPSIS +.Nm node +.Op Ar options +.Op Ar v8-options +.Op Fl e Ar string | Ar script.js | Fl +.Op Fl \- +.Op Ar arguments ... +. +.Nm node +.Cm debug +.Op Fl e Ar string | Ar script.js | Fl | Ar : +.Ar ... +. +.Nm node +.Op Fl -v8-options +. +.\"====================================================================== +.Sh DESCRIPTION +Node.js is a set of libraries for JavaScript which allows it to be used outside of the browser. +It is primarily focused on creating simple, easy-to-build network clients and servers. +.Pp +Execute +.Nm +without arguments to start a REPL. +. +.Sh OPTIONS +.Bl -tag -width 6n +.It Fl v , Fl -version Print node's version. - -.TP -.BR \-h ", " \-\-help +. +.It Fl h , Fl -help Print node command line options. The output of this option is less detailed than this document. - -.TP -.BR \-e ", " \-\-eval " " \fR"\fIscript\fR" -Evaluate the following argument as JavaScript. - -.TP -.BR \-p ", " \-\-print " " \fR"\fIscript\fR" -Identical to \fB-e\fR but prints the result. - -.TP -.BR \-c ", " \-\-check -Syntax check the script without executing. - -.TP -.BR \-i ", " \-\-interactive +. +.It Fl e , Fl -eval Ar string +Evaluate +.Ar string +as JavaScript. +. +.It Fl p , Fl -print Ar string +Identical to +.Fl e , +but prints the result. +. +.It Fl c , Fl -check +Check the script's syntax without executing it. +Exits with an error code if script is invalid. +. +.It Fl i , Fl -interactive Open the REPL even if stdin does not appear to be a terminal. - -.TP -.BR \-r ", " \-\-require " " \fImodule\fR -Preload the specified module at startup. Follows `require()`'s module resolution -rules. \fImodule\fR may be either a path to a file, or a node module name. - -.TP -.BR \-\-inspect \fI[=[host:]port]\fR -Activate inspector on host:port. Default is 127.0.0.1:9229. - -V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js -instances for debugging and profiling. It uses the Chrome Debugging Protocol. - -.TP -.BR \-\-inspect-brk \fI[=[host:]port]\fR -Activate inspector on host:port and break at start of user script. - -.TP -.BR \-\-inspect-port \fI=[host:]port\fR -Set the host:port to be used when the inspector is activated. - -.TP -.BR \-\-no\-deprecation +. +.It Fl r , Fl -require Ar module +Preload the specified +.Ar module +at startup. +Follows `require()`'s module resolution rules. +.Ar module +may be either a path to a file, or a node module name. +. +.It Fl -inspect Ns = Ns Ar [host:]port +Activate inspector on +.Ar host:port . +Default is +.Sy 127.0.0.1:9229 . +.Pp +V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js instances for debugging and profiling. +It uses the Chrome Debugging Protocol. +. +.It Fl -inspect-brk Ns = Ns Ar [host:]port +Activate inspector on +.Ar host:port +and break at start of user script. +. +.It Fl -inspect-port Ns = Ns Ar [host:]port +Set the +.Ar host:port +to be used when the inspector is activated. +. +.It Fl -no-deprecation Silence deprecation warnings. - -.TP -.BR \-\-trace\-deprecation +. +.It Fl -trace-deprecation Print stack traces for deprecations. - -.TP -.BR \-\-throw\-deprecation +. +.It Fl -throw-deprecation Throw errors for deprecations. - -.TP -.BR \-\-pending\-deprecation +. +.It Fl -pending-deprecation Emit pending deprecation warnings. - -.TP -.BR \-\-no\-warnings +. +.It Fl -no-warnings Silence all process warnings (including deprecations). - -.TP -.BR \-\-napi\-modules +. +.It Fl -napi-modules Enable loading native modules compiled with the ABI-stable Node.js API (N-API) (experimental). - -.TP -.BR \-\-abort\-on\-uncaught\-exception +. +.It Fl -abort-on-uncaught-exception Aborting instead of exiting causes a core file to be generated for analysis. - -.TP -.BR \-\-trace\-warnings +. +.It Fl -trace-warnings Print stack traces for process warnings (including deprecations). - -.TP -.BR \-\-redirect\-warnings=\fIfile\fR -Write process warnings to the given file instead of printing to stderr. - -.TP -.BR \-\-trace\-sync\-io -Print a stack trace whenever synchronous I/O is detected after the first turn -of the event loop. - -.TP -.BR \-\-no\-force\-async\-hooks\-checks -Disables runtime checks for `async_hooks`. These will still be enabled -dynamically when `async_hooks` is enabled. - -.TP -.BR \-\-trace\-events\-enabled -Enables the collection of trace event tracing information. - -.TP -.BR \-\-trace\-event\-categories " " \fIcategories\fR -A comma separated list of categories that should be traced when trace event -tracing is enabled using \fB--trace-events-enabled\fR. - -.TP -.BR \-\-zero\-fill\-buffers +. +.It Fl -redirect-warnings Ns = Ns Ar file +Write process warnings to the given +.Ar file +instead of printing to stderr. +. +.It Fl -trace-sync-io +Print a stack trace whenever synchronous I/O is detected after the first turn of the event loop. +. +.It Fl -no-force-async-hooks-checks +Disable runtime checks for `async_hooks`. +These will still be enabled dynamically when `async_hooks` is enabled. +. +.It Fl -trace-events-enabled +Enable the collection of trace event tracing information. +. +.It Fl -trace-event-categories Ar categories +A comma-separated list of categories that should be traced when trace event tracing is enabled using +.Fl -trace-events-enabled . +. +.It Fl -zero-fill-buffers Automatically zero-fills all newly allocated Buffer and SlowBuffer instances. - -.TP -.BR \-\-preserve\-symlinks -Instructs the module loader to preserve symbolic links when resolving and -caching modules. - -.TP -.BR \-\-track\-heap-objects +. +.It Fl -preserve-symlinks +Instructs the module loader to preserve symbolic links when resolving and caching modules. +. +.It Fl -track-heap-objects Track heap object allocations for heap snapshots. - -.TP -.BR \-\-prof\-process -Process V8 profiler output generated using the V8 option \fB\-\-prof\fR - -.TP -.BR \-\-v8\-options -Print V8 command line options. - -Note: V8 options allow words to be separated by both dashes (\fB-\fR) or -underscores (\fB_\fR). - -For example, \fB\-\-stack\-trace\-limit\fR is equivalent to -\fB\-\-stack\_trace\_limit\fR - -.TP -.BR \-\-v8\-pool\-size =\fInum\fR -Set v8's thread pool size which will be used to allocate background jobs. -If set to 0 then V8 will choose an appropriate size of the thread pool based -on the number of online processors. If the value provided is larger than v8's -max then the largest value will be chosen. - -.TP -.BR \-\-tls\-cipher\-list =\fIlist\fR -Specify an alternative default TLS cipher list. (Requires Node.js to be built -with crypto support. (Default)) - -.TP -.BR \-\-enable\-fips -Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with -\fB./configure \-\-openssl\-fips\fR) - -.TP -.BR \-\-force\-fips -Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.) -(Same requirements as \fB\-\-enable\-fips\fR) - -.TP -.BR \-\-openssl\-config =\fIfile\fR -Load an OpenSSL configuration file on startup. Among other uses, this can be -used to enable FIPS-compliant crypto if Node.js is built with -\fB./configure \-\-openssl\-fips\fR. - -.TP -.BR \-\-use\-openssl\-ca,\-\-use\-bundled\-ca -Use OpenSSL's default CA store or use bundled Mozilla CA store as supplied by -current Node.js version. The default store is selectable at build-time. - -Using OpenSSL store allows for external modifications of the store. For most -Linux and BSD distributions, this store is maintained by the distribution -maintainers and system administrators. OpenSSL CA store location is dependent on -configuration of the OpenSSL library but this can be altered at runtime using -environment variables. - -The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store -that is fixed at release time. It is identical on all supported platforms. - -See \fBSSL_CERT_DIR\fR and \fBSSL_CERT_FILE\fR. - -.TP -.BR \-\-icu\-data\-dir =\fIfile\fR -Specify ICU data load path. (overrides \fBNODE_ICU_DATA\fR) - -.TP -.BR \-\fR -Alias for stdin, analogous to the use of - in other command line utilities, -meaning that the script will be read from stdin, and the rest of the options -are passed to that script. - -.TP -.BR \-\-\fR -Indicate the end of node options. Pass the rest of the arguments to the script. - +. +.It Fl -prof-process +Process V8 profiler output generated using the V8 option +.Fl -prof . +. +.It Fl -v8-options +Print V8 command-line options. +.Pp +Note: V8 options allow words to be separated by both dashes (\fB-\fR) or underscores (\fB_\fR). +.Pp +For example, +.Fl -stack-trace-limit +is equivalent to +.Fl -stack_trace_limit . +. +.It Fl -v8-pool-size Ns = Ns Ar num +Set V8's thread pool size which will be used to allocate background jobs. +If set to 0 then V8 will choose an appropriate size of the thread pool based on the number of online processors. +If the value provided is larger than V8's maximum, then the largest value will be chosen. +. +.It Fl -tls-cipher-list Ns = Ns Ar list +Specify an alternative default TLS cipher list. +Requires Node.js to be built with crypto support. (Default) +. +.It Fl -enable-fips +Enable FIPS-compliant crypto at startup. +Requires Node.js to be built with +.Sy ./configure --openssl-fips . +. +.It Fl -force-fips +Force FIPS-compliant crypto on startup +(Cannot be disabled from script code). +Same requirements as +.Fl -enable-fips . +. +.It Fl -openssl-config Ns = Ns Ar file +Load an OpenSSL configuration file on startup. +Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with +.Sy ./configure --openssl-fips . +. +.It Fl -use-openssl-ca , Fl -use-bundled\-ca +Use OpenSSL's default CA store or use bundled Mozilla CA store as supplied by current Node.js version. +The default store is selectable at build-time. +.Pp +Using OpenSSL store allows for external modifications of the store. +For most Linux and BSD distributions, this store is maintained by the distribution maintainers and system administrators. +OpenSSL CA store location is dependent on configuration of the OpenSSL library but this can be altered at runtime using environment variables. +.Pp +The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store that is fixed at release time. +It is identical on all supported platforms. +.Pp +See +.Ev SSL_CERT_DIR +and +.Ev SSL_CERT_FILE . +. +.It Fl -icu-data-dir Ns = Ns Ar file +Specify ICU data load path. +Overrides +.Ev NODE_ICU_DATA . +. +.It Fl \-experimental-modules +Enable experimental ES module support and caching modules. +. +.It Fl \-experimental-vm-modules +Enable experimental ES module support in VM module. +. +.It Sy \- +Alias for stdin, analogous to the use of - in other command-line utilities. +The executed script is read from stdin, and remaining arguments are passed to the script. +. +.It Fl \- +Indicate the end of node options. +Pass the rest of the arguments to the script. +.Pp If no script filename or eval/print script is supplied prior to this, then the next argument will be used as a script filename. - -.SH ENVIRONMENT VARIABLES - -.TP -.BR NODE_DEBUG =\fImodule\fR[,\fI...\fR] -\',\'\-separated list of core modules that should print debug information. - -.TP -.BR NODE_DISABLE_COLORS =\fI1\fR -When set to \fI1\fR, colors will not be used in the REPL. - -.TP -.BR NODE_EXTRA_CA_CERTS =\fIfile\fR -When set, the well known "root" CAs (like VeriSign) will be extended with the -extra certificates in \fIfile\fR. The file should consist of one or more -trusted certificates in PEM format. A message will be emitted (once) with -\fBprocess.emitWarning()\fR if the file is missing or misformatted, but any -errors are otherwise ignored. - -.TP -.BR NODE_ICU_DATA =\fIfile\fR -Data path for ICU (Intl object) data. Will extend linked-in data when compiled -with small\-icu support. - -.TP -.BR NODE_NO_WARNINGS =\fI1\fR -When set to \fI1\fR, process warnings are silenced. - -.TP -.BR NODE_OPTIONS =\fIoptions...\fR -A space-separated list of command line options. \fBoptions...\fR are interpreted -as if they had been specified on the command line before the actual command line -(so they can be overridden). Node will exit with an error if an option that is -not allowed in the environment is used, such as \fB-p\fR or a script file. - -.TP -.BR NODE_PATH =\fIpath\fR[:\fI...\fR] -\':\'\-separated list of directories prefixed to the module search path. - -.TP -.BR NODE_PENDING_DEPRECATION = \fI1\fR -When set to \fI1\fR, emit pending deprecation warnings. - -.TP -.BR NODE_REPL_HISTORY =\fIfile\fR -Path to the file used to store the persistent REPL history. The default path -is \fB~/.node_repl_history\fR, which is overridden by this variable. Setting the -value to an empty string ("" or " ") disables persistent REPL history. - -.TP -.BR OPENSSL_CONF = \fIfile\fR -Load an OpenSSL configuration file on startup. Among other uses, this can be -used to enable FIPS-compliant crypto if Node.js is built with -\fB./configure \-\-openssl\-fips\fR. - +.El +. +.\" ===================================================================== +.Sh ENVIRONMENT +.Bl -tag -width 6n +.It Ev NODE_DEBUG Ar modules... +Comma-separated list of core modules that should print debug information. +. +.It Ev NODE_DISABLE_COLORS +When set to +.Ar 1 , +colors will not be used in the REPL. +. +.It Ev NODE_EXTRA_CA_CERTS Ar file +When set, the well-known +.Dq root +CAs (like VeriSign) will be extended with the extra certificates in +.Ar file . +The file should consist of one or more trusted certificates in PEM format. +.Pp +If +.Ar file +is missing or misformatted, a message will be emitted once using +.Sy process.emitWarning() , +but any errors are otherwise ignored. +. +.It Ev NODE_ICU_DATA Ar file +Data path for ICU (Intl object) data. +Will extend linked-in data when compiled with small-icu support. +. +.It Ev NODE_NO_WARNINGS +When set to +.Ar 1 , +process warnings are silenced. +. +.It Ev NODE_OPTIONS Ar options... +A space-separated list of command-line +.Ar options , +which are interpreted as if they had been specified on the command-line before the actual command (so they can be overridden). +Node will exit with an error if an option that is not allowed in the environment is used, such as +.Fl -print +or a script file. +. +.It Ev NODE_PATH Ar directories... +A colon-separated list of +.Ar directories +prefixed to the module search path. +. +.It Ev NODE_PENDING_DEPRECATION +When set to +.Ar 1 , +emit pending deprecation warnings. +. +.It Ev NODE_REPL_HISTORY Ar file +Path to the +.Ar file +used to store persistent REPL history. +The default path is +.Sy ~/.node_repl_history , +which is overridden by this variable. +Setting the value to an empty string ("" or " ") will disable persistent REPL history. +. +.It Ev OPENSSL_CONF Ar file +Load an OpenSSL configuration file on startup. +Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with +.Sy ./configure --openssl-fips . +.Pp If the -\fB\-\-openssl\-config\fR -command line option is used, the environment variable is ignored. - -.TP -.BR SSL_CERT_DIR = \fIdir\fR -If \fB\-\-use\-openssl\-ca\fR is enabled, this overrides and sets OpenSSL's directory -containing trusted certificates. - -.TP -.BR SSL_CERT_FILE = \fIfile\fR -If \fB\-\-use\-openssl\-ca\fR is enabled, this overrides and sets OpenSSL's -file containing trusted certificates. - -.TP -.BR NODE_REDIRECT_WARNINGS=\fIfile\fR -Write process warnings to the given file instead of printing to stderr. -(equivalent to using the \-\-redirect\-warnings=\fIfile\fR command-line -argument). - -.SH BUGS +.Fl -openssl-config +command-line option is used, this environment variable is ignored. +. +.It Ev SSL_CERT_DIR Ar dir +If +.Fl -use-openssl-ca +is enabled, this overrides and sets OpenSSL's directory containing trusted certificates. +. +.It Ev SSL_CERT_FILE Ar file +If +.Fl -use-openssl-ca +is enabled, this overrides and sets OpenSSL's file containing trusted certificates. +. +.It Ev NODE_REDIRECT_WARNINGS Ar file +Write process warnings to the given +.Ar file +instead of printing to stderr. +Equivalent to passing +.Fl -redirect-warnings Ar file +on command-line. +.El +. +.\"===================================================================== +.Sh BUGS Bugs are tracked in GitHub Issues: -.ur https://github.com/nodejs/node/issues - - -.SH AUTHORS -Written and maintained by 1000+ contributors: -.ur https://github.com/nodejs/node/blob/master/AUTHORS - - -.SH COPYRIGHT -Copyright Node.js contributors. Node.js is available under the MIT license. - -Node.js also includes external libraries that are available under a variety -of licenses. See -.ur https://github.com/nodejs/node/blob/master/LICENSE +.Sy https://github.com/nodejs/node/issues +. +.\"====================================================================== +.Sh COPYRIGHT +Copyright Node.js contributors. +Node.js is available under the MIT license. +. +.Pp +Node.js also includes external libraries that are available under a variety of licenses. +See +.Sy https://github.com/nodejs/node/blob/master/LICENSE for the full license text. - - -.SH RESOURCES AND DOCUMENTATION +. +.\"====================================================================== +.Sh SEE ALSO Website: -.ur https://nodejs.org/ - +.Sy https://nodejs.org/ +. +.Pp Documentation: -.ur https://nodejs.org/api/ - +.Sy https://nodejs.org/api/ +. +.Pp GitHub repository & Issue Tracker: -.ur https://github.com/nodejs/node - +.Sy https://github.com/nodejs/node +. +.Pp Mailing list: -.ur http://groups.google.com/group/nodejs - +.Sy http://groups.google.com/group/nodejs +. +.Pp IRC (general questions): -.ur "chat.freenode.net #node.js" +.Sy "chat.freenode.net #node.js" (unofficial) - +. +.Pp IRC (Node.js core development): -.ur "chat.freenode.net #node-dev" +.Sy "chat.freenode.net #node-dev" +. +.\"====================================================================== +.Sh AUTHORS +Written and maintained by 1000+ contributors: +.Sy https://github.com/nodejs/node/blob/master/AUTHORS +. -- cgit v1.2.3