autobib.scrbl (10978B)
1 #lang scribble/manual 2 @(require (for-label (only-in scribble/core content?) 3 scribble/struct 4 scriblib/autobib 5 scheme/base 6 scheme/contract)) 7 8 @title[#:tag "autobib"]{Bibliographies} 9 10 @defmodule[scriblib/autobib] 11 12 This library provides support for bibliography management in a Scribble 13 document. The @racket[define-cite] form is used to bind procedures 14 that create in-line citations and generate the bibilography in the 15 document. 16 17 Individual bibliography entries are created with the @racket[make-bib] 18 function. See below for an example. 19 20 @codeblock|{ 21 #lang scribble/base 22 23 @(require scriblib/autobib) 24 25 @(define-cite ~cite citet generate-bibliography) 26 27 @(define plt-tr1 28 (make-bib 29 #:title "Reference: Racket" 30 #:author (authors "Matthew Flatt" "PLT") 31 #:date "2010" 32 #:location (techrpt-location #:institution "PLT Inc." 33 #:number "PLT-TR-2010-1") 34 #:url "http://racket-lang.org/tr1/")) 35 36 Racket is fun@~cite[plt-tr1]. 37 38 @(generate-bibliography) 39 }| 40 41 For citations that reference a page number or section, the @racket[in-bib] 42 function can be used. For example, the following snippet: 43 44 @codeblock[#:keep-lang-line? #f]|{ 45 #lang scribble/base 46 Racket has a contract library.@~cite[(in-bib plt-tr1 ", ยง8")] 47 }| 48 49 includes a citation to section 8 of the Racket reference. 50 51 @defform/subs[(define-cite ~cite-id citet-id generate-bibliography-id 52 option ...) 53 ([option (code:line #:style style-expr) 54 (code:line #:disambiguate disambiguator-expr) 55 (code:line #:spaces spaces-expr) 56 (code:line #:render-date-in-bib render-date-expr) 57 (code:line #:render-date-in-cite render-date-expr) 58 (code:line #:date<? date-compare-expr) 59 (code:line #:date=? date-compare-expr) 60 (code:line #:cite-author cite-author-id) 61 (code:line #:cite-year cite-year-id)]) 62 #:contracts ([style-expr (or/c number-style author+date-style author+date-square-bracket-style)] 63 [spaces-expr number?] 64 [disambiguator-expr (or/c #f (-> exact-nonnegative-integer? element?))] 65 [render-date-expr (or/c #f (-> date? element?))] 66 [date-compare-expr (or/c #f (-> date? date? boolean?))])]{ 67 68 Binds @racket[~cite-id], @racket[citet-id], 69 @racket[generate-bibliography-id], (optionally) 70 @racket[cite-author-id], and (optionally) @racket[cite-year-id] which 71 share state to accumulate and render citations. 72 73 The function bound to @racket[~cite-id] produces a citation referring 74 to one or more bibliography entries with a preceding non-breaking 75 space, by default sorting the entries to match the bibliography order. 76 It has the contract 77 78 @racketblock[ 79 (->* (bib?) (#:sort? any/c) #:rest (listof bib?) element?) 80 ] 81 82 The function bound to @racket[citet-id] generates an element suitable 83 for use as a noun---referring to a document or its author---for one 84 or more bibliography entries which have the same authors. It has the contract 85 86 @racketblock[ 87 (->* (bib?) () #:rest (listof bib?) element?) 88 ] 89 90 The function bound to @racket[generate-bibliography-id] generates the 91 section for the bibliography. It has the contract 92 93 @racketblock[ 94 (->* () (#:tag string? #:sec-title string?) part?) 95 ] 96 97 If provided, the function bound to @racket[cite-author-id] 98 generates an element containing the authors of a paper. 99 100 @racketblock[ 101 (->* (bib?) element?) 102 ] 103 104 If provided, the function bound to @racket[cite-year-id] 105 generates an element containing the year the paper was 106 published in, or possibly multiple years if multiple papers 107 are provided. 108 109 @racketblock[ 110 (->* (bib?) #:rest (listof? bib?) element?) 111 ] 112 113 The functions bound to @racket[cite-author-id] and 114 @racket[cite-year-id] make it possible to create possessive textual citations. 115 116 @codeblock[#:keep-lang-line? #f]|{ 117 #lang scribble/base 118 @citeauthor[scribble-cite]'s (@citeyear[scribble-cite]) autobib library is pretty nifty. 119 }| 120 121 The default value for the @racket[#:tag] argument is @racket["doc-bibliography"] 122 and for @racket[#:sec-title] is @racket["Bibliography"]. 123 124 The optional @racket[spaces-expr] determines the number of blank lines that appear 125 between citations. The default number of lines is 1. 126 127 The optional @racket[style-expr] determines the way that citations and 128 the bibliography are rendered.@margin-note*{Programmer-defined styles 129 may be supported in the future.} Currently, two built-in style are 130 provided, and @racket[author+date-style] is the default. 131 132 For @racket[author+date-style], 133 if two citations' references would render the same (as judged by equal 134 authors and dates that are considered the same) but are different, the 135 optionally provided function from @racket[disambiguator-expr] is used 136 to add an extra element after the date; the default disambiguator adds 137 @litchar{a}, @litchar{b}, @etc until @litchar{z}, and anything more 138 ambiguous raises an exception. Date comparison is controlled by 139 @racket[date-compare-expr]s. Dates in citations and dates in the 140 bibliography may be rendered differently, as specified by the 141 optionally given @racket[render-date-expr] functions. 142 143 @history[#:changed "1.22" "Add optional ids for author-name and author-year"] 144 } 145 146 @deftogether[( 147 @defthing[author+date-style any/c] 148 @defthing[author+date-square-bracket-style any/c] 149 @defthing[number-style any/c] 150 )]{ 151 152 Styles for use with @racket[define-cite]. 153 154 The @racket[author+date-square-bracket-style] definition is the same 155 as @racket[author+date-style], except that references to citations 156 are enclosed in @litchar["[]"] instead of @litchar["()"]. 157 } 158 159 160 @defproc[(bib? [v any/c]) boolean?]{ 161 162 Returns @racket[#t] if @racket[v] is a value produced by 163 @racket[make-bib] or @racket[in-bib], @racket[#f] otherwise.} 164 165 166 @defproc[(make-bib [#:title title any/c] 167 [#:author author any/c #f] 168 [#:is-book? is-book? any/c #f] 169 [#:location location any/c #f] 170 [#:date date (or/c #f date? exact-nonnegative-integer? string?) #f] 171 [#:url url string? #f] 172 [#:note note any/c #f]) 173 bib?]{ 174 175 Produces a value that represents a document to cite. Except for 176 @racket[is-book?] and @racket[url], the arguments are used as 177 content, except that @racket[#f] means that the information is not 178 supplied. Functions like @racket[proceedings-location], 179 @racket[author-name], and @racket[authors] help produce elements in a 180 standard format. 181 182 Dates are internally represented as @racket[date] values, so a @racket[date] 183 may be given, or a number or string that represent the year. 184 185 An element produced by a function like @racket[author-name] tracks 186 first, last names, and name suffixes separately, so that names can be 187 ordered and rendered correctly. When a string is provided as an author 188 name, the last non-empty sequence of alphabetic characters or 189 @litchar["-"] after a space is treated as the author name, and the 190 rest is treated as the first name.} 191 192 @defproc[(in-bib [orig bib?] [where string?]) bib?]{ 193 194 Extends a bib value so that the rendered citation is suffixed with 195 @racket[where], which might be a page or chapter number.} 196 197 @defproc[(proceedings-location [location any/c] 198 [#:pages pages (or (list/c any/c any/c) #f) #f] 199 [#:series series any/c #f] 200 [#:volume volume any/c #f]) 201 element?]{ 202 203 Combines elements to generate an element that is suitable for 204 describing a paper's location within a conference or workshop 205 proceedings.} 206 207 @defproc[(journal-location [title any/c] 208 [#:pages pages (or (list/c any/c any/c) #f) #f] 209 [#:number number any/c #f] 210 [#:volume volume any/c #f]) 211 element?]{ 212 213 Combines elements to generate an element that is suitable for 214 describing a paper's location within a journal.} 215 216 217 @defproc[(book-location [#:edition edition any/c #f] 218 [#:publisher publisher any/c #f]) 219 element?]{ 220 221 Combines elements to generate an element that is suitable for 222 describing a book's location. 223 Both arguments are optional, but at least one must be supplied.} 224 225 @defproc[(techrpt-location [#:institution institution any/c] 226 [#:number number any/c]) 227 element?]{ 228 229 Combines elements to generate an element that is suitable for 230 describing a technical report's location.} 231 232 @defproc[(dissertation-location [#:institution institution any/c] 233 [#:degree degree any/c "PhD"]) 234 element?]{ 235 236 Combines elements to generate an element that is suitable for 237 describing a dissertation.} 238 239 240 @defproc[(book-chapter-location [title any/c] 241 [#:pages pages (or (list/c any/c any/c) #f) #f] 242 [#:section section any/c #f] 243 [#:volume volume any/c #f] 244 [#:publisher publisher any/c #f]) 245 element?]{ 246 247 Combines elements to generate an element that is suitable for 248 describing a paper's location within a chapter or part of a book.} 249 250 251 @defproc[(author-name [first any/c] 252 [last any/c] 253 [#:suffix suffix any/c #f]) 254 element?]{ 255 256 Combines elements to generate an element that is suitable for 257 describing an author's name, especially where the last name is not 258 merely a sequence of ASCII alphabet letters or where the name has a 259 suffix (such as ``Jr.'').} 260 261 @defproc[(authors [name content?] [names content?] ...) element?]{ 262 263 Combines multiple author elements into one, so that it is rendered and 264 alphabetized appropriately. Any of @racket[name] or @racket[names] 265 that are strings are 266 parsed in the same way as by @racket[make-bib].} 267 268 @defproc[(org-author-name [name (or/c element? string?)]) element?]{ 269 270 Converts an element for an organization name to one suitable for use 271 as a bib-value author.} 272 273 @defproc[(other-authors) element?]{ 274 275 Generates an element that is suitable for use as a ``others'' author. 276 When combined with another author element via @racket[authors], the 277 one created by @racket[other-authors] renders as ``et al.''} 278 279 @defproc[(editor [name (or/c element? string?)]) element?]{ 280 281 Takes an author-name element and create one that represents the editor 282 of a collection. If a @racket[name] is a string, it is parsed in the 283 same way as by @racket[make-bib].} 284 285 @defparam[abbreviate-given-names abbreviate? any/c]{ 286 Shortens given names in calls to @racket[author] and @racket[make-bib] 287 to just the first initial when the parameter value is not @racket[#f]. 288 Otherwise, does not change the author names. 289 290 Defaults to @racket[#f]. 291 292 @history[#:added "1.5"] 293 }