PAPIS(1)

NAME
papis - Papis Documentation

Papis is a command-line based document and bibliography manager. Its command-line interface (CLI) is heavily tailored after Git.

QUICK START

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 in 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 without you maybe being aware of it. Papis' configuration files are stored together inside the folder

~/.config/papis

Bear in mind that ~ means "Home Directory". Inside this directory a configuration file is found,

~/.config/papis/config

Right now we will open this file to edit 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 in your computer. We can create this library by putting inside the config file the two lines:

[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 ~/Documents/mypapers directory, self-contained.

So now 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: link. You can download this document and we are going to add it into the papers library.

Supposing that you have the document in the current directory and you have renamed the document to document.pdf, you can do the following to add this into your library:

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. Add itself has many flags, which are options for the given command. In the example above we have used the flags author and title to tell papis to use Newton as the author's name and Principia 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 following command

papis add --help

Now you are asking yourself, what happened to the pdf file? Where it is 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 folder ~/Documents/papers/. If you go now 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, info.yaml.

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

papis open

and the document should just 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 paper that you are looking for very easily.

INSTALLATION
.SS Using pip

The easiest way of installing papis is using the PyPi repositories and the package manager pip3, just open a terminal and type in

pip3 install papis

If you are on GNU/Linux like systems you might need to type sudo

sudo pip3 install papis

of if you prefer installing it locally then simply type

pip3 install --user papis

You can also update papis with pip

pip3 install --upgrade papis

  Archlinux

The package papis is also found in the archlinux repositories here.

  NixOS

If you are running NixOS or you have the nix package manager installed, you can install papis by running:

nix-env -i papis

If you like papis, just clone the repository

git clone git@github.com:papis/papis.git
cd papis

and start hacking it with:

nix-shell --expr 'with import <nixpkgs> {}; papis.overrideDerivation (drv: { src = ./.; })'

This command will provide you a shell with all the dependencies required.

  From source

First of all you have to get the code, open a terminal and hit

git clone https://github.com/alejandrogallo/papis.git

or download the zip file.

Go inside of the papis source folder and you can either use the Makefile or install it with python3.

  Using the Makefile

If you want to install it globally, just hit

sudo make install

If you want to install it locally:

make install-local

If you want to install it locally and have the development version:

make install-dev-local

And to see the available targets hit:

make help

  Using python3

The general command that you have to hit is by using the setup.py script:

python3 setup.py install

Again, if you want to install it locally because you don't have administrative rights in your computer you can just simply type

python3 setup.py install --user

If you want to develop on the code, you can also alternatively hit

python3 setup.py develop --user

WARNING: If you install the package locally, the program papis will be installed by default into your ~/.local/bin direcrtory, so that you will have to set your PATH accordingly.

One way of doing this in bash shells (Linux and the like, also Ubuntu on Windows or cygwin) is by adding the following line to your ~/.bashrc file

export PATH=$PATH:$HOME/.local/bin

  Requirements

Papis needs the following packages that are sometimes not installed with the system python3 distribution

python3-setuptools

However if you have a general enough python distribution they should be installed.

CONFIGURATION FILE

Papis uses a configuration file in INI format. You can then have several libraries which work independently from each other.

For example, maybe you want to have one library for papers and the other for some miscellaneous documents. An example for that is given below

[papers]
dir = ~/Documents/papers
[settings]
editor = vim
default-library = papers
[books]
dir = ~/Documents/books

A more complete example of a configuration file is the following

[settings]
# Open file with rifle, a nice python program
opentool = rifle
# Use gvim as a graphical editor
xeditor = gvim
# Use ranger as a file browser, too a  nice python package
file-browser = ranger
# Ask for confirmation when doing papis add ...
add-confirm = True
# Edit the info.yaml file before adding a doc into the library
# papis add --edit
add-edit = True
# Open the files before adding a document into the library
# papis add --open
add-open = True
# Define custom default match and header formats
match-format = {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}
# Define header format with colors and multiline support
header-format = <red>{doc.html_escape[title]}</red>
  <span color='#ff00ff'>  {doc.html_escape[author]}</span>
  <yellow>   ({doc.html_escape[year]})</yellow>
# Define a lib
[papers]
dir = ~/Documents/papers
# Define a lib for books
[books]
dir = ~/Documents/books
database-backend = whoosh
# Define a lib for Videos
[videos]
dir = ~/Videos/courses
# Define a lib for contacts, why not?
# To make it work you just have to define some default settings
[contacts]
dir = ~/contacts/general
database-backend = papis
mode = contact
header-format = {doc[first_name]} {doc[last_name]}
match-format = {doc[org]} {doc[first_name]} {doc[last_name]}
browse-query-format = {doc[first_name]} {doc[last_name]}
add-open = False
rofi-gui-gui-eh = 2
rofi-gui-header-format = %(header-format)s
                     {doc[tel][cell]}
tk-gui-header-format = %(rofi-gui-header-format)s
vim-gui-header-format = Title: %(header-format)s
                        Tel  : {doc[tel]}
                        Mail : {doc[email]}
                     {doc[empty]}

  Local configuration files

Papis also offers the possibility of creating local configuration files. The name of the local configuration file can be configured with the local-config-file setting.

The local configuration file can be found in the current directory of where you are issuing the papis command or in the directory of the library that you are considering in the papis command.

For instance let us suppose that you are in some project folder ~/Documents/myproject and you have a local config file there with a definition of a new library. Then whenever you are in the ~/Documents/myproject directory papis will also source the local configuration file found there.

On the other hand, also if you have a configuration file in the library folder for your papers, for instance in

~/Documents/papers/.papis.config

then everytime that you use this library also papis will source this configuration file.

  Default settings

  General

local-config-file (config-settings-local-config-file)

•   Default: .papis.config

    Name AND relative path of the local configuration file that papis will additionally read if the file is present in the current directory or in the base directory of a given library.

    This is useful for instance if you have a library somewhere for which you want special configuration settings to be set but you do not want these settings to cluster in your configuration file. It is also useful if you're sharing a library with someone else and you want them to have the same settings in that library as you. Imagine you're sharing a library of datasheets with your friend Fulano. You have your library at

    ~/Documents/lib-with-fulano

    and you've set a local configuration file there

    ~/Documents/lib-with-fulano/.papis.config

    then whenever Fulano uses that library and the file is also present, his papis program will also read the configuration settings at the path above.

dir-umask (config-settings-dir-umask)

•   Default: 493

    This is the default umask that will be used to create the new documents' directories.

use-git (config-settings-use-git)

•   Default: False

    Some commands will issue git commands if this option is set to True. For example in mv or rename.

browse-query-format (config-settings-browse-query-format)

•   Default: {doc[title]} {doc[author]}

    The query string that is to be searched for in the browse command whenever a search engine is used.

search-engine (config-settings-search-engine)

•   Default: https://duckduckgo.com

    Search engine to be used by some commands like browse.

user-agent (config-settings-user-agent)

•   Default: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)

    User agent used by papis whenever it obtains information from external servers.

scripts-short-help-regex (config-settings-scripts-short-help-regex)

•   Default: .*papis-short-help: *(.*)

    This is the format of the short help indicator in external papis commands.

info-name (config-settings-info-name)

•   Default: info.yaml

    The default name of the information files.

doc-url-key-name (config-settings-doc-url-key-name)

