doc: Improved bibliography doc, documented `noabbrev'.

* doc/user/bib.skb (Bibliography): Better explain the constraints with
  `name+year'.  Document `noabbrev'.
  (Sorting Bibliography Entries): Document
  `bib-sort/first-author-last-name'.

* doc/user/src/bib1.sbib: Use proper `author' fields, including
  `noabbrev'.

git-archimport-id: lcourtes@laas.fr--2006-libre/skribilo--devo--1.2--patch-99

2 files changed, 52 insertions, 11 deletions

diff --git a/doc/user/bib.skb b/doc/user/bib.skb
index 6349697..4ede5fd 100644
--- a/doc/user/bib.skb
+++ b/doc/user/bib.skb
@@ -1,7 +1,7 @@
 ;;; bib.skb  --  The Skribilo bibliography.
 ;;;
 ;;; Copyright 2001, 2002, 2003, 2004  Manuel Serrano
-;;; Copyright 2007  Ludovic Courtès <ludovic.courtes@laas.fr>
+;;; Copyright 2007  Ludovic Courtès <ludo@gnu.org>
 ;;;
 ;;;
 ;;; This program is free software; you can redistribute it and/or modify
@@ -112,7 +112,7 @@ the ,(code "bibliography") Skribe function call before the call to the
 	      (#!rest entry... ,[If ,(param 'entry) is a string, it denotes
               a file containing the entry (see ,(ref :mark "skribe-bib-path" 
               :text "bibliograph path")). Otherwise, it is a list described
-              by the ,(ref :subsection "Bibliography syntax" :text "syntax") 
+              by the ,(ref :subsection "Bibliography Syntax" :text "syntax") 
               below.]))
 	    :see-also '(bib-table? make-bib-table *bib-table* the-bibliography)
 	    :force-engines *api-engines*
@@ -169,17 +169,41 @@ Here is an example of a simple Skribe database.])
                         the year of publication will be used.  For
                         instance: "\[Smith 1984\]",
                         "\[Smith & Johnson 1979\]", or
-                        "\[Smith et al. 1980\]".])
+                        "\[Smith ,(it [et al.]) 1980\]".])
 	      (:count ,[The symbol ,(code "partial") or ,(code "full")
                specifies the numbering to be applied. The value 
                ,(code "partial") tells Skribilo to count only the entries
                filtered in by ,(param :pred). The value ,(code "full")
                tells Skribilo to count all entries, event those filtered out
                by ,(param :pred).]))
-	    :see-also '(bib-table? make-bib-table *bib-table* bibliography)
+	    :see-also '(bib-table? make-bib-table *bib-table*
+	                bibliography noabbrev)
 	    :force-engines *api-engines*
 	    :common-args '())
 
+(p [Note that the ,(code "name+year") label style will only work if the
+following conventions are followed by the ,(code "author") field of your
+bibliography entries:
+
+,(itemize
+    (item [the ,(code [author]) fields of bibliographic entries should
+be a string containing a comma-separated list of full author names;])
+    (item [each ``full author name'' should have the form ,(code
+"first-name second-name ... last-name");]))
+
+When using the ,(code "name+year") label style, it is sometimes
+desirable to preclude automatic abbreviations for some authors, e.g.,
+when the author is the name of a consortium or company rather than that
+of a person.  In that case, you should enclose the value of your ,(code
+"author") field in a ,(ref :ident "noabbrev" :text (code "noabbrev"))
+markup.])
+   
+(doc-markup 'noabbrev
+	    '()
+	    :see-also '(the-bibliography bib-sort/first-author-last-name))
+   
+(p [The following example illustrates typical use of a bibliography.])
+
 (example-produce 
  (example :legend "Printing a Bibliography" (prgm :file "src/bib2.skb"))
  (disp (include "src/bib2.skb")))
@@ -233,6 +257,7 @@ pre-existing functions for sorting entries:])
 	    :force-engines *api-engines*
 	    :source "skribilo/biblio.scm"
 	    :others '(bib-sort/idents bib-sort/dates)
+	    :see-also '(bib-sort/first-author-last-name)
 	    :common-args '())
 
 (p [The first function sorts the entries according to an alphabetic ordering
@@ -242,7 +267,23 @@ entries identifier. The last one sorts according to entries date.])
 (example-produce 
  (example :legend "Sorting Bibliography Entries" 
 	  (prgm :file "skribilo/biblio.scm"
-	        :definition 'bib-sort/idents)))))
+	        :definition 'bib-sort/idents)))
+   
+(p [In addition, the ,(code [(skribilo biblio author)]) module exports
+a fourth procedure that sorts bibliography entries:])
+
+(doc-markup 'bib-sort/first-author-last-name
+            '((entries [The list of entries.]))
+            :force-engines *api-engines*
+            :source "skribilo/biblio/author.scm"
+            :see-also '(bib-sort/authors the-bibliography noabbrev)
+            :common-args '())
+	    
+(p [This procedure allows entries to be sorted according to the last
+name of the first author of each bibliography entry.  For this to work,
+the author field of bibliography entries must follow the same
+conventions as for the ,(code "name+year") label style of ,(ref :ident
+"the-bibliography" :text (code "the-bibliography")).])))
 
 ;*---------------------------------------------------------------------*/
 ;*    skribebibtex                                                     */
diff --git a/doc/user/src/bib1.sbib b/doc/user/src/bib1.sbib
index 6afff71..6e41f1a 100644
--- a/doc/user/src/bib1.sbib
+++ b/doc/user/src/bib1.sbib
@@ -1,12 +1,12 @@
 (book queinnec:lisp
-   (author "Queinnec, C.")
+   (author "Christian Queinnec")
    (title "Lisp In Small Pieces")
    (publisher "Cambridge University Press")
    (year "1996"))
 
 (book scheme:ieee
    (title "IEEE Standard for the Scheme Programming Language")
-   (author "IEEE Std 1178-1990")
+   (author (noabbrev "IEEE Std 1178-1990"))
    (publisher "Institute of Electrical and Electronic Engineers, Inc.")
    (address "New York, NY")
    (year "1991"))
@@ -17,15 +17,15 @@
    (url "http://www.inria.fr/mimosa/fp/Bigloo"))
 
 (misc scheme:r4rs
-   (title "The Revised4 Report on the Algorithmic Language Scheme")
-   (author "Clinger, W. and Rees, J.")
+   (title [The Revised,(sup [4]) Report on the Algorithmic Language Scheme])
+   (author "William D. Clinger, Jonathan Rees")
    (month "Nov")
    (year "1991")
    (url "http://www.cs.indiana.edu/scheme-repository/R4RS/r4rs_toc.html"))
 
 (article scheme:r5rs
    (title "The Revised5 Report on the Algorithmic Language Scheme")
-   (author "Kelsey, R. and Clinger, W. and Rees, J.")
+   (author "Richard Kelsey, William D. Clinger, Jonathan Rees")
    (journal "Higher-Order and Symbolic Computation")
    (volume "11")
    (number "1")
@@ -34,7 +34,7 @@
    (url "http://kaolin.unice.fr/Bigloo/doc/r5rs.html"))
 
 (book as:sicp
-   (author "Abelson, H. and Sussman, G.")
+   (author "Harold Abelson, Gerald Jay Sussman")
    (title "Structure and Interpretation of Computer Programs")
    (year "1985")
    (publisher "MIT Press")