Configuration file

Papis uses a configuration file in *INI* format.

The basic configuration unit is a library. Imagine you want to have a library called papers and another called books. You can have these libraries work independently from each other.

You would declare these libraries telling papis where the folders are in your system, like so:

# my library for papers and stuff
[papers]
dir = ~/Documents/papers

# my library for books and related documents
[books]
dir = ~/Documents/books

One important aspect of the configuration system is that you can override settings on a per library basis, this means that you can set settings that should have a value for the library papers and another value if you’re currently using the library books. The settings have to be set in the section under the library definition. For example, let’s suppose you want to open your documents in papers using the pdf reader okular however in books you want to open the documents in firefox, for some reason, the you would write

# my library for papers and stuff
[papers]
dir = ~/Documents/papers
opentool = okular

# my library for books and related documents
[books]
dir = ~/Documents/books
opentool = firefox

[settings]
opentool = evince
default-library = papers

Here we wrote also the special section [settings], which sets global settings that are valid in all libraries. Of course, every setting set within [settings] can be overridden by any library through the mechanism previously discussed.

A more complete example of a configuration file is the following

#
# This is a general section, the settings set here will be set for
# all libraries
#
[settings]
#
# General file opener program, rifle is a nice python program
# If you're on macOS, you can write "open", if you're on linux
# you can also write "xdg-open", on windows-cygwin, you can set it to
# "cygstart"
#
opentool = rifle
# Use ranger as a file browser, a nice python program
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>

[tui]
editmode = vi
options_list.selected_margin_style = bg:ansigreen fg:ansired
options_list.unselected_margin_style =

# Define a lib
[papers]
dir = ~/Documents/papers

# override settings from the section tui only for the papers library
# you have to prepend "tui-" to the settings
tui-editmode = emacs
tui-options_list.unselected_margin_style = bg:blue
# use whoosh as a database for papers
database-backend = whoosh
# rename files added by author and title
add-file-name = {doc[author]}{doc[title]}

# 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

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 read 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 every time that you use this library papis will also source this configuration file.

An example of a project using a local configuration file can be seen here , where the repository includes documents for component datasheets and every time papis is using that library the .papis.config file is also read and some settings will be getting overridden.

Python configuration file

For some users it would be useful to have a python file that gets loaded together with the usual configuration file, this file lives in your papis configuration directory with the name config.py, for instance for most users it will be in

~/.config/papis/config.py

General settings

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 but 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, apart from an url, also a file url associated with them. 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.

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 the title of a document will not work to match a document, only the year and author.

header-format (config-settings-header-format)
  • Default: 
    <ansired>{doc.html_escape[title]}</ansired>
 <ansigreen>{doc.html_escape[author]}</ansigreen>
  <ansiblue>({doc.html_escape[year]})</ansiblue> [<ansiyellow>{doc.html_escape[tags]}</ansiyellow>]

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

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 opened and decide upon how to open the document. You should set this to the right program for the tool. If you are on 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

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

Only option is:

  • papis

editor (config-settings-editor)

  • Default: $EDITOR

Editor used to edit files in papis, e.g., 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.

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 or ranger just 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 as a valid python list of strings, for instance:

[mylib]
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,

[mylib]
extra-bibtex-types = ["wikipedia", "video", "song"]

See bibtex reference.

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

  • Default: {au[family]}, {au[given]}

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

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

papis add options

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

  • Default: {doc[title]:.15} {doc[author]:.6} {doc[year]}

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]}

In general however I recomment the default behaviour of just using the author key of the document, i.e.,

ref-format = {doc[title]:.15} {doc[author]:.6} {doc[year]}

The spaces in the value of the format will be important in order to capitalize the string, i.e., if you have a title like STUDIES ABOUT EARTH AND HIMMEL and and an author list like mesh-ki-ang-nuna then the built reference will be StudiesAboutEMeshKi.

Note

Special characters will be replaced when generating the ref entry (e.g. Ö → O, . and other symbols will be striped from the string).

If you want to add some punctuation, dots (.) and underscores (_) can be escaped by a backslash. For example,

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

would result in ‘Plews.2019’. To ensure correct capitalization you might consider inserting whitespaces after an escaped character.

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

  • Default: False

If set to True, every time 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 have the contrary effect, i.e., it will not ask for confirmation.

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

  • Default: empty string

