On this page:
define-cite
author+  date-style
author+  date-square-bracket-style
number-style
bib?
make-bib
in-bib
proceedings-location
journal-location
book-location
techrpt-location
dissertation-location
author-name
authors
org-author-name
other-authors
editor
abbreviate-given-names
7.1

3 Bibliographies

 (require scriblib/autobib) package: scribble-lib

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 bibilography 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.

syntax

(define-cite ~cite-id citet-id generate-bibliography-id
             option ...)
 
option = #:style style-expr
  | #:disambiguate disambiguator-expr
  | #:spaces spaces-expr
  | #:render-date-in-bib render-date-expr
  | #:render-date-in-cite render-date-expr
  | #:date<? date-compare-expr
  | #:date=? date-compare-expr
  | #:cite-author cite-author-id
  | #:cite-year cite-year-id
 
  style-expr : (or/c number-style author+date-style author+date-square-bracket-style)
  spaces-expr : number?
  disambiguator-expr : (or/c #f (-> exact-nonnegative-integer? element?))
  render-date-expr : (or/c #f (-> date? element?))
  date-compare-expr : (or/c #f (-> date? date? boolean?))
Binds ~cite-id, citet-id, generate-bibliography-id, (optionally) cite-author-id, and (optionally) cite-year-id which share state to accumulate and render citations.

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. It has the contract

(->* () (#:tag string? #:sec-title string?) part?)

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 default value for the #:tag argument is "doc-bibliography" and for #:sec-title is "Bibliography".

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 style 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

Styles for use with define-cite.

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

procedure

(bib? v)  boolean?

  v : any/c
Returns #t if v is a value produced by make-bib or in-bib, #f otherwise.

procedure

(make-bib #:title title    
  [#:author author    
  #:is-book? is-book?    
  #:location location    
  #:date date    
  #:url url    
  #:note note])  bib?
  title : any/c
  author : any/c = #f
  is-book? : any/c = #f
  location : any/c = #f
  date : (or/c #f date? exact-nonnegative-integer? string?) = #f
  url : string? = #f
  note : any/c = #f
Produces a value that represents a document to cite. Except for is-book? and url, the arguments are used as content, except that #f means that the information is not supplied. Functions like proceedings-location, author-name, and authors help produce elements in a standard format.

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.

procedure

(in-bib orig where)  bib?

  orig : bib?
  where : string?
Extends a bib value so that the rendered citation is suffixed with where, which might be a page or chapter number.

procedure

(proceedings-location location    
  [#:pages pages    
  #:series series    
  #:volume volume])  element?
  location : any/c
  pages : (or (list/c any/c any/c) #f) = #f
  series : any/c = #f
  volume : any/c = #f
Combines elements to generate an element that is suitable for describing a paper’s location within a conference or workshop proceedings.

procedure

(journal-location title    
  [#:pages pages    
  #:number number    
  #:volume volume])  element?
  title : any/c
  pages : (or (list/c any/c any/c) #f) = #f
  number : any/c = #f
  volume : any/c = #f
Combines elements to generate an element that is suitable for describing a paper’s location within a journal.

procedure

(book-location [#:edition edition    
  #:publisher publisher])  element?
  edition : any/c = #f
  publisher : any/c = #f
Combines elements to generate an element that is suitable for describing a book’s location. Both arguments are optional, but at least one must be supplied.

procedure

(techrpt-location #:institution institution    
  #:number number)  element?
  institution : any/c
  number : any/c
Combines elements to generate an element that is suitable for describing a technical report’s location.

procedure

(dissertation-location [#:institution institution    
  #:degree degree])  element?
  institution : edition = any/c
  degree : any/c = "PhD"
Combines elements to generate an element that is suitable for describing a dissertation.

procedure

(author-name first last [#:suffix suffix])  element?

  first : any/c
  last : any/c
  suffix : any/c = #f
Combines elements to generate an element that is suitable for describing an author’s name, especially where the last name is not merely a sequence of ASCII alphabet letters or where the name has a suffix (such as “Jr.”).

procedure

(authors name names ...)  element?

  name : content?
  names : content?
Combines multiple author elements into one, so that it is rendered and alphabetized appropriately. Any of name or names that are strings are parsed in the same way as by make-bib.

procedure

(org-author-name name)  element?

  name : any/c
Converts an element for an organization name to one suitable for use as a bib-value author.

procedure

(other-authors)  element?

Generates an element that is suitable for use as a “others” author. When combined with another author element via authors, the one created by other-authors renders as “et al.”

procedure

(editor name)  element?

  name : name/c
Takes an author-name element and create one that represents the editor of a collection. If a name is a string, it is parsed in the same way as by make-bib.

parameter

(abbreviate-given-names)  any/c

(abbreviate-given-names abbreviate?)  void?
  abbreviate? : any/c
Shortens given names in calls to author and make-bib to just the first initial when the parameter value is not #f. Otherwise, does not change the author names.

Defaults to #f.

Added in version 1.5 of package scribble-lib.