Manual section on prompt buffer. #2772
Conversation
aadcg
changed the title
aadcg
force-pushed
the
prompt-buffer-manual
branch
2 times, most recently
from
7975faf
to
c98cd66
Compare
|
I will be backporting an article written by @Ambrevar which serves as the base to a section called "Programming Interface". |
To be converted in the final manual format at the last moment.
aadcg
force-pushed
the
prompt-buffer-manual
branch
from
c98cd66
to
17c80c4
Compare
|
The first draft of the prompt buffer manual section is ready (still in At this point we should validate the following:
Broadly speaking, there are two distinct sections in the document. In the first part, the target is the user. In the second, (introduced by "Programming Interface") the target is the developer. Ideally, everyone should read and review it. CC @aartaka @Ambrevar @jmercouris. |
|
To clarify, do you want a review now or when you will be done with the draft? |
|
@Ambrevar now, the draft is ready to review. |
| toggle-mark-backwards | ||
| toggle-mark-all | ||
|
|
||
| Once the current suggestion (or the marks) is set, hitting the Return key to |
| next-source | ||
| previous-source | ||
|
|
||
| Oftentimes, you will interact with a collection of suggestions, which we call |
There was a problem hiding this comment.
Maybe mention why we use marks—to act on more than one suggestion at a time?
| Notice that the contents of the input bar is matched against all suggestion | ||
| attributes shown. | ||
|
|
||
| The syntax of regular expressions is not supported. |
|
|
||
| Within the :nyxt package, a set of primitives is defined on top of :prompter to | ||
| suit the browser's needs. Additionally, the package :nyxt/prompt-buffer-mode | ||
| defines the relevant mode. |
There was a problem hiding this comment.
What does mode do? It's worth mentioning that it hosts necessary commands and keybindings.
| define an example-source: | ||
|
|
||
| #+begin_src lisp | ||
| (defun set-suggestions (n) |
There was a problem hiding this comment.
This additional function may be quite confusing. I'd rather use something simpler (inline constructor?), at least for the first appearance of sources.
| :sources (make-instance 'example-source)) | ||
| #+end_src | ||
|
|
||
| Sources can be inspected with the describe-class command. Particularly |
There was a problem hiding this comment.
Dunno whether this describe-class reference belong here. But the source listing, augmented with :nxref links is a worthy thing.
| - =prompter:actions-on-marks= | ||
|
|
||
| An action is either a symbol or a command, that may be locally-defined by either | ||
| =lambda-mapped-command= or =lambda-command=. |
There was a problem hiding this comment.
lambda-unmapped-command is useful too.
|
|
||
| The =prompter:object-attributes= method serves precisely that purpose. It | ||
| enables displaying something more meaningful than the standard printed | ||
| representation of class instance =#<CLASS-NAME {ID}>=. |
There was a problem hiding this comment.
Note that this representation is not really standardized beyond the sharp-less-than syntax. SBCL, CCL, ECL, and other implementations have it slightly different.
SBCL:
#<FOO {100833DF63}>
CCL:
#<FOO #x302000F91BBD>
ECL:
#<a COMMON-LISP-USER::FOO 0x7fbe8c6e62c0>
| Finally, the =prompter:filter-postprocessor= is run of the result of the filter, | ||
| this time again over the entire list at once. | ||
|
|
||
| Once again, the source view is only updated when the postprocessor is done with |
There was a problem hiding this comment.
Mention that postprocessor is asynchronous, in contrast to preprocessor?
| The class is useful to store information through the processing pipeline | ||
| described in the previous section. For instance, the filter can calculate and | ||
| store the score of each suggestion, in the =score= slot, which in turn is | ||
| readily available to the =filter-postprocessor= for sorting. |
There was a problem hiding this comment.
Mention the prompter:suggestion-maker here and add an example code to redefine it?
| @@ -0,0 +1,283 @@ | |||
| * Prompt buffer | |||
| The prompt buffer is a special buffer where Nyxt commands read arguments, such | |||
| * Prompt buffer | ||
| The prompt buffer is a special buffer where Nyxt commands read arguments, such | ||
| as URLs, file names or Common Lisp expressions. We call it prompt buffer | ||
| because, as the name suggests, it prompts the user for textual input. |
There was a problem hiding this comment.
Last sentence is probably unnecessary.
|
|
||
| Each suggestion belongs to a source. Sources define consistent umbrellas for | ||
| specific use cases. For example, the command describe-any has sources for | ||
| variables, functions and classes. |
| When invoked, the prompt buffer occupies the lower region of the screen, and the | ||
| cursor is set at the top bar, featuring: the prompter message on the left, the | ||
| input area at the center and the active modes on the right. The suggestions are | ||
| listed vertically below the top bar, and are shown before you start typing. |
There was a problem hiding this comment.
Calling it the "top bar" may not be future-proof, e.g. if the prompt is displayed on top of the window.
Maybe "input area"?
| next-page | ||
| previous-page | ||
| next-source | ||
| previous-source |
| The system nyxt/prompter (containing the :prompter package) defines the | ||
| primitives that make prompt buffers possible in Nyxt. | ||
|
|
||
| Within the :nyxt package, a set of primitives is defined on top of :prompter to |
| # Link to slots. | ||
| # (:nxref :slot 'prompter:constructor :class-name 'prompter:source) | ||
|
|
||
| You can further study it by looking at prompter:source. |
There was a problem hiding this comment.
Inspect prompter:source for more details.
|
|
||
| #+begin_src lisp | ||
| (prompt :prompt "Prompter" | ||
| :sources (make-instance 'example-source)) |
There was a problem hiding this comment.
You can show the full form with :sources (list (make-instance ...)) and then show the shortcut with neither list nor make-instance.
| An action is either a symbol or a command, that may be locally-defined by either | ||
| =lambda-mapped-command= or =lambda-command=. | ||
|
|
||
| Regardless, actions are functions that takes a list as a sole argument - either |
|
|
||
| This filter function is particularly useful to score suggestions by relevance. | ||
|
|
||
| Finally, the =prompter:filter-postprocessor= is run of the result of the filter, |
|
@aadcg can I review and merge this? |
|
@jmercouris your review would be a waste of time. A lot has changed ever since with respect to the prompt buffer. Also, it's still an org file, since I don't think humans are meant to write documentation in spinneret. I don't like PR that are "marinating" but I'll do it by the next major release. |
|
If you would like to use org-mode, we would lose /a lot/ of the abilities we have right now. I think our documentation has become a lot more rich because of embedding it directly into the source code. The only thing I might suggest, that might make writing documentation easier would be an embeddable DSL. That is however a large project, and a discussion for a different time. |
|
@jmercouris, as I've mentioned above this PR is still a draft and the current state just helps to edit faster.
See #2674 |
|
@jmercouris given the above exchange, closing the PR comes as a surprise:
I'm OK with the decision, as I still have the changes saved in a local branch, but a warning or explanation wouldn't hurt! |
|
I'm sorry, it was again an accident, the stupid page froze on my machine and I don't even know what it clicked or didn't. I meant to only close the PR, not delete the branch! I just wanted to remove clutter and keep only the fresh active things in view. |
|
All clear, let's keep it as is regardless! |
A follow up of the manual section drafted in #2655.
Description
Work in progress. I'll let you know when to take a look @aartaka.
Checklist:
Everything in this checklist is required for each PR. Please do not approve a PR that does not have all of these items.
cd /path/to/nyxt/checkout git submodule add https://gitlab.common-lisp.net/nyxt/py-configparser _build/py-configparser:documentations written in the aforementioned style. (It's OK to skip the docstring for really trivial parts.)changelog.lispwith my changes if it's anything user-facing (new features, important bug fix, compatibility breakage).migration.lispentry for all compatibility-breaking changes.