Skip to content

Latest commit

 

History

History
3040 lines (2598 loc) · 174 KB

README.org

File metadata and controls

3040 lines (2598 loc) · 174 KB
Raw

Table of contents

1 Introduction

Managing knowledge of related literature is an important activity for both graduate students and researchers. A central piece of this activity is maintaining notes both about individual research papers and, more importantly, about whole branches of research. Notes that cover branches of research are extremely useful. These notes are tools for uncovering connections between papers and discovering venues for new research. The purpose of LiteRef is to provide a thin layer of software that would make it natural and easy to collect papers, maintain notes about both individual papers and branches of research, explore connections between papers and export all or part of this body of knowledge into a coherent document.

There are many software packages for reference management out there. The main difference between LiteRef and these packages is the focus. While the focus of existing reference management software is on maintaining the database of bibliography entries, the focus of LiteRef is on providing the researcher with tools that would aid him in growing his understanding of the research field. Consequently, LiteRef is centered around the notes written by the researcher.

LiteRef runs under Emacs, an extremely powerful and flexible text editor. In particular, Emacs comes with an awesome major mode for organizing notes called org-mode. LiteRef harnesses the power of org-mode and several other packages (most notably org-ref) to put at the researcher’s disposal a potent tool for maintaining his knowledge of related literature.

LiteRef offers:

  • A variety of means for importing BibTeX entries into the database and performing actions on these entries. In particular, BibTeX entries can be fetched from an extensible set of online resources. Also, one can import entries for all the papers in a given journal volume or conference proceedings. This feature supports maintaining an edge in the knowledge of the papers in the narrow specialization of the researcher. The researcher can conveniently track his progress on studying the imported papers.
  • Powerful tools for citing papers and for intelligently handling citations in org-mode notes maintained by the researcher.
  • Automated fetching of paper PDFs from an extensible set of online resources.
  • Specialized org-mode links enabling references to a particular annotation in a paper PDF from a notes file. The annotations themselves are handled by the awesome pdf-tools package for Emacs.
  • Automated generation of bibliography for export and powerful synergies with the standard org-mode tools such as narrowing to sub-trees and inclusion directives.
  • Annotation of citations by their role. This seemingly trivial feature gives raise to some of the most powerful features of LiteRef. In particular, the annotated citations in the notes associated with the research papers induce a citation graph, whereby related papers are connected by arcs labeled by citation functions.
  • A general way of defining a citation subgraph, which is a subgraph of the citation graph possibly augmented with papers cited in an arbitrary buffer.
  • The ability to obtain much insight by visualizing the citation subgraph.
  • The ability to restrict the action of several commonly used activities such as searching for papers to the citation subgraph.
  • Advanced export that integrates all the notes relevant to the citation subgraph into a coherent document. Thus, one can quickly obtain a well-formed survey of a branch of his research area.

The following sections describe both the overall design of LiteRef and its features. Each feature’s description is accompanied by a short video demonstrating the feature’s usage.

2 The overall design

The purpose of this section is to describe the conceptual design of LiteRef and thereby make reading the sections that describe particular features comfortable.

2.1 Physical structure

As far as the user is concerned, two folders in the distribution are of interest: papers/ and drop/. As suggested by their names, the papers/ folder contains the database of papers, while the drop/ folder is the place where new BibTeX and PDF entries are to be deposited for subsequent handling by LiteRef.

The database of papers has a very simple structure, whereby each paper gets a folder whose name is the key of that paper’s BibTeX entry (LiteRef generates these keys automatically). A paper’s folder contains at least two files: paper.bib (the BibTeX entry of the paper) and paper.org (the researcher’s notes about the paper). In addition, it may contain paper.pdf (the PDF of the paper) and any other files that the researcher wishes to associate with the paper.

LiteRef does not impose any restrictions on the format of the notes. Thus, all the arsenal of org-mode is put at the researcher’s disposal. In addition, the researcher can maintain any number of survey notes, which can reside anywhere in the file system. Such notes are usually dedicated to branches of research rather than to a particular paper.

2.2 Import of entries

Insertion of a new BibTeX entry into the LiteRef database is triggered by the appearance of a .bib file in the drop/ folder and handled by the server written in Python. This can happen in a large number of ways from manual creation of this file to automated search in online sources. Whatever way is chosen, each BibTeX entry in the new .bib file receives an automatically generated key. This key consists of three parts:
  • The last name of the first author followed by a capital first letter of each co-author’s last name,
  • Year of publication followed by a letter signifying the type of venue, e.g. 2000c (a conference proceedings in 2000) or 2005j (a journal volume in 2005).
  • Two (possibly abbreviated) words from the title.

After duplicate detection, the new entries are entered into the database. Both paper.bib and (an empty) paper.org for each of the new entries are created at this point.

Searching for a PDF file is triggered by trying to open a paper’s PDF file in any one of the ways described below and is handled by the server as well. When this happens, if the drop/ folder contains PDF files, these become the first candidates. If the user rejects these candidates, automated search in the online sources ensues.

The online sources for searching for BibTeX and PDF files are defined in an extensible way in the online_sources.py module of the server. This module documents in detail how one can extend the set of online sources with sources of his own. If such an extension takes place, it is up to the user to respect the terms of service of whatever sites are searched. The author of LiteRef does not assume any responsibility for violations.

Note that changes in the format of the HTML pages and in the access policies of the online sources may break the ability of LiteRef to import from those sources. As of 13.11.2018, import from both DBLP and Semantic Scholar (of both BibTeX entries and paper PDFs) works well, while Google Scholar blocks access.

2.3 The user interface

Most features of LiteRef are implemented in Emacs Lisp. These features use uniquely Emacs ways for doing things. These ways may come as a surprise to an uninitiated user, but inevitably prove to be extremely time-effective. Once having got used to using Emacs properly, one rejoices for the rest of his life at having found the ultimate tool for everything related to editing text, maintaining notes and too many other tasks to list. LiteRef adds maintaining knowledge of related literature to these tasks.

The functionalities related to watching the drop/ folder and creating/fetching new entries are delegated to the server. In contrast to actions executed entirely inside Emacs, the server relies on dialog windows for its features’ user interface. One positive effect of this difference is that the user can visually and easily distinguish a candidate BibTeX entry or PDF that has just been found and downloaded automatically from an entry that is already in the LiteRef database. Thus, the overall user experience only wins from this non-uniformness of presentation means.

2.4 Paper citations

The features that distinguish LiteRef are centered around working with paper citations. A paper is cited using the org-ref citation link, which consists of cite: (or its derivatives, such as citea: etc.) followed by the keys of the BibTeX entries of the papers being cited, e.g. cite:AbrahamDGW2011c-Hub-Based,ChakrabortiSSKK2016c-Compl-Condit. In most cases, one would cite a paper by searching for it using helm, which is the Emacs way of searching in a large collection of candidates by gradually narrowing the candidate set. The candidates for this search can be either the whole paper database or the papers that form the current citation subgraph. Once some paper citations are added, a number of features of LiteRef dedicated to making the editing tasks related to paper citations effective are available.

Besides the paper citations, two other types of links are at the user’s disposal. First, a paper citation can be followed by a list of citation functions, e.g. cite:AlfeldZB2016c-Machin-Teach f:develops,compares. Citation functions allow the researcher to characterize the relationships between the two papers. For example, suppose the notes for the paper X cite the paper Y. This citation could signify that X develops the ideas of Y, that the ideas presented in X bear a degree of resemblance to those of Y, that X compares its results to those of Y etc. LiteRef leaves it to the researcher to define the list of legal citation functions. One can either come up with his own list or use an existing set of citation functions such as the Citation Typing Ontology. Once such a list is defined, LiteRef makes inserting citation function links convenient. As mentioned earlier, citation function links are utilized by LiteRef to provide functionalities related to the citation (sub-)graph.

Second, a paper’s notes can contain links to particular annotations in the paper’s PDF. This feature allows the researcher to easily relate his comments to particular clauses in the paper.

3 Features

This section describes the features of LiteRef in detail.

3.1 Importing BibTeX entries

There are several ways to import a new BibTeX entry into the database of LiteRef.

3.1.1 By putting a .bib file into the drop/ folder.

The most direct way to import BibTeX entries into the database of LiteRef is to either download or copy the corresponding .bib file into the drop/ folder. Should you like to write the new BibTeX entries from scratch, the .bib file can be either created directly in the drop/ folder or in another location and then copied over. The following actions are performed automatically as soon as a new .bib file appears in the drop/ folder:
  • The BibTeX entries are extracted.
  • The key for each BibTeX entry is generated.
  • All the BibTeX entries are added into the database subject to duplicate detection. In case a duplicate is detected, the user may choose to keep both entries, in which case the key of the new entry is modified to guarantee uniqueness. One practical case when a need for this feature may arise is when the new entry refers to an extended abstract of the full-size conference paper that is already present in the database.
    • Note that all the added entries get the same creation time stamp. This makes a difference when ordering papers by multiple criteria as described below.
  • The list of newly added keys is put into the clipboard, so the papers can be immediately cited in the notes by invoking the yank command (yanking is the Emacs term for pasting), which is typically bound to C-y.

