XAPERS(1)

💖 XAPERS(1) 💖 personal journal article indexing system

okay bestie, pull up a chair, because this is xapers — straight out of the General Commands Manual section 1, and it's about to become your new obsession. no cap. 🎀

---

✨ SYNOPSIS ✨

xapers command [args ...]

---

🦋 DESCRIPTION 🦋

Xapers is a personal document indexing system, and she is geared towards academic journal articles specifically. what she does, and she does it slayfully:

• fast search of document text AND bibliographic data (which gets synced from online libraries) 📚
• simple document and bibtex retrieval — literally just ask and receive

So here's the vibe. Xapers takes as input document files (as PDF) and source identifiers. Here's what happens to each:

• Documents get copied into a local document store (~/.xapers/docs by default), then the text is extracted from the PDF and fully indexed into a Xapian database. 🔥
• Source identifiers are used to download document bibliographic data from online digital libraries (peep SOURCES below, bestie), which then gets parsed and indexed to prefixed terms in the database. That bibliographic data also gets stored as bibtex in the document store, so retrieval is easy peasy. 🍓

Documents can be arbitrarily tagged. arbitrary!! go feral!!

There's also a curses UI for simple access to your documents (see the view command below, she's iconic 💅). But honestly? Xapers is ultimately a document indexing library, so development of alternate user interfaces is encouraged — go build something, main character. 👑

Underneath all of this, the wonderful Xapian database/search engine is doing the heavy lifting. See http://xapian.org/ for more information.

---

👑 MAIN COMMANDS 👑

These are the main xapers commands, bestie. And for the tea on the supported syntax for <search-terms>, scroll down to SEARCH TERMS.

💖 add [options] [<search-terms>]

Add a document, or update an existing document. You must specify at least one of --file or --source. And if you do provide search terms, they have to match exactly one document — that matching document then gets updated with all the new info you just handed over. Available options, periodt:

• --source=[<sid>|<file>] — Source identifier for the document. See SOURCES below. This may also be a path to a file that contains a single bibtex entry.
• --file[=<file>] — Document file (as PDF) to add. The text of the document will be extracted and indexed, and a copy of the file will be placed in the Xapers document store. If you provide it without a path, xapers will attempt to download the file from the source — assuming the source supports file downloads, iykyk.
• --tags=<tag>[,...] — Initial tags to apply to the document. Multiple tags can be specified, comma separated. 🏷️
• --prompt — Prompt the user for source/file/tags, if not specified. When prompting for source information, input files are automatically scanned for source IDs and any found ids are displayed. so helpful of her.
• --view — View the resulting entry in the curses UI when done. See the viewP command below for more info.

🌸 import [options] <bibtex>

Import an existing bibtex database. Each bibtex entry gets added as a new document. If the bibtex key — or any sources found in the bibtex — matches an existing document, that document is instead updated (which makes this command effectively idempotent, slay). Any "file" fields will be parsed for document files to add. Files can be specified as a single path, or in Mendeley/Jabref format. Options:

• --tags=<tag>[,...] — Tags to apply to all imported documents. Multiple tags can be specified, comma separated. 🎀

🎀 tag +<tag>|-<tag> [...] [--] <search-terms>

Add/remove tags from documents. The -- can be used to separate tagging operations from search terms.

⭐ search [options] <search-terms>

Search for documents in the database. Document information gets printed to stdout.

• --output=[summary|bibtex|tags|sources|keys|files] — Specify which document information to output:
  • summary outputs a single-line summary of the documents (this is the default).
  • bibtex outputs bibtex for all documents (if available).
  • tags outputs all tags associated with documents.
  • sources outputs all sources associated with documents.
  • keys outputs all bibtex citation keys associated with documents.
  • files outputs the full paths to all files associated with documents.

Default is summary.

• --limit=N — Limit the number of results returned to N.

🦋 bibtex <search-terms>

Short for "search --output=bibtex <search-terms>". she's efficient like that.

