diff options
Diffstat (limited to 'README.html')
| -rw-r--r-- | README.html | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/README.html b/README.html new file mode 100644 index 0000000..d3daee2 --- /dev/null +++ b/README.html @@ -0,0 +1,130 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>bibutils</title> +<style> + body { + max-width: 42em; + margin: 2em auto; + padding: 0 1em; + font-family: Georgia, "Times New Roman", serif; + line-height: 1.5; + color: #222; + } + h1 { + border-bottom: 1px solid #ccc; + padding-bottom: 0.2em; + } + h2 { + font-family: "Courier New", monospace; + font-size: 1.1em; + margin-bottom: 0.2em; + } + h2 + p { + margin-top: 0.2em; + } + code, pre { + font-family: "Courier New", monospace; + background: #f4f4f4; + } + code { + padding: 0 0.2em; + } + pre { + padding: 0.7em 1em; + border: 1px solid #ddd; + overflow-x: auto; + } +</style> +</head> +<body> + +<h1>bibutils</h1> + +<p>A collection of small, single-purpose scripts written in POSIX shell and +awk for the manipulation of bibtex database files from the command line. +Each one is small and single purpose. They are as follows:</p> + +<h2>bib-util</h2> +<p>A general wrapper script that centralizes the functionality of many of +the smaller provided scripts for convenience's sake.</p> + +<h2>bib-add</h2> +<p>A script for inserting a new entry into a bibtex database file. It will +accept a fully formatted entry on standard input and add it to a database +file presented as an argument. The database is never modified in place: +the new version is built in a temporary file, verified, and only then +swapped in, with the previous contents saved in <code>db.bib.bak</code>. +Replacing an entry (<code>-f</code>) preserves every other byte of the +file.</p> + +<h2>bib-gen</h2> +<p>A script which generates a bibtex entry based on input. By default it +will run in an interactive mode, prompting the user to enter the relevant +details. Additionally, it can be configured to read the data directly from +stdin based on format arguments, or data can be provided directly as +arguments. The formatted bibtex entry will be emitted on stdout.</p> + +<h2>bib-extract</h2> +<p>A script which filters a bibtex database provided on stdin or as an +argument and emits only those entries contained within a specified aux +file. Both classic bibtex and biblatex/biber aux files are understood, and +<code>\nocite{*}</code> selects the whole database. (roff citation sources +are planned but not yet supported.)</p> + +<h2>bib-ls</h2> +<p>List the entries in a database, one key per line, or with +<code>-l</code> as tab-separated key, type, author, year and title.</p> + +<h2>bib-check</h2> +<p>Lint a database: reports missing required fields, duplicate keys, +duplicate titles (likely duplicated entries) and empty field values. +Exits nonzero if any problem was found.</p> + +<h2>bib-key</h2> +<p>A script which accepts a bibtex entry on stdin, and emits it on stdout +with an automatically generated bibtex key.</p> + +<h2>bib-fetch</h2> +<p>A script which accepts a pdf file as an input argument and will attempt +to fetch a corresponding bibtex entry based on its DOI (via crossref.org) +or, failing that, its arXiv id (via arxiv.org). An identifier can also be +given directly with <code>-d</code> (DOI) or <code>-a</code> (arXiv +id).</p> + +<h2>bib-convert</h2> +<p>Convert between bibtex and refer database formats. The direction is +detected automatically from the input, or can be forced with +<code>-b</code> (to bibtex) or <code>-r</code> (to refer).</p> + +<h1>Canonical form</h1> +<p>Entries that pass through these tools are canonicalized: lowercase +entry types and field names, 2-space indentation, brace-delimited values +with internal whitespace collapsed, bare numbers left bare, and macro +references/concatenations preserved verbatim. <code>@string</code> and +<code>@preamble</code> blocks pass through untouched.</p> + +<h1>Installation</h1> +<pre>make install # PREFIX=/usr/local by default</pre> + +<p>Scripts go to <code>$(PREFIX)/bin</code>, the shared awk library to +<code>$(PREFIX)/share/bibutils</code>, and man pages to +<code>$(PREFIX)/share/man/man1</code>.</p> + +<p>The scripts look for the shared awk library in +<code>$BIBUTILS_LIB</code>, then in <code>lib/</code> next to the script, +then in <code>/usr/local/share/bibutils</code>. If installing with a +non-default PREFIX, set <code>BIBUTILS_LIB</code> accordingly.</p> + +<h1>Dependencies</h1> +<p>POSIX shell and awk only, with two exceptions: <code>bib-fetch</code> +requires curl, plus pdftotext (poppler) for DOI extraction from pdfs.</p> + +<h1>Tests</h1> +<pre>make test # unit + integration suites +make fuzz # robustness fuzzing against bogus input</pre> + +</body> +</html> |