From 08f2474a31da503120c1f6c180767b2c68c9f498 Mon Sep 17 00:00:00 2001 From: Ludovic Court`es Date: Wed, 29 Aug 2007 12:39:00 +0000 Subject: 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 --- doc/user/bib.skb | 51 +++++++++++++++++++++++++++++++++++++++++++++----- doc/user/src/bib1.sbib | 12 ++++++------ 2 files changed, 52 insertions(+), 11 deletions(-) (limited to 'doc') 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 +;;; Copyright 2007 Ludovic Courtès ;;; ;;; ;;; 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") -- cgit v1.2.3