Documentation not current?

jacg commented 4 years ago

[Aside: as a fan of Common Lisp for over 20 years (even if I haven't had the time or opportunity to use it in the last 10) and a user of Conkeror for over a decade, I really want Next browser to succeed: this is my second attempt at getting started (last time (about a year ago) it just hanged almost immediately, this time it's a little more usable) and I'm finding the experince veeeeeery frustrating. I don't want to pollute the issue tracker with what could be my local problems, but I have not found any other place where to discuss or get help: is there such a place?. What follows looks like a genuine global problem, rather than a local one.]

I am running Next 1.4.0, installed with nix (on NixOS).

The manual section on keybindings states that "Keys are defined with the define-key command." and shows the following code:

(defvar *my-keymap* (make-keymap "my-map")
  "My keymap.")

(define-key *my-keymap*
  "C-x o" #'example
  "space" #'scroll-page-down)

The problems with this are many:

make-keymap, define-key etc. are in the next package. I cannot find any mention of this on the help page, nor the advice to use (in-package :next) or to qualify the names with next:. If I were not previously familiar with CL, I don't see how I could have got around this problem.
The example calls make-keymap with one argument ((make-keymap "my-map")), while inspecting the symbol in SLIME reveals that its lambda list is (). Removing "my-map" allows me to proceed ...
define-key crashes complaining about odd number of &KEY arguments. Digging around the source tree, I am led to try adding :keymap [(define-key :keymap *my-keymap* ...)], which allows me to proceed.
After removing the non-existent #'example, and adding some new keybindings (space is already bound to scroll-page-down by default) I now have an init file which doesn't crash, but doesn't have any effect on the keybindings: not surprising as *my-keymap* isn't used anywhere. For that I need to read on ... the manual eventually shows the code
```
(define-mode my-mode ()
 "Dummy mode for the custom key bindings in `*my-keymap*'."
 ((keymap-scheme :initform (keymap:make-scheme
                            scheme:emacs *my-keymap*
                            scheme:vi-normal *my-keymap*))))