3.1.2 By copying a BibTeX entry into the clipboard

With some sites, it is easier to put a BibTeX entry into the clipboard than to download/create a .bib file. The literef-bibtex-from-clipboard command (bound by default to C-c c) caters to this case.

3.1.3 By searching in online sources

The literef-get-region-bibtex command (bound by default to C-c g) searches for a BibTeX entry corresponding to the text in the active region. The region can be either in a regular Emacs buffer (e.g. in a notes file) or in a PDF buffer. The latter is the most widespread use case, since most often the researcher becomes interested in a paper that is cited in the paper currently being studied. When the selected region consists of multiple lines with words split between the lines, LiteRef forms the single-line query intelligently. That is, it uses spell checking to determine whether the hyphen should be kept or removed. It defers to the user’s help only in case of doubt (i.e. when both the hyphenated and the „glued“ versions are spelled (in)correctly).

The researcher can configure LiteRef to search several online sources. This is done by appropriately setting the BIB_AUTOMATED_SOURCES variable in config.py. In addition, the user can set the BIB_MANUAL_SOURCE variable of the server. When this variable is set and the automated search does not come up with the desired BibTeX entry, LiteRef will open the browser for searching in the specified source manually.

The currently implemented online sources for BibTeX entries are Google Scholar, Semantic Scholar and DBLP. The user can add more online sources by extending online_sources.py with classes that implement interfaces documented in that module.

3.1.4 By downloading an HTML containing a number of papers

Suppose that there is a venue that publishes papers in the narrow specialization of the researcher. The researcher needs to be knowledgeable about all the papers appearing in that venue. He may even want to dedicate a special notes file, in which papers from this venue will be represented and organized. (We will see below that LiteRef makes it easy to track his progress on studying these papers as well.)

To cater to the above scenario, LiteRef can handle .html files downloaded into the drop/ folder. LiteRef extracts from such an HTML links to BibTeX entries and downloads the entries themselves. Of the implemented online sources, only DBLP is currently supported by this feature.

Note that downloading hundreds of BibTeX entries may take a while (up to a few minutes). LiteRef does not show the progress of downloads, since, in order to re-use connections, all of the BibTeX entries are downloaded with a singe invocation of wget. Running the following command from the terminal (while in the LiteRef root folder) will show the downloaded files: grep "Saving" drop/temp/wget.log.

3.2 Working with citations

Most of the functionalities of LiteRef are centered around citations. In this section, we focus on the tasks of finding the keys to cite, editing the text containing citations, splitting a list of citations and working with the currently active citation or paper.

All the functionalities presented in this and further sections work with all types of citation links supported by org-ref and described by the variable org-ref-cite-types. The video demos of this section were recorded before this enhancement and use cite: links exclusively. The demo in the below section on advanced export capabilities of LiteRef shows the use of other types of citation links.

3.2.1 Searching the papers database

LiteRef inherits from org-ref and significantly improves the org-ref-insert-link command (bound by default to C-c ]) for inserting a citation.

Just like it’s predecessor, the command uses the helm interface for finding candidates by iterative process of filtering. LiteRef helps make this process more effective by extending the sorting capabilities to support multiple criteria. Just like in org-ref, the sorting is bound by default to M-<down> (M stands for the Meta key, which is Alt on most keyboards). For example, one can access the recently added entries by sorting the candidates on the date and time of creation (which is taken to be the date and time of the last update of paper.bib for that entry; entries added within a small time margin, which is two seconds by default, of each other are considered to be added at the same time to enable sorting papers that were imported together on additional criteria).

As in org-ref, one can select (by pressing C-<SPACE>) and cite multiple papers. If the configuration variable literef-sort-citation-links is not nil, the cited papers are sorted on the criteria encoded in the string value of literef-citation-link-sorting-criteria.

Note that one can perform actions other than inserting a citation on a candidate (this is done by pressing <TAB> while the candidate is active).

One can also insert citations based on searching for a given string in the first page of all the paper PDFs contained in the LiteRef database. This is done with the literef-search-pdfs command. The following demo shows how to find all papers written by researchers from Toronto (e.g. in order to establish contacts with the researchers from Toronto working in his area).

3.2.2 Intelligent handling of copying and pasting citations

When a (multi-)paper citation is inserted as shown above or a BibTeX entry’s key is yanked from the kill ring (which is the Emacs way of storing multiple pieces of text for future use) on top of an already existing citation, LiteRef makes sure that a well-formed multi-paper citation results. If automated ordering of citation is enabled (i.e. literef-sort-citation-links is set to t), then the keys will be sorted on the criteria specified by literef-citation-link-sorting-criteria. The order of keys appearing in a multi-paper citation can be changed at any time by invoking the literef-sort-citation-link command (bound by default to C-c <down>). This command offers the multi-criteria sorting capability familiar to the reader from the above section on searching the papers database. The literef-sort-citation-links command (not bound to a key by default) can be used to re-order all the citation links in the current buffer.

In addition, LiteRef offers the literef-copy-current-key command (bound by default to C-c w), which puts the currently active citation key into the kill ring. When used in conjunction with helm-show-kill-ring and bookmarks (which are one of those many tools Emacs has to make your life easier once you discover them), one can easily collect citations scattered all over his notes.

Note that automated ordering of keys in multi-paper citations may affect the operation of the yank-pop command. However, given the superior convenience offered by helm-show-kill-ring, this limitation should not discourage one from using automated ordering of citation keys.

3.2.3 Splitting a multi-paper citation

Many a time it helps to organize a notes file such that each paper under study is given a headline or a list item. In LiteRef, this is easy to achieve by splitting a multi-paper citation using either literef-split-cite (bound to C-c d by default) or literef-split-cite-title-author (bound to C-c s by default). The latter adds authors and title to each paper. Both commands replicate the context of the original multi-paper citation (i.e. the preceding and the following text) with each resulting single-paper citation.

In addition, when the original multi-paper citation appears as a list item, LiteRef will offer to create an org-mode inline task for each paper.

3.2.4 Actions on a paper

To bring the actions menu associated with a cited paper, one needs to simply follow the citation link. This can be done either by pressing C-c C-o when the cursor is on the link or by mouse-clicking the link. The actions menu allows the user to open the BibTeX entry, the notes or the PDF associated with the paper. An additional recently added action is for building a citation subgraph rooted at the paper.

When the cursor is located over a citation or the active buffer is visiting a file associated with the paper, each of the above actions can be invoked with a command:

  • literef-open-bibfile for opening the BibTeX entry is bound by default to C-c b.
  • literef-open-notes for opening the notes is bound by default to C-c n.
  • literef-open-pdf for opening the PDF is bound by default to C-c o. The next section describes what happens when the PDF for the paper has not yet been added to the LiteRef database.
  • literef-select-subgraph for building a citation subgraph rooted at the paper is bound by default to C-c u.

These commands can also be invoked for an active candidate when searching the papers database.

3.3 Importing PDF of a paper

LiteRef takes a lazy approach to adding paper PDFs to the LiteRef database. Namely, importing a PDF is initiated when the user tries to open a PDF that is not currently in the database. The search for the needed PDF proceeds in three stages:
  1. If one or more PDF files exist in the drop/ folder, the user is asked about each one of them whether it is the one being sought. If the answer for one of these PDFs is positive, that PDF is added to the database and opened. Otherwise, the next step is taken.
  2. The PDF is searched for in the online sources defined by the PDF_AUTOMATED_SOURCES configuration variable of the server. The currently implemented online sources for PDFs are GoogleScholar and SemanticScholar. The user can add more online sources by extending online_sources.py with classes that implement interfaces documented in that module. If a matching PDF is found and confirmed by the user, it is added to the database and opened. Otherwise, the next step is taken.
  3. If the PDF_MANUAL_SOURCE configuration variable of the server is not None, LiteRef opens the browser for searching in the online source specified by that variable. Once a new PDF appears in the drop/ folder, LiteRef asks the user to match it with one of the BibTeX entries for which manual download of a PDF had been requested. If none of the entries is matched, the downloaded PDF remains in the drop/ folder for future use, e.g. as described in the first step above.

3.4 Working with PDF

When it comes to working with the PDF of a paper, the rendering speed and features of the pdf-tools package of Emacs are prodigious. LiteRef integrates with the annotation capabilities of pdf-tools by providing the literef-cite-pdf-annotation command (bound by default to C-c a) for linking directly from the researcher’s notes to PDF annotations. Upon the command’s invocation, the user chooses among the currently visited paper PDFs using the uniquely Emacs Interactively Do Things interface. The buffer visiting the chosen PDF becomes active and a single click is needed to choose the target annotation. Following that choice, the link to the PDF annotation is inserted at the point of the cursor in the notes buffer that was active at the time of invoking the command and that buffer becomes active again. If another kind of a buffer was active, the link is saved in the kill ring.

