doc: document readline keybindings #20825

shobhitchittora · 2018-05-18T18:25:52Z

Closes: #20814

make -j4 test (UNIX), or vcbuild test (Windows) passes
~~tests and/or benchmarks are included~~
documentation is changed or added
commit message follows commit guidelines

Affected subsystem(s)

doc

Closes: nodejs#20814

addaleax · 2018-05-19T00:51:04Z

doc/api/tty.md

@@ -158,7 +158,109 @@ The `tty.isatty()` method returns `true` if the given `fd` is associated with
 a TTY and `false` if it is not, including whenever `fd` is not a non-negative
 integer.

+## TTY keybindings


Can we document these in the readline doc? While a TTY is required for most of these, they shouldonly affect readline behaviour

I guess it would be fine to add a reference to those in the repl ~~and in here~~.

@addaleax @BridgeAR just to be clear, I'll add the table of keybindings in the readline doc and ref the table in REPL and TTY doc.

@shobhitchittora Yes, that’s the idea (although I don’t really understand why this would be added to the TTY doc)

@addaleax I saw this code in readline -

Interface.prototype.write = function(d, key) { if (this.paused) this.resume(); this.terminal ? this._ttyWrite(d, key) : this._normalWrite(d); };

and thought that TTY case need a doc. But yeah we can have the table in readline doc and ref it in REPL and / or TTY.

Need you opinion on this.

Yeah, exactly – it’s code in readline. :) We should point out that these codes apply only for TTYs, but it’s not something that’s interesting for code that uses TTYs in general.

@addaleax you are right, the TTY docs are actually the wrong place for this. The repl should have a reference however.

richardlau · 2018-05-19T12:33:03Z

Nit: handled is misspelled in the commit message. Alternatively maybe use the shorter doc: document readline keybindings.

Trott · 2018-05-21T01:48:13Z

doc/api/readline.md

@@ -287,7 +287,8 @@ added: v0.1.98

 The `rl.write()` method will write either `data` or a key sequence identified
 by `key` to the `output`. The `key` argument is supported only if `output` is
-a [TTY][] text terminal.
+a [TTY][] text terminal. See [`TTY keybindings`][] for a list of covered key 


Nit: remove "covered"?

1. Adds ref in repl doc 2. Removes ref from tty doc Closes: nodejs#20814

shobhitchittora · 2018-05-21T07:43:53Z

@addaleax @Trott is TTY keybindings fine or the bindings should be named Special keys?

vsemozhetbyt · 2018-05-22T18:27:39Z

doc/api/repl.md

@@ -634,3 +636,4 @@ For an example of running a REPL instance over [curl(1)][], see:
 [`util.inspect()`]: util.html#util_util_inspect_object_options
 [curl(1)]: https://curl.haxx.se/docs/manpage.html
 [stream]: stream.html
+[`TTY keybindings`]: readline.html#readline_tty_keybindings 


It seems we do not need backticks in this case (this is not a code fragment). So this should be [TTY keybindings] and go before the [curl(1)]: (as per ASCII sorting we use in reference lists).

vsemozhetbyt · 2018-05-22T18:29:56Z

doc/api/tty.md

@@ -161,4 +161,4 @@ integer.
 [`net.Socket`]: net.html#net_class_net_socket
 [`process.stdin`]: process.html#process_process_stdin
 [`process.stdout`]: process.html#process_process_stdout
-[`process.stderr`]: process.html#process_process_stderr
+[`process.stderr`]: process.html#process_process_stderr


Missing line break at the end of the file?

vsemozhetbyt · 2018-05-22T18:31:52Z

doc/api/repl.md

@@ -67,6 +67,8 @@ The following key combinations in the REPL have these special effects:
  variables. When pressed while entering other input, displays relevant
  autocompletion options.

+For a full list of special keys, refer [`TTY keybindings`][].


refer -> refer to?

vsemozhetbyt · 2018-05-22T18:33:11Z

