So I’ve been looking through the various describe-X functions to try and get an idea of how things are set up. However I’m finding myself very lost by the sheer amount of information. I also don’t know many of the terms, like what a slot is.
Is there a glossary of terms somewhere, and a categorization of what/where various functions are relevant?
There are thousands of functions, slots, etc and I don’t have any idea how to navigate any of it. I’m not a programmer so that may be why I’m struggling. I can just barely hack together the odd thing I’m trying to do.
Indeed, we’re quite code-oriented here. A quick glossary is:
-
Class is a template for entities we use. You open a buffer/tab – and it’s constructed based on the class that we defined. To see what this buffer template is, use C-SPC describe-class RET buffer RET.
-
Slot is a small piece of data belonging to a class. So, if a class is a template, slot is a separate part of this template. For example, every buffer has a url – a link to the currently opened page. Do C-SPC describe-slot RET url RET – and you’ll learn a bit more about what this particular piece of data adds to the template.
-
Functions (as in describe-function) are pieces of code that you can call by name. Those are not necessarily something you encounter directly when using Nyxt, but those are a valuable concept to understand…
-
Commands. Those are basically functions (pieces of code) that you can bind to a key or call by name from the execute-command (C-SPC, M-x, :) prompt. To learn what that familliar key does, you can use C-SPC describe-key RET and press it. It will show you the documentation (the clarifying text) and some other information for the command bound to that key. If you already know which command it is that you need – just use describle-command. For example, do C-SPC describe-command RET set-url RET, for example, to learn more about the most frequent and necessary command in Nyxt – set-url, the one responsible for navigating you to websites.
-
And then there are also tutorial and manual that help you to make more sense of what’s going on (but yes, they are quite techy in terms of jargon). What manual suggests (and I am happy to re-emphasize) is to look at the documentation of buffer, browser, and window classes (C-SPC describe-class RET browser RET)
I hope that it helped 
2 Likes
This really helps thank you!
Why is there a difference between a function and a command? Aren’t commands also functions?
Is there like a thematic classification of how things fit together? So like this bunch of things are related to the interface, and that bunch of things has to do with the page rendering, etc? Or is that kind of thing already covered by the classes?
Indeed, all commands are functions (while not all functions are commands). The difference is mostly that commands are also accounted for by Nyxt and easy to call from the execute-command interface. From the programming and extension writing perspective, there’s not much diffference.
Most of Nyxt is class-based, yes. We try to use as much of so called Object Oriented Programming (an idea that writing a reasonable set of interrelated classes can help you with making programs that are easy to maintain and expand). So, if you want to know how a certain mode is working, you can look at its documentation as a class (describe-class RET auto-mode, for example). If you want to know how to configure the prompts to your liking, look at prompt-buffer. The list goes on.
It’s also important that a lot of internal pages you see in Nyxt (downloads, manual, describe-* pages) are generated by the commands. Because of that, looking at commands’ source and documentation can be revealing too. Some commands even include the code that generates the pages you see, so you can redefine those to make prettier pages.
In Nyxt 3.0 we’ll have concepts like internal pages, internal schemes, and there will be more structure about interfaces in general. For example,
- all the Nyxt-specific pages will quite likely be created using the
define-internal-page-command macro, thus making a command, a URL (a command named list-downloads becomes a universally accessible nyxt:list-downloads URL), and a page accessible through both command and URL.
- All the panel buffers are also working in the same way, being created with the
define-panel macro and having their own URLs and commands.
But you’ll be served best by looking at the commands you use in your everyday browsing as the starting point of discovering Nyxt inner working and starting your own configuration by defining new commands.
2 Likes
Thank you, this greatly reduces the overwhelm of knowing where to start. 
Maybe soon I’ll be able to also contribute little things.
1 Like