diff options
| author | Douglas B. Rumbaugh <doug@douglasrumbaugh.com> | 2026-06-06 13:46:14 -0400 |
|---|---|---|
| committer | Douglas B. Rumbaugh <doug@douglasrumbaugh.com> | 2026-06-06 13:46:14 -0400 |
| commit | 9f01aaa6360d65f70b5ff8b31c2f79e7feb1ca94 (patch) | |
| tree | 8d960288d0990a4444fd76aea8029717aedf6191 | |
| parent | c102ab995f9a86a77e40b9a952b2b23c0bd7de74 (diff) | |
| download | bibutils-9f01aaa6360d65f70b5ff8b31c2f79e7feb1ca94.tar.gz | |
HTML readme
| -rw-r--r-- | README.html | 130 | ||||
| -rw-r--r-- | README.md | 79 |
2 files changed, 130 insertions, 79 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> diff --git a/README.md b/README.md deleted file mode 100644 index 434a98a..0000000 --- a/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# bibutils -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: - -## bib-util -A general wrapper script that centralizes the functionality of many of the -smaller provided scripts for convenience's sake. - -## bib-add -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 db.bib.bak. Replacing an -entry (-f) preserves every other byte of the file. - -## bib-gen -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. - -## bib-extract -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 \nocite{*} -selects the whole database. (roff citation sources are planned but not yet -supported.) - -## bib-ls -List the entries in a database, one key per line, or with -l as -tab-separated key, type, author, year and title. - -## bib-check -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. - -## bib-key -A script which accepts a bibtex entry on stdin, and emits it on stdout with -an automatically generated bibtex key. - -## bib-fetch -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 -d (DOI) or -a (arXiv id). - -## bib-convert -Convert between bibtex and refer database formats. The direction is detected -automatically from the input, or can be forced with -b (to bibtex) or -r -(to refer). - -# Canonical form -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. @string and @preamble blocks -pass through untouched. - -# Installation - make install # PREFIX=/usr/local by default - -Scripts go to $(PREFIX)/bin, the shared awk library to -$(PREFIX)/share/bibutils, and man pages to $(PREFIX)/share/man/man1. - -The scripts look for the shared awk library in $BIBUTILS_LIB, then in -lib/ next to the script, then in /usr/local/share/bibutils. If installing -with a non-default PREFIX, set BIBUTILS_LIB accordingly. - -# Dependencies -POSIX shell and awk only, with two exceptions: bib-fetch requires curl, -plus pdftotext (poppler) for DOI extraction from pdfs. - -# Tests - make test # unit + integration suites - make fuzz # robustness fuzzing against bogus input |