3 Bibliographies🔗ℹ

This library provides support for bibliography management in a Scribble document. The define-cite form is used to bind procedures that create in-line citations and generate the bibliography in the document.

Individual bibliography entries are created with the make-bib function. See below for an example.

#lang scribble/base

@(require scriblib/autobib)

@(define-cite ~cite citet generate-bibliography)

@(define plt-tr1

(make-bib

#:title    "Reference: Racket"

#:author   (authors "Matthew Flatt" "PLT")

#:date     "2010"

#:location (techrpt-location #:institution "PLT Inc."

#:number "PLT-TR-2010-1")

#:url      "http://racket-lang.org/tr1/"))

Racket is fun@~cite[plt-tr1].

@(generate-bibliography)

For citations that reference a page number or section, the in-bib function can be used. For example, the following snippet:

Racket has a contract library.@~cite[(in-bib plt-tr1 ", §8")]

includes a citation to section 8 of the Racket reference.

Changed in version 1.61 of package scribble-lib: Added fields and location types for better bibtex support.
Changed in version 1.68: Improved bibliography layout, added support for multi-paragraph notes and extended support for structured content in bibliography fields.

The function bound to ~cite-id produces a citation referring to one or more bibliography entries with a preceding non-breaking space, by default sorting the entries to match the bibliography order. It has the contract

(->* (bib?) (#:sort? any/c) #:rest (listof bib?) element?)

The function bound to citet-id generates an element suitable for use as a noun—referring to a document or its author—for one or more bibliography entries which have the same authors. It has the contract

(->* (bib?) () #:rest (listof bib?) element?)

The function bound to generate-bibliography-id generates the section for the bibliography, with a title as per the #:sec-title argument (defaults to "Bibliography") and a tag as per the #:tag argument (defaults to "doc-bibliography"). If the #:sec-title argument is #f instead a string, only the content of the bibliography is created, as a table, and not the enclosing section as a part.

(->* () (#:tag string? #:sec-title (or/c #f string?))

(or/c part? block?))

If provided, the function bound to cite-author-id generates an element containing the authors of a paper.

(->* (bib?) element?)

If provided, the function bound to cite-year-id generates an element containing the year the paper was published in, or possibly multiple years if multiple papers are provided.

(->* (bib?) #:rest (listof? bib?) element?)

The functions bound to cite-author-id and cite-year-id make it possible to create possessive textual citations.

@citeauthor[scribble-cite]'s (@citeyear[scribble-cite]) autobib

library is pretty nifty.

The optional spaces-expr determines the number of blank lines that appear between citations. The default number of lines is 1.

The optional style-expr determines the way that citations and the bibliography are rendered.Programmer-defined styles may be supported in the future. Currently, two built-in styles are provided, and author+date-style is the default.

For author+date-style, if two citations’ references would render the same (as judged by equal authors and dates that are considered the same) but are different, the optionally provided function from disambiguator-expr is used to add an extra element after the date; the default disambiguator adds a, b, etc. until z, and anything more ambiguous raises an exception. Date comparison is controlled by date-compare-exprs. Dates in citations and dates in the bibliography may be rendered differently, as specified by the optionally given render-date-expr functions.

Changed in version 1.22 of package scribble-lib: Add optional ids for author-name and author-year

With number-style, bibliography entries use hanging indentation in HTML and LaTeX output, with citation numbers aligned in a separate label column. Text output instead separates each number from its entry with a non-breaking space.

The author+date-square-bracket-style definition is the same as author+date-style, except that references to citations are enclosed in [] instead of ().

In LaTeX output, Scribble tries to keep short bibliography entries together, reserving at least five lines before starting an entry. This approximates the previous behavior, which prevented page breaks within individual entries altogether. Longer entries may now span pages.

The \AutobibNeedlines counter controls the minimum number of lines, defaulting to 5. Set it to 0 to disable this constraint. The optional needspace package is required for the constraint to take effect; this behavior is disabled if the package is unavailable, as if the counter were 0.

The \AutobibEntrySetup command, empty by default, allows additional LaTeX settings to be applied locally to each bibliography entry.

To require four lines before each entry and relax line breaking for long annotations, configure these settings using \AtBeginDocument from e.g. a tex-addition that you add to your document’s style:

(tex-addition

(bytes-append

#"\\AtBeginDocument{%\n"

#"  \\AutobibNeedlines=4\\relax\n"

#"  \\renewcommand{\\AutobibEntrySetup}{%\n"

#"    \\emergencystretch=2em\n"

#"    \\tolerance=1000}}%\n"))

The #:note argument may contain multiple paragraphs, separated by blank lines. The first paragraph follows the bibliographic information; subsequent paragraphs remain within the same bibliography entry.

When both #:doi and #:url are supplied, the DOI takes precedence. A period is inserted after a DOI when followed by a non-empty note. No period is appended directly to a URL.

#:accessed gives the date a #:url (in CSL terms, the date it was accessed), and is only used when #:url is displayed, i.e. when no #:doi is supplied. It is rendered right after the URL, separated from it by a space, as (accessed ...). A period is inserted after it when followed by a non-empty note; a naked URL (no #:accessed) never gets that period.

Dates are internally represented as date values, so a date may be given, or a number or string that represent the year.

An element produced by a function like author-name tracks first, last names, and name suffixes separately, so that names can be ordered and rendered correctly. When a string is provided as an author name, the last non-empty sequence of alphabetic characters or - after a space is treated as the author name, and the rest is treated as the first name.

Changed in version 1.49 of package scribble-lib: Added #:doi.
Changed in version 1.68: Added #:accessed, which replaces the accessed-date support formerly provided by the now-removed webpage-location function: the accessed date is now attached directly to the bib entry instead of being embedded in its #:location, so it renders next to the URL rather than before the date.

Each of the following *-location functions combines its arguments into a single element?. proceedings-location, book-location, booklet-location, misc-location, and manual-location may legitimately be called by scriblib/bibtex with no useful information at all (e.g. a BibTeX entry that supplies none of the corresponding optional fields): each returns #f when every one of its arguments is either omitted (#f) or supplied as empty content. The rest each have at least one genuinely required argument, so they always have something to report and never return #f.

For a handful of fields across these functions – an edition, an editor, a location, a page range, a series number – #f alone isn’t enough to tell “omitted” from “supplied but empty,” because the field gets wrapped in surrounding text (e.g. an editor’s name becomes “NAME (Ed.)”; an edition becomes “EDITION edition”). Omitting the field (#f, the default) still quietly contributes nothing, but explicitly supplying empty or otherwise trivial content for one of these particular fields (e.g. "") raises a contract violation instead of silently producing an orphaned fragment like “(Ed.)” with no name attached. Each function’s entry below says which of its fields this applies to.

Changed in version 1.61 of package scribble-lib: Added fields for bibtex support: editor number organization publisher address.
Changed in version 1.68: Added #f as a possible result.

A numeric chapter, supplied as a number or a string of decimal digits, is prefixed with “chapter”. Other chapter content is used unchanged.

Changed in version 1.61 of package scribble-lib: Added fields for bibtex support: editor chapter series volume number pages address. Made all arguments optional.
Changed in version 1.68: Added #f as a possible result.

Added in version 1.61 of package scribble-lib.
Changed in version 1.68: Added #f as a possible result.

Added in version 1.61 of package scribble-lib.
Changed in version 1.68: Added #f as a possible result.

Changed in version 1.61 of package scribble-lib: Added fields for bibtex support: type address.

Changed in version 1.61 of package scribble-lib: Added fields for bibtex support: type address.

The chapter argument is formatted as by book-location.

Changed in version 1.61 of package scribble-lib: Added fields for bibtex support: editor chapter number address.

Raises a contract violation if name is empty or otherwise trivial content (e.g. ""), rather than silently producing a name-less “(Ed.)” credit.

Changed in version 1.68 of package scribble-lib: Raises on empty or trivial content instead of silently producing a bogus, name-less credit.

Defaults to #f.

Added in version 1.5 of package scribble-lib.

Defaults to (λ (url) (link url (make-element 'url (list url)))).

Added in version 1.39 of package scribble-lib.