.. _quick-guide: Quick guide =========== In this quick guide, we'll create a library, download a couple documents, and then work on them by opening, tagging, updating, exporting, and organising them. In doing so, you will be introduced to the ``papis`` command and a number of its subcommands. These subcommands (which we'll simply call "commands" from now on) are run with ``papis COMMAND`` (where ``COMMAND`` is the command you want). To get a list of all commands, simply run ``papis --help``. If you want to get help with a specific command, check out ``papis COMMAND --help``. Creating a new library ---------------------- You can't manage a library without a library to manage, and so the first thing we will do is create one! You could do this manually by editing the :ref:`configuration file `, but there's a command that will help you get going: .. code:: bash papis init This command will prompt you for some settings, such as the name and location of the library, which programs to use to open files, and so on. All of the settings can be changed by editing the configuration file, so feel free to accept the defaults for the time being and fine-tune them once you have become familiar with Papis. Adding the first documents -------------------------- Let's populate our library next. There are several ways to add a document to your library: you can automatically fetch a document's metadata along with a PDF or add the document manually. Adding documents is done with the ``papis add`` command. Let's start with the automatic method. We will download an example article from arXiv: ``_. The command will download all the data, show the downloaded file, and then (after asking for confirmation) automatically add it to the library: .. code:: bash papis add --from arxiv https://arxiv.org/abs/2404.14339 We have invoked ``papis add`` with the ``--from arxiv`` option, which specifies the ``arxiv`` *importer*. Papis contains various importers, which allow it to get data from a variety of online sources. Finally, we provide the arXiv URL of the document in which we're interested. You can take a look at all the other available importers with ``papis list --importers``. If Papis is missing an importer for some website, you may need to manually download the PDF and enter the metadata yourself. We'll illustrate this by downloading the PDF of Isaac Newton's Principia Mathematica and then adding the file along with some basic metadata: .. code:: bash curl https://www.gutenberg.org/files/28233/28233-pdf.pdf -o principia.pdf papis add principia.pdf \ --set author "Isaac Newton" \ --set title "Principia Mathematica" First, we download the file with ``curl``. We then run ``papis add`` with the filename as the first argument and two instances of the ``--set`` option to manually set the ``author`` and ``title`` (the ``papis add`` command is split over multiple lines with ``\`` just so it displays better in this guide). Finally, a situation that is unfortunately familiar to most: papers behind paywalls. The importer might be able to get the metadata automatically but fail at fetching the PDF. In this case, you might have to get the file yourself. You can use a slightly modified ``papis add`` command if you then want to create an entry in your library: .. code:: bash curl https://www.unicode.org/L2/L2017/17407-frowning-poo.pdf -o poop.pdf papis add poop.pdf --from doi https://doi.org/10.1007/s11192-017-2554-0 First, we're downloading a PDF about the Unicode frowning poop emoji as a substitute for the paywalled paper that you'd have downloaded yourself. We then use ``papis add`` with the ``doi`` importer, which downloads metadata based on an article's ``doi`` identifier (from `Crossref `__). Adding files ------------ You can also add files to existing documents in your library. This can be useful in various situations. For instance, you might have tried to add a document, but Papis couldn't download the relevant file. You then find the file elsewhere and want to add it to the existing document. Or maybe you'd like to add both the PDF and EPUB version of some file to a document. Just to show how this works, let's add the frowning poop emoji PDF once more to the same document (so that we end up with two PDFs attached to it): .. code:: bash papis addto --files poop.pdf mikki The path specified after ``--files`` tells Papis where to find the file. Papis will attach the file to the document that matches the query "mikki" or open the picker if there are multiple matching documents. Listing documents ----------------- All the documents you add end up in folders inside your library. To find out where exactly a specific file is, use the ``papis list`` command: .. code:: bash papis list Here, Papis will open the picker listing all the files in the library. You can further narrow down the results by typing your query. Alternatively, you can use the arrow keys to select the entry you're interested in. You can also use ``ctrl-t`` to select multiple entries. Pressing ``Enter`` will leave the picker and print the paths to the selected documents. As usual, you can optionally provide a query to filter the database: .. code:: bash papis list newton Here, Papis will list only the documents whose metadata matches "newton". Because there is only one such document, Papis skips the picker and directly provides you with the path. If you want to filter in a more specific manner, for instance by a document's title, you can use the following: .. code:: bash papis list title:principia Instead of by "title", you can filter by any other field stored in the Papis library. The :doc:`info.yaml section ` gives an overview of these fields. Opening documents ----------------- Using ``papis list`` to find a document's path to manually open a file gets old quickly. That's why Papis also provides facilities to open documents directly. We can open a document with: .. code:: bash papis open This will work similarly to ``papis list``. If there are multiple matches, Papis opens the picker, and if there is only a single match, the picker is skipped. However, unlike ``papis list``, ``papis open`` doesn't print the path to the document, but opens the attached file. You can narrow down your query just as in ``papis list``: .. code:: bash papis open newton Adding notes ------------ You opened the Principia Mathematica and started reading. Now you want to jot down some notes so that you can review them later. Papis has built-in functionality for this: .. code:: bash papis edit --notes newton We called ``papis edit`` with the ``--notes`` flag, which tells Papis that we want to edit the note file (or create one if it doesn't yet exist). We need to specify ``--notes`` because ``papis edit`` will otherwise open the :doc:`info.yaml ` where Papis stores the document's metadata. The command ends with the query "newton", which we use to select the document in which we're interested. Tagging the documents --------------------- As your library grows, you might want to add tags to keep things organised and searchable. For instance, you could create tags with your documents' keywords, note whether you've read the document, keep track of publishing status, and so on. Let's say you want to add the tag "physics" to all documents by Isaac Newton: .. code:: bash papis tag --append physics newton Or maybe, you want to tag the documents used in a specific project. We could add the tag "project apple" to them using the command: .. code:: bash papis tag --append "project apple" newton Because our tag has white space in it, we had to surround it with ``"``. Updating documents ------------------ You realise that you want to adjust the metadata of the Principia Mathematica document in our library. While "Isaac Newton" is indeed the guy's name, you'd like to be more polite and include his title and rename the author to "Sir Isaac Newton". While the ``papis tag`` command we've discussed previously is specialised for editing tags, the ``papis update`` command can be used to change metadata more generally. We can use it to easily rename the author: .. code:: bash papis update --set author "Sir Isaac Newton" newton The structure of the command might be familiar to you by now. First, we use ``--set author "Sir Isaac Newton"`` to tell ``papis update`` to set the author to what we want, and then we add a query to identify the document we're interested in. Exporting documents ------------------- You're likely using some other piece of software to write text with proper referencing and bibliographies. The most widely supported file format used for these purposes is BibTeX. You can export your Papis library to BibTeX, so that you can then use it elsewhere. To export all documents in the library to a BibTeX file called ``all.bib``, you can use the command: .. code:: bash papis export --all --output all.bib Note the use of the ``--all`` flag. This tells Papis that you want to run the command with all files that match the query. In this case, it means that ``papis export`` creates a ``.bib`` file based on all documents in the library. Without the ``--all`` flag, Papis would instead have opened the picker (as it did in previous examples where we didn't use this flag), allowing you to select the document. To export only a part of the library, for instance all documents that contain the tag "project", you can add a query: .. code:: bash papis export --all --output project_apple.bib tags:"project apple" Papis supports exporting to several formats, which you can check out using: .. code:: bash papis list --exporters Renaming folders ---------------- Papis will automatically name the folders in your library in a reasonable (and configurable) way, but if you want to rename them manually, you're free to do so. For this purpose, Papis offers the ``rename`` command, which changes the name of a document's folder. This can be particularly useful when you've adjusted some document's metadata and would like the folder's name to reflect this. Remember how we changed the author of the Principia Mathematica from "Isaac Newton" to "Sir Isaac Newton"? Let's make that show up in the folder name! It's simple to do this: run ``papis rename``, pick the relevant document, and follow the prompts. Here, you do not need to set anything by hand as Papis regenerates the folder name based on the updated metadata. Alternatively, you could also use the ``--folder-name`` option to set the folder name to whatever you want. Finally, you could also adjust the :confval:`add-folder-name` configuration option so that folders are automatically named according to your preferences. Starting over ------------- You should now know about Papis' basics and be able to use it to organise your library. If you want to start over and add your own documents, you may want to delete the files we've added in this quick guide. You will need to delete the Papis configuration folder and the library you've created when running ``papis init``. This resets everything, so that by running ``papis init`` again, you'll start anew. If you're unsure about the location of the library we've created for this quick guide, run the following command: .. code:: bash papis config --section papis dir The ``papis config`` command can tell you about the state of the Papis configuration. Here, we're asking it to give us the value of the option ``dir`` in the section ``papis``. If you've changed the name of the library when running ``papis init`` you will need to change the section name to your library's name. You can now use ``rm -r`` or your file browser to delete this folder. The Papis configuration folder's location depends on your operating system. You can find out where it is by running: .. code:: bash papis list --paths The folder you'll need to the delete is the one called ``PAPIS_CONFIG_FOLDER``.