Add first draft.

Author: aadcg

source/manual-prompt-buffer.org

@@ -0,0 +1,103 @@
+* Prompt buffer
+
+# We must all refer to prompt buffer as is, not as prompt-buffer.
+
+The prompt buffer is special buffer where Nyxt commands read arguments, such as
+URLs, file names or Common Lisp expressions.  We call it prompt buffer because
+it requests textual input from the user.
+
+Refer to nyxt/prompt-buffer-mode:prompt-buffer-mode for an overview.
+
+# move somewhere else!
+
+It provides contextual suggestions that are narrowed down to those matching what
+you type in the input area.  At any given moment, there is a special suggestion
+that has the focus - the current suggestion.
+
+A selection is a collection of suggestions, and these are allowed when the
+multi-selection-p slot is non-nil.  For instance, the delete-buffer command
+deletes all selected buffers at once.
+
+Every collection of suggestions belongs to a source.  Sources define consistent
+umbrellas for specific collections of suggestions.  For instance, the command
+describe-any features separate sources for variables, functions and classes.
+# and other things I want to omit.
+
+# I just realized how hard it is to describe how users can understand which
+# source is the current one.  Shouldn't this UI be re-thought?  Thomas?
+
+** Basic Usage
+When the prompt buffer is invoked it occupies the lower region of the screen,
+and the cursor is set at the top bar.  It features the input area at the center,
+the active modes on the right and the prompter message on the left.  The
+suggestions are listed vertically below the top bar and are immediately shown
+before you start typing.
+
+# Can the user define its own completion algorithm?  Yes, by setting
+# prompter:filter in each prompt buffer source
+
+As you type or delete each character, the list of suggestions is updated.  The
+commands defined by input-edit-mode apply to the input area.
+
+Parallel to that, you can set the current suggestion by using these navigation
+commands:
+
+select-previous
+select-next
+select-first
+select-last
+select-previous-page
+select-next-page
+select-previous-source
+select-next-source
+
+Once you have set the desired current suggestion, you can run the command
+return-selection, bound to RET by default, to submit the argument exit the
+prompt buffer.
+
+In some cases, the argument you will submit is a list of suggestions, which we
+call selection.  The following command add suggestions to the selection:
+
+# rename all of these commands since mark is a defunct concept.
+mark-all
+unmark-all
+toggle-mark
+toggle-mark-backwards
+toggle-mark-all
+
+You can exit the prompt buffer at any given moment with command cancel-input.
+
+** Notable sources
+Should we refer to some of them?
+
+buffer-source
+new-url-or-search-source
+
+hint-source
+file-source
+
+** Attributes
+
+** Actions
+
+** Passwords
+Sometimes, you may need to enter a password or other sensitive information in
+Nyxt.
+
+# Do we handle this??
+
+** History
+
+** Completion
+
+** Keybindings
+
+** Multi tasking
+# missing feature
+You can't focus the former buffer without exiting the prompt while it is up.
+However, it is still possible to scroll the other buffer with these commands.
+
+scroll-other-buffer-down
+scroll-other-buffer-up
+scroll-page-down-other-buffer
+scroll-page-up-other-buffer