Following a link to a PDF annotation results in opening the corresponding paper’s PDF and jumping directly to the annotation.

3.5 Basic export of notes

LiteRef extends the functionality of the org-export-dispatch command. In its original form, this command was already capable of exporting notes in a variety of formats, including LaTeX and PDF. LiteRef extends the capabilities of this command, so that:
  • The bibliography based on the citations found in the buffer being exported is automatically built. The underlying bibliography file created by LiteRef contains only the papers that appear in the bibliography, ordered by the increasing order of the BibTeX key. The bibliography style and the bibliography package used for LaTeX export are determined by the configuration variables literef-bibliography-style and literef-bibliography-package, respectively.
  • Links to PDF annotations are replaced with references to page numbers.
  • Citation functions are removed.

In addition to this command, LiteRef provides a much more powerful command for exporting, which we discuss below.

Two facilities can be particularly powerful when used in conjunction with the export feature of LiteRef:

  • Narrowing is a standard Emacs feature, whereby only part of the buffer is visible both to the user and to the commands. In addition to this standard narrowing, org-mode has the org-narrow-to-subtree command (bound by default to C-x n s), which narrows the buffer to the current headline. When each headline in the notes buffer is dedicated to a research (sub-)area, one can easily focus on that (sub-)area by narrowing the buffer to the corresponding headline. Since a subsequent export command would respect such narrowing, one can easily export notes pertaining to the part of his survey dedicated to the (sub-)area of interest.
  • One of the keywords understood by org-mode is #+INCLUDE, which allows one to include an external file or a portion of it at the time of export. This allows the researcher to organize his notes into a collection of files, while still being able to collect these notes together for export.

3.6 Defining and using citation functions

The functionalities of LiteRef that aid the researcher in grasping the overall state of research in a given area are based on the notion of a citation function. Citation function is the role that the cited paper plays in the paper that cites it as reflected in the notes on the latter paper. For example, suppose that a paper X cites a paper Y, because X develops the ideas of Y. The researcher can reflect this in the notes on X by citing Y while specifying the citation function corresponding to the role of developing the ideas of the cited paper. It can look something like this: cite:Y f:develops-ideas.

The set of citation functions in use is defined by the configuration variable literef-citation-functions. The citation functions can be conveniently inserted into the notes by using the literef-citation-function command (bound by default to C-c f).

3.7 The citation (sub-)graph

3.7.1 The notion of the citation graph

The most powerful features of LiteRef are based on the observation that the papers and the citations (possibly labeled with citation functions) induce a directed graph with labeled arcs. This graph is called the citation graph. The vertex set of the citation graph is the set of all papers in the LiteRef database. If the notes for a paper A cite a paper B and this citation is labeled with citation functions F1, F2, …, Fn, then there is an arc in the citation graph from A to B labeled by the set {F1, F2, …, Fn}. If the notes of A cite B without specifying citation functions, the arc from A to B is labeled with the empty set. It is convenient, though not totally accurate, to call such an arc unlabeled and we do so hereafter. If the notes for A cite B multiple times, then the arc from A to B is labeled by the union of the labels induced by each citation.

LiteRef maintains the citation graph automatically. Namely, the citation graph is computed at the beginning of the Emacs session and updated whenever a notes file is saved.

3.7.2 The notion of the citation subgraph

The citation subgraph is a subgraph of the citation graph induced by a subset of the papers in the LiteRef database, possibly appended with a vertex corresponding to an Emacs buffer and the (unlabeled) arcs corresponding to the citations in that buffer.

At any given time, there is a single active citation subgraph, called the selected subgraph. When the Emacs session begins, the selected subgraph is the whole citation graph. This subgraph can be selected again at any time by invoking the literef-subgraph-reset-selection command.

All the operations described below work with the selected subgraph. In principle, this design allows working with multiple subgraphs, one being selected at a time. However, this is not yet supported.

3.7.3 Building a citation subgraph

A citation subgraph is built by invoking the literef-select-subgraph command bound by default to C-c u. This command performs a uniform-cost search, with the root being either the active paper (i.e. the paper whose link is under the cursor or whose associated file is being visited by the active buffer) or (if there is no active paper) all the papers cited in the active buffer. The user can specify a filter for the arcs to be followed by the search. These arcs are called the generating arcs of the resulting subgraph, which is induced by the papers reached by the search.

The filter on the arcs is an expression in Emacs Lisp. This expression is evaluated for each candidate arc. A candidate arc is followed if and only if the filter evaluates to a value other than nil. When writing the filter, one can use the following variables:

  • The variable named after a citation function. This variable’s value is t if and only if the candidate arc’s label contains the corresponding citation function. Otherwise, it is nil. For example, if a citation function develops-ideas is defined, then the variable develops-ideas indicates whether the candidate label contains this specific citation function.
  • in, which is t if and only if the candidate arc is incoming. Otherwise, it is nil.
  • out, which is t if and only if the candidate arc is outgoing. Otherwise, it is nil.
  • depth, which is the current depth of the search. The papers at the root of the search are at depth 0. The arcs (traversed either along or against the direction of the arc) leaving the root of the search are at depth 1, etc.

Here is an example of a filter: (and (or (and develops-ideas (< depth 3)) compares-results) out). This filter says that we would like to follow the arcs having the develops-ideas citation function in their label up to depth 2 and the arcs with the compares-results citation function in their label regardless of the depth. Furthermore, we would like to follow only the outgoing arcs.

Basing arc filters on Emacs Lisp expressions augmented by special variables allows for great flexibility in specifying the citation subgraph.

The demonstration of selecting the citation subgraph is deferred to a later section that introduces the capabilities of LiteRef for visualizing the selected subgraph.

3.8 Operations on the citation subgraph

The operations on the citation subgraph are simple and yet very potent. The below descriptions reflect the simplicity of these operations, while the demonstrations reveal some of their potential applications.

3.8.1 Visualization

Visualization of the citation subgraph allows the researcher to view a whole research area as represented by the selected subgraph at a glance. LiteRef provides two ways of visualization:
  • textual by means of the literef-show-selected-subgraph command (bound by default to C-c v). This command visualizes the selected subgraph in an org buffer. This allows the nodes in the visualization to contain regular citation links that support all the operations described above. In addition, the visualization can be scrolled by pressing an arrow while holding the Meta key.
  • graphical by means of the literef-show-selected-subgraph-png command.

Whichever of the two commands is used, two configuration variables control the information that appears in the visualization:

  • When literef-subgraph-show-only-generating-arcs is set (i.e. is not nil), the visualizations shows only the generating arcs of the selected subgraph. This variable is nil by default.
  • When literef-subgraph-show-buffer is set (i.e. is not nil) and the selected subgraph was built by searching from a buffer rather than from an active paper, the source buffer is shown as a node of the selected subgraph. This variable is nil by default.

The two ways of visualization are demonstrated by the following two demos.

3.8.2 Search

The literef-subgraph-helm command (bound by default to C-c )) operates similarly to the org-ref-insert-link command explained above with the exception that the set of candidate papers is limited to the current citation subgraph.

3.8.3 Export

We already described above how LiteRef extends the functionality of the org-export-dispatch command. The literef-subgraph-export-dispatch command goes further – it performs export of the citation subgraph. The document for export is constructed in a temporary buffer using the following algorithm:
  • The document is initialized based on the subgraph’s source (i.e. the root of the search for building the citation subgraph). In particular:
    • If the subgraph’s source is a buffer, the document is initialized to the contents of that buffer. However, if the source buffer does not exist or is visiting a different file, then the contents of the file visited by the source buffer at the time of building the subgraph is used instead. In any case, the name of that file is used to compute the name of the exported document.
    • If the subgraph’s source is a paper or the literef-select-subgraph command for building the subgraph has not been invoked after the last reset of the subgraph, then the document is initialized to be empty. The user is requested to provide the name of the exported document. Depending on the source, the default folder is either the folder of the source paper or the value of the configuration variable literef-survey-directory.
  • The document is appended with the notes for the papers in the citation subgraph. Notes of each paper appear in a section of their own. The title of that section consists of the paper’s title and authors, followed by the citation link to the paper. Empty sections, i.e. sections dedicated to papers with empty notes, do not appear.
  • Optionally, a section containing all the notes as subsections can be created. This may be desirable when the subgraph’s source is a buffer containing several headlines.
  • The #+INCLUDE directives are expanded.
  • A reference to the appropriate notes section is supplied for each paper citation. These references will conveniently become hyperlinks in the exported document.
  • Links to PDF annotations and citation functions are handled just like during the basic export.
  • The bibliography is created. The underlying bibliography file contains only the papers cited in the document.

3.8.4 Visualization in export

