Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

src/doc: improve man page and --help #10157

Closed
wants to merge 1 commit into from
Closed

src/doc: improve man page and --help #10157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 25 additions & 8 deletions doc/node.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,15 @@ Print stack traces for process warnings (including deprecations).
Print a stack trace whenever synchronous I/O is detected after the first turn
of the event loop.

.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
Automatically zero-fills all newly allocated Buffer and SlowBuffer instances.
Expand Down Expand Up @@ -182,28 +191,36 @@ Specify ICU data load path. (overrides \fBNODE_ICU_DATA\fR)
\',\'\-separated list of core modules that should print debug information.

.TP
.BR NODE_PATH =\fIpath\fR[:\fI...\fR]
\':\'\-separated list of directories prefixed to the module search path.
.BR NODE_DISABLE_COLORS =\fI1\fR
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's not really an authority on this but I think this isn't correct in the way we've been using it.

That is, we italicize what kind of thing we pass to it, not what it actually is. Since that is inconsistent with things that can take multiple values, I left it as just all bold since that is the only way it could ever work anyways.

Copy link
Contributor Author

@silverwind silverwind Dec 6, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you suggesting not highlighting the value at all? This is how the current release renders for me:

While it seems more common that man pages don't add arguments in the title, it doesn't seem wrong to me to have them highlighted like this:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess to me the difference is that for NODE_DISABLE_COLORS the "value" is what it actually must be, and for the others it describes what the value should be set to.

I'm not hugely against changing it, but I feel it is no less confusing, perhaps either way.

Copy link
Contributor Author

@silverwind silverwind Dec 16, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I see what you mean. I still think it'be more consistent to still highlight the 1, maybe in the description below as well.

When set to \fI1\fR, colors will not be used in the REPL.

.TP
.BR NODE_DISABLE_COLORS=1
When set to 1 colors will not be used in the REPL.
.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_PATH =\fIpath\fR[:\fI...\fR]
\':\'\-separated list of directories prefixed to the module search path.

.TP
.BR NODE_REPL_HISTORY =\fIfile\fR
Path to the file used to store the persistent REPL history. The default path
is ~/.node_repl_history, which is overridden by this variable. Setting the
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 NODE_TTY_UNSAFE_ASYNC=1
When set to 1, writes to stdout and stderr will be non-blocking and asynchronous
when outputting to a TTY on platforms which support async stdio.
.BR NODE_TTY_UNSAFE_ASYNC =\fI1\fR
When set to \fI1\fR, writes to stdout and stderr will be non-blocking and
asynchronous when outputting to a TTY on platforms which support async stdio.
Setting this will void any guarantee that stdio will not be interleaved or
dropped at program exit. \fBAvoid use.\fR

Expand Down
23 changes: 12 additions & 11 deletions src/node.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3482,8 +3482,7 @@ static void PrintHelp() {
"repeated)\n"
" --no-deprecation silence deprecation warnings\n"
" --trace-deprecation show stack traces on deprecations\n"
" --throw-deprecation throw an exception anytime a deprecated "
"function is used\n"
" --throw-deprecation throw an exception on deprecations\n"
" --no-warnings silence all process warnings\n"
" --trace-warnings show stack traces on process warnings\n"
" --trace-sync-io show stack trace when use of sync IO\n"
Expand Down Expand Up @@ -3514,27 +3513,29 @@ static void PrintHelp() {
" --icu-data-dir=dir set ICU data load path to dir\n"
" (overrides NODE_ICU_DATA)\n"
#if !defined(NODE_HAVE_SMALL_ICU)
" note: linked-in ICU data is\n"
" present.\n"
" note: linked-in ICU data is present\n"
#endif
" --preserve-symlinks preserve symbolic links when resolving\n"
" and caching modules.\n"
" and caching modules\n"
#endif
"\n"
"Environment variables:\n"
#ifdef _WIN32
"NODE_PATH ';'-separated list of directories\n"
#else
"NODE_PATH ':'-separated list of directories\n"
#endif
" prefixed to the module search path.\n"
"NODE_DEBUG ','-separated list of core modules that\n"
" should print debug information\n"
"NODE_DISABLE_COLORS set to 1 to disable colors in the REPL\n"
"NODE_EXTRA_CA_CERTS path to additional CA certificates file\n"
#if defined(NODE_HAVE_I18N_SUPPORT)
"NODE_ICU_DATA data path for ICU (Intl object) data\n"
#if !defined(NODE_HAVE_SMALL_ICU)
" (will extend linked-in data)\n"
#endif
#endif
#ifdef _WIN32
"NODE_PATH ';'-separated list of directories\n"
#else
"NODE_PATH ':'-separated list of directories\n"
#endif
" prefixed to the module search path\n"
"NODE_REPL_HISTORY path to the persistent REPL history file\n"
"\n"
"Documentation can be found at https://nodejs.org/\n");
Expand Down