diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 5bc99f34..6738aa2b 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -1546,27 +1546,67 @@ ;; ---------------------------------------- - (provide cite) + (provide cite + bib-entry + (rename-out [a-bib-entry? bib-entry?]) + bibliography) - (define (cite #:key key #:title title #:author author #:location location #:date date #:url [url #f]) - "[...]" - #; - (make-bibliography-element - #f - (list "[...]") - key - (list (string-append - (content->string (list author)) - ", " - (content->string (list title)))) - (list (make-element #f (list author - ", " - title - ", " - date - ". " - location - "."))))) + (define (cite key) + (make-link-element + #f + (list (format "[~a]" key)) + `(cite ,key))) + + (define-struct a-bib-entry (key val)) + + (define (bib-entry #:key key #:title title #:author author #:location location #:date date #:url [url #f]) + (make-a-bib-entry + key + (make-element + #f + (list author + ", " + 'ldquo + title + "," 'rdquo " " + location + ", " + date + "." + (if url + (make-element #f + (list " " + (link url + (tt url)))) + ""))))) + + (define (bibliography #:tag [tag "doc-bibliography"] . citations) + (make-unnumbered-part + #f + (list `(part ,tag)) + (list "Bibliography") + '() + null + (make-flow + (list + (make-table + "bibliography" + (map (lambda (c) + (let ([key (a-bib-entry-key c)] + [val (a-bib-entry-val c)]) + (list + (make-flow + (list + (make-paragraph + (list + (make-target-element + #f + (list "[" key "]") + `(cite ,key)))))) + (make-flow (list (make-paragraph (list (hspace 1))))) + (make-flow (list (make-paragraph (list val))))))) + citations)))) + null)) ;; ---------------------------------------- diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css index 91abe129..65edba73 100644 --- a/collects/scribble/scribble.css +++ b/collects/scribble/scribble.css @@ -419,6 +419,10 @@ font-family: Consolas, Courier, monospace; font-size: 13px; } + .bibliography td { + vertical-align: top; + } + .imageleft { float: left; margin-right: 0.3em; diff --git a/collects/scribble/struct.ss b/collects/scribble/struct.ss index 0fbcc685..f11475f8 100644 --- a/collects/scribble/struct.ss +++ b/collects/scribble/struct.ss @@ -50,13 +50,24 @@ (let-values ([(v ext?) (resolve-get/where part ri key)]) v)) + (define (resolve-get-keys part ri key-pred) + (let ([l null]) + (hash-table-for-each + (collected-info-info + (part-collected-info part ri)) + (lambda (k v) + (when (key-pred k) + (set! l (cons k l))))) + l)) + (provide (struct-out collect-info) (struct-out resolve-info) part-collected-info collect-put! resolve-get - resolve-get/tentative) + resolve-get/tentative + resolve-get-keys) ;; ---------------------------------------- diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 3c8138db..fe975d3b 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -690,6 +690,65 @@ key for the index iterm does not include quotes.} @defproc[(indexed-envvar [pre-content any/c] ...) element?]{A combination of @scheme[envvar] and @scheme[as-index].} +@; ------------------------------------------------------------------------ +@section{Bibliography} + +@defproc[(cite [key string?]) element?]{ + +Links to a bibliography entry, using @scheme[key] both to indicate the +bibliography entry and, in square brackets, as the link text.} + +@defproc[(bibliography [#:tag string? "doc-bibliography"] + [entry bib-entry?] ...) + part?]{ + +Creates a bibliography part containing the given entries, each of +which is created with @scheme[bib-entry]. The entries are typeset in +order as given} + +@defproc[(bib-entry [#:key key string?] + [#:title title any/c] + [#:author author any/c] + [#:location location any/c] + [#:date date any/c] + [#:url url any/c #f]) + bib-entry?]{ + +Creates a bibliography entry. The @scheme[key] is used to refer to the +entry via @scheme[cite]. The other arguments are used as elements in +the entry: + +@itemize{ + + @item{@scheme[title] is the title of the cited work. It will be + surrounded by quotes in typeset form.} + + @item{@scheme[author] lists the authors. Use names in their usual + order (as opposed to ``last, first''), and separate multiple + names with commas using ``and'' before the last name (where + there are multiple names). The @scheme[author] is typeset in + the bibliography as given.} + + @item{@scheme[location] names the publication venue, such as a + conference name or a journal with volume, number, and + pages. The @scheme[location] is typeset in the bibliography as + given.} + + @item{@scheme[date] is a date, usually just a year (as a string). It + is typeset in the bibliography as given.} + + @item{@scheme[url] is an optional URL. It is typeset in the + bibliography using @scheme[tt] and hyperlinked.} + +}} + + +@defproc[(bib-entry? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a bibliography entry created by +@scheme[bib-entry], @scheme[#f] otherwise.} + + @; ------------------------------------------------------------------------ @section{Miscellaneous} diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl index 25466042..23867600 100644 --- a/collects/scribblings/scribble/style.scrbl +++ b/collects/scribblings/scribble/style.scrbl @@ -1,6 +1,7 @@ #lang scribble/doc -@require[scribble/manual] -@require["utils.ss"] +@(require scribble/manual + "utils.ss" + (for-label scribble/manual)) @title[#:tag "reference-style"]{Style Guide} @@ -48,3 +49,6 @@ Use American style for quotation marks and punctuation at the end of quotation marks (i.e., a sentence-terminating period goes inside the quotation marks). Of course, this rule does not apply for quotation marks that are part of code. + +Do not use a citation reference (as created by @scheme[cite]) as a +noun. Use it as an annotation.