doc/api/readline.md

@@ -535,3 +637,4 @@ rl.on('line', (line) => {
 [TTY]: tty.html
 [Writable]: stream.html#stream_writable_streams
 [reading files]: #readline_example_read_file_stream_line_by_line
+[`TTY keybindings`]: #readline_tty_keybindings


It seems we do not need backticks in this case (this is not a code fragment). So this should be [TTY keybindings] and go after the [TTY]: (as per ASCII sorting we use in reference lists).

We need the same fix in the text)

vsemozhetbyt · 2018-05-22T19:03:07Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl+c</code></td>
+    <td>emits SIGINT</td>


emits -> emit for consistency with other cells?

vsemozhetbyt · 2018-05-22T19:04:07Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl+a</code></td>
+    <td>goto start of line</td>


goto -> go to?

vsemozhetbyt · 2018-05-22T19:04:23Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl+e</code></td>
+    <td>goto to end of line</td>


goto to -> go to?

vsemozhetbyt · 2018-05-22T19:05:28Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl+p</code></td>
+    <td>prev history item </td>


prev -> previous for more formal style?

vsemozhetbyt · 2018-05-22T19:13:55Z

Should we note that some bindings are OS-dependent? For example, these seem to not work for me on Windows as documented (tested in REPL): ctrl+shift+backspace, ctrl+u, ctrl+backspace, meta+delete (i.e. win+delete).

1. typo fix 2. adding new lines Closes: nodejs#20814

shobhitchittora · 2018-05-24T12:42:22Z

@vsemozhetbyt I think it'd be great if we can do that. Unfortunately I don't have a windows system and cannot verify bindings for the same. All help is appreciated. 😇

vsemozhetbyt · 2018-05-24T15:08:33Z

doc/api/repl.md

 [curl(1)]: https://curl.haxx.se/docs/manpage.html
 [stream]: stream.html
+


This empty line seems unneeded)

vsemozhetbyt · 2018-05-24T15:14:23Z

cc @nodejs/platform-windows: can we have some more verification of keybindings and suggestions how to better document possible differences (if we should)?

bzoz · 2018-05-24T15:27:57Z

Meta is the Alt key (maybe we should add that to the docs?), bindings with those work.

The ctrl+shift+... don't work on Windows and also do not work on WSL.

vsemozhetbyt · 2018-05-24T15:34:22Z

@bzoz Sorry, was confused by the MDN page.

But alt+delete still does not work for me (alt+d works).

BridgeAR

LGTM with the whitespace removed. My two comments would also be nice but I think that could also be done later on (even though I would prefer to have it that way right away).

BridgeAR · 2018-05-24T16:21:39Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl+shift+backspace</code></td>
+    <td>delete line left</td>


Not a must but I personally would prefer the descriptions all to start with a upper case character.

BridgeAR · 2018-05-24T16:25:43Z

doc/api/readline.md

+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>ctrl+shift+backspace</code></td>


Suggestion: add whitespace between the individual commands and maybe also only highlight the keys, not the plus. As in: <code>ctrl</code> + <code>shift</code> + <code>backspace</code>

Any reason these are wrapped in <code> and not <kbd>?

bzoz · 2018-05-24T16:46:05Z