💜 count <search-terms>

Return a simple count of search results. numbers. cute.

🌈 view [<search-terms>] / show [<search-terms>]

View search results in the curses search UI. Documents matching the search are displayed with their bibliographic information and a short text summary. It lets you manipulate document tags, and retrieve document files and source URLs for viewing (see xdg-open(1) for more info). Initial search terms can be provided, but you can run further searches from within the UI too. While you're in there, type "?" for available commands. ✨

NOTE: At the moment only the top 20 search results are displayed, due to synchronous loading restrictions. This obviously needs to be fixed. 😭

🍓 export <directory> <search-terms>

Copy PDF files of the resulting documents into <directory>, named with document titles when available.

💀 delete <search-terms>

Delete documents from the database. All document files will purged from the document store. gone. deleted. not coming back. 💀

• --noprompt — Do not prompt to confirm deletion of documents.

🧚 restore

Restore a database from an existing xapers root.

---

💅 SOURCE COMMANDS 💅

These commands provide access to some of the source module methods. See SOURCES below, bestie.

sources

List available sources.

source2url <sid> [<sid>...]

Parse a source identifier string and print the corresponding source URL.

source2bib <sid> [<sid>...]

Retrieve bibtex from source for a specified URL or source id, and write to stdout.

source2file <sid>

Retrieve file from source for a specified URL or source id, and write to stdout.

scandoc <file>

Scan a document file (PDF) for source IDs, and print and recognized source ids to stdout. 🔍

---

🌸 SOURCES 🌸

Sources are online databases from which document bibliographic data can be retrieved. In Xapers, online libraries are assigned unique prefixes. The online libraries associate unique document identifiers to individual documents. Run 'xapers sources' for a list of available online sources.

Xapers recognizes document a source identifier, or sid, in two forms:

• full URL — http://dx.doi.org/10.1364/JOSAA.29.002092
• sid of form <source>:<id> — doi:10.1364/JOSAA.29.002092

URLs are parsed into sources and source ids when recognized, and this information is used to retrieve bibtex from the online library databases. The sources and sids for a given document are stored as prefixed terms in the Xapers database (see below).

---

🔍 SEARCH TERMS 🔍

Xapers supports a common syntax for search terms. here's the lore:

Search can consist of free-form text and quoted phrases. Terms can be combined with standard Boolean operators. All terms are combined with a logical OR by default. Parentheses can be used to group operators, but must be protect from shell interpretation. The string '*' will match all documents in the database.

Additionally, the following prefixed terms are understood (where <brackets> indicate user-supplied values):

• id:<docid> — Xapers document ID
• author:<string> — string in authors (also a:)
• title:<string> — string in title (also t:)
• tag:<tag> — specific user tag
• <source>:<id> — specific source id (sid)
• source:<source> — specific source
• key:<key> — specific bibtex citation key
• year:<year> — specific publication year (also y:)
• year:<since>..<until> — publication year range (also y:)
• year:..<until>
• year:<since>..

Publication years must be four-digit integers. fr fr.

See the following for more information on search terms:

http://xapian.org/docs/queryparser.html

---

🌈 ENVIRONMENT 🌈

The following environment variables can be used to control the behavior of xapers:

XAPERS_ROOT

Location of the Xapers document store. Defaults to "~/.xapers/docs" if not specified.

XAPERS_SOURCE_PATH

Path specification for location of additional custom Xapers source modules. Defaults to "~/.xapers/sources" if not specified.

---

🫶 CONTACT 🫶

Feel free to email the author, she'd love to hear from you:

Jameson Rollins <jrollins@finestructure.net>

---

okay that's the whole page, bestie. 💖 this one's a General Commands Manual entry called XAPERS(1) — that's the manual name, that's the page, that's her whole identity. and the footer is just XAPERS(1) again, no version, no date, she's mysterious like that. 🙈 go index something iconic. periodt. 👑✨