(define-configuration buffer
 ((default-modes (append '(my-mode) %slot-default))))
```
which crashes with "Package KEYMAP does not exist." At which point my patience runs out.

Am I missing something, or is the documentation simply out of date?

What follows is not really part of this issue, but as I see nowhere else where to ask such questions, and I don't want to open another issue, as I suspect these might be local problems, I'll just add them here.

Keybindings which involve more than one modified key are very flaky:

Example 1: C-x C-c only works if I keep C- pressed down while pressing x followed by c: If I release C- after C-x and press C- a second time for the C-c, absolutely nothing happens.
Example 2: Out of the 7 advertised bindings for zooming

C-x +, C-x C-+ and C-x C-=: Increase size
C-x C--, C-x -: Decrease size
C-x 0, C-x C-0: Restore defaults

the only ones that I can get to react are C-x C--, C-x 0 and C-x C-0, (and those only work if C- is not released mid-way, as in example 1).

Example 3: M-> and M-< do not react at all.

========

Are there really no C-h k (describe-key) and C-h w (where-is) available in Next?

========

Is it normal that the minibuffer does not show any keystrokes being typed?

Ambrevar commented 4 years ago

Hi Jacek!

Thanks for reaching out and thanks for your enthusiasm! Don't worry, you'll find help here!

I have not found any other place where to discuss or get help: is there such a place?

For now, mainly here, on the GitHub issue tracker. In the future we might have a different platform.

You can also try on #next-browser on IRC (Freenode) and https://old.reddit.com/r/next_browser/.

I am running Next 1.4.0, installed with nix (on NixOS).

This is getting very old now ;) The latest stable is 1.5, but even then I'd recommend running Next from master as it has progressed tremendously. 2.0 coming hopefully soon, stay tuned.

The manual section on keybindings states that "Keys are defined with the define-key command." and shows the following code:
(defvar *my-keymap* (make-keymap "my-map")
  "My keymap.")

(define-key *my-keymap*
  "C-x o" #'example
  "space" #'scroll-page-down)

This manual is for the upcoming version. If you want the manual for 1.4, see https://github.com/atlas-engineer/next/blob/1.4.1/documents/MANUAL.org.

In the future, documentation will be embedded in the browser. Master does much better in that regard, see the tutorial command.

Am I missing something, or is the documentation simply out of date?

Indeed, you were consulting the wrong documentation, sorry about the confusion.

@jmercouris, we should remove the documentation link from the homepage, it's confusing everyone :(

Keybindings which involve more than one modified key are very flaky:

The longstanding issues in Next 1.x have been fixed on master. You should have no more issues there.

Are there really no C-h k (describe-key) and C-h w (where-is) available in Next?

On master, yes!

Is it normal that the minibuffer does not show any keystrokes being typed?

Not sure I understand. In which context? What are you expecting?

Maybe you meant like how Emacs displays the current prefix key in the echo area. E.g. if you press "C-c" and wait for a second, you see it displayed in the echo area.

This is a good idea actually, I'll implement it.

jacg commented 4 years ago

Hi Pierre!

Thanks for your warm reply.

I'll try again with master: it sounds like a lot of progress has been made.

I am running Next 1.4.0, installed with nix (on NixOS).

This is getting very old now ;) The latest stable is 1.5, but even then I'd recommend running Next from master as it has progressed tremendously. 2.0 coming hopefully soon, stay tuned.

... in which case it's a shame that the most recent version mentioned on https://next.atlas.engineer/articles is 1.3.4!

Is it normal that the minibuffer does not show any keystrokes being typed?

Not sure I understand. In which context? What are you expecting?

Maybe you meant like how Emacs displays the current prefix key in the echo area. E.g. if you press "C-c" and wait for a second, you see it displayed in the echo area.

Yes, that's exactly what I meant.

This is a good idea actually, I'll implement it.

Great! Thanks

(Actually, if it's not too involved, I'd like to have a go at it myself.)

Ambrevar commented 4 years ago

Jacek Generowicz notifications@github.com writes:

... in which case it's a shame that the most recent version mentioned on https://next.atlas.engineer/articles is 1.3.4!

@jmercouris: Time to publish an article introducing the upcoming 2.0?

(Actually, if it's not too involved, I'd like to have a go at it myself.)

Sorry, it was a one-liner, I've already pushed it on master :D

jacg commented 4 years ago

I'm struggling to compile master on NixOS. Does anyone have a shell.nix for hacking on Next?

I have tried, among other things, nix-shell -p next -I nixpkgs=<path/to/local/clone/of/nixpkgs> (with the nixpkgs updated to recent master) ... and invariably the final result (after much noise) is

Compilation failed, see the above stacktrace.
Also make sure 'xclip' and latest cl-webkit are available on your system.
make[1]: *** [Makefile:41: application] Error 1
make[1]: Leaving directory '/home/jacek/common-lisp/next'
make: *** [Makefile:36: next] Error 2

Looking through the noise, I guess that the important parts are two occurences of

  Unable to load any of the alternatives:
   ("libssl.so.1.1" "libssl.so.1.0.2m" "libssl.so.1.0.2k" "libssl.so.1.0.2"
    "libssl.so.1.0.1l" "libssl.so.1.0.1j" "libssl.so.1.0.1f" "libssl.so.1.0.1e"
    "libssl.so.1.0.1" "libssl.so.1.0.0q" "libssl.so.1.0.0" "libssl.so.0.9.8ze"
    "libssl.so.0.9.8" "libssl.so.10" "libssl.so.4" "libssl.so")

which I guess are caused by Nix' deviation from FSH. The developer readme addresses this in the contex of Guix, suggesting that "you may want to expose ~/.guix-profile/lib" (which for Nix would translate to ~/.nix-profile/lib). However this would seem to be a solution that is dependent on what the user currently has installed, rather than what the current nix-shell provides, which seems to miss the point of a nix-shell for development.

At this stage the avenues to explore bifurcate enormously, and I run out of steam. Any hints?

Ambrevar commented 4 years ago

The cl+ssl Nix package is probably missing (or broken).

There is a Guix package in the build-scripts/ folder: Nix can get most of what it needs out of it.

Once all the Common Lisp packages are ready for Nix, the rest is pretty straightforward.

@nlewo Any clue about cl+ssl?

Ambrevar commented 4 years ago

See issue #753 and @DieracDelta.

tviti commented 4 years ago

I've got one here too that I've been using for doing impure builds:

https://gist.github.com/tviti/0c77befa1ba6dacaf41d3ab3c3142031

On Sat, May 30, 2020, 6:04 AM Pierre Neidhardt notifications@github.com wrote:

See issue #753 https://github.com/atlas-engineer/next/issues/753 and @DieracDelta https://github.com/DieracDelta.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/atlas-engineer/next/issues/764#issuecomment-636351058, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARFZCEHZT4Q5AB4WFHXI6DRUEU7FANCNFSM4NOC32TA .

jacg commented 4 years ago

Thanks @tviti, your shell.nix allows me to make some progress.

@Ambrevar

Maybe you meant like how Emacs displays the current prefix key in the echo area. E.g. if you press "C-c" and wait for a second, you see it displayed in the echo area.

This is a good idea actually, I'll implement it.

Quick bit of feedback: I've got as far as seeing this in action. It seems that it only reports keystrokes which have been accepted, while remaining silent on ones which are not recognized. For example, I was unaware that I was in a CUA rather than an Emacs map, so quit was bound to C-q rather than C-x C-c. When typing C-x C-c the echo area reported C-x but there was no reaction to the C-c that followed. From Emacs (and webmacs, and conkeror etc.) I expect to be told something along the lines of "C-x C-c is undefined", so I was VERY confused, thinking that next was not receiving my C-c at all.

On another note, I really want my Emacs keybingings back. Lest I waste more time on following the wrong version of the documentation, could you point me to where I can find the current instructions for switching all my keymaps from CUA to Emacs?

Ambrevar commented 4 years ago

Jacek Generowicz notifications@github.com writes:

Quick bit of feedback: I've got as far as seeing this in action. It seems that it only reports keystrokes which have been accepted, while remaining silent on ones which are not recognized. For example, I was unaware that I was in a CUA rather than an Emacs map, so quit was bound to C-q rather than C-x C-c. When typing C-x C-c the echo area reported C-x but there was no reaction to the C-c that followed. From Emacs (and webmacs, and conkeror etc.) I expect to be told something along the lines of "C-x C-c is undefined", so I was VERY confused, thinking that next was not receiving my C-c at all.

The problem is that unrecognized keys are forwarded to the rendered in which case they might do something. For instance, tab will cycle through the DOM elements. Should we print "Forwarded TAB" in the echo area all the time? This might get very annoying. I can't think of a way to make the distinction between the keys that don't do anything and those that are caught by the web renderer.

On another note, I really want my Emacs keybingings back. Lest I waste more time on following the wrong version of the documentation, could you point me to where I can find the current instructions for switching all my keymaps from CUA to Emacs?

Look at the tutorial (f1-t), you'll find an example these. If you can't figure it out in less than 5 minutes, it's a bug, please report :)

Ambrevar commented 4 years ago

Closing this since MANUAL.org has been removed.

For the Nix recipe, please keep us updated (maybe in a new issue).

For the keybinding feedback, if you can think of a better design, feel free to share! We can also discuss this in a separate issue.

atlas-engineer / nyxt

Documentation not current? #764