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 you don’t want to go into a browser and look for it. The explore command gives you way to do this using several services available online. More should be coming on the way!

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 Schroedinger’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 as such

papis explore crossref -a 'Schrodinger' export --format bibtex 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 lib.bib

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

papis explore \
    crossref -a Schroedinger \
    crossref -a Einstein \
    arxiv -a 'Felix Hummel' \
    export --format yaml docs.yaml \
    pick  \
    export --format bibtex specially-picked-document.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 specially-picked-document.bib, and we could go on and on.

If you want to follow-up on these documents and get them again to pick one, 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, that accepts a papis formatting string to issue a general shell command. 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.

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
papis explore add [OPTIONS]

arxiv

Look for documents on arXiv.org.

For example, to search for documents with the authors “Hummer” and “Garnet Chan” (a maximum of 100 articles), use

papis explore arxiv -a 'Hummel' -m 100 arxiv -a 'Garnet Chan' pick

If you want to search for the exact author name ‘John Smith’, you should enclose it in extra quotes, as in the example below

papis explore arxiv -a '"John Smith"' pick
papis explore arxiv [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
-a, --author <author>
-t, --title <title>
--abstract <abstract>
--comment <comment>
--journal <journal>
--report-number <report_number>
--category <category>
--id-list <id_list>
--page <page>
-m, --max <max_results>

bibtex

Import documents from a BibTeX file.

This explorer be used as

papis explore bibtex 'lib.bib' pick
papis explore bibtex [OPTIONS] BIBFILE

Options

-h, --help

Show this message and exit.

Arguments

BIBFILE

Required argument

citations

Query the citations for a paper.

For example, to go through the citations of a paper and export it in a YAML file, you can call

papis explore citations 'einstein' export --format yaml einstein.yaml
papis explore citations [OPTIONS] [QUERY]

Options

--doc-folder <doc_folder>

Document folder on which to apply action

-h, --help

Show this message and exit.

-b, --cited-by

Use the cited-by citations

-a, --all

Apply action to all matching documents

Arguments

QUERY

Optional argument

cmd

Run a general command on the document list.

For example, to look for 200 Schroedinger 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]}'
papis explore cmd [OPTIONS] COMMAND

Options

-h, --help

Show this message and exit.

Arguments

COMMAND

Required argument

crossref

Look for documents on Crossref.

For example, to look for a document with the author “Albert Einstein” and export it to a BibTeX file, you can call

papis explore \
    crossref -a 'Albert einstein' \
    pick \
    export --format bibtex lib.bib
papis explore crossref [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>

General query

-a, --author <author>

Author of the query

-t, --title <title>

Title of the query

-m, --max <_ma>

Maximum number of results

-f, --filter <_filters>

Filters to apply

-o, --order <order>

Order of appearance according to sorting

Default:

desc

Options:

asc | desc

-s, --sort <sort>

Sorting parameter

Default:

score

Options:

relevance | published-print | published | issued | deposited | score | is-referenced-by-count | references-count | indexed | updated | published-online

dblp

Look for documents on dblp.org.

For example, to look for a document with the author “Albert Einstein” and export it to a BibTeX file, you can call

papis explore \
    dblp -a 'Albert einstein' \
    pick \
    export --format bibtex lib.bib
papis explore dblp [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>

General query

-m, --max <max_results>

Maximum number of results

dissemin

Look for documents on dissem.in.

For example, to look for a document with the author “Albert Einstein” and open it with Firefox, you can call

papis explore \
    dissemin -q 'Albert einstein' \
    pick \
    cmd 'firefox {doc[url]}'
papis explore dissemin [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>

export

Export retrieved documents into various formats.

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

papis explore \
    crossref -m 200 -a 'Schrodinger' \
    export --format yaml lib.yaml
papis explore export [OPTIONS]

Options

-h, --help

Show this message and exit.

-f, --format <fmt>

Format for the document

Options:

bibtex | json | typst | yaml

-o, --out <out>

Outfile to write information to

isbn

Look for documents using isbnlib.

For example, to look for a document with the author “Albert Einstein” and open it with Firefox, you can call

papis explore \
    isbn -q 'Albert einstein' \
    pick \
    cmd 'firefox {doc[url]}'
papis explore isbn [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
-s, --service <service>
Options:

default | goob | openl | wiki

json

Import documents from a JSON file.

For example, you can call

papis explore json ‘lib.json’ pick

papis explore json [OPTIONS] JSONFILE

Options

-h, --help

Show this message and exit.

Arguments

JSONFILE

Required argument

lib

Query for documents in your library.

For example, to query all the documents containing “einstein” in the “books” library, you can call

papis lib -l books einstein pick
papis explore lib [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--doc-folder <doc_folder>

Document folder on which to apply action

-l, --library <library>

Papis library to look

Arguments

QUERY

Optional argument

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
papis explore pick [OPTIONS]

Options

-h, --help

Show this message and exit.

-n, --number <number>

Pick automatically the n-th document

yaml

Import documents from a YAML file.

For example, you can call

papis explore yaml ‘lib.yaml’ pick

papis explore yaml [OPTIONS] YAMLFILE

Options

-h, --help

Show this message and exit.

Arguments

YAMLFILE

Required argument