The researcher can put visualizations of various parts of the citation graph into the exported document, both for the basic and for the subgraph export. This is done by inserting a code block that calls the literef-subgraph-image-file-link function, which builds a subgraph, saves its graphical visualization into a temporary file and returns a link to that file along with the necessary attributes for export. Although this function takes quite a few arguments, LiteRef makes things easy by providing the literef-insert-subgraph-image-file-link command, which is basically a wizard for constructing a call to literef-subgraph-image-file-link. Once the researcher provides the information requested by this command, the corresponding code block is inserted automatically.

Lastly, the user should remember that the export features discussed in this manual are not limited to exporting into LaTeX or PDF. In particular, the researcher can put exporting into HTML to good use for sharing his knowledge with students and colleagues.

4 Installation

Please use the instructions for automated installation, unless your system does not use the apt manager or some other circumstances necessitate a manual install.

4.1 Automated installation

LiteRef comes with the installaction script install.sh. Simply run this script and you are all set. The script will:

  • use the apt manager to install all the package dependencies of the server,
  • install the pip manager and use the latter to install all the needed Python libraries and
  • set up Emacs configuration for LiteRef.

When you run Emacs with the proper configuration (e.g. set up by the installation script), the needed Emacs packages will be installed automatically.

4.2 Manual installation

In case manual installation is required (e.g. if your system does not use the apt manager), you will need to install the following packages (only the packages not installed by default in Ubuntu 18.04 LTS, as well as pip, are listed). To install these packages, you will need to use the equivalent of the commands provided in parentheses.

  • pip (sudo apt install python-pip)
  • Tkinter (sudo apt install python-tk)
  • pdfgrep (sudo apt install pdfgrep)
  • xsel (sudo apt install xsel)
  • Graph::Easy (sudo apt install libgraph-easy-perl)
  • Graphviz (sudo apt install graphviz)
  • epdfinfo (sudo apt install elpa-pdf-tools-server)
  • TexLive (sudo apt install texlive-latex-base)
  • TexLive extras (sudo apt install texlive-latex-extra)
  • bibtex (sudo apt install texlive-binaries)
  • ChromeDriver (download from here and put the executable into a folder listed in PATH)
  • Google Chrome (as detailed here)
  • pyinotify (sudo pip install pyinotify)
  • flufl.enum (sudo pip install flufl.enum)
  • PybTex (sudo pip install pybtex)
  • requests (sudo pip install requests)
  • Selenium (sudo pip install selenium)

LiteRef relies on the following Emacs packages:

  • org (version 9.0 or newer, so that the built-in package may not suffice)
  • org-ref
  • pdf-tools (you will need to run the pdf-tools-install interactive command in Emacs after installing the package from the package manager)
  • smooth-scrolling
  • company

4.3 Manual configuration

The following lines need to appear in the Emacs configuration file:

