Improve BibTeX parsing and bibliography rendering by fare · Pull Request #573 · racket/scribble

fare · 2026-09-13T20:35:32Z

Improve bibliography rendering and BibTeX support

Improve Scribble's support for rich bibliographies, particularly annotated bibliographies with long, formatted, multi-paragraph notes. The immediate motivation is the bibliography of my book Lambda: the Ultimate Object, but the improvements apply to ordinary academic papers as well.

Bibliography rendering

Remove the old LaTeX \parbox layout, which prevented page breaks within bibliography entries, with needspace, allowing long annotations to span pages.
Use needspace when available instead of \parbox to still try to keep short entries together.
Allow opt-in LaTeX adjustments in entries through \AutobibEntrySetup for e.g. line-breaking settings.
Improve numbered bibliography layout using CSS and LaTeX environments, with hanging indentation and aligned citation numbers.
Improve formatting across bibliography fields.
Add a period after a DOI only when a note follows it, preserving the existing formatting of ordinary entries without notes. Avoid appending punctuation directly to URLs.
Render numeric book chapters as “chapter 3”, with appropriate capitalization when the chapter starts the location.
Add an optional #:accessed field to make-bib, displayed
immediately after the URL, when one is displayed.
BibTeX online and webpage entries now use this field
instead of putting access dates in their location.
This places access dates after publication dates and
next to the URLs they qualify, without changing the
generic ordering of bibliography fields.
The webpage-location API from 1.61 is removed.

The improvements primarily target HTML and LaTeX. Typst receives minimal compatibility support rather than a new rendering implementation.

BibTeX parsing

Add a small LaTeX reader supporting common formatting commands, accents, special characters, protected groups and mathematical expressions.
Preserve protected groups when parsing author names and other fields.
Support LaTeX escapes in URLs and DOIs, generating correct hyperlinks in HTML and LaTeX.
Improve parsing of BibTeX string references, including references adjacent to delimiters.
Support formatted content and multiple paragraphs in bibliography notes.
Check required fields of standard BibTeX entry types more precisely.

The reader deliberately supports a useful subset of LaTeX rather than attempting to implement a complete TeX interpreter. Unknown commands are preserved rather than silently discarded.

API, documentation and tests

Add #:accessed to make-bib; access dates are displayed only when the corresponding URL is displayed. DOI still takes precedence over URL.
Some location helpers now compose Scribble can return #f when they contain no information. This lets callers omit empty components entirely rather than retaining opaque empty elements that can cause stray separators and punctuation.
Update the manuals to document the new behavior and configuration options.
Bump scribble-lib to version 1.68.
Add unit tests, expected-output tests and rendering tests, including regression tests for accented names, protected groups, escaped hyperlinks, access dates, BibTeX string references and multi-paragraph notes.

The changes have been exercised against my book's heavily annotated bibliography and reviewed through several rounds of automated and manual testing.

Compatibility notes

webpage-location is removed. It was a recent addition from 1.61, I'm not sure anyone uses it directly (as opposed to through bibtex.rkt), but if they do they will have to migrate to #:accessed instead.
bibtex-parse now keeps inner braces in raw field values
(e.g. "The {ACM} Paper") so that protected groups survive until
rendering; rendered output is unchanged, but code that reads
bibdb-raw directly will now see the braces.
BibTeX titles are no longer passed through verbatim to LaTeX;
they go through the same reader as other fields. Math and unknown
commands are still emitted verbatim in LaTeX output.
Notes are now decoded like other Scribble text, so -- becomes
an en dash and straight quotes become curly quotes.
A purely numeric #:chapter now renders as "chapter N".
In LaTeX output, entries may now break across pages (subject to
the five-line minimum), and numbered bibliographies use hanging
indentation instead of a table.
In text output, numbered entries are no longer aligned as a table.
Various minor bugfixes, in handling inbook, proceedings, or braces in author names.

The implementation was substantially assisted by GPT-5.6 Sol and Claude Sonnet 5, with additional review by Claude Opus 5.5.

fare · 2026-09-13T20:38:53Z

PS: I'm tempted to have a clanker improve the parsing of bibtex to support (a) emphasis, in notes, (b) {} in titles to prevent lowercasification when using LaTeX.

Also, maybe to improve autobib so multi-paragraph notes are a thing, and maybe crossing page boundaries within a bibliography entry.

These two would also much improve LtUO.

PPS: I'm still thinking about (a), but at least the basics of (b) was apparently done by #571.

PPPS: The clankers did it!

fare · 2026-09-14T05:42:51Z

Weird: the CI failed on Racket 9.3.0.8, but at home it just worked on v9.3.0.8-2026-09-14-06fd59e02c [cs].

PS: I had forgotten to update a test.

mflatt · 2026-09-19T12:11:33Z

The change to add . after a DOI would cause papers written with Scribble+autobib to render differently than Latex+bibtex (in the "acmart" style). Would it work to add . only when there's a note? Or maybe it should be configurable?

fare · 2026-09-19T16:19:41Z

Yes, adding a "." only if there's a note makes a lot sense, especially for backwards compatibility. Thanks for the suggestion.

PS: also rebasing to the latest master.

Much improves the bibliography for my book LtUO.

github-actions