commit a8dec74ffaa73f26b289736529fcdc63999a1027
parent ba2e1d6ca7103620af9d206f7e59277ae5e52a6f
Author: Leif Andersen <leif@leifandersen.net>
Date: Thu, 18 May 2017 13:07:20 -0400
Add commands for cite-author and cite-year to autobib. (#111)
These commands work like natbib's citeauthor and citeyear commands,
and facilities making possessive citations. For example:
> Thanks to @(cite-author foo)'s (@(cite-year foo)) paper on stuff...
These identifiers are added with `define-cite` as keywords, and thus
can be omitted with no downside for backwards compatibility.
@(define-cite cite citet generate-bib
#:cite-author cite-author
#:cite-year cite-year)
Also in this commit:
* Add documentation.
* Add tests for autobib
* Bump version and add history.
Diffstat:
4 files changed, 66 insertions(+), 11 deletions(-)
diff --git a/scribble-doc/scriblib/scribblings/autobib.scrbl b/scribble-doc/scriblib/scribblings/autobib.scrbl
@@ -55,16 +55,19 @@ includes a citation to section 8 of the Racket reference.
(code:line #:render-date-in-bib render-date-expr)
(code:line #:render-date-in-cite render-date-expr)
(code:line #:date<? date-compare-expr)
- (code:line #:date=? date-compare-expr)])
+ (code:line #:date=? date-compare-expr)
+ (code:line #:cite-author cite-author-id)
+ (code:line #:cite-year cite-year-id)])
#:contracts ([style-expr (or/c author+date-style number-style)]
- [spaces-expr number]
+ [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 @racket[~cite-id], @racket[citet-id], and
-@racket[generate-bibliography-id], which share state to accumulate and
-render citations.
+Binds @racket[~cite-id], @racket[citet-id],
+@racket[generate-bibliography-id], (optionally)
+@racket[cite-author-id], and (optionally) @racket[cite-year-id] which
+share state to accumulate and render citations.
The function bound to @racket[~cite-id] produces a citation referring
to one or more bibliography entries with a preceding non-breaking
@@ -90,6 +93,30 @@ section for the bibliography. It has the contract
(->* () (#:tag string? #:sec-title string?) part?)
]
+If provided, the function bound to @racket[cite-author-id]
+generates an element containing the authors of a paper.
+
+@racketblock[
+ (->* (bib?) element?)
+]
+
+If provided, the function bound to @racket[cite-year-id]
+generates an element containing the year the paper was
+published in, or possibly multiple years if multiple papers
+are provided.
+
+@racketblock[
+ (->* (bib?) #:rest (listof? bib?) element?)
+]
+
+The functions bound to @racket[cite-author-id] and
+@racket[cite-year-id] make it possible to create possessive textual citations.
+
+@codeblock[#:keep-lang-line? #f]|{
+ #lang scribble/base
+ @citeauthor[scribble-cite]'s (@citeyear[scribble-cite]) autobib library is pretty nifty.
+}|
+
The default value for the @racket[#:tag] argument is @racket["doc-bibliography"]
and for @racket[#:sec-title] is @racket["Bibliography"].
@@ -110,7 +137,10 @@ to add an extra element after the date; the default disambiguator adds
ambiguous raises an exception. Date comparison is controlled by
@racket[date-compare-expr]s. Dates in citations and dates in the
bibliography may be rendered differently, as specified by the
-optionally given @racket[render-date-expr] functions.}
+optionally given @racket[render-date-expr] functions.
+
+@history[#:changed "1.22" "Add optional ids for author-name and author-year"]
+}
@deftogether[(
@defthing[author+date-style any/c]
diff --git a/scribble-lib/info.rkt b/scribble-lib/info.rkt
@@ -23,4 +23,4 @@
(define pkg-authors '(mflatt eli))
-(define version "1.21")
+(define version "1.22")
diff --git a/scribble-lib/scriblib/autobib.rkt b/scribble-lib/scriblib/autobib.rkt
@@ -365,15 +365,17 @@
(define-syntax (define-cite stx)
(syntax-parse stx
- [(_ (~var ~cite) citet generate-bibliography
+ [(_ (~var ~cite id) citet:id generate-bibliography:id
(~or (~optional (~seq #:style style) #:defaults ([style #'author+date-style]))
(~optional (~seq #:disambiguate fn) #:defaults ([fn #'#f]))
(~optional (~seq #:render-date-in-bib render-date-bib) #:defaults ([render-date-bib #'#f]))
(~optional (~seq #:spaces spaces) #:defaults ([spaces #'1]))
(~optional (~seq #:render-date-in-cite render-date-cite) #:defaults ([render-date-cite #'#f]))
(~optional (~seq #:date<? date<?) #:defaults ([date<? #'#f]))
- (~optional (~seq #:date=? date=?) #:defaults ([date=? #'#f]))) ...)
- (syntax/loc stx
+ (~optional (~seq #:date=? date=?) #:defaults ([date=? #'#f]))
+ (~optional (~seq #:cite-author cite-author:id) #:defaults ([cite-author #'#f]))
+ (~optional (~seq #:cite-year cite-year:id) #:defaults ([cite-year #'#f]))) ...)
+ (quasisyntax/loc stx
(begin
(define group (make-bib-group (make-hasheq)))
(define the-style style)
@@ -382,7 +384,15 @@
(define (citet bib-entry . bib-entries)
(add-inline-cite group (cons bib-entry bib-entries) the-style date<? date=?))
(define (generate-bibliography #:tag [tag "doc-bibliography"] #:sec-title [sec-title "Bibliography"])
- (gen-bib tag group sec-title the-style fn render-date-bib render-date-cite date<? date=? spaces))))]))
+ (gen-bib tag group sec-title the-style fn render-date-bib render-date-cite date<? date=? spaces))
+ #,(when (identifier? #'cite-author)
+ #'(define (cite-author bib-entry)
+ (add-cite group bib-entry 'autobib-author #f #f the-style)))
+ #,(when (identifier? #'cite-year)
+ #'(define (cite-year bib-entry . bib-entries)
+ (add-date-cites group (cons bib-entry bib-entries)
+ (send the-style get-group-sep)
+ the-style #t date<? date=?)))))]))
(define (ends-in-punc? e)
(regexp-match? #rx"[.!?,]$" (content->string e)))
diff --git a/scribble-test/tests/scriblib/autobib.rkt b/scribble-test/tests/scriblib/autobib.rkt
@@ -0,0 +1,15 @@
+#lang racket
+
+(require scriblib/autobib)
+
+(let ()
+ (define-cite cite citet gen-bib)
+ cite citet gen-bib
+ (void))
+
+(let ()
+ (define-cite cite citet gen-bib
+ #:cite-author cite-author
+ #:cite-year cite-year)
+ cite citet gen-bib cite-author cite-year
+ (void))
