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.

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]

scribble-lib/info.rkt

@@ -23,4 +23,4 @@
 
 (define pkg-authors '(mflatt eli))
 
-(define version "1.21")
+(define version "1.22")

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

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