Merge branch 'refactor'v0.6

76 files changed, 5610 insertions, 2590 deletions

diff --git a/.travis.yml b/.travis.yml
index b655095d..5df54c8f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -19,3 +19,5 @@ install:
   - pip install -e .[optional]
   - pip install pytest
   - make install
+  - sudo apt-get update -qq
+  - sudo apt-get install -y git
diff --git a/doc/build/man/papis-config.1 b/doc/build/man/papis-config.1
index 58842748..abda2fb4 100644
--- a/doc/build/man/papis-config.1
+++ b/doc/build/man/papis-config.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "PAPIS-CONFIG" "1" "Feb 20, 2018" "0.5.3" "papis"
+.TH "PAPIS-CONFIG" "1" "May 08, 2018" "0.6" "papis"
 .SH NAME
 papis-config \- Papis Configuration
 .
@@ -168,34 +168,40 @@ configuration file.
 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.
+.sp
+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\(aqre sharing a library with someone
+else and you want them to have the same settings in that library as
+you. Imagine you\(aqre sharing a library of datasheets with your friend
+Fulano. You have your library at
 .INDENT 0.0
-.TP
-\fBmode\fP (\fI\%config\-settings\-mode\fP)
-.INDENT 7.0
-.IP \(bu 2
-\fBDefault\fP: \fBdocument\fP
+.INDENT 3.5
+.sp
+.nf
+.ft C
+~/Documents/lib\-with\-fulano
+.ft P
+.fi
 .UNINDENT
 .UNINDENT
 .sp
-Papis is a modal program and it can be configured to support different
-operating modes. The default is considering that every papis document
-or entry is a \(aqdocument\(aq.
+and you\(aqve set a local configuration file there
 .INDENT 0.0
-.TP
-\fBopentool\fP (\fI\%config\-settings\-opentool\fP)
-.INDENT 7.0
-.IP \(bu 2
-\fBDefault\fP: \fBxdg\-open\fP
+.INDENT 3.5
+.sp
+.nf
+.ft C
+~/Documents/lib\-with\-fulano/.papis.config
+.ft P
+.fi
 .UNINDENT
 .UNINDENT
 .sp
-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 \fI\%ranger\fP or let
-the default handle it in your system.
-For mac users you might set this to \fBopen\fP\&.
+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.
 .INDENT 0.0
 .TP
 \fBdir\-umask\fP (\fI\%config\-settings\-dir\-umask\fP)
@@ -209,301 +215,251 @@ This is the default \fBumask\fP that will be used to create the new
 documents\(aq directories.
 .INDENT 0.0
 .TP
-\fBbrowser\fP (\fI\%config\-settings\-browser\fP)
+\fBuse\-git\fP (\fI\%config\-settings\-use\-git\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fB$BROWSER\fP
+\fBDefault\fP: \fBFalse\fP
 .UNINDENT
 .UNINDENT
 .sp
-Program to be used for opening websites, the default is the environment
-variable \fB$BROWSER\fP\&.
+Some commands will issue git commands if this option is set to \fBTrue\fP\&.
+For example in \fBmv\fP or \fBrename\fP\&.
 .INDENT 0.0
 .TP
-\fBpicktool\fP (\fI\%config\-settings\-picktool\fP)
+\fBbrowse\-query\-format\fP (\fI\%config\-settings\-browse\-query\-format\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBpapis.pick\fP
+\fBDefault\fP: \fB{doc[title]} {doc[author]}\fP
 .UNINDENT
 .UNINDENT
 .sp
-This is the program used whenever papis asks you to pick a document
-or options in general.
-.INDENT 0.0
-.TP
-.B Possible options are:
-.INDENT 7.0
-.IP \(bu 2
-papis.pick
-.IP \(bu 2
-rofi
-.IP \(bu 2
-vim
-.IP \(bu 2
-dmenu
-.UNINDENT
-.UNINDENT
+The query string that is to be searched for in the \fBbrowse\fP command
+whenever a search engine is used.
 .INDENT 0.0
 .TP
-\fBmvtool\fP (\fI\%config\-settings\-mvtool\fP)
+\fBsearch\-engine\fP (\fI\%config\-settings\-search\-engine\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBmv\fP
+\fBDefault\fP: \fBhttps://duckduckgo.com\fP
 .UNINDENT
 .UNINDENT
 .sp
-Tool used to in the \fBpapis mv\fP command to move documents.
-If you are using \fBgit\fP to manage your documents, you might consider
-setting it to \fBmvtool = git mv\fP\&.
+Search engine to be used by some commands like \fBbrowse\fP\&.
 .INDENT 0.0
 .TP
-\fBeditor\fP (\fI\%config\-settings\-editor\fP)
+\fBuser\-agent\fP (\fI\%config\-settings\-user\-agent\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fB$EDITOR\fP
+\fBDefault\fP: \fBMozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)\fP
 .UNINDENT
 .UNINDENT
 .sp
-Editor used to edit files in papis, for instance for the \fBpapis edit\fP
-command. It defaults to the \fB$EDITOR\fP environment variable, if this is
-not set then it will default to the \fB$VISUAL\fP environment variable.
-Otherwise the default editor in your system will be used.
+User agent used by papis whenever it obtains information from external
+servers.
 .INDENT 0.0
 .TP
-\fBxeditor\fP (\fI\%config\-settings\-xeditor\fP)
+\fBdefault\-gui\fP (\fI\%config\-settings\-default\-gui\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBxdg\-open\fP
+\fBDefault\fP: \fBvim\fP
 .UNINDENT
 .UNINDENT
 .sp
-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.:
-\fBgedit\fP, \fBxemacs\fP, \fBgvim\fP to name a few.
+Default gui to be used by papis, it can have the values given
+by \fBpapis gui \-\-help\fP\&.
 .INDENT 0.0
 .TP
-\fBsync\-command\fP (\fI\%config\-settings\-sync\-command\fP)
+\fBscripts\-short\-help\-regex\fP (\fI\%config\-settings\-scripts\-short\-help\-regex\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBgit \-C {lib[dir]} pull origin master\fP
+\fBDefault\fP: \fB\&.*papis\-short\-help: *(.*)\fP
 .UNINDENT
 .UNINDENT
 .sp
-Command that is to be used when \fBpapis sync\fP is run.
+This is the format of the short help indicator in external papis
+commands.
 .INDENT 0.0
 .TP
-\fBnotes\-name\fP (\fI\%config\-settings\-notes\-name\fP)
+\fBinfo\-name\fP (\fI\%config\-settings\-info\-name\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBnotes.tex\fP
+\fBDefault\fP: \fBinfo.yaml\fP
 .UNINDENT
 .UNINDENT
 .sp
-In \fBpapis edit\fP you can edit notes about the document. \fBnotes\-name\fP
-is the default name of the notes file, which by default is supposed
-to be a TeX file.
+The default name of the information files.
 .INDENT 0.0
 .TP
-\fBuse\-cache\fP (\fI\%config\-settings\-use\-cache\fP)
+\fBdoc\-url\-key\-name\fP (\fI\%config\-settings\-doc\-url\-key\-name\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBTrue\fP
+\fBDefault\fP: \fBdoc_url\fP
 .UNINDENT
 .UNINDENT
 .sp
-Set to \fBFalse\fP if you do not want to use the \fBcache\fP
-for the given library.
-.INDENT 0.0
-.TP
-\fBcache\-dir\fP (\fI\%config\-settings\-cache\-dir\fP)
-.INDENT 7.0
-.IP \(bu 2
-\fBDefault\fP: \fB/home/gallo/.cache/papis\fP
-.UNINDENT
-.UNINDENT
+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.
 .INDENT 0.0
 .TP
-\fBuse\-git\fP (\fI\%config\-settings\-use\-git\fP)
+\fBdefault\-library\fP (\fI\%config\-settings\-default\-library\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBFalse\fP
+\fBDefault\fP: \fBpapers\fP
 .UNINDENT
 .UNINDENT
 .sp
-Some commands will issue git commands if this option is set to \fBTrue\fP\&.
-For example in \fBmv\fP or \fBrename\fP\&.
+The name of the library that is to be searched when \fBpapis\fP
+is run without library arguments.
 .INDENT 0.0
 .TP
-\fBadd\-confirm\fP (\fI\%config\-settings\-add\-confirm\fP)
+\fBexport\-text\-format\fP (\fI\%config\-settings\-export\-text\-format\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBFalse\fP
+\fBDefault\fP: \fB{doc[author]}. {doc[title]}. {doc[journal]} {doc[pages]} {doc[month]} {doc[year]}\fP
 .UNINDENT
 .UNINDENT
 .sp
-If set to \fBTrue\fP, everytime you run \fBpapis add\fP
-the flag \fB\-\-confirm\fP will be added automatically. If is set to \fBTrue\fP
-and you add it, i.e., you run \fBpapis add \-\-confirm\fP, then it will
-fave the contrary effect, i.e., it will not ask for confirmation.
+The default output papis format for \fBpapis export \-\-text\fP\&.
 .INDENT 0.0
 .TP
-\fBadd\-name\fP (\fI\%config\-settings\-add\-name\fP)
+\fBformat\-doc\-name\fP (\fI\%config\-settings\-format\-doc\-name\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: 
-.nf
-\(ga\(ga
-.fi
-
-.nf
-\(ga\(ga
-.fi
-
+\fBDefault\fP: \fBdoc\fP
 .UNINDENT
 .UNINDENT
 .sp
-Default name for newly added documents. For example, if you want
-your documents to be \fBauthor\-title\fP then you should set it to
-the papis format: \fB{doc[author]}\-{doc[title]}\fP\&.
+This setting controls the name of the document in the papis format strings
+like in format strings such as \fBmatch\-format\fP or \fBheader\-format\fP\&.
+For instance, if you are managing videos, you might want to
+set this option to \fBvid\fP in order to set  the \fBheader\-format\fP to
+\fB{doc[title]} \- {doc[director]} \- {doc[duration]}\fP\&.
 .INDENT 0.0
 .TP
-\fBfile\-name\fP (\fI\%config\-settings\-file\-name\fP)
+\fBmatch\-format\fP (\fI\%config\-settings\-match\-format\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBNone\fP
+\fBDefault\fP: \fB{doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}\fP
 .UNINDENT
 .UNINDENT
 .sp
-Same as \fBadd\-name\fP, but for files, not folders. If it is not set,
-the names of the files will be cleaned and taken \fIas\-is\fP\&.
+Default format that is used to match a document against in order to select
+it. For example if the \fBmatch\-format\fP is equal to
+\fB{doc[year]} {doc[author]}\fP then title of a document will not work
+to match a document, only the year and author.
 .INDENT 0.0
 .TP
-\fBadd\-interactive\fP (\fI\%config\-settings\-add\-interactive\fP)
+\fBheader\-format\fP (\fI\%config\-settings\-header\-format\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBFalse\fP
+\fBDefault\fP: \fB{doc[title]:<70.70}|{doc[author]:<20.20} ({doc[year]:\-<4})\fP
 .UNINDENT
 .UNINDENT
 .sp
-If set to \fBTrue\fP, everytime you run \fBpapis add\fP
-the flag \fB\-\-interactive\fP will be added automatically. If is set to
-\fBTrue\fP and you add it, i.e., you run \fBpapis add \-\-interactive\fP, then it
-will fave the contrary effect, i.e., it will not run in interactive mode.
+Default format that is used to show a document in order to select it.
 .INDENT 0.0
 .TP
-\fBadd\-edit\fP (\fI\%config\-settings\-add\-edit\fP)
+\fBinfo\-allow\-unicode\fP (\fI\%config\-settings\-info\-allow\-unicode\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBFalse\fP
+\fBDefault\fP: \fBTrue\fP
 .UNINDENT
 .UNINDENT
 .sp
-If set to \fBTrue\fP, everytime you run \fBpapis add\fP
-the flag \fB\-\-edit\fP will be added automatically. If is set to
-\fBTrue\fP and you add it, i.e., you run \fBpapis add \-\-edit\fP, then it
-will fave the contrary effect, i.e., it will not prompt to edit the info
-file.
+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 \fBTrue\fP
+by default.
 .INDENT 0.0
 .TP
-\fBadd\-open\fP (\fI\%config\-settings\-add\-open\fP)
+\fBsync\-command\fP (\fI\%config\-settings\-sync\-command\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBFalse\fP
+\fBDefault\fP: \fBgit \-C {lib[dir]} pull origin master\fP
 .UNINDENT
 .UNINDENT
 .sp
-If set to \fBTrue\fP, everytime you run \fBpapis add\fP
-the flag \fB\-\-open\fP will be added automatically. If is set to
-\fBTrue\fP and you add it, i.e., you run \fBpapis add \-\-open\fP, then it
-will fave the contrary effect, i.e., it will not open the attached files
-before adding the document to the library.
+Command that is to be used when \fBpapis sync\fP is run.
+.SS Tools options
 .INDENT 0.0
 .TP
-\fBcheck\-keys\fP (\fI\%config\-settings\-check\-keys\fP)
+\fBopentool\fP (\fI\%config\-settings\-opentool\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBfiles\fP
+\fBDefault\fP: \fBxdg\-open\fP
 .UNINDENT
 .UNINDENT
 .sp
-Comma separated key values to be checked by default by the command
-\fBcheck\fP\&. E.g: \fBcheck\-keys = author, doi\fP\&.
+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 \fI\%ranger\fP or let
+the default handle it in your system.
+For mac users you might set this to \fBopen\fP\&.
 .INDENT 0.0
 .TP
-\fBbrowse\-query\-format\fP (\fI\%config\-settings\-browse\-query\-format\fP)
+\fBbrowser\fP (\fI\%config\-settings\-browser\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fB{doc[title]} {doc[author]}\fP
+\fBDefault\fP: \fB$BROWSER\fP
 .UNINDENT
 .UNINDENT
 .sp
-The query string that is to be searched for in the \fBbrowse\fP command
-whenever a search engine is used.
+Program to be used for opening websites, the default is the environment
+variable \fB$BROWSER\fP\&.
 .INDENT 0.0
 .TP
-\fBsearch\-engine\fP (\fI\%config\-settings\-search\-engine\fP)
+\fBpicktool\fP (\fI\%config\-settings\-picktool\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBhttps://duckduckgo.com\fP
+\fBDefault\fP: \fBpapis.pick\fP
 .UNINDENT
 .UNINDENT
 .sp
-Search engine to be used by some commands like \fBbrowse\fP\&.
+This is the program used whenever papis asks you to pick a document
+or options in general.
 .INDENT 0.0
 .TP
-\fBuser\-agent\fP (\fI\%config\-settings\-user\-agent\fP)
+.B Possible options are:
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBMozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3)\fP
-.UNINDENT
-.UNINDENT
-.sp
-User agent used by papis whenever it obtains information from external
-servers.
-.INDENT 0.0
-.TP
-\fBdefault\-gui\fP (\fI\%config\-settings\-default\-gui\fP)
-.INDENT 7.0
+papis.pick
 .IP \(bu 2
-\fBDefault\fP: \fBvim\fP
-.UNINDENT
-.UNINDENT
-.sp
-Default gui to be used by papis, it can have the values given
-by \fBpapis gui \-\-help\fP\&.
-.INDENT 0.0
-.TP
-\fBscripts\-short\-help\-regex\fP (\fI\%config\-settings\-scripts\-short\-help\-regex\fP)
-.INDENT 7.0
+rofi
 .IP \(bu 2
-\fBDefault\fP: \fB\&.*papis\-short\-help: *(.*)\fP
+vim
+.IP \(bu 2
+dmenu
 .UNINDENT
 .UNINDENT
-.sp
-This is the format of the short help indicator in external papis
-commands.
 .INDENT 0.0
 .TP
-\fBinfo\-name\fP (\fI\%config\-settings\-info\-name\fP)
+\fBeditor\fP (\fI\%config\-settings\-editor\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBinfo.yaml\fP
+\fBDefault\fP: \fB$EDITOR\fP
 .UNINDENT
 .UNINDENT
 .sp
-The default name of the information files.
+Editor used to edit files in papis, for instance for the \fBpapis edit\fP
+command. It defaults to the \fB$EDITOR\fP environment variable, if this is
+not set then it will default to the \fB$VISUAL\fP environment variable.
+Otherwise the default editor in your system will be used.
 .INDENT 0.0
 .TP
-\fBdoc\-url\-key\-name\fP (\fI\%config\-settings\-doc\-url\-key\-name\fP)
+\fBxeditor\fP (\fI\%config\-settings\-xeditor\fP)
 .INDENT 7.0
 .IP \(bu 2
-\fBDefault\fP: \fBdoc_url\fP
+\fBDefault\fP: \fBxdg\-open\fP
 .UNINDENT
 .UNINDENT
 .sp
-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.
+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.
+\fBgedit\fP, \fBxemacs\fP, \fBgvim\fP to name a few.
 .INDENT 0.0
 .TP
 \fBfile\-browser\fP (\fI\%config\-settings\-file\-browser\fP)
@@ -516,6 +472,7 @@ this setting.
 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 \fBdolphin\fP, \fBthunar\fP, \fBranger\fP to name a few.
+.SS Bibtex options
 .INDENT 0.0
 .TP
 \fBextra\-bibtex\-keys\fP (\fI\%config\-settings\-extra\-bibtex\-keys\fP)
@@ -556,65 +513,222 @@ these here as comma separated values, for example
 .sp
 Allow non\-standard bibtex types to be recognized, e.g,
 \fBextra\-bibtex\-types = wikipedia, video, song\fP\&.
-See \fI\%bibtex reference\fP\&.