simple bibliography support in Scribble

svn: r7929

original commit: 8e68038c83caf89c979d04c66228140163dc178f

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/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.