pdf-tools documentation

pdf-tools documentation

[Julius Hamilton]

Hey,

I am relatively new to Emacs.

I am trying to learn how to use pdf-tools, for example its highlighting
features.

I noticed on its official page, https://github.com/politza/pdf-tools, it
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?

Thanks very much,
Julius

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

Re: pdf-tools documentation

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Date: Sat, 19 Jun 2021 22:50:32 +0200
> Cc: help-gnu-emacs@gnu.org
> 
> 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...

Excellent and comprehensive advice, but please don't forget that
reading the package source, at least some of it, is also a powerful
means for learning about a package.  That's why Free Software is a win
for users: you have all the information before you, whether the author
wants that or not.

Re: pdf-tools documentation

[Óscar Fuentes]

Julius Hamilton <julkhami@gmail.com> writes:

> I am relatively new to Emacs.
>
> I am trying to learn how to use pdf-tools, for example its highlighting
> features.
>
> I noticed on its official page, https://github.com/politza/pdf-tools, it
> 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?

The section at the end of the webpage you linked titled "Some
keybindings" is quite self-explanatory, as a pdf reader goes.

For more details, while visiting a pdf file with pdf-tools, you can use

C-h k <key sequence>

for seeing the docstring of the command associated to that sequence.

You can also invoke the command pdf-tools-help, which will show commands
and variables associated with the mode.

Finally

M-x customize-group [ENTER] pdf-tools [ENTER]

will show an interface for configuring how pdf-tools works.