This is a tutorial that should be enough to get you started using papis. Papis tries to be as simple and lightweight as possible, therefore its database structure is ridiculously simple.
But before taking a look at its database structure let us see how is the daily usage of papis for a regular user. This tutorial is command-line based, so you should be familiar with opening a terminal window on your system.
Creating a new library¶
We will illustrate the process by creating a first library with a couple of
`pdf` documents in it. Papis can be highly configured using configuration
files. Many programs use configuration files maybe without you being aware of
it. Papis’ configuration files are stored together inside the folder
Bear in mind that
~ means “Home Directory”. Inside this directory a
configuration file is found,
Right now we will open this file for editing and we will create a library. In papis everything should be human-readable and human-editable. So adding a library is as easy as adding two lines to this configuration file.
Say that you want to create a “papers” library, where you can finally order all those pdf’s hanging around on your computer. We create this library by putting these two lines inside the config file:
[papers] dir = ~/Documents/mypapers
In the above lines we have created a library with the name
papers which is
located in the directory
~/Documents/mypapers. So all the documents that
we will be adding to the library will be located inside
~/Documents/mypapers, and nowhere else. Everything that papis needs to take
care of your
papers library is inside the
If you have not already, add the two lines to the
~/.config/papis/config file and save it, and we will
proceed to add some documents.
Adding the first document¶
If you don’t have any special pdf lying around let me choose one for you:
You can download this document and we are going to add it into the
Assuming that you have the document in the current directory and you have renamed
the document to
document.pdf, do the following to add the pdf into your
papis add document.pdf --set author "Newton" --set title "Principia Mathematica"
And it’s done! We have added our first book to the library.
Let us see how this works exactly. Papis consists of many commands, and one of
these commands is
add itself has many flags, which are options for the
given command. In the example above we have used the flags
title to tell papis to use
Newton as the author’s name and
Mathematica as the document’s title. You can see all the possible flags
for the command
add if you use the
help flag, i.e., if you issue the
papis add --help
Now you are asking yourself, what happened to the pdf-file? Where is it
stored? Is it stored in an obscure database somewhere in my computer? No,
papis just copied the
document.pdf file into a folder inside the library
~/Documents/papers/. If you now go there, you will see that a folder
with a weird name has been created. Inside of the folder there is the
document.pdf file and another file,
If you open the
info.yaml file you will see the following contents:
author: Newton title: Principia Mathematica files: - document.pdf
This file is all that papis uses to store the information of your newly added document. It is stored in a nicely readable yaml format.
Now you already have your first document, and.. you can open it! Just do
and the document should open in your default pdf-viewer. You can change the default pdf-viewer in your configuration file (see section on Configuration file).
Now you can try to repeat the same process with another pdf-file lying around.
When you hit
papis open again, it will ask you which one you want.
If you input parts of the title or the author’s name it will try to match
what you typed with the paper you are looking for, so that you can get the
desired paper very easily.