Package: zoia
Zoiazoiais a utility to organize your library of academic papers.InstallationYou can installzoiaby running:pipinstallzoiaOrganizationzoiauses a simple, flat layout to organize data.  Every paper is referenced
by a unique citation key (typically shortened to "citekey").  This would be
the same key that you would reference withciteporcitetin LaTeX.
Bibliographic data is by default stored in a SQLite database calledmetadata.dbwhich is located in$HOME/.local/share/zoia.Each paper also gets its own subdirectory in the root directory.  Within each
subdirectory the document (if it exists) is stored asdocument.pdf.  Any
notes associated with the document are stored asnotes.md.  However,zoiaimposes no additional structure on the layout.  If you would like to add
additional files for a paper (e.g., supplementary data, code, or text), you are
free to do so.A sample directory structure might look like this:my_library
         └── einstein05-electrodynamics
             ├── document.pdf
             └── notes.mdCitation key stylezoia's citation key style is based onHarvard
referencing.zoiagenerates citekeys by taking the last names of the first three authors on the
paper and joining them by+, (with a trailing+if there are more than
three authors), followed by the last two digits of the publication year,
followed by a hyphen, followed by the first word of the title (excluding common
words like "the", "a", "on", etc.).ExamplesAuthor(s)TitleYearCitation keyEinstein, A.On the electrodynamics of moving bodies1905einstein05-electrodynamicsEinstein, A., and Rosen, N.The particle problem in the general theory of relativity1935einstein+rosen35-particleAbbott, B. P., et al.Observation of Gravitational Waves from a Binary Black Hole Merger2016abbott+16-obseravtionCollisionsInevitably you will one day try to add two different papers which have the same
auto-generated citation keys.  The default style makes this rare, but does not
guarantee that it will never happen.  When it does,zoiawill add the
characterbafter the year.  For example, suppose a lesser known physicist by
the name of Egbert Einstein had written another, somewhat less revolutionary,
paper in 1905 called "On the electrodynamics of stationary bodies".  If you
tried to add it, it would get a citekey ofeinstein05b-electrodynamics.  If
the citekey with thebalready exists,zoiawill try adding ac, and then
ad, etc. all the way up toz.  If that's still not good enough it will
continue withaa,ab, etc., though pray that things never come to that.Note that the first paper will retain its original citekey --- it won't get anaadded to it.  This is because you may have been using that old citekey in
your papers.  Changing the citekey would break that link.Configurationzoiafollows the XDG standard and stores its configuration data in$XDG_CONFIG_HOME/zoiaif theXDG_CONFIG_HOMEenvironment variable is set.
If it is not set it uses the standard default of$HOME/.config/zoia.
Whatever the directory,zoiakeeps its configuration data in file calledconfig.yaml.UsageInitializationAfter you have installedzoiayou can initialize your library by running:zoia init [directory]This will tellzoiathat your library is going to be stored in the provided
directory.  (Note that this directory must be empty.)  If you don't provide a
directory,zoiawill store your library in your current working directory if
it is empty.  If it isn't empty, it will try creating a subdirectory namedzoiaand will store your library there (assuming that that subdirectory
doesn't already exist).Adding a paperOnce you have initialized your library, you can add items by specifying an
identifier.  The following identifiers are currently supported:arXiv IDsDOIsISBNszoiawill figure out what kind of identifier you've given it on its own:zoiaadd1602.03837
zoiaadd10.1103/PhysRevLett.116.061102
zoiaadd9781400889099It's also fine to include prefixes likearxiv:1602.03837ordoi:10.1103/PhysRevLett.116.061102.zoiawill add the paper's metadata to the.metadata.jsonfile and download
the PDF if it is on the arXiv.  (If you provide a DOI,zoiawill still check
to see if the paper exists on the arXiv and download it if it does.)In the futurezoiawill also support adding papers by their PDFs directly.Opening a paperYou can open the PDF of a paper in your library from its citekey by running:zoia open <citekey>This will open the PDF using your default PDF viewer.  In the future it will be
possible to also open the PDF based on the arXiv ID, DOI, or ISBN.Taking notes on a paperzoiakeeps your notes for a paper in a Markdown file callednotes.mdin
that paper's subdirectory.  You can edit that file in your default editor by
running:zoia note <citekey>Editing a paper's metadataIf there is an error in a paper's metadata, you can edit it by running:zoia edit <citekey>By defaultzoiawill present the data in JSON format, but if you prefer YAML,
you can specify that with the--syntax=yamloption.SynchronizationAlthoughzoiadoes not natively support synchronization across multiple
devices at the moment, its simple data structure makes it easy to use with
third-party synchronization software.  In particular I recommend usingSyncthingfor this purpose.  By pointing Syncthing at
the directory containingzoia's library on both devices you can keep your
library synchronized.About the namezoiais named in honor of the librarianZoia
Hornwho spent her life fighting for
intellectual and academic freedom.