Next User Manual

Next User Manual

Next is the next generation browsing experience designed for power users. 100% of the functions and classes are exposed to the end-user allowing for infinite customization.

Contents TOC

Basics

Within a tab, all navigation is possible using only the keyboard. To navigate up and down on a web page, the following keybindings are provided.

  1. C-n: Move down
  2. C-p: Move up
  3. scroll-left: Move left (no keybindings for now)
  4. scroll-right: Move right (no keybindings for now)
  5. M->: Jump to bottom of page
  6. M-<: Jump to top of page

Note_: Next also ships VI-style keybindings.

Zooming page

Use the zoom keybindings to make everything on a web page larger or smaller.

  1. C-x +, C-x C-+ and C-x C-=: Increase size
  2. C-x C--, C-x -: Decrease size
  3. C-x 0, C-x C-0: Restore defaults

In order to visit a link, one never has to remove their fingers from the keyboard. It works like this:

  1. Enter in a special key combination C-g
  2. Several strings will appear on screen "AZ" "CY", these special strings represent links that you can visit
  3. Enter in one of these strings into the minibuffer
  4. Press Return
  5. Visit the page

The full key-bindings for link-hint based navigate are found below:

  1. C-g: Go to link in current tab
  2. M-g: Create new tab with link, focus on new tab
  3. C-u M-g: Create new tab with link, keep focus on current tab

Visiting URLs

When ambiguous URLs are inputted, Next will attempt the best guess about what the user wishes. If the user does not supply a protocol in a URL, https will be assumed. To visit a site supporting only http, the user must explicitly type the full URL with http included.

  1. C-l: Change URL of current document
  2. M-l: New document-mode tab

Searching via search engine

From the new URL prompt, any input that is not recognized as a URL will be searched using the default search engine. Any query that starts with a known search engine prefix will use the corresponding search engine for the query.

For instance, to search "parrot" on Wikipedia:

From a Lisp REPL, you can query the list of search engines with

(get-default 'remote-interface 'search-engines)

It will return something like

'(("default"
   "https://duckduckgo.com/?q=~a"
   "https://duckduckgo.com/")
  ("wiki"
   "https://en.wikipedia.org/w/index.php?search=~a"
   "https://en.wikipedia.org/"))

The ~a in the search engine URI is a place holder for the search pattern.

To set the list of search engines, do:

(in-package :next-user)

(defclass my-remote-interface (remote-interface)
  ((search-engines :initform
    '(("default"
       "https://duckduckgo.com/?q=~a"
       "https://duckduckgo.com/")
      ("yt"
       "https://www.youtube.com/results?search_query=~a"
       "https://www.youtube.com/")
      ("wiki"
       "https://en.wikipedia.org/w/index.php?search=~a"
       "https://en.wikipedia.org/")))))

(setf *remote-interface-class* 'my-remote-interface)

and to append a search engine to the list, you can do

(in-package :next-user)

(defclass my-remote-interface ()
  ((search-engines :initform
    (append
     '(("yt"
        "https://www.youtube.com/results?search_query=~a"
        "https://www.youtube.com/")
       ("wiki"
        "https://en.wikipedia.org/w/index.php?search=~a"
        "https://en.wikipedia.org/"))
       (get-default 'remote-interface 'search-engines)))))

