tFirst completed draft of scholarref blog entry - adamsgaard.dk - my academic w… | |
git clone git://src.adamsgaard.dk/adamsgaard.dk | |
Log | |
Files | |
Refs | |
README | |
LICENSE | |
--- | |
commit 91c6cf410237ba846ea1aa079ee2a4ebe14a38f0 | |
parent 8261f49d9cdb15d18adcfa231afea6d2e861440d | |
Author: Anders Damsgaard <[email protected]> | |
Date: Fri, 15 Nov 2019 15:13:46 +0100 | |
First completed draft of scholarref blog entry | |
Diffstat: | |
A pages/002-scholarref.cfg | 8 ++++++++ | |
A pages/002-scholarref.html | 223 ++++++++++++++++++++++++++++++ | |
2 files changed, 231 insertions(+), 0 deletions(-) | |
--- | |
diff --git a/pages/002-scholarref.cfg b/pages/002-scholarref.cfg | |
t@@ -0,0 +1,8 @@ | |
+filename=scholarref.html | |
+title=The scholarref tools: never deal with journal webpages again | |
+description=Fetch publications and bibliography references from the command li… | |
+id=scholarref | |
+tags=scholarref, references, academia, bibtex, latex | |
+created=2019-11-15 | |
+updated=2019-11-15 | |
+#index=0 | |
diff --git a/pages/002-scholarref.html b/pages/002-scholarref.html | |
t@@ -0,0 +1,223 @@ | |
+<h2>Rationale</h2> | |
+<p>During the writing phase of an academic paper, common | |
+tasks include downloading PDFs of publications and getting | |
+their references into your bibliography. <a | |
+href="https://en.wikipedia.org/wiki/Digital_object_identifier">DOIs</a> | |
+are central to modern reference management, and many journals require that | |
+all cited references are listed with their DOI in the bibliography. I am | |
+not a fan of navigating the bloated and distracting webpages of academic | |
+journals and publication aggregators. Their pages are often slow and | |
+hard to navigate. Often, clicking the "Download PDF" link redirects the | |
+viewer into an unusable in-browser PDF viewer instead of providing the | |
+PDF directly. Journal webpages provide links to export a citation for the | |
+relevant publication, but these are inconsistent in style and content.</p> | |
+ | |
+<p>For these reasons, I constructed a set of shell tools | |
+that allow me to perform most of the tasks without having to | |
+open a browser. As post title indicates, the goal of the <a | |
+href="https://src.adamsgaard.dk/scholarref">scholarref</a> tools | |
+is to provide as much functionality a person might need during as | |
+possible from a set of command-line utilities. The tools are under | |
+<a href="https://src.adamsgaard.dk/scholarref/log.html">continuous | |
+development</a>, and at present I avoid roughly 90% of visits to journal | |
+webpages.</p> | |
+ | |
+<p>The <strong>scholarref</strong> design goals are the following:</p> | |
+<ul> | |
+<li>POSIX shell scripts with minimal external dependencies: | |
+Ensures maximum flexibility and portability.</li> | |
+<li>Aim for simplicity: | |
+Fewer lines of code make the programs easier to understand, maintain, | |
+and debug.</li> | |
+<li>Each tool should do one thing, and do it well: | |
+Let the users piece the components together to fit their workflow.</li> | |
+<li>Return references in BibTeX format</li> | |
+</ul> | |
+ | |
+<p><strong>DISCLAIMER:</strong> The functionality provided by these | |
+programs depends on communication with third party webpages, which may | |
+or may not be permitted by law and the terms of service upheld by the | |
+third parties. What is demonstrated here is an example only. Use of | |
+the tools is entirely your own responsibility.</p> | |
+ | |
+ | |
+<h2>Installation</h2> | |
+ | |
+<pre><code>$ git clone git://src.adamsgaard.dk/scholarref | |
+$ cd scholarref | |
+# make install</pre></code> | |
+ | |
+<p>The <strong>make install</strong> command may require superuser | |
+priviledges to install the tools to <strong>/usr/local</strong>. Prefix | |
+with <strong>doas</strong> or <strong>sudo</strong>, whatever is | |
+appropriate for the target system.</p> | |
+ | |
+<h2>The scholarref toolset</h2> | |
+ | |
+<p>The tools adhere to certain standards, namely POSIX compatibility | |
+which ensures that the code is portable. The tools use standard UNIX | |
+concepts of streams, which makes them modular and compatible with other | |
+text-manipulating tools. Furthermore, I strive to keep the code as simple | |
+and minimal as possible. Fewer lines of code means fever bugs.</p> | |
+ | |
+<p>All programs accept input as command-line arguments or from standard | |
+input (stdin). The programs come with several OPTIONS, and | |
+it is encouraged to explore the program help text (option: | |
+<strong>-h</strong>). The <strong>-t</strong> option may be of | |
+particular interest, since it tunnels all communication through <a | |
+href="https://torproject.org">Tor</a> via <strong>torsocks</strong>, | |
+if available on the system.</p> | |
+ | |
+<h3>getdoi</h3> | |
+This tool accepts names of PDF files or arbitrary search queries. | |
+If a PDF file name is supplied, <strong>getdoi</strong> scans the PDF | |
+text in order to find the first occuring DOI entry, which typically is | |
+the DOI of the publication itself. If an arbitrary query is supplied, | |
+the <a href="http://api.crossref.org">CrossRef API</a> to find the | |
+closest matching publication and its DOI. You can supply author names, | |
+parts of the title, ORCID, journal name, etc. Examples:</p> | |
+ | |
+<pre><code>$ getdoi damsgaard2018.pdf | |
+10.1029/2018ms001299 | |
+$ getdoi 'damsgaard sergienko adcroft journal advances modeling earth systems' | |
+10.1029/2018ms001299 | |
+</code></pre> | |
+ | |
+<h3>getref</h3> | |
+<p>The <strong>getref</strong> tool fetches the BibTeX citation for a | |
+given DOI from <a href="https://doi.org">doi.org</a>. By default, | |
+the journal names and author first names are abbreviated, which is | |
+what most journals want. I have taken most abbreviations from the <a | |
+href="https://www.library.caltech.edu/journal-title-abbreviations">Caltech | |
+Library list of Journal Title Abbreviations</a>. My journal-title | |
+abbreviation ruleset is incomplete, and is expanded on a per-need | |
+basis. The abbreviation functionality can be disabled, see <strong>getref | |
+-h</strong> for details.</p> | |
+ | |
+<pre><code>$ getref 10.1029/2018ms001299 | |
+@article{Damsgaard2018, | |
+ doi = {10.1029/2018ms001299}, | |
+ year = 2018, | |
+ publisher = {American Geophysical Union ({AGU})}, | |
+ volume = {10}, | |
+ number = {9}, | |
+ pages = {2228--2244}, | |
+ author = {A. Damsgaard and A. Adcroft and O. Sergienko}, | |
+ title = {Application of Discrete Element Methods to Approximate Sea Ic… | |
+ journal = {J. Adv. Mod. Earth Sys.} | |
+} | |
+$ getref -j 10.1029/2018ms001299 # do not abbreviate journal title | |
+@article{Damsgaard2018, | |
+ doi = {10.1029/2018ms001299}, | |
+ year = 2018, | |
+ publisher = {American Geophysical Union ({AGU})}, | |
+ volume = {10}, | |
+ number = {9}, | |
+ pages = {2228--2244}, | |
+ author = {A. Damsgaard and A. Adcroft and O. Sergienko}, | |
+ title = {Application of Discrete Element Methods to Approximate Sea Ic… | |
+ journal = {Journal of Advances in Modeling Earth Systems} | |
+} | |
+</code></pre> | |
+ | |
+<h3>shdl</h3> | |
+<p>This tool takes a DOI as input and attempts to | |
+download the corresponding publication as a PDF through <a | |
+href="https://sci-hub.tw">sci-hub</a>. Unfortunately, the sci-hub web | |
+interface often puts up captias to restrict automated downloads. If that's | |
+the case, <strong>shdl</strong> opens the tor browser (if installed) | |
+or the system web browser in order to manually complete the | |
+download. Output PDF files are saved in the present working directory.</p> | |
+ | |
+ | |
+<h2>Usage examples</h2> | |
+ | |
+<p>If you want a BibTeX reference a search query, simply use UNIX | |
+pipes to send the <strong>getdoi</strong> output as input for | |
+<strong>getref</strong>:</p> | |
+ | |
+<pre><code>$ getdoi 'damsgaard egholm ice flow dynamics' | getref | |
+@article{Damsgaard2016, | |
+ doi = {10.1002/2016gl071579}, | |
+ year = 2016, | |
+ publisher = {American Geophysical Union ({AGU})}, | |
+ volume = {43}, | |
+ number = {23}, | |
+ pages = {12,165--12,173}, | |
+ author = {A. Damsgaard and D. L. Egholm and L. H. Beem and S. Tulaczyk… | |
+ title = {Ice flow dynamics forced by water pressure variations in subg… | |
+ journal = {Geophys. Res. Lett.} | |
+} | |
+</code></pre> | |
+ | |
+<p>The <strong>scholarref</strong> program itself is an aggregation of | |
+the <strong>getdoi</strong> and <strong>getref</strong> commands. If | |
+called with the <strong>-a</strong> option, the reference | |
+is directly inserted into the system bibliography. The full | |
+path to the bibliography file (.bib) is assumed to be set in the | |
+<strong>$BIB</strong> environment variable, for instance defined in the | |
+user <strong>~/.profile</strong>.</p> | |
+ | |
+<pre><code>$ echo $BIB | |
+/home/ad/articles/own/BIBnew.bib | |
+$ scholarref -a 'damsgaard egholm ice flow dynamics' | |
+Citation Damsgaard2016 added to /home/ad/articles/own/BIBnew.bib | |
+</code></pre> | |
+ | |
+ | |
+<h2>Integrating into your favorite $EDITOR</h2> | |
+<p>The <strong>scholarref</strong> tool is particularly useful if called | |
+from within a text editor.</p> | |
+ | |
+<h3>vi</h3> | |
+<p>My editor of choice is the plain, old, and simple <a | |
+href="https://man.openbsd.org/vi">vi(1)</a>. I have the following binding | |
+in my <strong>~/.exrc</strong>, including a trailing space:</p> | |
+ | |
+<pre><code>map qr :r !scholarref </code></pre> | |
+<p>The rest of my editor configuration can be found under my <a | |
+href="https://src.adamsgaard.dk/dotfiles/file/.exrc.html">dotfiles source | |
+code repository</a>.</p> | |
+ | |
+<h3>vim</h3> | |
+<p>You can add the following bindings to <strong>~/.vimrc</strong> | |
+or <strong>~/.vim/vimrc</strong> in order to get scholarref functionality | |
+within <a href="https://www.vim.org/">vim(1)</a>:</p> | |
+ | |
+<pre><code>nnoremap <leader>r :r !scholarref<space> " insert refer… | |
+nnoremap <leader>R :r !scholarref --add<space> " append reference… | |
+</code></pre> | |
+ | |
+<h3>vis</h3> | |
+<p>The <a href="https://github.com/martanne/vis">vis(1)</a> | |
+editor is an interesting combination of modal editing | |
+and structural regular expressions from the plan9 editor <a | |
+href="https://sam.cat-v.org/">sam(1)</a>. After using it exclusively for | |
+three months, I concluded that it is too immature for general use. I have | |
+the following binding in my <strong>~/.config/visrc.lua</strong>:</p> | |
+ | |
+<pre><code>vis:map(vis.modes.NORMAL, leader..'r', ':< scholarref ')</code><… | |
+ | |
+<h3>emacs</h3> | |
+<p>Don't know, figure it out yourself.</p> | |
+ | |
+<h2>Integrating into your pdf viewer</h2> | |
+<p>My PDF viewer of choice is <a | |
+href="https://pwmt.org/projects/zathura">zathura(1)</a>, which has a | |
+minimal graphical user interface and is keyboard-centric. The following | |
+configuration calls <strong>getdoi</strong> on the currently open file | |
+if I press <strong>Ctrl-i</strong>. The resultant DOI is copied to the | |
+clipboard. Similarly, <strong>Ctrl-s</strong> tries to extract the DOI | |
+in the same manner, but fetches the accompanying reference and adds it | |
+directly to the bibliography.</p> | |
+ | |
+<pre><code>map <C-i> feedkeys ":exec getdoi --notify --clip '$FILE'<R… | |
+map <C-s> feedkeys ":exec scholarref --add '$FILE'<Return>" | |
+</code></pre> | |
+ | |
+<p>My full zathura configuration file is available <a | |
+href="https://src.adamsgaard.dk/dotfiles/file/.config/zathura/zathurarc.html">… | |
+ | |
+<h2>Questions/bugs/feedback/improvements</h2> | |
+<p>Please <a href="contact.html">get in touch</a> if you encounter | |
+any. Improvement suggestions are best sent as patches by e-mail.</p> |