adamsgaard.dk

my academic webpage
git clone git://src.adamsgaard.dk/adamsgaard.dk
Log | Files | Refs | README | LICENSE Back to index

commit 0eabbd1c838698962abc30ddd05d72ad528d7a1c
parent 91c6cf410237ba846ea1aa079ee2a4ebe14a38f0
Author: Anders Damsgaard <anders@adamsgaard.dk>
Date:   Fri, 15 Nov 2019 15:53:19 +0100

Finalize first published version of scholarref entry

Diffstat:
Mpages/002-scholarref.html | 98+++++++++++++++++++++++++++++++++++++++----------------------------------------
1 file changed, 48 insertions(+), 50 deletions(-)

diff --git a/pages/002-scholarref.html b/pages/002-scholarref.html @@ -1,43 +1,41 @@ <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>During the writing phase of an academic paper, common tasks include +downloading PDFs of publications and getting their references into your +bibliography. However, I am not a fan of navigating the slow, bloated, +tracker-filled, and distracting webpages of academic journals and +publication aggregators. For some reason, many publishers decided +that clicking the "Download PDF" link should redirect the user to +an unusable in-browser PDF viewer instead of providing the PDF file +directly. While the majority of journal webpages provide formatted +citations for their publications, 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> +called <strong>scholarref</strong> that allow me to +perform most of the tasks without having to open a browser. +As the title of this post indicates, the goal of the toolset is to +provide as much functionality a person might need during scientific +writing without leaving the command line. The tools are under <a +href="https://src.adamsgaard.dk/scholarref/log.html">continuous +development</a>. At present I avoid roughly 90% of visits to journal +webpages. I hope to get to 100% someday.</p> <p>The <strong>scholarref</strong> design goals are the following:</p> <ul> -<li>POSIX shell scripts with minimal external dependencies: +<li>Written as 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> +<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 +third parties. What is demonstrated here are examples only. Use of the tools is entirely your own responsibility.</p> @@ -54,27 +52,23 @@ 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> +<p>The core functionality is provided by the scripts +<strong>getdoi</strong>, <strong>getref</strong>, and +<strong>shdl</strong>. 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 help text +(invoke with 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. +This tool accepts either 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, +the <a href="http://api.crossref.org">CrossRef API</a> is used to find +the DOI of the closest publication match. You can supply author names, parts of the title, ORCID, journal name, etc. Examples:</p> <pre><code>$ getdoi damsgaard2018.pdf @@ -89,10 +83,11 @@ 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> +Library list of Journal Title Abbreviations</a>. The +<strong>getref</strong> ruleset of journal-title abbreviations is +incomplete, and is expanded on a per-need basis. If desired, the +abbreviation functionality can be disabled. See <strong>getref -h</strong> +for details.</p> <pre><code>$ getref 10.1029/2018ms001299 @article{Damsgaard2018, @@ -132,9 +127,10 @@ 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> +<p>The <strong>scholarref</strong> tools are meant to be chained +together. For example, if you want a BibTeX reference a search query, +simply use UNIX pipes to send the <strong>getdoi</strong> output as +input to <strong>getref</strong>:</p> <pre><code>$ getdoi 'damsgaard egholm ice flow dynamics' | getref @article{Damsgaard2016, @@ -167,7 +163,8 @@ Citation Damsgaard2016 added to /home/ad/articles/own/BIBnew.bib <h2>Integrating into your favorite $EDITOR</h2> <p>The <strong>scholarref</strong> tool is particularly useful if called -from within a text editor.</p> +from within a text editor. Below I demonstrate how keyboard bindings +can be bound in various editors to provide scholarref functionality.</p> <h3>vi</h3> <p>My editor of choice is the plain, old, and simple <a @@ -192,9 +189,10 @@ nnoremap &lt;leader&gt;R :r !scholarref --add&lt;space&gt; " append reference i <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> +href="https://sam.cat-v.org/">sam(1)</a>. However, after using +it exclusively for three months, I concluded that it is too +immature for general use. If desired, add the following binding to +<strong>~/.config/visrc.lua</strong>:</p> <pre><code>vis:map(vis.modes.NORMAL, leader..'r', ':&lt; scholarref ')</code></pre>