•   Default: doc_url

    Some documents might have associated apart from an url also a file url, the key name appearing in the information file is defined by this setting.

default-library (config-settings-default-library)

•   Default: papers

    The name of the library that is to be searched when papis is run without library arguments.

export-text-format (config-settings-export-text-format)

•   Default: {doc[author]}. {doc[title]}. {doc[journal]} {doc[pages]} {doc[month]} {doc[year]}

    The default output papis format for papis export --text.

format-doc-name (config-settings-format-doc-name)

•   Default: doc

    This setting controls the name of the document in the papis format strings like in format strings such as match-format or header-format. For instance, if you are managing videos, you might want to set this option to vid in order to set the header-format to {doc[title]} - {doc[director]} - {doc[duration]}.

match-format (config-settings-match-format)

•   Default: {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

    Default format that is used to match a document against in order to select it. For example if the match-format is equal to {doc[year]} {doc[author]} then title of a document will not work to match a document, only the year and author.

header-format (config-settings-header-format)

•

Default:

    <red>{doc.html_escape[title]}</red>
     <span color='#00ff00'>{doc.html_escape[author]}</span>
      <span color='#00ffaa'>({doc.html_escape[year]})</span> [<yellow>{doc.html_escape[tags]}</yellow>]

    Default format that is used to show a document in order to select it.

format-jinja2-enable (config-settings-format-jinja2-enable)

•   Default: False

    This setting is to enable the jinja2 template engine to render the papis templates being used, as header-format, match-format etc...

    For instance you could set the option header-format to

    <span color='#ff00ff'>{{doc.html_escape["title"]}}</span>
    <span color='#00ff00'>  {{doc.html_escape["author"]}}</span>
    <span color='#00ffaa'>   ({{doc.html_escape["year"]}}) </span>
    {%- if doc.has('tags') %}<span>[<yellow>{{doc['tags']}}</yellow>] </span>{%- endif %}
    {%- if doc.has('citations') %}<red>{{doc['citations']|length}}</red>{%- endif %}
    {%- if doc.has('url') %}
    <span>    {{doc.html_escape["url"]}}</span>
    {%- endif %}

    To use it, just install jinja2.

header-format-file (config-settings-header-format-file)

•   Default: None

    This option should have the path of a file with the header-format template. Sometimes templates can get big so this is a way of not cluttering the config file with text.

    As an example you would set

    [papers]
    header-format-file = ~/.papis/config/styles/header.txt

info-allow-unicode (config-settings-info-allow-unicode)

•   Default: True

    This flag is to be set if you want to allow unicode characters in your info file or not. If it is set to false then a representation for the unicode characters will be written in its place. Since we should be living in an unicode world, it is set to True by default.

  Tools options

opentool (config-settings-opentool)

•   Default: xdg-open

    This is the general program that will be used to open documents. As for now papis is not intended to detect the type of document to be open and decide upon it how to open the document. You should set this to the right program for the tool. If you are in linux you might want to take a look at ranger or let the default handle it in your system. For mac users you might set this to open.

browser (config-settings-browser)

•   Default: $BROWSER

    Program to be used for opening websites, the default is the environment variable $BROWSER.

picktool (config-settings-picktool)

•   Default: papis.pick

    This is the program used whenever papis asks you to pick a document or options in general.

Possible options are:

•   papis.pick

•   vim

•   dmenu

editor (config-settings-editor)

•   Default: $EDITOR

    Editor used to edit files in papis, for instance for the papis edit command. It defaults to the $EDITOR environment variable, if this is not set then it will default to the $VISUAL environment variable. Otherwise the default editor in your system will be used.

xeditor (config-settings-xeditor)

•   Default: xdg-open

    Sometimes papis might use an editor that uses a windowing system (GUI Editor), you can set this to your preferred gui based editor, e.g. gedit, xemacs, gvim to name a few.

file-browser (config-settings-file-browser)

•   Default: xdg-open

    File browser to be used when opening a directory, it defaults to the default file browser in your system, however you can set it to different file browsers such as dolphin, thunar, ranger to name a few.

  Bibtex options

bibtex-journal-key (config-settings-bibtex-journal-key)

•   Default: journal

    Journal publishers may request abbreviated journal titles. This option allows the user to set the key for the journal entry when using papis export --bibtex.

    Set as full_journal_title or abbrev_journal_title for whichever style required. Default is journal.

extra-bibtex-keys (config-settings-extra-bibtex-keys)

•   Default:
    ``
    ``

    When exporting documents in bibtex format, you might want to add non-standard bibtex keys such as doc_url or tags, you can add these here as comma separated values, for example extra-bibtex-keys = tags, doc_url.

extra-bibtex-types (config-settings-extra-bibtex-types)

•   Default:
    ``
    ``

    Allow non-standard bibtex types to be recognized, e.g, extra-bibtex-types = wikipedia, video, song. See
    `
    bibtex reference <http://mirror.easyname.at/ctan/biblio/bibtex/base/btxdoc.pdf>`_.

multiple-authors-format (config-settings-multiple-authors-format)

•   Default: {au[surname]}, {au[given_name]}

    When retrieving automatic author information from services like crossref.org, papis usually builds the author field for the given document. The format how every single author name is built is given by this setting, for instance you could customize it by the following:

    multiple-authors-format = {au[surname]} -- {au[given_name]}

    which would given in the case of Albert Einstein the string Einstein -- Albert.

multiple-authors-separator (config-settings-multiple-authors-separator)

•   Default: `` and ``

    Similarly to multiple-authors-format, this is the string that separates single authors in the author field. If it is set to `` and `` then you would have <author 1> and <author 2> and .... in the author field.

bibtex-unicode (config-settings-bibtex-unicode)

•   Default: False

    Wether or not to allow direct unicode characters in the document fields to be exported into the bibtex text.

  Add command options

ref-format (config-settings-ref-format)

•   Default: {doc[doi]}

    This flag is set to change the ref flag in the info.yaml file when a document is imported. For example: I prefer the format FirstAuthorYear e.g. Plews2019. This would be achieved by the following:

    ref-format = {doc[author_list][0][surname]}{doc[year]}

    The default behavior is to set the doi as the ref.

add-confirm (config-settings-add-confirm)

•   Default: False

    If set to True, everytime you run papis add the flag --confirm will be added automatically. If is set to True and you add it, i.e., you run papis add --confirm, then it will fave the contrary effect, i.e., it will not ask for confirmation.

add-name (config-settings-add-name)

•   Default: empty string

    Default name for the folder of newly added documents. For example, if you the folder of your documents to be named after the format author-title then you should set it to the papis format: {doc[author]}-{doc[title]}. Per default a hash followed by the author name is created.

file-name (config-settings-file-name)

•   Default: None

    Same as add-name, but for files, not folders. If it is not set, the names of the files will be cleaned and taken as-is.

add-interactive (config-settings-add-interactive)

•   Default: False

    If set to True, everytime you run papis add the flag --interactive will be added automatically. If is set to True and you add it, i.e., you run papis add --interactive, then it will fave the contrary effect, i.e., it will not run in interactive mode.

add-edit (config-settings-add-edit)

•   Default: False

    If set to True, everytime you run papis add the flag --edit will be added automatically. If is set to True and you add it, i.e., you run papis add --edit, then it will fave the contrary effect, i.e., it will not prompt to edit the info file.

add-open (config-settings-add-open)

•   Default: False

    If set to True, everytime you run papis add the flag --open will be added automatically. If is set to True and you add it, i.e., you run papis add --open, then it will fave the contrary effect, i.e., it will not open the attached files before adding the document to the library.

  Browse command options

browse-key (config-settings-browse-key)

•   Default: url

    This command provides the key that is used to generate the url. For users that papis add --from-doi, setting browse-key to doi constructs the url from dx.doi.org/DOI, providing a much more accurate url.

    Default value is set to url. If the user needs functionality with the search-engine option, set the option to an empty string e.g.

    browse-key = ''

  Edit command options

notes-name (config-settings-notes-name)

•   Default: notes.tex

    In papis edit you can edit notes about the document. notes-name is the default name of the notes file, which by default is supposed to be a TeX file.

  Marks

open-mark (config-settings-open-mark)

•   Default: False

    If this option is set to True, then every time that papis opens a document it will ask to open a mark first. If it is set to False, then doing

    papis open --mark

    will avoid opening a mark.

mark-key-name (config-settings-mark-key-name)

•   Default: marks

    This is the default key name for the marks in the info file, for example if you set mark-key-name = bookmarks then you would have in your info.yaml file

    author: J. Krishnamurti
    bookmarks:
    - name: Chapter 1
      value: 120

mark-format-name (config-settings-mark-format-name)

•   Default: mark

    This is the name of the mark to be passed to the options mark-header-format etc... E.g. if you set mark-format-name = m then you could set mark-header-format = {m[value]} - {m[name]}.

mark-header-format (config-settings-mark-header-format)

•   Default: {mark[name]} - {mark[value]}

    This is the format in which the mark will appear whenever the user has to pick one, you can change this in order to make marks work in the way you like. Per default it is assumed that every mark has a name and a value key, but this you can change.

mark-match-format (config-settings-mark-match-format)

•   Default: {mark[name]} - {mark[value]}

    Format in which the mark name has to match the user input.

mark-opener-format (config-settings-mark-opener-format)

•   Default: xdg-open

    Due to the difficulty to generalize opening a general document at a given bookmark, the user should set this in whichever way it suits their needs. For example

•   If you are using the pdf viewer evince and you want to open a mark, you would use

    mark-opener-format = evince -p {mark[value]}

•   If you are using okular you would use

    mark-opener-format = okular -p {mark[value]}

•   If you are using zathura, do

    mark-opener-format = zathura -P {mark[value]}

  Downloaders

downloader-proxy (config-settings-downloader-proxy)

•   Default: None

    There is the possibility of download papers using a proxy. To know more you can checkout this link.

  Databases

default-query-string (config-settings-default-query-string)

•   Default: .

    This is the default query that a command will take if no query string is typed in the command line. For example this is the query that is passed to the command open whenever no search string is typed:

    papis open

    Imagine you want to have all your papers whenever you do not specify an input query string, then you would set

    default-query-string = author="John Smith"

    and whenever you typed papis open, onlye the John Smith authored papers would appear. Notice that the current example has been done assuming the database-backend = papis.

database-backend (config-settings-database-backend)

•   Default: papis

    The backend to use in the database. As for now papis supports the own database system papis and whoosh.

use-cache (config-settings-use-cache)

•   Default: True

    Set to False if you do not want to use the cache for the given library. This is only effective if you're using the papis database-backend.

cache-dir (config-settings-cache-dir)

•   Default: None

whoosh-schema-fields (config-settings-whoosh-schema-fields)

•   Default: ['doi']

    Python list with the TEXT fields that should be included in the whoosh database schema. For instance say that you want to be able to search for the doi and ref of the documents, then you could include

    whoosh-schema-fields = ['doi', 'ref']

whoosh-schema-prototype (config-settings-whoosh-schema-prototype)

•

Default:

    {
    "author": TEXT(stored=True),
    "title": TEXT(stored=True),
    "year": TEXT(stored=True),
    "tags": TEXT(stored=True),
    }

    This is the model for the whoosh schema, check the documentation for more information.

  Other

citation-string (config-settings-citation-string)

•   Default: *

    string that can be displayed in header if the reference has a citation

    Default set to '*'

unique-document-keys (config-settings-unique-document-keys)

•   Default: ['doi','ref','isbn','isbn10','url','doc_url']

    Whenever you add a new document, papis tries to figure out if you have already added this document before. This is partially done checking for some special keys, and checking if they match. Which keys are checked against is decided by this option, which should be formatted as a python list, just as in the default value.

    For instance, if you add a paper with a given doi, and then you add another document with the same doi, then papis will notify you that there is already another document with this doi because the doi key is part of the unique-document-keys option.

  Vim gui

help-key (config-vim-gui-help-key)

•   Default: h

open-key (config-vim-gui-open-key)

•   Default: o

edit-key (config-vim-gui-edit-key)

•   Default: e

search-key (config-vim-gui-search-key)

•   Default: /

delete-key (config-vim-gui-delete-key)

•   Default: dd

open-dir-key (config-vim-gui-open-dir-key)

•   Default: <S-o>

next-search-key (config-vim-gui-next-search-key)

•   Default: n

prev-search-key (config-vim-gui-prev-search-key)

•   Default: N

header-format (config-vim-gui-header-format)

•

Default:

    Title : {doc[title]}
    Author: {doc[author]}
    Year  : {doc[year]}
    -------

  dmenu gui

See dmenu and the python wrapper here for more information. You will need to install the latter to make use of this function,

pip3 install dmenu

lines (config-dmenu-gui-lines)

•   Default: 20

case_insensitive (config-dmenu-gui-case_insensitive)

•   Default: True

bottom (config-dmenu-gui-bottom)

•   Default: True

font (config-dmenu-gui-font)

•   Default: monospace-14

background (config-dmenu-gui-background)

•   Default: #000000

foreground (config-dmenu-gui-foreground)

•   Default: #55ff55

background_selected (config-dmenu-gui-background_selected)

•   Default: #005500

foreground_selected (config-dmenu-gui-foreground_selected)

•   Default: #f0f0f0

header-format (config-dmenu-gui-header-format)

•   Default: None

    This is not set per default, and it will default to the general header-format if not set.

THE INFO.YAML FILE

At the heart of papis there is the information file. The info file contains all information about the documents.

It uses the yaml syntax to store information, which is a very human readable language. It is quite format free, papis does not assume that any special information should be there.

If you are storing papers with papis, then you most probably would like to store author and title in there,

author: Isaac Newton
title: Opticks, or a treatise of the reflections refractions, inflections and
  colours of light
files:
  - document.pdf

THE LIBRARY STRUCTURE

One of the things that makes papis interesting is the fact that its library structure is nearly nonexistent.

A papis library is linked to a directory, where all the documents are (and possibly sublibraries). What papis does is simply to go to the library folder and look for all subfolders that contain a information file, which by default is a info.yaml file.

Every subfolder that has an info.yaml file in it is a valid papis document. As an example let us consider the following library

/home/fulano/Documents/papers/
├── folder1
│   └── paper.pdf
├── folder2
│   ├── folder3
│   │   ├── info.yaml
│   │   └── blahblahblah.pdf
│   └── folder4
│       ├── info.yaml
│       └── output.pdf
├── classics
│   └── folder5
│       ├── info.yaml
│       └── output.pdf
├── physics
│   └── newton
│       └── principia
│           ├── document.pdf
│           ├── supplements.pdf
│           └── info.yaml
└─── rpa
    └── bohm
        ├── info.yaml
        ├── notes.tex
        └── output.pdf

The first thing that you might notice is that there are really many folders of course. Just to check that you undeerstand exactly what is a document, just please think about which of these pdfs is not a valid papis document... That's right!, folder1/paper.pdf is not a valid document since the folder1 does not contain any info.yaml file. You see also that it does not matter how deep the folder structure is, you can have in your library a physics folder, where you have a newton folder, where also you have a folder containing the actual book document.pdf plus some supplementary information supplements.pdf. In this case inside the info.yaml you would have the following file section

files:
- document.pdf
- supplements.pdf

so that you are telling papis that in this folder there are two relevant files.

THE DATABASE

One of the things that makes papis interesting is the fact that there can be many backends for the database system, including no database.

Right now there are three types of database in that the user can use:

•   No database

•   Simple cache based database

•   Whoosh based database.

    If you just plan to have or have few dozen of documents in your library, probably you'll have ample performance with the two first options. However if you're reaching higher numbers, 500, 1000, 2000 documents, you'll probably want to use the Whoosh backend for very good performance.

    You can select the databases using the flag database-backend.

  Papis database

The fact that there is no database means that papis should crawl through the library folder and see which folders have an info.yaml file, which is for slow computers quite bad.

Papis implements a very rudimentary caching system. A cache is created for every library. Inside the cache only the paths to the different valid papis documents are stored.

These cache files are stored per default in

~/.cache/papis/

Some papis commands update the cache automatically, for example the add and rm command clear the cache when something is changed.

  Clearing the cache

To clear the cache for a given library you can use the flag --clear-cache, e.g.

papis --clear-cache

  Query language

Since version 0.3 there is a query language in place for the searching of documents. The queries can contain any field of the info file, i.e., author=einstein publisher = review will match documents that have a matching author with einstein AND having a publisher matching review. The AND part here is important, since only the AND filter is implemented in this simple query language, at the moment it is not possible to do an OR. If you need this, you should consider using the Whoosh database.

To illustrate it here are some examples:

•   Open documents where the author key matches 'albert' (ignoring case), year matches '19' (i.e., 1990, 2019, 1920):

    papis open 'author = albert year = 05'

•   Add the restriction to the previous search that the usual matching matches the substring 'licht' in addition to the previously selected

    papis open 'author = albert year = 05 licht'

    This is not to be mixed with the restriction that the key year matches '05 licht', which will not match any year, i.e.

    papis open 'author = albert year = "05 licht"'

  Disabling the cache

You can disable the cache using the configuration setting use-cache and set it to False, e.g.

[settings]
use-cache = False
[books]
# Use cache for books but don't use for the rest of libraries
use-cache = True

  Whoosh database

Papis has also the possibility to use the blazing fast and pure python Whoosh library. Its performance is orders of magnitude better than the crude cache based database.

Of course, the performance comes at a cost. To achieve more performance a database backend should create an index with information about the documents. Parsing a user query means going to the index and matching the query to what is found in the index. This means that the index can not in general have all the information that the info file of the documents includes.

In other words, the whoosh index will store only certain fields from the document's info files. The good news is that we can tell papis exactly which fields we want to index. These flags are

•   whoosh-schema-fields

•   whoosh-schema-prototype

    The prototype is for advanced users. If you just want to say, include the publisher to the fields that you can search in, then you can put

    whoosh-schema-fields = ['publisher']

    and you will be able to find documents by their publisher. For example, without this line set for publisher, the query

    papis open publisher:*

    will not return anything, since the publisher field is not being stored.

  Query language

The whoosh database uses the whoosh query language which is much more advanced than the query language in the Papis database.

The whoosh query language supports both AND and OR, for instance

papis open '(author:einstein AND year:1905) OR title:einstein'

will give papers of einstein in the year 1905 together with all papers where einstein appears in the title.

You can read more about the whoosh query language here.

COMMANDS

  Add

The add command is one of the central commands of the papis command line interface. It is a very versatile command with a fair amount of options.

There are also customization settings availabe for this command, check out the configuration page for add.

  Examples

•   Add a document located in ~/Documents/interesting.pdf and name the folder where it will be stored in the database interesting-paper-2021

    papis add ~/Documents/interesting.pdf --name interesting-paper-2021

    if you want to add directly some key values, like author, title and tags, you can also run the following:

    papis add ~/Documents/interesting.pdf \
        --name interesting-paper-2021 \
        --set author 'John Smith' \
        --set title 'The interesting life of bees' \
        --set year 1985 \
        --set tags 'biology interesting bees'

•   Add a paper that you have locally in a file and get the paper information through its doi identifier (in this case 10.10763/1.3237134 as an example):

    papis add ~/Documents/interesting.pdf --from-doi 10.10763/1.3237134

•   Add paper to a library named machine-learning from arxiv.org

    papis -l machine-learning add \
        --from-url https://arxiv.org/abs/1712.03134

•   If you do not want copy the original pdfs into the library, you can also tell papis to just create a link to them, for example

    papis add --link ~/Documents/interesting.pdf \
        --from-doi 10.10763/1.3237134

    will add an entry into the papis library, but the pdf document will remain at ~/Documents/interesting.pdf, and in the document's folder there will be a link to ~/Documents/interesting.pdf instead of the file itself. Of course you always have to be sure that the document at ~/Documents/interesting.pdf does not disappear, otherwise you will end up without a document to open.

  Examples in python

There is a python function in the add module that can be used to interact in a more effective way in python scripts,

papis.commands.add.run(paths, data={}, name=None, file_name=None, subfolder=None, interactive=False, confirm=False, open_file=False, edit=False, commit=False, link=False)

Parameters

•   paths ([]) -- Paths to the documents to be added

•   data (dict) -- Data for the document to be added. If more data is to be retrieved from other sources, the data dictionary will be updated from these sources.

•   name (str) -- Name of the folder where the document will be stored

•   file_name (str) -- File name of the document's files to be stored.

•   subfolder (str) -- Folder within the library where the document's folder should be stored.

•   interactive (bool) -- Wether or not interactive functionality of this command should be activated.

•   confirm (bool) -- Wether or not to ask user for confirmation before adding.

•   open_file (bool) -- Wether or not to ask user for opening file before adding.

•   edit (bool) -- Wether or not to ask user for editing the infor file before adding.

•   commit (bool) -- Wether or not to ask user for committing before adding, in the case of course that the library is a git repository.

  Cli

  papis add

Add a document into a given library

papis add [OPTIONS] [FILES]...
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-s, --set <set_list>
    Set some information before

-d, --dir <directory>
    Subfolder in the library

-i, --interactive, --no-interactive
    Do some of the actions interactively

--name <name>
    Name for the document's folder (papis format)

--file-name <file_name>
    File name for the document (papis format)

--from-bibtex <from_bibtex>
    Parse information from a bibtex file

--from-yaml <from_yaml>
    Parse information from a yaml file

--from-folder <from_folder>
    Add document from folder being a valid papis document (containing info.yaml)

--from-url <from_url>
    Get document and information from agiven url, a parser must be implemented

--from-doi <from_doi>
    Doi to try to get information from

--from-pmid <from_pmid>
    PMID to try to get information from

--from-lib <from_lib>
    Add document from another library

--confirm, --no-confirm
    Ask to confirm before adding to the collection

--open, --no-open
    Open file before adding document

--edit, --no-edit
    Edit info file before adding document

--commit, --no-commit
    Commit document if library is a git repository

--link, --no-link
    Instead of copying the file to the library, create a link toits original location

--no-document
    DEPRECATION NOTICE: This option is no longer valid, it will be removed in future releases Arguments.INDENT 0.0

FILES
    Optional argument(s)

  Addto

This command adds files to existing papis documents in some library.

For instance imagine you have two pdf files, a.pdf and b.pdf that you want to add to a document that matches with the query string einstein photon definition, then you would use

papis addto 'einstein photon definition' -f a.pdf -f b.pdf

notice that we repeat two times the flag -f, this is important.

  Cli

  papis addto

Add files to an existing document

papis addto [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-f, --files <files>
    File fullpaths to documents

--file-name <file_name>
    File name for the document (papis format) Arguments.INDENT 0.0

QUERY
    Optional argument

  Browse

This command will try its best to find a source in the internet for the document at hand.

Of course if the document has an url key in its info file, it will use this url to open it in a browser. Also if it has a doc_url key, or a doi, it will try to compose urls out of these to open it.

If none of the above work, then it will try to use a search engine with the document's information (using the browse-query-format). You can select wich search engine you want to use using the search-engine setting.

  Cli

  papis browse

Open document's url in a browser

papis browse [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-k, --key <key>
    Use the value of the document's key to open in the browser, e.g.doi, url, doc_url ... Arguments.INDENT 0.0

QUERY
    Optional argument

  Config

The command config is a useful command because it allows you to check the configuration settings' values that your current papis session is using.

For example let's say that you want to see which dir setting your current library is using (i.e., the directory or the dir that appears in the definition of the library in the configuration file), then you would simply do:

papis config dir

If you wanted to see which dir the library books has, for example then you would do

papis -l books config dir

This works as well for default settings, i.e., settings that you have not customized, for example the setting match-format, you would check it with

papis config match-format
> {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

You can find a list of all available settings in the configuration section.

  Cli

  papis config

Print configuration values

papis config [OPTIONS] OPTION
Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

OPTION
    Required argument

  Main

  Examples

•   To override some configuration options, you can use the flag --set, for instance, if you want to override the editor used and the opentool to open documents, you can just type

    papis --set editor gedit --set opentool firefox edit
    papis --set editor gedit --set opentool firefox open

•   If you want to list the libraries and pick one before sending a database query to papis, use --pick-lib as such

    papis --pick-lib open 'einstein relativity'

  Cli

  papis

papis [OPTIONS] COMMAND [ARGS]...
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--version
    Show the version and exit.

-v, --verbose
    Make the output verbose (equivalent to --log DEBUG)

-l, --lib <lib>
    Choose a library name or library path (unamed library)

-c, --config <config>
    Configuration file to use

--log <log>
    Logging level

--pick-lib
    Pick library to use

--cc, --clear-cache
    Clear cache of the library used

-s, --set <set_list>
    Set key value, e.g., --set info-name information.yaml --set opentool evince

  Edit

This command edits the information of the documents. The editor used is defined by the editor configuration setting.

  Cli

  papis edit

Edit document information from a given library

papis edit [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-n, --notes
    Edit notes associated to the document

--all
    Edit all matching documents

-e, --editor <editor>
    Editor to be used Arguments.INDENT 0.0

QUERY
    Optional argument

  Explore

This command is in an experimental stage but it might be useful for many people.

Imagine you want to search for some papers online, but you don't want to go into a browser and look for it. Explore gives you way to do this, using several services available online, more should be coming on the way.

An excellent such resource is crossref, which you can use by using the subcommand crossref:

papis explore crossref --author 'Freeman Dyson'

If you issue this command, you will see some text but basically nothing will happen. This is because explore is conceived in such a way as to concatenate commands, doing a simple

papis explore crossref -h

will tell you which commands are available. Let us suppose that you want to look for some documents on crossref, say some papers of Schroedinger, and you want to store them into a bibtex file called lib.bib, then you could concatenate the commands crossref and export --bibtex as such

papis explore crossref -a 'Schrodinger' export --bibtex lib.bib

This will store everything that you got from crossref in the file lib.bib and store in bibtex format. explore is much more flexible than that, you can also pick just one document to store, for instance let's assume that you don't want to store all retrieved documents but only one that you pick, the pick command will take care of it

papis explore crossref -a 'Schrodinger' pick export --bibtex lib.bib

notice how the pick command is situated before the export. More generally you could write something like

papis explore \
    crossref -a Schroedinger \
    crossref -a Einstein \
    arxiv -a 'Felix Hummel' \
    export --yaml docs.yaml \
    pick  \
    export --bibtex specially-picked-document.bib

The upper command will look in crossref for documents authored by Schrodinger, then also by Einstein, and will look on the arxiv for papers authored by Felix Hummel. At the end, all these documents will be stored in the docs.yaml. After that we pick one document from them and store the information in the file specially-picked-document.bib, and we could go on and on.

If you want to follow-up on these documents and get them again to pick one, you could use the yaml command to read in document information from a yaml file, i.e., the previously created docs.yaml

papis explore \
    yaml docs.yaml \
    pick \
    cmd 'papis scihub {doc[doi]}' \
    cmd 'firefox {doc[url]}'

In this last example, we read the documents' information from docs.yaml and pick a document, which then feed into the explore cmd command, that accepts a papis formatting string to issue a general shell command. In this case, the picked document gets fed into the papis scihub command which tries to download the document using scihub, and also this very document is tried to be opened by firefox (in case the document does have a url).

  Cli

  papis explore

Explore new documents using a variety of resources

papis explore [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
Options.INDENT 0.0

-h, --help
    Show this message and exit.

  arxiv

Look for documents on ArXiV.org.

Examples of its usage are papis explore arxiv -a 'Hummel' -m 100 arxiv -a 'Garnet Chan' pick

If you want to search for the exact author name 'John Smith', you should enclose it in extra quotes, as in the example below papis explore arxiv -a '"John Smith"' pick

papis explore arxiv [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-q, --query <query>

-a, --author <author>

-t, --title <title>

--abstract <abstract>

--comment <comment>

--journal <journal>

--report-number <report_number>

--category <category>

--id-list <id_list>

--page <page>

-m, --max <max>

  bibtex

Import documents from a bibtex file

Examples of its usage are

papis explore bibtex lib.bib pick

papis explore bibtex [OPTIONS] BIBFILE
Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

BIBFILE
    Required argument

  citations

Query the citations of a paper

Example:

Go through the citations of a paper and export it in a yaml file papis explore citations 'einstein' export --yaml einstein.yaml

papis explore citations [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-s, --save
    Store the citations in the document's folder for later use

--rmfile
    Remove the stored citations file

-m, --max-citations <max_citations>
    Number of citations to be retrieved Arguments.INDENT 0.0

QUERY
    Optional argument

  cmd

Import documents based on a yaml file

Examples of its usage are:

Look for 200 Schroedinger papers, pick one, and add it via papis-scihub

papis explore crossref -m 200 -a 'Schrodinger'
    pick cmd 'papis scihub {doc[doi]}'

    papis explore cmd [OPTIONS] COMMAND
    Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

COMMAND
    Required argument

  crossref

Look for documents on crossref.org.

Examples of its usage are

papis explore crossref -a 'Albert einstein' pick export --bibtex lib.bib

papis explore crossref [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-q, --query <query>

-a, --author <author>

-t, --title <title>

-m, --max <max>

  dissemin

Look for documents on dissem.in

Examples of its usage are

papis explore dissemin -q 'Albert einstein' pick cmd 'firefox {doc[url]}'

papis explore dissemin [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-q, --query <query>

  export

Export retrieved documents into various formats for later use

Examples of its usage are

papis explore crossref -m 200 -a 'Schrodinger' export --yaml lib.yaml

papis explore export [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--bibtex <bibtex>
    Export list of documents retrieved to a bibtex file

--yaml <yaml>
    Export list of documents retrieved to a yaml file

--json <json>
    Export list of documents retrieved to a json file

  isbn

Look for documents using isbnlib

Examples of its usage are

papis explore isbn -q 'Albert einstein' pick cmd 'firefox {doc[url]}'

papis explore isbn [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-q, --query <query>

-s, --service <service>

  isbnplus

Look for documents on isbnplus.com

Examples of its usage are

papis explore isbnplus -q 'Albert einstein' pick cmd 'firefox {doc[url]}'

papis explore isbnplus [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-q, --query <query>

-a, --author <author>

-t, --title <title>

  json

Import documents from a json file

Examples of its usage are

papis explore json lib.json pick

papis explore json [OPTIONS] JSONFILE
Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

JSONFILE
    Required argument

  lib

Query for documents in your library

Examples of its usage are papis lib -l books einstein pick

papis explore lib [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-l, --library <library>
    Papis library to look Arguments.INDENT 0.0

QUERY
    Optional argument

  libgen

Look for documents on library genesis

Examples of its usage are

papis explore libgen -a 'Albert einstein' export --yaml einstein.yaml

papis explore libgen [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-a, --author <author>

-t, --title <title>

-i, --isbn <isbn>

  pick

Pick a document from the retrieved documents

Examples of its usage are

papis explore bibtex lib.bib pick

papis explore pick [OPTIONS]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-n, --number <number>
    Pick automatically the n-th document

  yaml

Import documents from a yaml file

Examples of its usage are

papis explore yaml lib.yaml pick

papis explore yaml [OPTIONS] YAMLFILE
Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

YAMLFILE
    Required argument

  Export

The export command is useful to work with other programs such as bibtex.

Some examples of its usage are:

•   Export one of the documents matching the author with einstein to bibtex:

    papis export --bibtex 'author = einstein'

    or export all of them

    papis export --bibtex --all 'author = einstein'

•   Export all documents to bibtex and save them into a lib.bib file

    papis export --all --bibtex --out lib.bib

•   Export a folder of one of the documents matching the word krebs into a folder named, interesting-document

      papis export --folder --out interesting-document krebs
    this will create the folder ``interesting-document`` containing the
    ``info.yaml`` file, the linked documents and a ``bibtex`` file for
    sharing with other people.
    You can also just export its associated document:

    papis export --file krebs

  Cli

  papis export

Export a document from a given library

papis export [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--yaml
    Export into yaml

--bibtex
    Export into bibtex

--json
    Export into json

--folder
    Export document folder to share

-o, --out <out>
    Outfile or outdir

-t, --text
    Text formated reference

-a, --all
    Export all without picking

--file
    Export a copy of a file Arguments.INDENT 0.0

QUERY
    Optional argument

  Git

This command is useful if your library is itself a git repository. You can use this command to issue git commands in your library repository without having to change your current directory.

  CLI Examples

•   Check the status of the library repository:

    papis git status

•   Commit all changes:

    papis git commit -a

  List

This command is to list contents of a library.

  CLI Examples

•   List all document files associated will all entries:

    papis list --file

•   List all document year and title with custom formatting:

    papis list --format '{doc[year]} {doc[title]}'

•   List all documents according to the bibitem formatting (stored in a template file bibitem.template):

    papis list --template bibitem.template

  Python examples

# Import the run function from the list command
from papis.commands.list import run as papis_list
documents = papis_list(query='einstein', library='papis')
for doc in documents:
    print(doc["url"])
# etc...
info_files = list(query='einstein', library='papis', info_files=True)
# do something with the info file paths...

  Cli

  papis list

List documents' properties

papis list [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-i, --info
    Show the info file name associated with the document

-f, --file
    Show the file name associated with the document

-d, --dir
    Show the folder name associated with the document

--format <format>
    List entries using a custom papis format, e.g. '{doc[year] {doc[title]}

--template <template>
    Template file containing a papis format to list entries

-p, --pick
    Pick the document instead of listing everything

--downloaders
    List available downloaders

--libraries
    List defined libraries Arguments.INDENT 0.0

QUERY
    Optional argument

  Mv

  Cli

  papis mv

Move a document into some other path

papis mv [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--git, --no-git
    Add git interoperability Arguments.INDENT 0.0

QUERY
    Optional argument

  Open

The open command is a very important command in the papis workflow. With it you can open documents, folders or marks.

  Marks

One of special things about this command is the possibility of creating marks for documents. As you would imagine, it is in general difficult to create marks for any kind of data. For instance, if our library consists of pdf files and epub files for instance, we would like to define bookmarks in order to go back to them at some later point.

How you define marks can be customized through the marks configuration settings here. The default way of doing it is just by defining a marks list in a document. Let us look at a concrete example:

author: Isaiah Shavitt, Rodney J. Bartlett
edition: '1'
files: [book.pdf]
isbn: 052181832X,9780521818322
marks:
- {name: Intermediates definition, value: 344}
- {name: EOM equations, value: 455}
publisher: Cambridge University Press
ref: book:293288
series: Cambridge Molecular Science
title: 'Many-Body Methods in Chemistry and Physics'
type: book
year: '2009'

This book has defined two marks. Each mark has a name and a value. If you tell the open command to open marks, then it will look for the marks and open the value (page number). This is the default behaviour, however if you go to the configuration you'll see that you can change the convention to what it suits you.

  Examples

•   Open a pdf file linked to a document matching the string bohm

    papis open bohm

•   Open the folder where this last document is stored

    papis open -d bohm

    Please notice that the file browser used will be also related to the file-browser setting.

•   Open a mark defined in the info file

    papis open --mark bohm

  Cli

  papis open

Open document from a given library

papis open [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--tool <tool>
    Tool for opening the file (opentool)

-d, --dir
    Open directory

--all
    Open all matching documents

-m, --mark, --no-mark
    Open mark Arguments.INDENT 0.0

QUERY
    Optional argument

  Rename

  Cli

  papis rename

Rename entry

papis rename [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--git, --no-git
    Add git interoperability Arguments.INDENT 0.0

QUERY
    Optional argument

  Rm

  Cli

  papis rm

Delete command for several objects

papis rm [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

--file
    Remove files from a document instead of the whole folder

-f, --force
    Do not confirm removal Arguments.INDENT 0.0

QUERY
    Optional argument

  Run

This command is useful to issue commands in the directory of your library.

  CLI Examples

•   List files in your directory

    papis run ls

•   Find a file in your directory using the find command

    papis run find -name 'document.pdf'

  Python examples

  Cli

  papis run

Run an arbitrary shell command in the library folder

papis run [OPTIONS] [RUN_COMMAND]...
Options.INDENT 0.0

-h, --help
    Show this message and exit. Arguments.INDENT 0.0

RUN_COMMAND
    Optional argument(s)

  Update

This command is to update the information of the documents. Some examples of the usage are given below

  Examples

•   Update a document automatically and interactively (searching by doi number in crossref, or in other sources...)

    papis update --auto -i "author = dyson"

•   Update your library from a bib(la)tex file where many entries are listed. papis will try to look for documents in your library that match these entries and will ask you entry per entry to update it (of course this is done if you use the -i flag for interactively doing it). In the example libraryfile.bib is a file containing many entries.

    papis update --from-bibtex libraryfile.bib -i

•   Tag all einstein papers with the tag classics

    papis update --all --set tags classics einstein

    and add the tag of physics to all papers tagged as classics

    papis update --all --set tags '{doc[tags]} physics' einstein

  Cli

  papis update

Update a document from a given library

papis update [OPTIONS] [QUERY]
Options.INDENT 0.0

-h, --help
    Show this message and exit.

-i, --interactive, -b, --no-interactive
    Interactively update

-f, --force
    Force update, overwrite conflicting information

--from-crossref <from_crossref>
    Update info from crossref.org

--from-isbn <from_isbn>
    Update info from isbn

--from-isbnplus <from_isbnplus>
    Update info from isbnplus.org

--from-yaml <from_yaml>
    Update info from yaml file

--from-bibtex <from_bibtex>
    Update info from bibtex file

--from-url <from_url>
    Get document or information from url

--from-doi <from_doi>
    Doi to try to get information from

--auto
    Try to parse information from different sources

--all
    Update all entries in library

-s, --set <set>
    Update document's information with key value.The value can be a papis format. Arguments.INDENT 0.0

QUERY
    Optional argument

CUSTOM SCRIPTS

As in git, you can write custom scripts to include them in the command spectrum of papis.

  Example: Mail script

Imagine you want to write a script to send papers to someone via the email client mutt (you can try to do it with another mail client), you could write the following script called papis-mail:

#! /usr/bin/env bash
# papis-short-help: Email a paper to my friend
folder_name=$1
zip_name="${folder_name}.zip"
papis -l ${PAPIS_LIB} export --folder --out ${folder_name}
zip -r ${zip_name} ${folder_name}
mutt -a ${zip_name}

Papis defines environment variables such as PAPIS_LIB so that external scripts can make use of the user input.

To use the script you can put it somewhere in your PATH or alternatively inside the ~/.papis/scripts folder. If this is the case then you can run

papis -h

and you will see that there is another command besides the default called mail. You will see in fact

positional arguments:
  command               For further information for every command, type in 'papis <command> -h'
    add                 Add a document into a given library
    .............       ..........................
    mail                Email a paper to my friend
optional arguments:
  -h, --help            show this help message and exit
  ... .........         .... ... ...... ....... ........... .. ..... ......

where the description Email a paper to my friend is there because we have defined the comment # papis-short-help: Email a paper to my friend in the header of the script.

Then if you type

papis -l mylib mail this_paper

this will create a folder called this_paper with a selection of a document, zip it, and send it to whoever you choose to.

  Example: Accessing papis from within mutt

You may want to pick documents to attach to your email in mutt from the papis interface.

Add this code to your muttrc

# # macro to attach paper from papis
macro attach,compose \cp \
"\
<enter-command>unset wait_key<enter>\                        # Don't require 'press any key'
<shell-escape>rm -f /tmp/paper.pdf<enter>\                   # remove the file /tmp/paper.pdf if it already exists
<shell-escape>papis export --file -o /tmp/paper.pdf<enter>\  # start papis with the --file flag
<attach-file>/tmp/paper.pdf<enter>\                          # attach the new file created by papis
"

Try it out with Ctrl-p on your Compose screen. This makes use of the papis export --file flag that moves the paper you choose to a temporary location (/tmp/paper.pdf). Mutt will then attach the paper to the email, which you can rename to be more descriptive with R.

  Example: Define papis mode in i3wm

This is an example of using papis with the window manager i3.

# Enter papis mode
bindsym $mod+Ctrl+p mode "papis"
# Define papis mode
mode "papis" {
  # open documents
  bindsym $mod+o exec python3 -m papis.main \
    --pick-lib --set picktool dmenu open
  # edit documents
  bindsym $mod+e exec python3 -m papis.main \
    --pick-lib --set picktool dmenu --set editor gvim edit
  # open document's url
  bindsym $mod+b exec python3 -m papis.main \
    --pick-lib --set picktool dmenu browse
  # return to default mode
  bindsym Ctrl+c mode "default"
  bindsym Return mode "default"
  bindsym Escape mode "default"
}

API

This module describes which functions are intended to be used by users to create papis scripts.

papis.api.clear_lib_cache(lib=None)
    Clear cache associated with a library. If no library is given then the current library is used.

Parameters
    lib (str) -- Library name.

    >>> clear_lib_cache()

papis.api.edit_file(file_path, wait=True)
    Edit file using the editor key value as a program to handle file_path.

Parameters

•   file_path (str) -- File path to be handled.

•   wait (bool) -- Wait for the completion of the opener program to continue

papis.api.get_all_documents_in_lib(library=None)
    Get ALL documents contained in the given library with possibly.

Parameters
    library (str) -- Library name.

Returns
    List of all documents.

Return type
    list

    >>> import tempfile
    >>> folder = tempfile.mkdtemp()
    >>> set_lib(folder)
    >>> docs = get_all_documents_in_lib(folder)
    >>> len(docs)
    0

papis.api.get_documents_in_dir(directory, search='')
    Get documents contained in the given folder with possibly a search string.

Parameters

•   directory (str) -- Folder path.

•   search (str) -- Search string

Returns
    List of filtered documents.

Return type
    list

    >>> import tempfile
    >>> docs = get_documents_in_dir(tempfile.mkdtemp())
    >>> len(docs)
    0

papis.api.get_documents_in_lib(library=None, search='')
    Get documents contained in the given library with possibly a search string.

Parameters

•   library (str) -- Library name.

•   search (str) -- Search string

Returns
    List of filtered documents.

Return type
    list

papis.api.get_lib()
    Get current library, it either retrieves the library from the environment PAPIS_LIB variable or from the command line args passed by the user.

Returns
    Library name

Return type
    str

    >>> get_lib() is not None
    True

papis.api.get_libraries()
    Get all libraries declared in the configuration. A library is discovered if the dir key defined in the library section.

Returns
    List of library names

Return type
    list

    >>> len(get_libraries()) >= 1
    True

papis.api.open_dir(dir_path, wait=True)
    Open dir using the file-browser key value as a program to open dir_path.

Parameters

•   dir_path (str) -- Folder path to be handled.

•   wait (bool) -- Wait for the completion of the opener program to continue

papis.api.open_file(file_path, wait=True)
    Open file using the opentool key value as a program to handle file_path.

Parameters

•   file_path (str) -- File path to be handled.

•   wait (bool) -- Wait for the completion of the opener program to continue

papis.api.pick(options: list, pick_config={})
    This is a wrapper for the various pickers that are supported. Depending on the configuration different selectors or 'pickers' are used.

Parameters

•   options (list) -- List of different objects. The type of the objects within the list must be supported by the pickers. This is the reason why this function is difficult to generalize for external picker programs.

•   pick_config (dict) -- Dictionary with additional configuration for the used picker. This depends on the picker.

Returns
    Returns elements of options.

Return type
    Element(s) of options

    >>> papis.config.set('picktool', 'papis.pick')
    >>> pick(['something'])
    'something'
    >>> papis.config.set('picktool', 'nonexistent')
    >>> pick(['something'])
    Traceback (most recent call last):
    ...
    Exception: I don't know how to use the picker 'nonexistent'
    >>> papis.config.set('picktool', 'papis.pick')

papis.api.pick_doc(documents: list)
    Pick a document from documents with the correct formatting

Documents
    List of documents

Returns
    Document

    >>> from papis.document import from_data
    >>> doc = from_data({'title': 'Hello World'})
    >>> pick_doc([doc]).dump()
    'title:   Hello World\n'

papis.api.set_lib(library)
    Set current library, it either sets the library in the environment PAPIS_LIB variable or in the command line args passed by the user.

Parameters
    library (str) -- Name of library or path to a given library

GIT

Papis is conceived to work well with the tool git, this would also work with mercurial or subversion.

Here you will find a description of a possible workflow using git with papis. This is not the only workflow, but it is the most obvious.

Let's say you have a library named books in the directory ~/Documents/MyNiceBooks. You could turn the books library into a git repository, just doing for example

papis -l books run git init

or just going to the library directory and running the command there:

cd ~/Documents/MyNiceBooks
git init

Now you can add everything you have in the library with git add . if you are in the library's directory or

papis -l books git add .

if you want to do it using the papis' git command.

  Interplay with other commands

Some papis commands give you the opportunity of using git to manage changes. For instance if you are adding a new document, you could use the --commit flag to also add a commit into your library, so if you do

papis add --set author "Pedrito" --set title "Super book" book.pdf --commit

then also papis will do an automatic commit for the book, so that you can push your library afterwards to a remote repository.

You can imagine that papis command like rename and mv should also offer such functionality, and they indeed do through the --git flag. Go to their documentation for more information.

  Updating the libray

You can use the papis' simple git wrapper,

papis git pull

  Usual workflow

Usually the workflow is like this:

When adding a document that you know for sure you want in your library:

•   Add the document and commit it, either by git add --commit or committing the document after adding it to the library.

•   Pull changes from the remote library, maybe you pushed something at work (reference changes etc..) and you do not have it yet there, you would do something like

    papis git pull

•   Push what you just added

    papis git push

•   Review the status of the library

    papis git status

    When editing a document's info file:

•   Edit the file and then take a look at the diff maybe

    papis git diff

•   Add the changes

    papis git add -a

•   Commit

    papis git commit

•   Pull/push:

    papis git pull
    papis git push

    Of course these workflows are just very basic examples, you can imagine that your workflow would look completely different.

SCIHUB SUPPORT

Papis has a script that uses the scihub platform to download scientific papers. Due to legal caution the script is not included directly as a papis command, and it has its own PyPi repository.

To install it, just type

pip3 install papis-scihub

Now you can type

papis scihub -h

and see the help message of the script.

Some usage examples are:

•   Download via the doi number:

    papis scihub 10.1002/andp.19053220607 add -d einstein_papers --name photon_definition

•   Download via a url that contains the doi number in the format .*/doi/<doinumber>

    papis scihub http://physicstoday.scitation.org/doi/10.1063/1.881498 add --name important_paper

•   Download via the doi.org url:

    papis scihub https://doi.org/10.1016/j.physrep.2016.12.002 add

IMPORTING FROM BIBTEX FILES

Many users will want to import a library from a bibtex file that another program such as zotero, mendeley or jabref will have exported. These programs usually have a field called FILE or file that points to a path where the document file can be found.

To import such a library you can use a script originally intended for zotero but that is general enought to work for other programs too.

To install this script you can copy the file papis-zotero in the repository's example directory to your papis config/scripts directory.

You can do this automatically issuing the following commands

wget -O ~/.config/papis/scripts/papis-zotero https://raw.githubusercontent.com/alejandrogallo/papis/master/examples/scripts/papis-zotero
chmod +x ~/.config/papis/scripts/papis-zotero

Now the zotero script is accessible from papis:

papis zotero -h

If you have a bibtex somewhere in your computer, you can use the script:

papis zotero library.bib

WARNING: Note that if your bibtex file has some pdf entries, i.e., looks like:

@article{Einstein1905Photon,
  author = { A. Einstein },
  doi = { 10.1002/andp.19053220607 },
  journal = { Ann. Phys. },
  pages = { 132--148 },
  title = { Über einen die Erzeugung und Verwandlung des Lichtes betreffenden heuristischen Gesichtspunkt },
  FILE = { path/to/some/relative/file.pdf },
  volume = { 322 },
  year = { 1905 },
}

then papis-zotero will interpret the path of the FILE entry as a relative path, so you should run the command where this relative path makes sense.

IMPORTING FROM ZOTERO SQLITE FILE

There is also a script that decodes the zotero.sqlite sqlite file that zotero uses to manage documents and creates papis Documents out of it.

This script will retrieve the documents from zotero (be it pdf documents or else) and important information like tags.

wget -O ~/.config/papis/scripts/papis-zotero-sql https://raw.githubusercontent.com/alejandrogallo/papis/master/examples/scripts/papis-zotero-sql
chmod +x ~/.config/papis/scripts/papis-zotero-sql

Now you have to go to the directory where zotero saves all the information, it would look something like this on linux systems:

cd ~/.mozilla/firefox/zqb7ju1q.default/zotero

Maybe the path is slightly different, it may vary from version to version from zotero. In the zotero data directory there should be a file called zotero.sqlite and there might be a storage directory with document data inside. These will be used by zotero-sql to retrieve information and files from.

Now you can use the script as

papis zotero-sql

This script by default will create a directory named Documents (in your current directory) where papis documents are stored. You can add these document by simply moving them to your library folder

mv Documents/*      /path/to/your/papis/library

or also by adding them through papis using the folder flag

papis add --from-folder Documents/ZOTERO_ID

or write a bash for loop to do it with all the converted documents

for folder in Documents/* ; do papis add --from-folder $folder ; done

WARNING: Please be aware that the database structure of zotero is version dependent and this script might not work fully with your version. You can check issue #18 for more information.

SHELL AUTOCOMPLETION

Papis has a bash autocompletion script that comes installed when you install papis with pip3.

It should be installed in a relative path

PREFIX/etc/bash_completion.d/papis

normally the PREFIX part is /usr/local/, so you can add the following line to your ~/.bashrc file

source /usr/local/etc/bash_completion.d/papis

or get the bash script from here.

FAQ

Here are some problems that users have come accross with often:

•   When I remove a folder manually in a library or I synchronize manually the library I do not see the new papers in the library. Answer: You probably need to update the cache because papis did not know anything about your changes in the library since you did it by yourself.

    papis --clear-cache

    will do.

    For more information you can also check the github faq link.

•   genindex

•   modindex

•   search

AUTHOR
Alejandro Gallo

COPYRIGHT
2017, Alejandro Gallo