[DOC] New document "For Users" #856
Conversation
There was a problem hiding this comment.
I think this should not be added?
There was a problem hiding this comment.
I think this should not be added?
You mean the example (echo)? Or the page?
There was a problem hiding this comment.
No action on this (yet).
doc/for_users.md
Outdated
| require 'open-uri' | ||
|
|
||
| # Get words for completion. | ||
| words_url = 'https://raw.githubusercontent.com/first20hours/google-10000-english/refs/heads/master/google-10000-english-usa-no-swears-long.txt' |
There was a problem hiding this comment.
I don't think our example should suggest a script pulling from an external source. If the content becomes malicious, and a user runs this script, they'd be affected.
There was a problem hiding this comment.
For now, let's drop the example and perhaps just use IRB for feature demonstration? That's probably where most users would interact with Reline anyway.
There was a problem hiding this comment.
Makes sense. I'll see to it.
Also, I never used the character I mentioned in "About the Examples," so I'll remove that section.
There was a problem hiding this comment.
I have drawn words from bin/example, and changed the text accordingly.
I'd like to keep echo.rb and its examples. This doc is about Reline itself, not one of the Ruby apps that use it.
|
|
||
| ### Moving the Cursor | ||
|
|
||
| - `C-f` or `→`: [Character forward] [character forward]. |
There was a problem hiding this comment.
Not sure what you mean. "Character forward" is a link.
There was a problem hiding this comment.
No change for this (yet).
doc/for_users.md
Outdated
| on the _current_ command line; | ||
| nothing is ever undone in an already-entered line. | ||
|
|
||
| Some commands can be undone; others cannot. |
There was a problem hiding this comment.
Description of undoable/not-undoable commands are correct, but the actual intention of the implementation/mental model is simply "undo previous edit operation".
All commands that edits/changes input is undoable, every other commands that doesn't change the input is not undoable.
It's also worth noting redo M-C-_
There was a problem hiding this comment.
Improved the intro to undo, and changed 'fall-through' to 'pass-through', which I think is a better characterization.
There was a problem hiding this comment.
Should have added: I could not make M-C-_ (redo) work. Is it in baseline Reline, or maybe added in one of the other apps?
There was a problem hiding this comment.
It's in baseline Reline: ruby -r reline -e "p Reline.readline('>')"
If it doesn't work depend on terminal emulator's keyboard configuration, Esc C-_ should work.
There was a problem hiding this comment.
Right. Works in bash, but not in cmd. Will see to it.
There was a problem hiding this comment.
Redo added; needed adjustments made.
|
|
||
| ### Exiting the Application | ||
|
|
||
| To exit the application, use command `C-d` on an empty command line. |
There was a problem hiding this comment.
C-d exits/terminates current input, not the application. Reline.readline returns nil.
Application may(it's not must) exit in this case, but it depends on how the application use Reline.
There was a problem hiding this comment.
In rdbg(with ENV RUBY_DEBUG_IRB_CONSOLE=1) and in IRB's debug mode, C-d will continue until next breakpoint.
% RUBY_DEBUG_IRB_CONSOLE=1 rdbg program.rb
irb:rdbg(main):002> break 2
#0 BP - Line program.rb:2 (line)
irb:rdbg(main):003> [CTRL-d]
Stop by #0 BP - Line program.rb:2 (line)
irb:rdbg(main):004>
There was a problem hiding this comment.
In 'naked' Reline (the subject of this page), C-d exits the application.
There was a problem hiding this comment.
If this naked Reline points to doc/echo.rb, it exits because that's how echo.rb implements the exit condition.
while line = Reline.readline # exits from while loop if nil
endThis exit condition is the most common implementation in many application, so I think it's ok to make the doc simple 👍
doc/for_users.md
Outdated
| - `Enter`: [Enter command] [enter command]. | ||
| - `C-p` or `↑`: [Previous command] [previous command]. | ||
| - `C-n` or `↓`: [Next command] [next command]. |
There was a problem hiding this comment.
In IRB, input to is a command to be evaluated as Ruby, but in general, it's not always a command. (Example: Reline.readline "input your name>")
How about calling it just an input, input text or something similar?
Then the ambiguity of command(as input text) and command(as key associated operation, C-a, M-d, etc) will reduced in this document.
There was a problem hiding this comment.
If we change "command" → "input", how about changing "Enter command" → "Submit input" (Analogy with a browser input form submit by enter key)
There was a problem hiding this comment.
In general, I've tried to use terms as they're used in Gnu readline, which speaks of the input as a command. Also, both readline and Reline have the goal of supporting command-line interfaces, so I think "command" is the needed term here.
|
@tompng, one more thought: though the page title is "For Users," this is also the place where a developer planning to use Reline may learn exactly what its default behaviors are -- before any additions or overridings. |
3 participants
Other pages planned: