Top level keybindings documentation

[constraintAutomaton]

In this PR, we introduce keybindings documentation in the usage description.

I decided to include the full keybinding documentation in the -h command because to see the keybindings in the top level, you need to be inside a query that produces multiple results, which I think is not very convenient.

Closes #3154

[UWN]

Neither SICStus nor SWI does this. Just keep -h confined to the options that are of relevance at the point in time of starting up a system. What else should go into -h for the sake of a specific convenience? Maybe the entire manual?

[constraintAutomaton]

Neither SICStus nor SWI does this. Just keep -h confined to the options that are of relevance at the point in time of starting up a system. What else should go into -h for the sake of a specific convenience? Maybe the entire manual?

I think REPL interaction commands are immediately relevant upon startup since users enter the REPL directly. Currently, discovering these keybindings is not straightforward, you need to execute a multi-result query and press h to see them. The only other documentation is in the tutorial section of the README.

Unlike manual information that covers broader usage, these keybindings are essential for basic interaction with the system right after launch. I see them as similar to command-line flags. I also don't think this makes the help command too verbose, and multiple users might benefit from easier access to these commands that they might not suspect exist.

Usage: scryer-prolog [OPTIONS] [FILES] [-- ARGUMENTS]

Options:
   -h, --help             Display this message
   -v, --version          Print version information and exit
   -g, --goal GOAL        Run the query GOAL
   -f                     Fast startup. Do not load initialization file (~/.scryerrc)
   --no-add-history       Prevent adding input to history file (~/.scryer_history)

Top Level Keybindings:
   SPACE, "n" or ";": next solution, if any
   RETURN or ".": stop enumeration
   "a": enumerate all solutions
   "f": enumerate the next 5 solutions
   "h": display this help message
   "w": write terms without depth limit
   "p": print terms with depth limit
   
​```

[bakaq]

This should definitely be more discoverable in some way. I think stuff like this usually goes into a man page, but we don't have that yet. I feel like it's fine to put it into -h though. This is important, and I've seen stuff that is much less relevant being put there.

Maybe the entire manual?

Jujutsu does that, and it's pretty convenient in practice, though it's a completely different program.

[constraintAutomaton]

I was thinking that maybe we could have predicates to set

"w": write terms without depth limit
"p": print terms with depth limit

and a predicate to display the help?

[triska]

@constraintAutomaton, @bakaq: What do you think about adding a more comprehensive info manual for Scryer, and mentioning that in the -h output?

I think you @jjtolton at one point already mentioned an info manual for Scryer, based on the existing documentation?

[constraintAutomaton]

@constraintAutomaton, @bakaq: What do you think about adding a more comprehensive info manual for Scryer, and mentioning that in the -h output?

I think you @jjtolton at one point already mentioned an info manual for Scryer, based on the existing documentation?

I think it is a good idea! Do you have an example of how it would look? Like another software that does it the way you think it should be made? I can change this PR for doing that.

[jjtolton]

Yes I have a handmade one. It was the "Scrib Notes" I mentioned briefly in my talk. We could probably make something automated.

[bakaq]

I generally prefer man to info, but that's probably because I don't use Emacs, which seems to have really good support for navigating info docs from what I'm hearing. Both are equally janky to use with the default CLI interface.

There's probably software that can compile something like markdown into both man and info, so maybe we could even have both pretty easily? Though if we are going to do only one of them, then we should probably go with info because that's what the community seems more interested in. I never had to solve this problem before, so I'm note really aware of the available tools here, or the consequences for release and distribution.

[bakaq]

Oh, something that would be nice if we end up doing a "compile markdown to other formats" type of solution would be to also compile it for appearing in the https://scryer.pl site. I don't think it would be that difficult, but probably shouldn't be the first step.

[jjtolton]

Sounds like a good usecase for DCGs 🥳

But I think first we should decide on the content?

I am sorry @constraintAutomaton I feel like a TON of scope just got added to this story

[jjtolton]

We could probably take some inspiration from sicstus: https://sicstus.sics.se/sicstus/docs/latest4/html/sicstus.html/

[constraintAutomaton]

We could probably take some inspiration from sicstus: https://sicstus.sics.se/sicstus/docs/latest4/html/sicstus.html/

I think there's a question of scope that needs to be decided here. My initial intention was to provide convenient top-level key bindings. If we take inspiration from Siscus, we could start by emulating sections introduction through 3.0, at least for this PR.

Also what is stopping us from providing a man? Could we unified what would be in this info sub command to man.

[triska]

Do you have an example of how it would look?

Yes indeed, the SICStus info pages are a good example, and also the Emacs and Elisp info pages.

For instance, in Emacs, try: C-h R emacs RET

[jjtolton]

Personally @constraintAutomaton I would just stick to the keybindings and we can open another issue for the info. I think you did not sign up for all that scope.

Also it would be quite easy to simply procedurally generate the documentation, so it doesn't make much sense for you to spend a long time doing it by hand.

[constraintAutomaton]

Personally @constraintAutomaton I would just stick to the keybindings and we can open another issue for the info. I think you did not sign up for all that scope.

Also it would be quite easy to simply procedurally generate the documentation, so it doesn't make much sense for you to spend a long time doing it by hand.

Make sense, so than I am unsure then about what to do with this PR. Because I do still believe it is interesting to have this info ready at hand.