simple bibliography support in Scribble

svn: r7929

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])
+  (define (cite key)
-    "[...]"
+    (make-link-element
-    #;
+     #f
-    (make-bibliography-element
+     (list (format "[~a]" key))
-    #f
+     `(cite ,key)))
-    (list "[...]")
+
-    key
+  (define-struct a-bib-entry (key val))
-    (list (string-append
+
-    (content->string (list author))
+  (define (bib-entry #:key key #:title title #:author author #:location location #:date date #:url [url #f])
-    ", "
+    (make-a-bib-entry
-    (content->string (list title))))
+     key
-    (list (make-element #f (list author
+     (make-element
-    ", "
+      #f
-    title
+      (list author
-    ", "
+            ", "
-    date
+            'ldquo
-    ". "
+            title
-    location
+            "," '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))
 
   ;; ----------------------------------------
 

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;

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

collects/scribblings/reference/cont.scrbl

@@ -3,13 +3,10 @@
 
 @title[#:tag "cont"]{Continuations}
 
-See @secref["cont-model"] and @secref["prompt-model"] for
+See @secref["cont-model"] and @secref["prompt-model"] for general
-general information about continuations. PLT Scheme's support for
+information about continuations. PLT Scheme's support for prompts and
-prompts and composable continuations most closely resembles Dorai
+composable continuations most closely resembles Dorai Sitaram's
-Sitaram's @scheme[\%] and @scheme[fcontrol] operator @cite[#:key
+@scheme[\%] and @scheme[fcontrol] operator @cite["Sitaram93"].
-"cite:fcontrol" #:title "Handling Control" #:author "Dorai Sitaram"
-#:location "Programming Language Design and Implementation" #:date
-1993].
 
 Scheme installs a @defterm{continuation barrier} around evaluation in
 the following contexts, preventing full-continuation jumps across the

collects/scribblings/reference/exns.scrbl

@@ -4,12 +4,9 @@
 
 @title[#:tag "exns"]{Exceptions}
 
-See @secref["exn-model"] for information on the PLT Scheme
+See @secref["exn-model"] for information on the PLT Scheme exception
-exception model. It is based on @cite[#:key "friedman-exns" #:title
+model. It is based on a proposal by Friedman, Haynes, and Dybvig
-"Exception system proposal" #:author "Daniel P. Friedman and
+@cite["Friedman95"].
-C. T. Haynes and R. Kent Dybvig" #:location
-"http://www.cs.indiana.edu/scheme-repository/doc.proposals.exceptions.html"
-#:date ""].
 
 Whenever a primitive error occurs in PLT Scheme, an exception is
 raised.  The value that is passed to the current @tech{exception

collects/scribblings/reference/for.scrbl

@@ -6,11 +6,7 @@
 @guideintro["for"]{iterations and comprehensions}
 
 The PLT Scheme iteration forms are based on SRFI-42
-@cite[#:key "srfi-42"
+@cite["SRFI-42"].
-      #:title "SRFI-42: Eager Comprehensions"
-      #:author "Sebastian Egner"
-      #:location "http://srfi.schemers.org/srfi-42/"
-      #:date "2003"].
 
 @section{Iteration and Comprehension Forms}
 

collects/scribblings/reference/parameters.scrbl

@@ -5,9 +5,7 @@
 
 See @secref["parameter-model"] for basic information on the
 parameter model. Parameters correspond to @defterm{preserved thread
-fluids} in Scsh @cite[#:key "cite:thread-fluids" #:title "Processes
+fluids} in Scsh @cite["Gasbichler02"].
-vs. User-Level Threads in Scsh" #:author "Martin Gasbichler and
-Michael Sperber" #:date 2002 #:location "Scheme Workshop"].
 
 To parameterize code in a thread- and continuation-friendly manner,
 use @scheme[parameterize]. The @scheme[parameterize] form introduces a

collects/scribblings/reference/reference.scrbl

@@ -48,4 +48,36 @@ This chapter provides some temporary hyper-link targets.
 
 @;------------------------------------------------------------------------
 
+@(bibliography
+
+  (bib-entry #:key "Sitaram93" 
+             #:title "Handling Control" 
+             #:author "Dorai Sitaram"
+             #:location "Programming Language Design and Implementation" 
+             #:date 1993)
+
+  (bib-entry #:key "Friedman95" 
+             #:title "Exception system proposal" 
+             #:author "Daniel P. Friedman, C. T. Haynes, and R. Kent Dybvig" 
+             #:location "web page"
+             #:url "http://www.cs.indiana.edu/scheme-repository/doc.proposals.exceptions.html"
+             #:date "1995")
+
+  (bib-entry #:key "SRFI-42"
+             #:title "SRFI-42: Eager Comprehensions"
+             #:author "Sebastian Egner"
+             #:location "SRFI"
+             #:url "http://srfi.schemers.org/srfi-42/"
+             #:date "2003")
+
+  (bib-entry #:key "Gasbichler02" 
+             #:title "Processes vs. User-Level Threads in Scsh" 
+             #:author "Martin Gasbichler and Michael Sperber" 
+             #:date 2002 
+             #:location "Scheme Workshop")
+
+  )
+
+@;------------------------------------------------------------------------
+
 @index-section[]

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}
 

collects/scribblings/scribble/style.scrbl

@@ -1,6 +1,7 @@
 #lang scribble/doc
-@require[scribble/manual]
+@(require scribble/manual
-@require["utils.ss"]
+          "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.

collects/scribblings/slideshow/slideshow.scrbl

@@ -14,10 +14,7 @@ To get started, run the @exec{slideshow} executable, and click the
 @onscreen{Run Tutorial} link.
 
 To learn more about why Slideshow is cool, see also ``Slideshow:
-Functional Presentations'' @cite[#:key "slideshow" #:title "Slideshow:
+Functional Presentations'' @cite["Findler06"].
-Functional Presentations" #:author "Robert Bruce Findler and Matthew
-Flatt" #:location @elem{@italic{Journal of Functional Programming},
-16(4-5), pp. 583--619} #:date "2006" #:url paper-url].
 
 @defmodulelang*/no-declare[(slideshow)]{Most of the bindings defined in
 the manual are provided by the @schememodname[slideshow] language.}
@@ -29,3 +26,13 @@ the manual are provided by the @schememodname[slideshow] language.}
 @include-section["guide.scrbl"]
 @include-section["picts.scrbl"]
 @include-section["slides.scrbl"]
+
+@(bibliography
+  (bib-entry #:key "Findler06" 
+             #:title "Slideshow: Functional Presentations"
+             #:author "Robert Bruce Findler and Matthew Flatt" 
+             #:location @elem{@italic{Journal of Functional Programming}, 16(4-5), pp. 583--619} 
+             #:date "2006" 
+             #:url paper-url))
+
+@index-section[]