Explore

This command is mainly used to explore different databases and gather data for a project before adding it to the Papis libraries.

Examples

Imagine you want to search for some papers online but don’t want to open the browser to look for them. The explore command gives you a way to do this using several online services. The command itself supports plugins, so see papis explore --help for a complete list of supported online services. A summary can also be shown with

papis list --explorers

An excellent resource for this is Crossref. You can use it by using the crossref subcommand:

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 as a concatenating command. 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 Schrodinger’s, and you want to store them into a BibTeX file called lib.bib. Then you could concatenate the commands crossref and export --format bibtex:

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

This will store everything that you got from Crossref in the lib.bib file. However, 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 --format bibtex --out 'lib.bib'

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

papis explore \
    crossref -a 'Schrodinger' \
    crossref -a 'Einstein' \
    arxiv -a 'Felix Hummel' \
    export --format yaml --out 'docs.yaml' \
    pick  \
    export --format bibtex --out 'special-picked-documents.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 file. After that we pick one document from them and store the information in the file special-picked-documents.bib, and we could go on and on.

If you want to follow up on these documents and get them to pick one again, you could use the yaml command to read in document information from a YAML file, e.g. 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 from docs.yaml and pick a document, which we then feed into the explore cmd command. This command accepts a string to issue a general shell command and allows formatting with the Papis format syntax. In this case, the picked document gets fed into the papis scihub command which tries to download the document using scihub. Also this very document is opened by Firefox (in case the document does have a url).

Command-line interface

Explore new documents using a variety of resources.

Usage

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

Options

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

add

Add selected documents to the current library.

For example, to add documents from a BibTeX file, you can call:

papis explore bibtex 'lib.bib' pick add

Usage

papis explore add [OPTIONS]

Options

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

cmd

Run a general command on the document list.

For example, to look for 200 Schrodinger papers with Crossref, pick one, and add it to the current library via papis-scihub, you can call:

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

Usage

papis explore cmd [OPTIONS] COMMAND

Options

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

Arguments

COMMAND: Required argument

export

Export retrieved documents into various formats.

For example, to query Crossref and export all 200 documents to a YAML file, you can call:

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

Usage

papis explore export [OPTIONS]

Options

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

-f, --format <fmt>: Export format for document metadata.

--list-exporters: List all supported exporters.

-o, --out <out>: Output file for document metadata.

pick

Pick a document from the retrieved documents.

For example, to open a picker with the documents in a BibTeX file, you can call:

papis explore bibtex 'lib.bib' pick

Usage

papis explore pick [OPTIONS]

Options

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

-n, --number <number>: Automatically pick the n-th document.