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 --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 'Schroedinger' \
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 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. This command
accepts a string to issue a general shell command and allows formatting with the
Papis template 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.
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 can 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 --out '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:
updated | published-online | is-referenced-by-count | deposited | score | published | issued | indexed | relevance | published-print | references-count
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 explore 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