(require 'package)
(package-initialize)
(setq literef-directory "/home/meir/LiteRef/")
(add-to-list 'load-path (concat literef-directory "el/"))
(load-file (concat literef-directory "el/literef.el"))

Please make sure to edit the path in the definition of literef-directory.

5 Version and license information

  • Version: 1.0
  • Author: Meir Goldenberg ([email protected])
  • Copyright: GNU General Public License

6 Bug reports and future work

Please send bug reports and feature requests to the author. The current list of requested features and bug reports can be found in the files future.org and bugs.org in the root folder of LiteRef.

7 The API

The following API documentation follows Emacs Lisp conventions:

  • Function descriptions typeset formal arguments in all capital letters.
  • Function descriptions describe the formal arguments inline rather than starting the description of each parameter on a separate line.
  • Optional arguments are separated from the obligatory ones by the keyword &optional in the function signature.
  • The name of an unused formal argument begins with an underscore.
  • The formal argument named orig-fun is accepted by functions that modify (see Advising Emacs Lisp Functions) existing functions. This argument stands for the original function.

The Emacs Lisp terminology used most frequently:

Please follow this link to the documentation of the server API.

7.1 Module literef.el

This module loads all the features of the system, starts the server and performs some general setting up tasks.

7.1.a Functions

7.1.a.1 literef-completion-fallback-candidates(_orig-fun)

The LiteRef version of bibtex-completion-fallback-candidates. It simply returns bibtex-completion-fallback-options without appending this list by all the BibTeX files.

7.1.a.2 literef-install-packages

Install any missing packages. The code is taken from https://stackoverflow.com/a/10093312/2725810.

7.1.b Variables

No variables are defined by this module.

7.2 Module literef-citation-functions.el

This module defines the citation functions link and functions for computing its help echo and for providing a convenient completing read interface for entering the citation functions.

7.2.a Functions

7.2.a.1 literef-citation-function

Annotate the currently active citation link with user-selected citation functions.

7.2.a.2 literef-citation-function-help-echo(_window _object position)

Compute the help echo that appears when hovering over a citation function link. This particular implementation only uses POSITION of the mouse. The technique is described at http://kitchingroup.cheme.cmu.edu/blog/2016/11/04/New-link-features-in-org-9/#org1c56ce9.

7.2.a.3 literef-input-functions

Prompt the user to input citation functions using the completing read interface. Returns the list of selected citation functions.

7.2.b Variables

No variables are defined by this module.

7.3 Module literef-citation-link.el

This module contains functions that handle citation links and operations involving them: hovering over, clicking, splitting, ordering keys and others.

7.3.a Functions

7.3.a.1 literef-after-citation-type-p

Return t if point is after a citation link of any kind (e.g. citeauthor:) and nil otherwise.

7.3.a.2 literef-after-string-p(string)

Return t if point is after STRING and nil otherwise.

7.3.a.3 literef-bibtex-from-clipboard

Create an entry in the papers database from the BibTeX entry currently in the clipboard.

7.3.a.4 literef-cite-onclick-function

Handle following a citation link by offering a menu of actions that can be performed on the link.

7.3.a.5 literef-copy-current-key

Save the current key for later intelligent yanking.

7.3.a.6 literef-insert-for-yank(orig-fun string)

The version of insert-for-yank that handles the keys being yanked intelligently.

The STRING to be yanked is preceeded by the prefix computed as follows:

  1. Split the contents being yanked based on commas and analyze the first entry. If it is not a valid key, the prefix is empty. Otherwise, proceed to step 2.
  2. If over a citation key, go to its end and set the prefix to be comma.
  3. Otherwise, if the point is right after comma that follows a citation key or after a citation type (e.g. citeauthor:), the prefix is empty.
  4. Otherwise, the prefix is “cite:”.

After the original function is called for the prefixed STRING, the current citation link (if the cursor is over one) is sorted subject to the value of the variable literef-sort-citation-links.

7.3.a.7 literef-key-string(key)

Compute a string consisting of title and author based on the KEY.

7.3.a.8 literef-sort-citation-link(&optional no-read-criteria criteria)

Sort keys in the current citation. The sorting criteria are read from the user, unless the optional NO-READ-CRITERIA is set. If NO-READ-CRITERIA is set, then, if CRITERIA is set as well, it is used as the sorting criteria. Otherwise, the value of the variable literef-citation-link-sorting-criteria is used as the sorting criteria.

7.3.a.9 literef-sort-citation-links(&optional no-read-criteria)

Sort all citation links in the current buffer. The sorting criteria criteria are read from the user, unless the optional NO-READ-CRITERIA is set, in which case the value of the variable literef-citation-link-sorting-criteria is used as the sorting criteria.

7.3.a.10 literef-sort-keys(keys criteria)

Sort KEYS according to CRITERIA, which can be either a string or a list of characters as in the variable literef-citation-link-sorting-criteria.

7.3.a.11 literef-split-cite

Like literef-split-cite-title-author, but without prepending each citation with title and author.

7.3.a.12 literef-split-cite-raw(insert-title-author)

Split the first multi-paper citation found on the current line, so that each paper is cited on a separate line, while the text preceeding and succeeding the original citation is duplicated on each line. Insert information about title and author before the key if INSERT-TITLE-AUTHOR is not nil.

7.3.a.13 literef-split-cite-title-author

Split the first multi-paper citation found on the current line, so that each paper is cited on a separate line, preceeded by the information about title and author. The text preceeding and succeeding the original citation is duplicated on each line. Insert information about title and author before the key.

7.3.b Variables

No variables are defined by this module.

7.4 Module literef-config.el

This module defines the variables the control the functionalities of LiteRef and sets their values. It defines key shortcuts for frequently used commands as well. The user is welcome to set these variables and shortcuts to suit his needs and taste.

7.4.a Functions

No functions are defined by this module.

7.4.b Variables

7.4.b.1 literef-arc-filter-variables-prefix

The prefix used for the names of the special variables in the specification of the arc filter. See literef-arc-filter-variables and literef-arc-filter-temp-variable.

7.4.b.2 literef-bibliography-package

The bibliography package to be used for LaTeX export. If nil, no package specification is inserted into the document.

7.4.b.3 literef-bibliography-style

The bibliography style to be used for LaTeX export. If nil, no bibliography style specification is inserted into the document.

7.4.b.4 literef-citation-function-color

The color of citation function links.

7.4.b.5 literef-citation-function-link

The link name for specifying citation functions.

7.4.b.6 literef-citation-functions

Types of citation functions used for annotating citations.

7.4.b.7 literef-citation-link-sorting-criteria

The sorting criteria for automatic sorting of citation links. It is a string consisting of comma-separated characters that stand for sorting criteria. The following characters in parentheses can be used: Key↑ (k), Key↓ (K), Creation Date↑ (d), Creation Date↓ (D), Author↑ (a), Author↓ (A), Title↑ (t), Title↓ (T), Venue↑ (v), Venue↓ (V), Venue Type↑ (w), Venue Type↓ (W), Year↑ (y), Year↓ (Y).

7.4.b.8 literef-default-image-html-attrs

The default attributes for an inline image for HTML export. See https://www.gnu.org/software/emacs/manual/html_node/org/Images-in-HTML-export.html and https://orgmode.org/worg/org-tutorials/images-and-xhtml-export.html for the description of the possible attributes.

7.4.b.9 literef-default-image-latex-attrs

The default attributes for an inline image for LaTeX export. See https://www.gnu.org/software/emacs/manual/html_node/org/LaTeX-specific-attributes.html for the description of the possible attributes. Note that, when backslash is used, four backslashes need to be typed.

7.4.b.10 literef-drop-directory

The folder for dropping new files, such as downloaded BibTeX entries and PDF files. LiteRef uses this folder for files representing server requests as well.

7.4.b.11 literef-equal-timestamps

The number of seconds, within which creation timestamps of two papers database entries corresponding to two candidates in helm are considered to be same with respect to sorting the candidates.

7.4.b.12 literef-graph-font-height

The font height used in the textual visualization of the selected subgraph.

7.4.b.13 literef-papers-directory

The folder containing the papers database.

7.4.b.14 literef-pdf-annotation-color

The color of PDF annotation links.

7.4.b.15 literef-pdf-annotation-link

The link name for citing a PDF annotation.

7.4.b.16 literef-sort-citation-links

Determines whether citation links should be sorted on-the-fly.

7.4.b.17 literef-subgraph-show-buffer

Determines whether a node corresponding to the source buffer is to be shown in the subgraph visualization.

7.4.b.18 literef-subgraph-show-only-generating-arcs

Determines whether the set of arcs in the visualization of the selected subgraph should be restricted to the arcs traversed by the uniform-cost search that built the subgraph.

7.4.b.19 literef-survey-directory

The folder used by default for exporting the survey.

7.5 Module literef-export.el

This module contains functions for creating the survey, including the the wizard for inserting subgraph visualizations.

7.5.a Functions

7.5.a.1 literef-export-file-name-without-ext(orig-file-name)

Returns the file name for export without extension. ORIG-FILE-NAME is like FILE in org-export-to-file. Thus, the file name may need to be computed from the selected subgraph’s source or input by the user.

7.5.a.2 literef-export-to-file(orig-fun backend file &rest args)

The version of org-export-to-file that supports exporting the selected subgraph. BACKEND and FILE are as in org-export-to-file.

It performs some pre-processing and then calls ORIG-FUN, which is the original org-export-to-file. When exporting the selected subgraph, the pre-processing includes computing the file name for export to be passed to org-export-to-file.

7.5.a.3 literef-insert-note-references

For each citation in the current buffer, insert a reference to the sections corresponding to the keys in the selected subgraph. Properly handle comma-separated citations.

7.5.a.4 literef-insert-subgraph-image-file-link

The interactive wizard for inserting the code block that calls literef-subgraph-image-file-link, with the purpose of having a subgraph visualization in the survey.

7.5.a.5 literef-key-notes-p(key)

Return t if the notes for KEY are valid notes that can be inserted into a survey and nil otherwise. Currently the notes are considered valid if they are not empty.

7.5.a.6 literef-keys-to-insert

Compute the list of keys whose notes are to be inserted into the survey.

7.5.a.7 literef-make-bib-file(bib-file-name)

Make the bibliography file named BIB-FILE-NAME containing only the entries for the keys appearing in the survey.

7.5.a.8 literef-reference-text(keys)

Compute text for the reference for the given KEYS, e.g. “[1,4,10]”.

7.5.a.9 literef-remove-citation-functions

Remove all citation function links and the spaces preceding them in the current buffer.

7.5.a.10 literef-source-buffer-string

Return the contents of the source buffer, as follows:

  1. During basic export, i.e. if not exporting the selected subgraph, return contents of the current buffer.
  2. Otherwise, if the source is a paper or the whole citation graph, then return empty string.
  3. Otherwise, if the source buffer of the selected subgraph exists and is visiting the source file, then the source buffer’s contents is returned.
  4. Otherwise, return the source file’s contents if that file exists.
  5. Otherwise, abort the export and report an error.

7.5.a.11 literef-subgraph-export-dispatch

The version of org-export-dispatch that works with the selected subgraph.

7.5.a.12 literef-subgraph-image-file-link(key-or-file literef-subgraph-show-buffer buffer-node-name filter caption name attr-latex attr-html)

Create an image for the subgraph with the source specified by KEY-OR-FILE and the arcs filter string FILTER, while respecting the value of LITEREF-SUBGRAPH-SHOW-BUFFER (see the variable literef-subgraph-show-buffer) and BUFFER-NODE-NAME (see literef-select-subgraph-for-export and the variable literef-subgraph-show-buffer). Return a link to the created image. The caption, name and export attributes are set using the last three arguments.

7.5.a.13 literef-subgraph-image-file-name(file-name)

Compute the file name for the image visualizing the subgraph. If FILE-NAME is under the LiteRef directory, return the ELisp expression that constructs the file name using the value of the variable literef-directory, which must be defined in Emacs configuration (hence not linked in the HTML documentation). Otherwise, return FILE-NAME as is surrounded by quotes.

7.5.b Variables

7.5.b.1 literef-no-section-reference

The value of this variable is inserted by the exporter before citations that should not be supplied by reference during the later phase of export. This trick is used to avoid inserting self-references in the section headings of the survey.

7.6 Module literef-graph.el

This module contains functions for both building the citation graph from scratch and updating it dynamically upon changes in the researcher’s notes. The updates take place whenever notes associated with a key are saved.

7.6.a Functions

7.6.a.1 literef-add-citation-and-functions-to-hash(citation-link functions hash)

Add keys in CITATION-LINK and the citation FUNCTIONS to HASH, in which keys are keys of BibTeX entries and values are sets of citation functions corresponding to the keys. Return the resulting hash.

7.6.a.2 literef-compute-graph

Compute the citation graph, with keys corresponding to all the papers in the papers database in the vertex set, from scratch.

7.6.a.3 literef-graph-add-arc(from-key to-key citation-functions &optional graph)

Add an arc in GRAPH from FROM-KEY to TO-KEY labeled by CITATION-FUNCTIONS. If GRAPH is not specified, it is given by the current value of the variable literef-graph.

7.6.a.4 literef-graph-add-key(key &optional graph)

Add KEY to GRAPH. If GRAPH is not specified, it is given by the current value of the variable literef-graph.

7.6.a.5 literef-graph-arc-label(from-key to-key &optional graph)

Return the citation functions by which an arc in GRAPH from FROM-KEY to TO-KEY is labeled. If GRAPH is not specified, it is given by the current value of the variable literef-graph.

7.6.a.6 literef-graph-key-entry(key &optional no-error)

Return the set of arcs associated with KEY. If KEY is not in the citation graph, but is a valid key from the database, then add it to the citation graph. If KEY is not a valid key, then, throw fatal error instead, unless NO-ERROR is not nil, in which case nil is returned.

7.6.a.7 literef-graph-update-key(key)

Update the citation graph based on the current version of the notes associated with KEY.

7.6.a.8 literef-init-graph(&optional init-keys)

Initialize the citation graph using INIT-KEYS as the list of keys. If the optional INIT-KEYS is not specified, all of the keys in the papers database are used.

7.6.a.9 literef-key-in-neighbors(key &optional graph)

Compute the in-neighbors of KEY in GRAPH. If GRAPH is not specified, it is given by the current value of the variable literef-graph. If KEY is not in GRAPH, it is added.

7.6.a.10 literef-key-out-citations(key)

Compute a mapping, where keys are citations in the notes associated with KEY and values are functions associated with each citation.

7.6.a.11 literef-key-out-neighbors(key &optional graph)

Compute the out-neighbors of KEY in GRAPH. If GRAPH is not specified, it is given by the current value of the variable literef-graph. If KEY is not in GRAPH, it is added.

7.6.a.12 literef-out-citations

For the current buffer, compute a mapping, where keys are citations (i.e. keys of the BibTeX entries of the cited papers) and values are functions associated with each citation.

7.6.a.13 literef-save-hook

This hook is called to update the citation graph whenever the notes associated with a key are saved.

7.6.b Variables

7.6.b.1 literef-graph

The citation graph.

7.7 Module literef-helm.el

This module contains functions that implement the formation of the candidate list of the helm interface for searching in the papers database and handle actions associated with these candidates.

7.7.a Functions

7.7.a.1 literef-action-transformer(_orig-fun actions candidate)

Transform the initial list of ACTIONS associated with the CANDIDATE.

7.7.a.2 literef-assoc(property a-list)

Return the value in A-LIST (see https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html) associated with the PROPERTY of a candidate in helm. If no value is associated with the PROPERTY, return nil.

7.7.a.3 literef-author-down(c1 c2)

Compare the authors property of the candidates C1 and C2 using the inverse of literef-str-compare.

7.7.a.4 literef-author-up(c1 c2)

Compare the authors property of the candidates C1 and C2 using literef-str-compare.

7.7.a.5 literef-candidate-helm-string(c)

Compute the string to be displayed in helm for the candidate C.

7.7.a.6 literef-candidate-property(property c)

Return the PROPERTY of the candidate C or nil if the candidate does not have such a property.

7.7.a.7 literef-candidate-transformer(candidates)

Transform the initial candidate list given by CANDIDATES.

7.7.a.8 literef-candidate-venue(c)

Return the venue of the candidate C or nil of this property is not specified.

7.7.a.9 literef-candidate-venue-type(c)

Compute the venue type of the candidate C based on its key property.

7.7.a.10 literef-char-to-compare(char)

Return the comparison function symbol corresponding to CHAR, which is assumed to be one of the characters as in the variable literef-citation-link-sorting-criteria. If CHAR is not one of those characters, then return nil.

7.7.a.11 literef-compare(c1 c2)

Compare the candidates C1 and C2 based on the value of the variable literef-criteria.

7.7.a.12 literef-criteria-list(chars)

Compute the list of comparison functions from the list of characters CHARS as in the variable literef-citation-link-sorting-criteria.

7.7.a.13 literef-filtered-candidate-transformer(_orig-fun candidates &optional _source)

Transform the candidates list CANDIDATES by sorting.

7.7.a.14 literef-helm-insert-action(_c)

The insert-action of helm.

7.7.a.15 literef-helm-marked-keys

Computes the list of keys that are currently marked in helm.

7.7.a.16 literef-key-down(c1 c2)

Compare the key property of the candidates C1 and C2 using the inverse of literef-str-compare.

7.7.a.17 literef-key-up(c1 c2)

Compare the key property of the candidates C1 and C2 using literef-str-compare.

7.7.a.18 literef-kill-ring-action-yank(orig_fun _string)

The LiteRef version of helm-kill-ring-action-yank, which performs intelligent yanking of keys.

7.7.a.19 literef-read-sorting-criteria

Handle interactive input of the search criteria.

7.7.a.20 literef-sort(_orig-fun)

Sort the candidates.

7.7.a.21 literef-str-compare(c1 c2 property)

Compare the PROPERTY of the candidates C1 and C2. If the property is specified for both candidates, it is assumed to be of string type.

7.7.a.22 literef-subgraph-helm

The version of org-ref-helm-cite, in which the candidates are restricted to the selected subgraph.

7.7.a.23 literef-timestamp-compare(c1 c2)

Compare the candidates C1 and C2 based on timestamps of the corresponding entries in the papers database. Respect the value of the variable literef-equal-timestamps when deciding whether the two timestamps are equal.

7.7.a.24 literef-timestamp-down(c1 c2)

Compare timestamps of the candidates C1 and C2 using the inverse of literef-timestamp-compare.

7.7.a.25 literef-timestamp-up(c1 c2)

Compare timestamps of the candidates C1 and C2 using literef-timestamp-compare.

7.7.a.26 literef-title-down(c1 c2)

Compare the title property of the candidates C1 and C2 using the inverse of literef-str-compare.

7.7.a.27 literef-title-up(c1 c2)

Compare the title property of the candidates C1 and C2 using literef-str-compare.

7.7.a.28 literef-type-down(c1 c2)

Compare the venue property of the candidates C1 and C2 using the inverse of literef-raw-str-compare.

7.7.a.29 literef-type-up(c1 c2)

Compare the venue type property of the candidates C1 and C2 using literef-raw-str-compare.

7.7.a.30 literef-venue-down(c1 c2)

Compare the venue property of the candidates C1 and C2 using the inverse of literef-raw-str-compare.

7.7.a.31 literef-venue-up(c1 c2)

Compare the venue property of the candidates C1 and C2 using literef-raw-str-compare.

7.7.a.32 literef-year-down(c1 c2)

Compare the year property of the candidates C1 and C2 using the inverse of literef-str-compare.

7.7.a.33 literef-year-up(c1 c2)

Compare the year property of the candidates C1 and C2 using literef-str-compare.

7.7.b Variables

7.7.b.1 literef-criteria

The criteria for sorting candidates. See the variable literef-citation-link-sorting-criteria for the possible values.

7.8 Module literef-latex-map.el

This module contains mappings for handling accented characters and functions for correctly displaying BibTeX entries containing such characters.

7.8.a Functions

7.8.a.1 literef-bibtex-completion-get-value(orig-fun &rest args)

The version of bibtex-completion-get-value that maps accented characters. ARGS are simply forwarded to bibtex-completion-get-value.

7.8.a.2 literef-translate-latex(str)

Apply the mapping given by the value of the variable literef-latex-map to translate escaped characters in the string STR.

7.8.b Variables

7.8.b.1 literef-latex-full-map

This is a modified map from https://raw.githubusercontent.com/clarkgrubb/latex-input/master/latex.el.

7.8.b.2 literef-latex-map

The mapping to be used, must be either literef-latex-full-map or literef-latex-small-map.

7.8.b.3 literef-latex-small-map

A shorter version of the mapping contained in the variable literef-latex-full-map used for performance considerations. It can be shortened further if needed. See https://stackoverflow.com/a/4580132/2725810.

7.9 Module literef-pdf.el

This module contains the definition of the PDF annotation link. It provides functions for inserting such links into the researcher’s notes and handling the operations associated with these links, including the translation of these links to page references during export. In addition, this module handles import of papers by letting the user select a region in the PDF, e.g. in the references section of a paper. Lastly, the module supports searching for keys whose PDF matches a search criteria and inserting those keys into the current notes buffer.

7.9.a Functions

7.9.a.1 literef-buffers-in-mode(mode)

Compute the list of buffers that are currently in the major mode MODE.

7.9.a.2 literef-cite-pdf-annotation

Let the user choose an annotation in an open PDF of a paper by clicking on the annotation. Inserts a PDF annotation link corresponding to the chosen annotation into the active notes buffer. Only PDFs open in the PDFView mode are handled.

7.9.a.3 literef-first-word(line)

Return the first word in the string LINE.

7.9.a.4 literef-follow-pdf-annotation-link(path)

Jump to the place in the PDF pointed to by PATH, which is the path component of a PDF annotation link.

7.9.a.5 literef-get-region-bibtex

Search for a BibTeX entry in the online sources based on the selected region in the paper PDF.

7.9.a.6 literef-glue-p(line1-last line2-first)

Determine whether a line ending with the word LINE1-LAST and hyphen and the line beginning with the word LINE2-FIRST should be glued without the use of a hyphen when presenting those two lines as a single line. This involves trying to glue them without a hyphen and checking whether the resulting string is a word in the dictionary. If both glued and non-glued variants are correct or wrong, then the user is prompted to make a choice.

7.9.a.7 literef-last-word-hyphen(line)

Return the last word in the string LINE if it is followed by hyphen. If LINE is not ended with word and hyphen, return nil.

7.9.a.8 literef-pdf-annotation-string(path &rest _args)

Compute the page reference string that is to be substituted during exporting the survey for PDF annotation link with the path component PATH.

7.9.a.9 literef-pdf-buffer-keys

Return the list of keys, whose corresponding PDF is currently open in a buffer. This is done by looping through the open buffers and checking for each buffer currently in the PDFView mode whether it corresponds to an entry in the papers database.

7.9.a.10 literef-search-pdfs(string)

Yank into the current notes buffer the citation links for the keys matched by searching for STRING in the first page of the PDFs in the papers database. LiteRef’s intelligent yanking is used. The function relies on the pdfgrep shell command. The string STRING must be a valid search pattern for that command.

7.9.a.11 literef-single-line-query(query)

Compute a single-line query based on the possibly multi-line QUERY for searching for a BibTeX entry in the online sources, while correctly handling hyphen at the end of lines.

7.9.b Variables

No variables are defined by this module.

7.10 Module literef-server.el

This module contains functions that handle communication with the Python server.

7.10.a Functions

7.10.a.1 literef-request-filename

Compute the name of the next request file.

7.10.a.2 literef-server-request(type data)

Submit request to the server. TYPE is either “getPdf” or “getBib”. If it is “getPdf”, then DATA is the key for which pdf is required. If it is “getBib”, then DATA is the search query.

7.10.b Variables

No variables are defined by this module.

7.11 Module literef-subgraph.el

This module handles the whole process of building the citation subgraph, beginning with specifying the source and the arc filter and culminating in the uniform-cost search that builds the subgraph. It also handles building the subgraphs for the source blocks inserted into the researcher’s notes by the wizard. Lastly, it defines a minor mode for viewing the subgraph in a variety of formats.

7.11.a Functions

7.11.a.1 literef-add-to-next-iter(from-key to-key-cons)

Handle the arc represented by FROM-KEY and TO-KEY-CONS (consisting of a key and a plist). If the arc fits the filter, then both the sink key (i.e. the car component of TO-KEY-CONS) and the corresponding generating arc are inserted in the current subgraph. If, in addition, the duplicate detection is passed, then add the sink key to the keys for the next iteration.

7.11.a.2 literef-append-spaces(required-length)

Append spaces to all lines in the current buffer, so they become at least the given REQUIRED-LENGTH long.

7.11.a.3 literef-arc-filter-company-backend(command &optional arg &rest ignored)

The company-mode back-end for entering the filter with completion for citation functions. The technique is described at http://sixty-north.com/blog/writing-the-simplest-emacs-company-mode-backend.

7.11.a.4 literef-arc-filter-minibuffer-mode

Turn on company mode.

7.11.a.5 literef-arc-filter-p

Return t if the current arc satisfies the filter and nil otherwise. The implementation used for each particular building of the citation subgraph is formed by literef-make-arc-filter.

7.11.a.6 literef-arc-filter-temp-variable(str)

Return the symbol named literef-temp-<prefix>STR. The prefix is determined by the variable literef-arc-filter-variables-prefix.

7.11.a.7 literef-arc-filter-variables

Return the list of variables recognized by the arc filter. Respects the variable literef-arc-filter-variables-prefix.

7.11.a.8 literef-generating-arc-p(from-key to-key)

Return t if the arc from FROM-KEY to TO-KEY is a generating arc of the current subgraph and nil otherwise.

7.11.a.9 literef-graph-check-arc(from-key to-key-cons)

Return t if the arc represented by FROM-KEY and TO-KEY-CONS (consisting of a key and a plist) fits the arc filter and nil otherwise.

7.11.a.10 literef-graph-mode(&optional arg)

The definition of the minor mode for viewing the selected subgraph.

7.11.a.11 literef-graph-scroll-down

Handle scrolling down.

7.11.a.12 literef-graph-scroll-left

Handle scrolling left.

7.11.a.13 literef-graph-scroll-right

Handle scrolling right.

7.11.a.14 literef-graph-scroll-up

Handle scrolling up.

7.11.a.15 literef-init-subgraph

Make and return a new subgraph consisting of all the keys in the citation graph.

7.11.a.16 literef-key-in-subgraph-p(key)

Return t if KEY is in the current subgraph and nil otherwise.

7.11.a.17 literef-list-satisfies-predicate-p(predicate list)

Return t if the LIST of citation functions satisfies the PREDICATE and nil otherwise.

7.11.a.18 literef-longest-line-length

Compute the length of the longest line in the current buffer.

7.11.a.19 literef-make-arc-filter(str)

Form and evaluate the function literef-arc-filter-p corresponding to the filter represented by the string STR.

7.11.a.20 literef-neighbor-pairs(direction cur-properties)

Compute the neighbors pairs consisting of key and properties that fit the required DIRECTION of the arc. The properties are computed based on CUR-PROPERTIES of the key being expanded. Properties include depth, direction and citation functions.

7.11.a.21 literef-read-arc-filter(prompt)

Read the string representing an arc filter, while providing completion of citation functions. The recognized citation functions are given by the value of the variable literef-citation-functions. Prompt the user with the string PROMPT.

7.11.a.22 literef-select-subgraph(&optional key)

Select subgraph of the citation graph given by the variable literef-graph. If KEY is specified, it is considered to be the currently active key to be used as the source. All the information needed for building the subgraph, such as the arc filter, is requested from the user.

7.11.a.23 literef-select-subgraph-for-export(key-or-file filter buffer-node-name)

Select subgraph of the citation graph given by the value of the variable literef-graph for forming its visualization, with KEY-OR-FILE used as the source, FILTER used as the filter string and BUFFER-NODE-NAME used as the name of the buffer node in the visualization. In contrast to literef-select-subgraph, this function is non-interactive. It is to be called from a source block inserted into the survey by the wizard.

7.11.a.24 literef-selected-subgraph-string(format)

Return a string representation of the current subgraph in the given FORMAT.

For “txt” or “boxart” FORMAT, keys and labels are links. For non-clickable formats, such as “png”, links are not used to save space.

The function respects the values of the variable literef-subgraph-show-only-generating-arcs and the variable literef-subgraph-show-buffer.

7.11.a.25 literef-show-selected-subgraph

Visualize the selected subgraph. Respects literef-subgraph-show-only-generating-arcs and literef-subgraph-show-buffer.

7.11.a.26 literef-show-selected-subgraph-png

Compute the visualization of the selected subgraph using the “png” format and show it in a buffer. Respects the value of the variable literef-subgraph-show-only-generating-arcs and the variable literef-subgraph-show-buffer.

7.11.a.27 literef-show-selected-subgraph-raw(format)

Compute the visualization of the selected subgraph using FORMAT, such as “boxart” or “png” and show it in a buffer. Respects the value of the variable literef-subgraph-show-only-generating-arcs and the variable literef-subgraph-show-buffer.

7.11.a.28 literef-subgraph-add-generating-arc(from-key to-key)

Add a generating arc from FROM-KEY to TO-KEY to the current subgraph.

7.11.a.29 literef-subgraph-add-key(key)

Add KEY to the current-subgraph.

7.11.a.30 literef-subgraph-build-from-source

Build the current subgraph based on its source. If the source type is :buffer, assumes that the source buffer is currently active.

7.11.a.31 literef-subgraph-compute-initial-keys

Compute the list of keys for forming the subgraph. All the keys cited in the source are used. If the source is a buffer, it is assumed to be currently active.

7.11.a.32 literef-subgraph-generating-arcs

Return the generating arcs component of the current subgraph.

7.11.a.33 literef-subgraph-initial-keys

Return the initial keys component of the current subgraph.

7.11.a.34 literef-subgraph-keys

Return the keys component of the current subgraph.

7.11.a.35 literef-subgraph-reset-selection

Reset the subgraph selection to be the entire citation graph.

7.11.a.36 literef-subgraph-save-image(format)

Save the visualization of the selected subgraph using FORMAT, such as “boxart” or “png” in a temporary file and return the file’s name. Respects the values of the variable literef-subgraph-show-only-generating-arcs and the variable literef-subgraph-show-buffer.

7.11.a.37 literef-subgraph-select-source(&optional key file-name)

Compute the source for forming the current subgraph based on the optional arguments, as follows.

  1. If KEY is specified, it becomes the source. Otherwise,
  2. If some key is currently active, it becomes the source. Otherwise,
  3. If FILE is specified and the file exists, it becomes the source. Otherwise,
  4. The file returned by buffer-file-name becomes the source.

7.11.a.38 literef-subgraph-set-initial-keys(keys)

Set the initial keys component of the current subgraph to KEYS.

7.11.a.39 literef-subgraph-set-source-property(property value)

Set the property PROPERTY of the source of current subgraph to VALUE.

7.11.a.40 literef-subgraph-source

Return the source component of the current subgraph.

7.11.a.41 literef-subgraph-source-property(property)

Return the value of the property PROPERTY of the source of current subgraph.

7.11.a.42 literef-uniform-cost-search(initial-keys)

Build the current subgraph by performing uniform-cost search from INITIAL-KEYS while respecting the current arc filter. The search keeps direction. That is, if the current key was reached by following an outgoing arc, then only the out-neighbors of that key will be considered for the next iteration.

7.11.b Variables

7.11.b.1 literef-graph-mode

Non-=nil= if Literef-Graph mode is enabled. Use the command literef-graph-mode to change this variable.

7.11.b.2 literef-graph-mode-hook

Hook run after entering or leaving literef-graph-mode. No problems result if this variable is not bound. add-hook automatically binds it. (This is true for all hook variables.)

7.11.b.3 literef-graph-mode-map

The key map for the minor mode for viewing the selected subgraph literef-graph-mode.

7.11.b.4 literef-subgraph

The selected subgraph with the following components:

:keys – the hash of keys in the subgraph.

:initial-keys – the list of keys, which served as the root of the uniform-cost search that built the subgraph.

:generating-arcs – the arcs that were traversed by the uniform-cost search that built the subgraph.

:source – the source, based on which the subgraph was constructed. The source consists of:

  • :source-type – the type of the source for building the graph. This can be :all-keys, :key or :buffer.
  • :source-name – the name of key or buffer.
  • :buffer-node-name – the name to be used for the node corresponding to the buffer source in the visualization.
  • :file-name – the file which the source buffer was visiting at the time of building the subgraph.
  • :filter-string – the arcs filter that was used to construct the graph.

7.12 Module literef-util-links.el

This module contains some helper functions to make working with links in the other modules convenient.

7.12.a Functions

7.12.a.1 literef-all-links(predicate)

Compute the list of all links in the current buffer that satisfy a given PREDICATE (if PREDICATE is nil, all links are included). The links are sorted by their begin positions. The :end property is substituted to be the actual end point of the link without spaces after it.

7.12.a.2 literef-citation-function-link-p(link)

Return t if the LINK is a citation function link and nil otherwise.

7.12.a.3 literef-citation-function-links

Compute the list of all citation function links in the current buffer, sorted by the begin position.

7.12.a.4 literef-citation-link-p(link)

Return t if the LINK is a citation link and nil otherwise.

7.12.a.5 literef-citation-link-under-cursor

Return the citation link at point. If the cursor is not over a citation link, return nil.

7.12.a.6 literef-citation-links

Compute the list of all citation links in the current buffer, sorted by their begin positions.

7.12.a.7 literef-first-citation-link-on-line

Return the first citation link on the current line. If there is no citation link on the line, return nil.

7.12.a.8 literef-link-begin(link)

The beginning point of the LINK.

7.12.a.9 literef-link-end(link)

The end point of the LINK. The spaces following the link are not included.

7.12.a.10 literef-link-path(link)

Return the path component of the LINK.

7.12.a.11 literef-link-path-components(link)

Extract keys from the LINK’s path component.

7.12.a.12 literef-link-prev-element(link)

The org-element adjacent and before the LINK.

7.12.a.13 literef-link-prev-non-space(link)

Return the position of the first non-blank character before the LINK.

7.12.a.14 literef-link-type(link)

Return the type of the LINK.

7.12.a.15 literef-link<(link1 link2)

Determine which of the links LINK1 and LINK2 appears earlier in the buffer. The two links are assumed to appear in the same buffer. Return t if LINK1 appears before LINK2 and nil otherwise.

7.12.b Variables

No variables are defined by this module.

7.13 Module literef-utils.el

This module contains some helper functions. Some of these, such as literef-xor, are not related to LiteRef functionalities per se and can be used by other projects. Others, such as literef-bib-files are LiteRef-specific, but are used by many modules and hence are separated out as utilities.

7.13.a Functions

7.13.a.1 literef-all-keys

Compute the list of all keys in the papers database.

7.13.a.2 literef-bib-filename(key)

Compute the name of the BibTeX file based on KEY.

7.13.a.3 literef-bib-files(&optional _arg)

Compute the list of BibTeX files in the papers database.

7.13.a.4 literef-buffer-key(buffer)

Compute key based on the BUFFER visiting a file associated with a paper. If the buffer is not visiting a file associated with a paper, return nil.

7.13.a.5 literef-buffer-keys

Compute the list of all keys cited in the current buffer, sorted and with duplicates removed.

7.13.a.6 literef-check-arrived-pdfs

Open PDFs for the keys contained in the list given by the value of the variable literef-needed-pdfs.

7.13.a.7 literef-creation-timestamp(key)

Compute the creation timestamp of the database entry corresponding to KEY as a floating-point number of seconds. We use the modification timestamp of the BibTeX file, since, in general, the creation timestamp might not be stored by the operating system and accessing the creation date for ext4 is not trivial.

7.13.a.8 literef-current-buffer-key

Compute key of the paper whose associated file is being visited by the current buffer. If the current buffer is not visiting a file associated with a paper, return nil.

7.13.a.9 literef-current-key

Return the key at point. If there is no key under the cursor, then return the key whose associated file is being visited by the current buffer. If the current buffer is not visiting a file associated with a paper, return nil.

7.13.a.10 literef-eval-string(string)

Evaluate Emacs Lisp code given by STRING. The code is taken from https://emacs.stackexchange.com/a/19878/16048.

7.13.a.11 literef-file-key(filename)

Compute key based on the name FILENAME of one of the files associated with a paper. If the file is not associated with a paper, return nil.

7.13.a.12 literef-filename(key ext)

Compute the name of a file with the extension EXT pertaining to a paper whose BibTeX entry’s key is KEY. Note that this file does not need to exist.

7.13.a.13 literef-find-file-other-window(filename)

The version of find-file-other-window that does not do anything if the file is already being visited in the current window.

7.13.a.14 literef-folder-key(folder)

Compute key based on a paper’s FOLDER in the papers database. If FOLDER does not correspond to a paper, return nil.

7.13.a.15 literef-get-bibtex-key-under-cursor

Non-throwing version of org-ref-get-bibtex-key-under-cursor. This version does not affect the current point in the buffer.

7.13.a.16 literef-get-entry(orig-fun &rest args)

The version of bibtex-completion-get-entry1 with the only source set to the bib file corresponding to the given key, which is the entry-key argument contained in ARGS.

7.13.a.17 literef-hash-empty-p(hash)

Return t if HASH is empty and nil otherwise.

7.13.a.18 literef-hash-keys-minus(hash1 hash2)

Return a list of keys that are present in HASH1, but not in HASH2.

7.13.a.19 literef-hash-keys-to-list(hash)

Return a list of keys in HASH.

7.13.a.20 literef-hash-pairs-to-list(hash)

Return a list of key-value pairs in HASH.

7.13.a.21 literef-join-strings(strings separator)

Join the list STRINGS of strings putting the SEPARATOR string between them.

7.13.a.22 literef-key-exists(key)

Return t if KEY exists and nil otherwise.

7.13.a.23 literef-notes-filename(key)

Compute name of the notes file based on KEY.

7.13.a.24 literef-number-or-nil(string)

Convert STRING to number. Return nil if STRING does not represent a number.

7.13.a.25 literef-number-or-nil-p(string)

Return t if STRING represents a number and nil otherwise.

7.13.a.26 literef-open-bibfile

Open the BibTeX file for the current key. See literef-current-key.

7.13.a.27 literef-open-key-bibfile(key)

Open the BibTeX file for KEY.

7.13.a.28 literef-open-key-notes(key)

Open the researcher’s notes for KEY.

7.13.a.29 literef-open-key-pdf(key)

Open the PDF for KEY.

7.13.a.30 literef-open-key-pdf-raw(key)

Open the PDF for KEY. This function should not be used directly.

7.13.a.31 literef-open-notes

Open the researcher’s notes for the current key. See literef-current-key.

7.13.a.32 literef-open-pdf

Open the PDF for the current key. See literef-current-key.

7.13.a.33 literef-pdf-filename(key)

Compute name of the PDF file based on KEY.

7.13.a.34 literef-plist-put(plist prop val)

Just a shortcut for (setq plist (plist-put PLIST PROP VAL)).

7.13.a.35 literef-raw-str-compare(s1 s2)

Compare strings S1 and S2. Return -1 if S1 is smaller than S2, 1 if S2 is smaller than S1 and 0 if the strings are equal.

7.13.a.36 literef-read-char(prompt legal-chars)

Read a char until one of the chars in LEGAL-CHARS is entered. Return the last read char. Prompt the user with PROMPT.

7.13.a.37 literef-read-number-or-nil(prompt default)

Read either a number or “nil” from the user and return it.

7.13.a.38 literef-replace-in-string-whole-words(what with in)

Like replace-in-string, but replaces whole words. The code is taken from https://emacs.stackexchange.com/a/34665/16048.

7.13.a.39 literef-set-default-bibliography(&optional _orig-fun)

Set org-ref-default-bibliography to be the list of all the BibTeX files in the papers database.

7.13.a.40 literef-string-or-nil-to-string(string)

If STRING is nil, return “nil”, otherwise return STRING.

7.13.a.41 literef-word-correct-p(word)

Return t if WORD is spelled correctly and nil otherwise. Adapted from flyspell-correct-word-before-point.

7.13.a.42 literef-xor(a b)

Compute A xor B.

7.13.a.43 replace-in-string(what with in)

Replace each occurrence of WHAT in the string IN with WITH. The code is taken from https://stackoverflow.com/a/17325791/2725810.

7.13.a.44 with-cloned-buffer(&rest body)

Executes BODY just like progn but maintain the original buffer state. The code is taken from https://emacs.stackexchange.com/a/31763/16048.

7.13.b Variables

7.13.b.1 literef-needed-pdfs

Keys whose PDFs are currently being searched for in the online sources.

7.14 The server

Please follow this link to the documentation of the server API.