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 <leader>R :r !scholarref --add<space>… | |
<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><… | |