Hm.. Alt+Del does not work on Windows and WSL, but works on Linux. Libuv reports it as ^^[3~ on Windows.

Ctrl + Shift + Backspace does not work neither on Windows nor on Linux. On Windows libuv does not report any sequence at all.

Ctrl + Shift + Del works on both Windows and Linux.

refs: nodejs#20814

shobhitchittora · 2018-05-24T17:54:20Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl</code> + <code>z</code></td>
+    <td>(need clarification)</td>


Hey team.
Need clarification on this keybinding. I cannot think of a description for this. Can someone help with this?

cc @BridgeAR @vsemozhetbyt

I do not know, sorry(

@BridgeAR I found this for ctrl + z -
https://nodejs.org/api/readline.html#readline_event_sigtstp

If it's fine we can either ref to this or take the first paragraph and add here.

Please document it as e.g.: Moves running process into background. Type 'fg' and press 'enter' to return..

refs: nodejs#20814

vsemozhetbyt · 2018-05-26T09:56:08Z

CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite/754/

vsemozhetbyt · 2018-05-26T10:07:27Z

We have a linter issue:

06:00:06 Running Markdown linter on docs...
06:00:51 doc/api/readline.md
06:00:51   596:113  warning  Line must be at most 80 characters  maximum-line-length  remark-lint
06:00:51   599:108  warning  Line must be at most 80 characters  maximum-line-length  remark-lint
06:00:51   623:105  warning  Line must be at most 80 characters  maximum-line-length  remark-lint

vsemozhetbyt · 2018-05-26T10:09:35Z

doc/api/readline.md

+    <td>Moves running process into background. Type <code>fg</code> and press <code>enter</code> to return.</td>
+  </tr>
+  <tr>
+    <td><code>ctrl</code> + <code>w</code> &nbsp; or &nbsp; <code>ctrl</code> + <code>backspace</code></td>


Are these   intended here and below?

Yeah! added them for more spacing, but removing for now.

refs: nodejs#20814

vsemozhetbyt · 2018-05-27T16:08:10Z

CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite/757/

vsemozhetbyt · 2018-05-27T16:31:01Z

Should we land as is or need we elaborate some note about OS-dependent differences?

bzoz · 2018-05-27T21:51:18Z

I think we should document differences. And double check, since it looks like Ctrl + Shift + Backspace does not work on any platform.

vsemozhetbyt · 2018-06-17T08:23:48Z

Let's do not stall this PR.

shobhitchittora · 2018-06-17T08:29:43Z

@vsemozhetbyt please do let know if anything update / commit is required from my side.

vsemozhetbyt · 2018-06-21T15:28:47Z

@nodejs/platform-macos Are there any additions from your team?

vsemozhetbyt · 2018-06-28T18:26:00Z

ping @nodejs/documentation

shobhitchittora · 2018-08-24T10:16:21Z

@vsemozhetbyt any updates on this?

vsemozhetbyt · 2018-08-24T10:46:49Z

Sorry, it seems I've exhausted all the ways I could help(

Trott · 2018-11-20T03:27:48Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl</code> + <code>left</code></td>
+    <td>Word left </td>


On macOS, it's command+option+left. ctrl+left does not work.

Trott · 2018-11-20T03:28:07Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>ctrl</code> + <code>right</code></td>
+    <td>Word right</td>


On macOS, it's command+option+right. ctrl+right does not work.

Trott · 2018-11-20T03:29:29Z

doc/api/readline.md

+  </tr>
+  <tr>
+    <td><code>meta</code> + <code>backspace</code></td>
+    <td>Delete word left </td>


Does not work on macOS.

Trott · 2018-11-20T03:43:08Z

@shobhitchittora @vsemozhetbyt I've tested on my macOS laptop and have put the result in above as best I can. ("Meta" on macOS is "hold down the ESC key" and "backspace" is "fn + delete", in case that's relevant.)

Can that information be incorporated and this unstalled? Does anything else need to happen to unstall this?

Trott · 2018-11-20T03:43:41Z

Optimistically removing the stalled label...

Trott · 2018-11-30T06:00:27Z

@shobhitchittora Are you planning to finish this one? Or would it make sense to put a help wanted label on it or something like that?

fhinkel · 2019-10-26T23:20:00Z

Closing this due to inactivity. Please reopen if needed.

This is a rework of closed pr nodejs#20825 fixes: nodejs#20814

This documents all readline key bindings. It is a rework of #20825 PR-URL: #31256 Fixes: #20814 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

This documents all readline key bindings. It is a rework of nodejs#20825 PR-URL: nodejs#31256 Fixes: nodejs#20814 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

This documents all readline key bindings. It is a rework of #20825 PR-URL: #31256 Fixes: #20814 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

doc: adds handeled tty write keybindings

13ecfa3

Closes: nodejs#20814

nodejs-github-bot added the doc Issues and PRs related to the documentations. label May 18, 2018

addaleax reviewed May 19, 2018

View reviewed changes

vsemozhetbyt added the readline Issues and PRs related to the built-in readline module. label May 19, 2018

shobhitchittora changed the title ~~doc: adds handeled tty write keybindings~~ doc: document readline keybindings May 20, 2018

Trott reviewed May 21, 2018

View reviewed changes

doc: add the keybindings to readline doc. Also -

60165b7

1. Adds ref in repl doc 2. Removes ref from tty doc Closes: nodejs#20814

vsemozhetbyt reviewed May 22, 2018

View reviewed changes

doc: fixes as per review comments

c39f8b6

1. typo fix 2. adding new lines Closes: nodejs#20814

vsemozhetbyt reviewed May 24, 2018

View reviewed changes

BridgeAR approved these changes May 24, 2018

View reviewed changes

shobhitchittora added 2 commits May 24, 2018 23:21

doc: highlighting code + capital case description

2faec19

refs: nodejs#20814

doc: fixes typo

e3d38dd

refs: nodejs#20814

shobhitchittora commented May 24, 2018

View reviewed changes

doc: adds description for ctrl+z

76d462c

refs: nodejs#20814

vsemozhetbyt reviewed May 26, 2018

View reviewed changes

doc: fixes line warnings + removes nbsp;

67e3d92

refs: nodejs#20814

jasnell added the stalled Issues and PRs that are stalled. label Sep 10, 2018

Trott reviewed Nov 20, 2018

View reviewed changes

Trott removed the stalled Issues and PRs that are stalled. label Nov 20, 2018

Trott added the help wanted Issues that need assistance from volunteers or PRs that need help to proceed. label Dec 4, 2018

Trott force-pushed the master branch from 1ecc406 to 49cf67e Compare September 17, 2019 16:52

fhinkel closed this Oct 26, 2019

BridgeAR mentioned this pull request Dec 21, 2019

repl: add reverse search #31006

Closed

4 tasks

HarshithaKP added a commit to HarshithaKP/node that referenced this pull request Jan 8, 2020

doc: document readline keybindings

0de07fc

This is a rework of closed pr nodejs#20825 fixes: nodejs#20814

HarshithaKP mentioned this pull request Jan 8, 2020

Document readline keybindings #31256

Closed

4 tasks

		[curl(1)]: https://curl.haxx.se/docs/manpage.html
		[stream]: stream.html

doc: document readline keybindings #20825

doc: document readline keybindings #20825

Conversation

shobhitchittora commented May 18, 2018

doc

Choose a reason for hiding this comment

BridgeAR May 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardlau commented May 19, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shobhitchittora commented May 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented May 22, 2018

shobhitchittora commented May 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented May 24, 2018

bzoz commented May 24, 2018

vsemozhetbyt commented May 24, 2018

BridgeAR left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bzoz commented May 24, 2018

shobhitchittora May 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented May 26, 2018

vsemozhetbyt commented May 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented May 27, 2018

vsemozhetbyt commented May 27, 2018

bzoz commented May 27, 2018

vsemozhetbyt commented Jun 17, 2018

shobhitchittora commented Jun 17, 2018

vsemozhetbyt commented Jun 21, 2018

vsemozhetbyt commented Jun 28, 2018

shobhitchittora commented Aug 24, 2018

vsemozhetbyt commented Aug 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott commented Nov 20, 2018

Trott commented Nov 20, 2018

Trott commented Nov 30, 2018

fhinkel commented Oct 26, 2019

BridgeAR May 19, 2018 •

edited

Loading

shobhitchittora May 24, 2018 •

edited

Loading