summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Court`es2007-08-29 13:22:11 +0000
committerLudovic Court`es2007-08-29 13:22:11 +0000
commit34c706c18157fdcf474758466cb7d44f10c397b1 (patch)
tree7d308fcfd57337b4672d77835a800d3e82c304d8 /doc
parenta748ab9dc57810b8e2a1ddc776e2c697e2ab3070 (diff)
parent08f2474a31da503120c1f6c180767b2c68c9f498 (diff)
downloadskribilo-34c706c18157fdcf474758466cb7d44f10c397b1.tar.gz
skribilo-34c706c18157fdcf474758466cb7d44f10c397b1.tar.lz
skribilo-34c706c18157fdcf474758466cb7d44f10c397b1.zip
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: skribilo@sv.gnu.org--2006/skribilo--devo--1.2--patch-157
Diffstat (limited to 'doc')
-rw-r--r--doc/user/bib.skb51
-rw-r--r--doc/user/src/bib1.sbib12
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")