Default name for the folder of newly added documents. For example, if you want 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.

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

  • Default: None

Same as add-folder-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, every time 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 have the contrary effect, i.e., it will not run in interactive mode.

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

  • Default: False

If set to True, every time you run papis add the flag --edit will be added automatically. If it is set to True and you add something, i.e., you run papis add --edit, then it will have 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, every time you run papis add the flag --open will be added automatically. If it is set to True and you add something, i.e., you run papis add --open, then it will have the contrary effect, i.e., it will not open the attached files before adding the document to the library.

papis browse options

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

  • Default: url

This command provides the key that is used to generate the url. For users that run 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 you need functionality with the search-engine option, set the option to an empty string e.g.

browse-key = ''

papis edit 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. The notes-name is formated by the formater, so that the filename of notes can be dynamically defined, e.g.:

notes-name = notes_{doc[title]:.15}.tex
notes-template (config-settings-notes-template)

When editing notes for the first time, a preliminary note will be generated based on a template. The path to this template is specified by notes-template. The template will then be formated by formater. This can be useful to enforce the same style in the notes for all documents.

Default value is set to "", which will return an empty notes file. If no file is found at the path to the template, then also an empty notes file will be generated.

Marks

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

  • Default: False

If this option is set to True, every time 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.

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 open all papers authored by John Smith whenever you do not specify an input query string, i.e., papis open. Then setting

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

would do the trick. 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: $XDG_CACHE_HOME

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.

Terminal user interface (picker)

These options are for the terminal user interface (tui). They are defined in the section tui which means that you can set them in your configuration file globally like

[tui]
status_line_format = "F1: Help"
...

or inside the library sections prepending a tui-,

[papers]
tui-status_line_format = "Library papers**
...
status_line_format (config-tui-status_line_format)

  • Default: ``{selected_index}/{number_of_documents} F1:help c-l:redraw ``

This is the format of the string that appears at the bottom in the status line. Right now there are only two variables defined:

  • selected_index

  • number_of_documents

Which are self-explanatory.

status_line_style (config-tui-status_line_style)

  • Default: bg:ansiwhite fg:ansiblack

The style the status line should have. Examples are fg:#ff00aa bg:black etc… More information can be found here .

message_toolbar_style (config-tui-message_toolbar_style)

  • Default: bg:ansiyellow fg:ansiblack

The style of the message toolbar, this toolbar is the one where messages of the echo command are rendered for instance.

options_list.selected_margin_style (config-tui-options_list.selected_margin_style)

  • Default: bg:ansiblack fg:ansigreen

Style of the margin of the selected document in the picker.

options_list.unselected_margin_style (config-tui-options_list.unselected_margin_style)

  • Default: bg:ansiwhite

Style of the margin of the unselected documents in the picker. If you don’t want any coloring for them you can just set this setting to the empty string as such

tui-options_list.unselected_margin_style =
error_toolbar_style (config-tui-error_toolbar_style)

  • Default: bg:ansired fg:ansiblack

The style for the error messages.

editmode (config-tui-editmode)

  • Default: emacs

Whenever the user is typing text, one can use either emacs like keybindings or vi. If this does not tell you anything, you can just leave it as is.

move_down_key (config-tui-move_down_key)

  • Default: down

move_up_key (config-tui-move_up_key)

  • Default: up

move_down_while_info_window_active_key (config-tui-move_down_while_info_window_active_key)

  • Default: c-n

move_up_while_info_window_active_key (config-tui-move_up_while_info_window_active_key)

  • Default: c-p

focus_command_line_key (config-tui-focus_command_line_key)

  • Default: tab

edit_document_key (config-tui-edit_document_key)

  • Default: c-e

open_document_key (config-tui-open_document_key)

  • Default: c-o

show_help_key (config-tui-show_help_key)

  • Default: f1

show_info_key (config-tui-show_info_key)

  • Default: s-tab

go_top_key (config-tui-go_top_key)

  • Default: home

go_bottom_key (config-tui-go_bottom_key)

  • Default: end

mark_key (config-tui-mark_key)

  • Default: c-t

FZF integration

From version 0.12 papis ships with an out-of-the-box fzf integration for the picker. A minimal terminal user interface is provided and together with options for its customization. You can set the picktool to fzf by setting

