Re: pdf-tools documentation

[Joost Kremers]

On Sat, Jun 19 2021, Julius Hamilton wrote:
> I noticed on its official page, https://github.com/politza/pdf-tools, it

Note that pdf-tools was recently taken over by another maintainer. If you go to
melpa.org, search for the package and then go to its home page, you'll notice
it's now maintained at <https://github.com/vedang/pdf-tools/>.

> has a lot of instructions about installation, and a list of some commands,
> but there's no link to any complete documentation which includes all
> features.
>
> How can I learn about its features in detail?
>
> Should I use some kind of Emacs help command about the library?

There is, unfortunately, not one single method of documenting Emacs packages.
There's a few things you can try, though. `C-h P` (`describe-package`) asks for
a package name and shows you the description that is provided in the package's
source code. Some packages have a lot of info there, some very little.

Other packages provide an info manual: `C-h i` takes you to the main info node,
there you can check if your package has an info manual.

In the case of pdf-tools, `C-h P` gives you the same info that is present in
Github, and there is no info manual, so neither method will help you...

The next thing to do is then to see what key bindings are present. If you do
`C-h m` (`describe-mode`) you'll get a description of the minor modes and the
major mode in the current buffer. There is usually a lot of irrelevant
information there, so you'll need to search a bit for what you are looking for.
The major mode is discussed first, though, and there is a list of keybindings.

The overview of keybindings only shows the commands that the keys execute, but
often the names are fairly self-explanatory, and clicking on a command usually
shows you a description.

If you have a completion package that shows you a list of candidates (I use
selectrum myself, but there are several other options), typing `M-x pdf-tools`
will give you a list of commands that have `pdf-tools` in their name, which can
also be a good way to look for something specific.

Sometimes, the menu-bar menu can be helpful as well. If you've disabled the menu
bar, you can still access the menu with F10.

Other useful things to know: `C-h c` lets you type a key and tells you which
command is bound to it. More useful perhaps is `C-h k`, which lets you type a
key and displays the documentation of the command that's bound to it.

In the end, the quality of the documentation really depends on the package
author, however...

-- 
Joost Kremers
Life has its moments