PAPIS-CONFIG(1)

NAME
papis-config - Papis Configuration

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.

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

  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.

AUTHOR
Alejandro Gallo

COPYRIGHT
2017, Alejandro Gallo