picktool = fzf

in the configuration section of your library.

In comparison to the built-in papis tui the advantage of the fzf picker is that it is much faster, however a disadvantage is that it is restricted to one-line entries. Also it is important to notice that fzf will only match against what is shown on the terminal screen, as opposed to the papis matcher, that can match against the whole title and whole author text since this is controlled by the match-format setting. However, for many uses it might not bother the user to have this limitation of fzf.

fzf-binary (config-settings-fzf-binary)

  • Default: fzf

Path to or name of the fzf binary.

fzf-extra-flags (config-settings-fzf-extra-flags)

  • Default: ['--ansi', '--multi', '-i']

Extra flags to be passed to fzf every time it gets called.

fzf-extra-bindings (config-settings-fzf-extra-bindings)

  • Default: ['ctrl-s:jump']

Extra bindings to fzf as a python list. Refer to the fzf documentation for more details.

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

  • Default: {c.Fore.MAGENTA}{doc[title]:<70.70}{c.Style.RESET_ALL} :: {c.Fore.CYAN}{doc[author]:<20.20}{c.Style.RESET_ALL}{c.Fore.YELLOW}«{doc[year]:4}»{c.Style.RESET_ALL}:{doc[tags]}

Format for the entries for fzf. Notice that if you want colors you should have in fzf-extra-flags the --ansi flag and include the colors in the header-format as ansi escape sequences.

The papis format string is given the additional variable c which contains the package colorama in it. Refer to the colorama documentation to see which colors are available here. For instance, if you want the title in red you would put in your fzf-header-format

"{c.Fore.RED}{doc[title]}{c.Style.RESET_ALL}"

fzf with a preview window

fzf has the disadvantage that it does not support multiline output and it matches only against what it shows on the screen.

You can go around this issue by composing an fzf customization. The following configuration

fzf-extra-flags = ["--ansi", "--multi", "-i",
                   "--preview", "echo {} | sed -r 's/~~/\\n/g; /^ *$/d' ",
                   "--preview-window", "bottom:wrap:20%%",
                   "--color", "preview-fg:#F6E6E4,preview-bg:#5B6D5B"]

fzf-extra-bindings = ["ctrl-s:jump",
                      "ctrl-t:toggle-preview"]

fzf-header-format = {c.Fore.MAGENTA}{doc[title]}{c.Style.RESET_ALL}~~ {c.Fore.CYAN}{doc[author]}{c.Style.RESET_ALL}~~ {c.Fore.YELLOW}«{doc[year]}»{c.Style.RESET_ALL}~~ {c.Fore.YELLOW}{doc[journal]}{c.Style.RESET_ALL}~~ :{doc[tags]}

will have unrestricted titles, author, journal etc fields against which the query will match and it will show in the fzf preview window a tidy description of the currently selected field by replacing the token ~~ by a newline. You can try this out and play with fzf customizations. Please note that bottom:wrap:20%% has two % since the config file interpolator uses % as a reserved symbol, so it must be escaped by writing two of them.

Other

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.

document-description-format (config-settings-document-description-format)

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

papis sometimes will have to tell you which document it is processing through text, for instance, imagine you are updating a document

author: Albert Einstein
title: General Relativity

and papis is doing something with it. Then if your document-description-format is set to {doc[title]} - {doc[author]}, you will see that papis tells you

.....
Updating 'General Relativity - Albert Einstein'
...

so you will know exactly what is going on.

sort-field (config-settings-sort-field)

  • Default: None

As of version 0.10, some command line commands have the --sort option to sort the documents according to a given field. If you set sort-field in your configuration file, this will sort by default the documents according to this sort field. For instance, if you want your documents by default to be sorted by year, you would set sort-field = year.

time-stamp (config-settings-time-stamp)

  • Default: True

Whether or not to add a timestamp to a document when is being added to papis. If documents have a timestamp, then they will be sortable using –sort time-added option.

formater (config-settings-formater)

  • Default: python

The formatting language in python can be configured through plugins.

class papis.format.PythonFormater[source]

Construct a string using a pythonic format string and a document. You can activate this formatter by setting formater = python.

class papis.format.Jinja2Formater[source]

Construct a Jinja2 formated string. You can activate this formatter by setting formater = jinja2.