00:24:41.380: So how do you find functions in Emacs? Well, there's an apropos command, which is spelled A-P-R-O-P-O-S because the S is silent. Apropos lets you search for something. For example, if you're looking for, let's say, anything related to finding a function, describing a function, function help, maybe. Then it will show you a list of those functions where the documentation matches those keywords or the name of the function matches those keywords. This is one of the things that I often do when I'm trying to find something that… There's probably a function out there to do what I want to do, so I start looking for it.

(use-package orderless
  :ensure t
  :custom
  (completion-styles '(orderless basic))
  (completion-category-overrides '((file (styles basic partial-completion)))))

00:26:39.280: Orderless is a package that works very well with different kinds of completion if you use this little snippet over here, which sets your completion styles to use orderless. So I'm using eval here to just evaluate that bit. Then I can say M-x and function here will now find things where the match isn't at the beginning. It can be in the middle. It can be somewhere else. You can even specify matches out of order. So, for example, if I know something is related to functions, I might start typing func, function or whatever, and then I might start saying, oh yeah, it's a describe thing, right? Even if you're specifying things out of order, you can get the completion for it. Often when I'm looking around for something, I will use this describe function with orderless and vertical to just start typing the words that I think it might be called. Let me show you that now. For example, the describe-function here… What describe-function does is it gets a name of a function, and it will display the documentation for it. Let's say, for example… Let's look for describe package. So it will describe this information. It will show you where it's found. It will show you what its arguments are and what the documentation is. So that's orderless. It helps you find things.

(use-package vertico
  :ensure t
  :config
  (vertico-mode))

00:25:29.380: Another way to do it is just to type in the names and hope that you can find the function that way. Now, when you're starting off with a plain Emacs, it's a little bit sparse. You actually have to remember the things. If you start typing describe, you can use tab for completion. You have to hit it twice to get more of a completion list. So this is one of the things that I tend to encourage people to change right away, because completions make it much easier for you to see what you actually want to do. One of the things that I like to use for this is a package called Vertico. And if I evaluate that, if I use the package and turn on vertico mode, then you'll see that it displays the functions right there. Even if I don't remember how to spell apropos, I can start typing apr and it will display it right away. If I'm looking for something like function, you'll notice that it can't find anything, but that's because we're still missing the next thing that I want to share, which is orderless.

(use-package marginalia
  :ensure t
  :bind (:map minibuffer-local-map
              ("M-A" . marginalia-cycle))
  :init
  (marginalia-mode))

00:28:10.920: So that's orderless. It helps you find things. The other nice thing that you can add on top of this completion is a package called marginalia. Marginalia, anyway, marginalia, sure. Now, when you're describing functions, sometimes the first line is all you need in order to figure out whether this is something you want or not. Marginalia will let you, let's say for example if you're looking for a function, it will let you see the arguments as well as a brief description of it in the right side here. It adds these margin notes to a lot of the searches, a lot of the completions that you have available. Let's say for example, if I'm looking for… I want a function that works with sequences and it makes things flatter. No, it makes things, okay, let's make, let's pick something that involves splitting things into different groups. And seq-partition here, you can see here that it takes a sequence and it returns a list of elements of sequence grouped into subsequences of length n. Having that function description right there can be really helpful when you're trying to find something. All right. So that's Marginalia.

M-x shortdoc:

00:29:56.020: Another way to find something if you aren't quite sure what you're looking for is shortdoc. With shortdoc, you can give it a group of functions, and the wonderful Emacs developers have already created a whole bunch of cheat sheets for these different functions. For example, I do a lot of work with sequences, which is basically any kind of list or vector or… I think, sets, maybe? I don't know, it's… Anyway, sequences. So there is a shortdoc for sequence, and what it does is it shows you very short documentation (hence short doc) showing you the different important functions in this group, with examples. I really like the fact that I can just flip through this and then in the different sections, try to find the function that I'm looking for. This is especially helpful if you don't know what something is called or even what keywords you might start to look for, because one of the big challenges with Emacs Lisp is just figuring out what things are called. So, shortdoc, you can just call it with M-x shortdoc, and then you can browse through it. As you can see, there are a whole lot of different things that are included there. You can probably define your own too if you want to. For example, string-related functions show me all the things that… Like one time I was trying to figure out whether it was called repeat or whatever. It's actually called make-string. You can see all of the examples there.

Install from MELPA:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

(use-package helpful
  :ensure t
  :bind
  (("C-h f" . helpful-callable)
   ("C-h v" . helpful-variable)
   ("C-h k" . helpful-key)
   ("C-h x" . helpful-command)))

00:31:44.120: Now, this is great for finding functions. but sometimes you want to have even more information about something when you're looking at it. So if I C-h f, which is the describe-function keyboard shortcut, the, it'll default to this, the symbol at point, which is helpful. It'll show me the documentation for it. But you can actually get even more documentation than this. That's where the helpful package comes in, which is another thing that I've been finding really useful. Now, Helpful is not built in, but you can install it from Melpa, which is the Milkypostman Elpa, Emacs Lisp package repository. Oh, sorry, archive, A, not R, archive. You can find the instructions for doing that at melpa.org. So let's get this into our configuration. I paste it in, I evaluate the lines, and then it has a bunch of commands that replace the functions that we have. Well, not replace, but you know, they encourage you to bind it over the keyboard shortcuts for find-function– sorry, describe-function or describe-variable or describe-key and so forth. For example, if I press C-h f, it will now call helpful-callable. If I then use something like seq-find, maybe, then it will show me not only the signature, the arguments for the function, and the documentation for it, which is fairly normal, but it'll give me as well references. It'll let me enable edebugging right from there, and even include the source code. I find that the source… Looking at the source code for functions is very helpful. Before, I used to use describe-function or find-function. Well, describe-function will give you a link to its implementation. And find~function will try to find the… Is it actually called find-function? Yeah. So, there is a find-function that finds the definition of a function, but with helpful, I can get the source code right there. So then I can say, show me all sorts of things, and I don't have to do that extra jump. A whole bunch of other things, in case you're curious: It'll show you the symbol properties or whether something is advised or not. You get some of that as well with a regular describe-function, but this is a little bit extra. So that's the helpful package, which I do find helpful, as it says. As Alejandro points out, even source code in C, if it's available. So I think I was talking about libxml-parse-html-region. libxml-parse-html-region is actually the thing that I mentioned. You'll see here that it's defined in xml.c, but the source code is here as well. All it does is it calls the parse region from libxml2, which is arcane wizardry, and I don't know how to fiddle with the C stuff yet, which is why we ended up hacking it at the Emacs Lisp level instead. So, helpful is actually very helpful. One thing that makes it even more helpful

(use-package elisp-demos
  :ensure t
  :init
  (advice-add 'describe-function-1 :after #'elisp-demos-advice-describe-function-1)
  (advice-add 'helpful-update :after #'elisp-demos-advice-helpful-update))

Example: set-transient-map

00:35:13.260: One thing that makes it even more helpful than that is another package called elisp-demos. elisp-demos adds some extra examples to this. Let's try that out here. Now that I've included that, it has added some advice around helpful-update to load the demos. If I look up something like seq-partition maybe, which is that function we mentioned earlier, you'll notice that there's a new section here called demos, and an example here of how someone uses it to… You pass a list, you pass a number, and it gives you some results. I put in this patch recently that the maintainer has accepted, hooray, and it allows you to add your own notes [with this button]. So you can add a note there. The kiddo is awake, so I'd better talk even faster. Okay, so the last thing I wanted to show is you can use this not only to include– hello kiddo, you're awake, you're awake– not only to include your own examples, but also, you can use it to take other notes. Here, for example, is set-transient-map. There are examples there. If I look at tabulated-list-mode, I think there aren't any demos for this one yet. But, very quickly, I will show you before I feed the kiddo some breakfast– (although if you want, you can start getting your own breakfast)– is you can also use that to add your own notes here. This is a blog post that had a whole bunch of information on how to set up tabulated list mode, which will open eventually in… Ah! Some browser. Okay, I will just open it here because I just remembered my default browser is Firefox, though… We will show that some other time. Okay, so this is the blog post that explains a lot about how to use tabulated-list-mode, or at least it gives a very short example. And then… Actually, let's just copy this over here. Sure, we can add… Ha, it's not added. Let's make that lisp… I don't have my usual structs defined here. OK, so now if I C-h f tabulate-list-mode you can see here the… Oh, that's not an end_export, is it? That should be an end_src. So you can see here, it has the example that we've just added and you can also include whatever notes you have all about the thing. That is probably all I can do today because I gotta go feed a kiddo. All right folks, thank you for joining me. Next stream is probably Sunday again, probably around this time, but maybe with faster talking. Thanks everyone and have lots of fun. Thanks for dropping by!