tFinalize first published version of scholarref entry - adamsgaard.dk - my academic webpage
(HTM) git clone git://src.adamsgaard.dk/adamsgaard.dk
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 0eabbd1c838698962abc30ddd05d72ad528d7a1c
(DIR) parent 91c6cf410237ba846ea1aa079ee2a4ebe14a38f0
(HTM) Author: Anders Damsgaard <anders@adamsgaard.dk>
Date: Fri, 15 Nov 2019 15:53:19 +0100
Finalize first published version of scholarref entry
Diffstat:
M pages/002-scholarref.html | 98 +++++++++++++++----------------
1 file changed, 48 insertions(+), 50 deletions(-)
---
(DIR) diff --git a/pages/002-scholarref.html b/pages/002-scholarref.html
t@@ -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>
t@@ -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
t@@ -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,
t@@ -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,
t@@ -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
t@@ -192,9 +189,10 @@ nnoremap <leader>R :r !scholarref --add<space> " 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', ':< scholarref ')</code></pre>