[issue6953] readline documenation needs work

[Martin Panter]

Martin Panter added the comment:

This patch addresses the following points:

1: Moved add_history() into new “History file” section with related functions.

2: Documented that remove_ and replace_history_item() are zero-based.

3: Documented that get_history_item() is one-based.

4: Listed the main underlying Readline function or variable that each Python function accesses. In many cases it should be fairly obvious because the name is essentially the same, but not always. I added them all for consistency.

5: Added six new sections to group functions: Init file, Line buffer, History file, History list, Startup hooks, and Completer.

7: Clarify that the parse_and_bind() line comes directly from the string argument, not a file.

8: Changed “command line” to “line buffer”.

9: read_init_file() also executes the bindings it reads; it does not return anything.

10: read_history_file() appends to the history list, contrary to what Andy suggested.

11: write_history_file() overwrites any existing file, and writes the history list

12: clear_history() is conditionally compiled in

13: Combined get_ and set_history_length() entries

14: Differentiated lines in the history file from history list items, which can be multi-line if an item includes a line break.

15: Added brief description of word completion in the new section. Entry get_completion_type() refers to the rl_completion_type variable, so it should be refer back to the Gnu documentation. Referred beginning and ending indexes to the corresponding callback arguments (these are affected by Issue 16182). Suggested that the word delimiters determine the word completion scope.

16: Whether libedit (Editline) is used or not really only depends on the -lreadline library at run time (out of Python’s hands). I clarified that its detection is what is implemented on OS X. See also Issue 13501 for expanding this support.

Another change:

17: Expanded information on setting up the completion word delimiters for a custom completer, to address Issue 10796.

Not addressed in my patch:

6: Init file information. May be better to just refer to the Gnu documentation <https://cnswww.cns.cwru.edu/php/chet/readline/readline.html#SEC1> and Editline documentation (does this exist?).

8: I do not know what “the last filename used” means for read_init_file(). It passes a null pointer as the filename in this case. I suspect the answer may actually be it uses the INPUTRC config file instead.

12: I do not know what Readline version clear_history() is available in. Anyway, this might vary between Gnu and Editline implementations.

----------
keywords: +patch
nosy: +martin.panter
Added file: http://bugs.python.org/file41157/readline-doc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue6953>
_______________________________________