Bibtex

This command is used for interacting with BibTeX bib files in your LaTeX projects.

It is meant to be used when the BibTeX file is a companion to your Papis library. Then, papis bibtex can be used to add, remove, update, and generally clean the file using information from the library.

Examples

You can use it to open some papers from the BibTeX file by calling:

papis bibtex read new_papers.bib open

This is done by matching the entry in the BibTeX file with a document in your library and then opening the corresponding files. If no document can be found in the library, then the file cannot be opened, of course. To add papers to the BibTeX file (from the current library) you can call:

papis bibtex             \
    read new_papers.bib  \ # Read bib file
    add -q einstein      \ # Pick a doc with query 'einstein' from library
    add -q heisenberg    \ # Pick a doc with query 'heisenberg' from library
    save new_papers.bib    # Save in new_papers.bib

To update some information that was modified in Papis’ YAML files, you can call:

papis bibtex            \
    read new_papers.bib \ # Read bib file
    update -f           \ # Update what has been read from Papis library
    save new_papers.bib   # Save everything to new_papers.bib, overwriting

Note

Reading, adding, and then saving documents in this fashion will re-export them and may change the formatting of your BibTeX file.

Local configuration file

If you are working in a local folder where you have a bib file called main.bib, you can avoid adding the repetitive read main.bib and save main.bib by using the configuration values described in the documentation. You can create a local configuration file .papis.config for papis bibtex to read and write automatically. This file should contain:

[bibtex]
default-read-bibfile = main.bib
default-save-bibfile = main.bib
auto-read = True

With this setup, you can just do:

papis bibtex add -q einstein save

Check reference quality

When you’re collaborating with someone, you might come across malformed or incomplete references. Most journals want to have all the DOIs and URLs available. For this you can use the doctor command:

papis bibtex read mybib.bib doctor

Usually, you likely want to only have the references that are actually cited in the LaTeX file in your project’s BibTeX file. You can check which references are not cited in the .tex files by calling:

papis bibtex iscited -f main.tex -f chapter-2.tex

and you can then filter them out using the filter-cited command.

To monitor the health of the project’s BibTeX file, you can add a simple target to the project’s Makefile like:

check-bib:
    papis bibtex iscited -f main.tex doctor
.PHONY: check-bib

Vim integration

This command can also be easily used from Vim with these simple lines:

function! PapisBibtexRef()
    let l:temp = tempname()
    echom l:temp
    silent exec "!papis bibtex ref -o ".l:temp
    let l:olda = @a
    let @a = join(readfile(l:temp), ',')
    normal! "ap
    redraw!
    let @a = l:olda
endfunction

command! -nargs=0 BibRef call PapisBibtexRef()
command! -nargs=0 BibOpen exec "!papis bibtex open"

And use as such:

Command-line interface

Interact with BibTeX files.

Usage

papis bibtex [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options

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

--noar, --no-auto-read: Do not auto read the ‘default-read-file’ (must call ‘read’ explicitly).

add

Add documents from the library to the BibTeX file.

Usage

papis bibtex add [OPTIONS]

Options

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

-a, --all: Apply action to all matching documents.

-q, --query <query>: Query for a document in the database.

-r, --refs-file <refs_file>: File with references to query in the database and then add.

bibtex

Import documents from a BibTeX file.

This explorer can be used as:

papis explore bibtex 'lib.bib' pick

Usage

papis bibtex bibtex [OPTIONS] BIBFILE

Options

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

Arguments

BIBFILE: Required argument

browse

Browse a document in the document list.

Usage

papis bibtex browse [OPTIONS]

Options

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

-k, --key <key>: doi, url, …

doctor

Check BibTeX file for correctness.

This can check missing keys, e.g. by running:

papis bibtex doctor -k title -k url -k doi

Usage

papis bibtex doctor [OPTIONS]

Options

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

-k, --key <key>: Key to check exists in all documents

edit

Edit documents by adding keys or opening an editor.

For example, you can run the following to add a special key __proj to all the documents:

papis bibtex read article.bib edit --set __proj focal-point --all

Usage

papis bibtex edit [OPTIONS]

Options

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

-s, --set <set_tuples>: Update a document with key value pairs.

-a, --all: Apply action to all matching documents.

filter-cited

Filter cited documents from the BibTeX file.

for example to filter cited documents in main.tex and save a unique list of documents in cited.bib, you can run:

papis bibtex read main.bib filter-cited -f main.tex save cited.bib

Usage

papis bibtex filter-cited [OPTIONS]

Options

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

-f, --file <_files>: Required Text file to check for references.

import

Import documents from a BibTeX file to the current library.

For example, you can run:

papis bibtex read mybib.bib import

Usage

papis bibtex import [OPTIONS]

Options

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

-o, --out <out>: Out folder to export.

-a, --all: Apply action to all matching documents.

-b, --batch: Batch mode (do not prompt or otherwise).

iscited

Check which documents are not cited.

For example, to print a list of documents that have not been cited in both main.tex and chapter-2.tex, run:

papis bibtex iscited -f main.tex -f chapter-2.tex

Usage

papis bibtex iscited [OPTIONS]

Options

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

-f, --file <_files>: Required Text file to check for references.

open

Open a document using the default application.

Usage

papis bibtex open [OPTIONS]

Options

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

ref

Print the reference for a document.

Usage

papis bibtex ref [OPTIONS]

Options

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

-o, --out <out>: Output ref to a file.

rm

Remove a document from the documents list.

Usage

papis bibtex rm [OPTIONS]

Options

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

save

Save the documents in the BibTeX format.

Usage

papis bibtex save [OPTIONS] BIBFILE

Options

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

-f, --force: Do not ask for confirmation when saving.

Arguments

BIBFILE: Required argument

sort

Sort the documents in the BibTeX file.

Usage

papis bibtex sort [OPTIONS]

Options

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

-k, --key <key>: Required Field to order by.

-r, --reverse: Reverse the sort order.

unique

Remove duplicate BibTeX entries.

Usage

papis bibtex unique [OPTIONS]

Options

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

-k, --key <key>: Field to test for uniqueness, default is ref.

-o <o>: Output the discarded documents to a file.

update

Update documents from and to the library.

Usage

papis bibtex update [OPTIONS]

Options

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

-a, --all: Apply action to all matching documents.

-f, --from: Update the document from the library.

-t, --to: Update the library document from the BibTeX file.

-k, --keys <keys>: Update only given keys (can be given multiple times).