(setf *remote-interface-class* 'my-remote-interface)

Jumping to Headings

Jumping to different headings based on fuzzy completion is available via the following keybindings:

  1. C-.: Jump to heading

Input (Minibuffer)

All input is handled within a special area called the minibuffer. The minibuffer will appear at the bottom of the screen when the user is responsible for inputting some value. The minibuffer may also suggest completions.

Any time a function activates the minibuffer there are two applicable returns:

  1. C-RET: Return Immediate - Return EXACTLY what has been typed into the minibuffer, ignoring completions.
  2. RET: Return Complete - If completion function provided, return the selected completion candidate. If completion not provided return the EXACT text inputted into the minibuffer. If completion function provided, no completion applicable (selected), and the :empty-complete is a truthy value, the function will accept the EXACT text inputted into the minibuffer.

Multi-selection

When that makes sense (e.g. for the delete-buffer command), multiple entries can be marked. The default bindings are:

When the input is change and the candidates are re-filtered, the selection is not alterered even if the marked elements don't show.

Once at least one candidate is marked, only the marked candidates are processed upon return. The candidate under the cursor is not processed if not marked.

Buffers ("tabs")

Many browsers implement the concept of multiple views with "tabs". Tabs are inherently flawed as they don't scale: it's hard to manage more than a few dozen of them.

In Next, multiple views are implemented as "buffers". Each buffer can use its own set of "modes". A mode is a collection of settings, key bindings, commands, etc. Regular web pages use the document-mode by default.

The standard keybindings for buffer management are:

  1. C-x b: Switch buffer
  2. C-x Left: Switch to previous buffer
  3. C-x Right: Switch to next buffer
  4. C-x k: Delete a buffer
  5. C-x C-k: Delete the current buffer
  6. M-l: Open URL in new buffer
  7. C-l: Change URL of current buffer
  8. C-t: Make new empty buffer

Switching Tabs by Order

In addition to switching tabs by selecting the current tab, you can cycle through them. This enables you to jump back and forth between two tabs that are next to each other.

  1. C-[: Switch tab previous
  2. C-]: Switch tab next

Modes

A mode is a collection of features, ranging from key bindings to network options. It can be enabled or disabled on a per-buffer basis via the command of the same name, e.g. vi-normal-mode.

Each buffer has its own list of modes. The first mode in the list has highest priority: this is important, for instance, to determine which key binding takes precedence in case of conflict. See Keybinding for more details.

Modes are CLOS objects that are instantiated per-buffer. No buffer shares the same instance of a mode (by default at least).

Modes are typically defined in their separate Common Lisp package. This allows for defining mode-specific functions and variables in a separate namespace.

To enable a mode for all buffers by default, add the mode to the list of default modes:

(in-package :next-user)

(defclass my-buffer (buffer)
  ((default-modes :initform
     (cons 'vi-normal-mode (get-default 'buffer 'default-modes)))))

(setf *buffer-class* 'my-buffer)

Windows vs. buffers

When opening a link from an external program, or when clicking on a link while C is pressed, Next can load the URL either

You can change the default behaviour by adding the following to your configuration file:

(in-package :next-user)

(defun my-remote-interface ()
  ((open-external-link-in-new-window-p :initform t)))

(setf *remote-interface-class* 'my-remote-interface)

Searching

There are a number of keybindings provided to enable searching within a buffer.

  1. C-s s: Search for a given term: This command will place a hint next to every match on a given web-page.
  2. C-s n: Next match: This command will move the next match to the top of the browser screen.
  3. C-s p: Previous match: This command will move the previous match to the top of the browser screen.
  4. C-s k: Clear search: Remove the search hints from the screen.

History

History is represented as a tree that you can traverse. More complex than the "forwards-backwards" abstraction found in other browsers, the tree makes sure you never lose track of where you've been.

In the example below, the user performs the following actions:

  1. Starts page Athens
  2. Visits page Ancient Greek
  3. Returns to page Athens
  4. Visits page Classical Athens
  5. Returns to page Athens
  6. Executes forwards keybind in history

It is at this point that a normal browser would not be able to navigate you forwards to your visit of Ancient Greek. Instead of erasing your history, Next offers smart navigation and prompts the user. Do you wish to go forwards to Ancient Greek or to Classical Athens?

The standard keybindings for forward-backward navigation are:

  1. C-f: Navigate Forward
  2. C-b: Navigate Backward
  3. M-f: Navigate Forward Tree
  4. M-b: Navigate Backward

By using navigate forward tree you will be prompted for which branch you'd like to visit as in the example above. The simple navigate forward command will simply visit the first child of the current node in the tree.

Bookmarks

In order to navigate and manage your bookmarks, a few functions are provided:

  1. C-m s: Bookmark Current Page
  2. C-m u: Bookmark URL (input URL via minibuffer)
  3. C-m o: Open Bookmark
  4. C-m g: Bookmark Anchor (input URL via link hints)
  5. C-m k: Delete Bookmark

Bookmarks can have tags, a shortcut string, a search-url and a timestamp.

You can filter them with selectors: use +, - or write a compound query inside parenthesis in which you can use and, or and not.

For example:

+lisp -blog
+blog (or lisp emacs)
+foo -bar (or (and john doe) (not (and tic tac)))

Bookmarks are stored in a plain text format, so than you can read and manipulate them easily with any other program.

Download manager

When you download a file, you are taken to a *Downloads* buffer, which shows the ongoing download progress and the list of files downloaded during the current session. You can switch to this buffer as usual, and also with M-x download-list.

To open a file, use M-x download-open-file. See the customization section to control how files are open.

Opening files

With M-x open-file (bound to C-x C-f), you are prompted a list of files, and you can select one with the usual fuzzy completion. You can go one directory up with M-Left or C-l, and enter the directory at point with M-Right or C-j.

Next will open itself directories and supported media types (new in Next 1.3.5), otherwise it will try to open the file with the system's default using xdg-open. See the command help for further details, and the customization section to override the default behavior.

Note: this feature is alpha and is meant to grow in Next 1.4 and onwards.

Next opening a directory:

Next opening a video. We can treat it like any other buffer:

Clearing the Echo Area

In the area at the bottom of the screen where the minibuffer resides, Next will occasionally display messages. These can be dismissed by using the binding C-x q.

Exiting

To exit Next enter the key-combination C-x C-c and the program will quit. All of your open tabs and form data will not be persisted. The only information saved will be your filled in passwords, cookies, and other information within your cache.

Proxy and Tor support

You can surf the web behind a proxy by issuing the command proxy-mode. Its default server address is socks5://127.0.0.1:9050, meaning it works out of the box for Tor.

You can change the default proxy with

(in-package :next-user)

(setf next/proxy-mode:*default-proxy*
 (make-instance 'proxy :server-address  "socks5://your.i.p:port"))

At the time of writing, there are differences between the Gtk and the Qt port: the Gtk one sets proxies per-buffer, whereas it is currently global for the Qt one.

To enable proxy for all buffers by default, add the proxy mode to the default modes. See Modes for details.

Cloning Git repositories

Use the vcs-clone (alias git-clone) command to clone a Git repository to disk. It asks you for the destination and then runs asynchronously.

This feature is meant to grow with Next 1.4 and onwards!.

By default, the command looks into the following directories for existing projects:

"~/projects" "~/src" "~/work" "~/common-lisp" "~/quicklisp/local-projects"

You can change the list like this:

(in-package :next-user)
(setf next/vcs:*vcs-projects-roots* '("~/src" "~/work" "~/my/directory"))

When there is one single choice, it doesn't ask for confirmation.

You can set your username for GitHub and other forges. It helps the clone command in doing the right thing©. For example, if it sees that you are cloning a repository of yours (the user/organization name of the cloned repository equals your vcs-username), it will use a git remote url instead of https.

Set next/vcs:*vcs-username* as a default username.

Change also the *vcs-username-alist*:

(in-package :next-user)

(setf next/vcs:*vcs-usernames-alist* '(("github.com" . "")
                                       ("gitlab.com" . "")
                                       ("bitbucket.org" . "")))

;; or
(push '("myforge.com" . "me") next/vcs::*vcs-usernames-alist*)

Note that the forge name should be a domain, such as github.com.

Downloading videos

The command M-x download-video will try to download the video at the current URL. For example, it works with any YouTube video.

It will ask for a target repository and will notify on success or failure.

It uses by default the program youtube-dl, that you must have installed first.

Disclaimer: this feature is meant to grow with Next 1.4 and onwards!

To customize it, see all the variables and functions in video-mode.

Advanced Topics

Execute Extended Command

You can execute any command by name by typing M-x. This will bring up a list of candidates that you can fuzzily complete.

Help

The help system allows you to look up variable and function docstrings directly within Next. Docstrings will appear in a new help buffer.

  1. C-h v: Look up a variable docstring
  2. C-h c: Look up a command docstring

SLIME with a compiled version of Next

SLIME provides a way of interacting with Next, and with Lisp code in general (e.g. in a REPL).

From the SLIME manual:

SLIME extends Emacs with support for interactive programming in Common Lisp. The features are centered around slime-mode, an Emacs minor-mode that complements the standard lisp-mode. While lisp-mode supports editing Lisp source files, slime-mode adds support for interacting with a running Common Lisp process for compilation, debugging, documentation lookup, and so on.

To use SLIME with a compiled version of Next use the keybinding C-h s to launch a Swank server. SLIME will connect to the Swank server and give you completion, debugging, documentation, etc. The port for Swank is define in *swank-port* and its default value is different from that of Swank on Emacs to avoid collisions with an Emacs *inferior-lisp* process.

After launching the Swank server in Next, execute the following within Emacs:

  1. M-x
  2. slime-connect
  3. Enter 127.0.0.1 for the host
  4. Enter the port number set in the Next variable *swank-port* (e.g. 4006)

To customize the port that Swank starts on, edit the global variable *swank-port* in your init file.

Customization

All customization begins by creating a ~/.config/next/init.lisp file. Within your init file you can write your own keybindings and customizations. If the directory ~/.config/next/ does not already exist, you will have to make it.

The first line of an init file should contain the following package declaration in order to modify Next-specific variables and functions:

(in-package :next-user)

Following the package declaration, you can write or override any functions and variables.

When you are done, you can load your changes while Next is running with the command load-init-file. Or load any file with load-file (C-o).

Next will warn you its best about type mismatches (new in Next 1.3.5). You should be confident that "if it loads, it works"©.

Keybinding

Keys are defined with the define-key command.

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

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

;; Bind in current buffer's first mode.  This won't affect other buffers.
(define-key :keymap (getf (keymap-scheme
                           (find-mode (current-buffer) 'my-mode))
                          :emacs)
  "C-x C-c h" #'hello-local-world)

Read on for an explanation of the meanings of :keymap.

In the previous example, the key sequence C-x o would invoke the example command. If later another command is bound to C-x, all other bindings starting with C-x will be overridden.

The following keys exist as special keys:

  1. C: Control
  2. S: Super (Windows key, Command Key)
  3. M: Meta (Alt key, Option Key)
  4. s: Shift key

Keymaps and key binding schemes

A keymap is a collection of key-to-command bindings.

Modes can define key binding schemes, which are sets of keymaps indexed by a scheme name like :emacs.

The currently active key binding scheme is selected by the current-key-scheme buffer slot. When a key is hit, Next looks up the keymaps of the corresponding scheme for all active modes in the current buffer.

You can change the default binding scheme for any buffer by setting current-key-scheme to the appropriate value.

To create a keymap, use the make-keymap function.

The user can define key bindings by creating a mode that is loaded before any other mode. In your configuration file:

(defvar *my-keymap* (make-keymap)
  "Keymap for `my-mode'.")

(define-mode my-mode ()
  "Dummy mode for the custom key bindings in `*my-keymap*'."
  ((keymap-schemes :initform (list :emacs-map *my-keymap*
                                   :vi-normal *my-keymap*))))

(defclass my-buffer (buffer)
  ((default-modes :initform
     (cons 'vi-normal-mode (get-default 'buffer 'default-modes)))))

(setf *buffer-class* 'my-buffer)

Override map

The override map is the first keymap that is looked up for a binding when a key is pressed. Override maps are stored in every buffer. They are exposed to the user as a mean to override any binding from any mode. They should not be modified by any library.

VI-style bindings

VI is a modal text editor that is famous for its modal key bindings. In normal mode, all keys are commands, they won't insert any text anywhere.

In insert mode, all textual keys insert the corresponding text.

Next offers two modes, vi-normal-mode and vi-insert-mode to simulate this behaviour. For instance, in vi-normal-mode, j scrolls the page down and k scrolls up.

To go from normal mode to insert mode, press i. To go from insert mode to normal mode, press ESCAPE.

The default keybindings for vi-normal-mode are:

"Z Z": kill
"[": switch-buffer-previous
"]": switch-buffer-next
"g b": switch-buffer
"d": delete-buffer
"D": delete-current-buffer
"B": make-visible-new-buffer
"o": set-url-current-buffer
"O": set-url-new-buffer
"m u": bookmark-url
"m d": bookmark-delete
"C-o": load-file
"C-h v": variable-inspect
"C-h c": command-inspect
"C-h s": start-swank
":": execute-command
"W": new-window

The minimal config that sets your Next in vi mode, is:

; $HOME/.config/next/init.lisp
(in-package :next)
(add-to-default-list 'vi-normal-mode 'buffer 'default-modes)

Start-up options

The next command accepts URLs as parameters, as well as some options.

The available options are:

Using the session

By default, Next will restore the previous session, and save the current one to disk.

You can disable this behavior with a command line option:

next --session nil

and a lisp parameter:

(setf next:*use-session* nil)

To quit Next without saving the session, use the command quit-after-clearing-session.

Decide how to open files

The commands open-file and download-open-file call the function next/file-manager-mode:open-file-function <filename>.

You can override this behaviour by binding another function to the variable next:*open-file-function*, in which you can fallback to the default function.

For example, below we open directories with emacsclient and some music ad videos with mpv:

(defun my-open-files (filename)
  "Open music and videos with mpv, open directories with emacsclient."
  (let ((args)
        (extension (pathname-type filename)))
    (cond
      ((uiop:directory-pathname-p filename)
       (log:info "Opening ~a with emacsclient." filename)
       (setf args (list "emacsclient" filename)))

      ((member extension '("flv" "mkv" "mp4") :test #'string-equal)
       (setf args (list "mpv" filename))))

    (handler-case (if args
                      (uiop:launch-program args)
                      ;; fallback to Next's default.
                      (next/file-manager-mode:open-file-function filename))
      (error (c) (log:error "Error opening ~a: ~a" filename c)))))

(setf next/file-manager-mode:*open-file-function* #'my-open-files)

Loading Files

To load a file again, or reload an init file use the function load-file. Within the minibuffer prompt enter the full path to the file you wish to load.

  1. C-o: Load File

A convenience function for reloading the init file called load-init-file can also be keybound.

Creating your own interactive commands

Creating your own invokable commands is the same as creating any other defun except the form is define-command. A docstring is highly recommended and will produce a style warning when it is missing.

An example of a trivial command definition can be seen below.

(define-command bookmark-url ()
  "Allow the user to bookmark a URL via minibuffer input."
  (with-result (url (read-from-minibuffer
                     (make-instance 'minibuffer
                                    :input-prompt "Bookmark URL:")))
    (bookmark-add url)))

These functions will help you retrieve information:

Getting input from the user

Getting input from the user via the minibuffer is an asynchronous command. That is why the read-from-minibuffer function is wrapped within a continuation-passing-style macro with-result. The form therefore takes the following look:

(with-result (variable-name-to-bind-minibuffer-input
              (read-from-minibuffer (minibuffer *interface*)))
  (print variable-name-to-bind-minibuffer-input))

Network resource dispatch (including ad-blocking)

The dispatching of network queries can be fully customized in the resource-query-function slot of the buffer class.

See the resource-query-default function for an example which dispatches downloads, new window requests,

This function can also serve as an entry point to URL-based resource blocking.

Resource blocking (Ad-blocking)

Next provides the blocker-mode. It filters networks requests (including ads)by the host name. A default filter list is automatically updated from https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts.

Multiple lists of hosts can be added and blocker mode will filter based on all the lists.

To add a list, add an instance of the hostlist class to the hostlists slot. For instance, you can add this to your init.lisp.

(in-package :next-user)

(defvar *my-blocked-hosts*
  (next/blocker-mode:make-hostlist
   :hosts '("platform.twitter.com"
            "syndication.twitter.com"
            "m.media-amazon.com")))

(define-mode my-blocker-mode (next/blocker-mode:blocker-mode)
  ((hostlists :initform (list *my-blocked-hosts* next/blocker-mode:*default-host-list*))))

(defclass my-buffer (buffer)
  ((default-modes :initform
     (cons 'my-blocker-mode (get-default 'buffer 'default-modes)))))

(setf *buffer-class* 'my-buffer)

The hostlist class also support fetching the list from a URL. The list can be persisted to the file specified in the path slot.

Styles

Some actions will draw elements on the HTML page, for instance go-anchor will draw link hints as boxes with indices.

The style of those boxes is defined in the box-style slot of the buffer class.

Like any other slot, you can set the default value from your init.lisp. For instance, to change the style to using upper case, no gradiant, and square boxes:

(in-package :next-user)

(defclass my-buffer (buffer)
  ((box-style :initform
    (cl-css:inline-css
     '(:background "#C38A22"
       :color "black"
       :border "1px #C38A22 solid"
       :font-weight "bold"
       :padding "1px 3px 0px 3px"
       :padding "1px 3px 0px 3px"
       :position "absolute"
       :text-align "center"
       :text-shadow "0 3px 7px 0px rgba(0,0,0,0.3)")))))

(setf *buffer-class* 'my-buffer)

Hooks

A hook is a variable that holds a list of functions. We say a hook is executed when all its functions are run one after the other, over its arguments (which are decided at the call site).

Hooks are exposed to the users so that they can customize the behaviour of specific actions in arbitrary ways.

Many hooks are executed at different points in Next, among others:

For instance, if you want to force old.reddit.com over www.reddit.com, you can set a hook like the following in you ~/.config/next/init.lisp:

(defun old-reddit-hook (url)
  (let* ((uri (quri:uri url)))
    (if (search "www.reddit" (quri:uri-host uri))
        (progn
          (setf (quri:uri-host uri) "old.reddit.com")
          (let ((new-url (quri:render-uri uri)))
            (log:info "Switching to old Reddit: ~a" new-url)
            new-url))
        url)))

(defclass my-buffer (buffer)
 ((load-hook :initform (list #'old-reddit-hook))))

(setf *buffer-class* 'my-buffer)

Some hooks like the above example expect a return value, so it's important to make sure we return url here. See the documentation of the respective hooks for more details.

List of available hooks

Commands hooks

All commands have an associated "before" and "after" list of hooks: the help command has help-before-hook and help-after-hook.

To add a hook handler, just push a function to those lists:

(defun hello-hook ()
  (log:info "hello"))

(push #'hello-hook help-before-hook)
;; (#<FUNCTION HELLO-HOOK>)

Now when you press M-x help, you'll see

<INFO> [18:15:45] next (hello-hook) - hello

Initialization and exit hooks

platform port have started.

platform port get terminated.

*Networking* hooks

*Window* hooks

*Buffer* hooks

*Download* hooks

*Mode* hooks

Startup behaviour

Once the platform port has been started, the default action of Next is to run

(funcall (startup-function *interface*) (or urls *free-args*))

startup-function defaults to default-startup and takes URLs that are passed to Next as command line arguments.

You can assign you own function to startup-function to change the behaviour of Next on startup, such as which URL it should display, if it should restore the previous session or not, etc.

Run Next in a security sandbox

For improved security while you browse the internet, you can run Next with Firejail on GNU/Linux.

Run it like this:

firejail --ignore=nodbus next-gtk-webkit

Troubleshooting

StumpWM mouse scroll

If the mouse scroll does not work for you, see the StumpWM FAQ for a fix.

D-Bus requirement

Next needs a D-Bus session bus to run. In most cases, it should already be running. If Next does not start up, it is very likely that D-Bus is not running for your user.