Introduction
Introduction Statistics Contact Development Disclaimer Help
tFinalize first published version of scholarref entry - adamsgaard.dk - my acad…
git clone git://src.adamsgaard.dk/adamsgaard.dk
Log
Files
Refs
README
LICENSE
---
commit 0eabbd1c838698962abc30ddd05d72ad528d7a1c
parent 91c6cf410237ba846ea1aa079ee2a4ebe14a38f0
Author: Anders Damsgaard <[email protected]>
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(-)
---
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 …
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 worki…
<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/BIBn…
<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 &lt;leader&gt;R :r !scholarref --add&lt;space&gt…
<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><…
You are viewing proxied material from mx1.adamsgaard.dk. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.