biblatex-apa 1.0 (13may10)

git-svn-id: svn://tug.org/texlive/trunk@18245 c570f23f-e606-0410-a88d-b1316a301751

9 files changed, 102 insertions, 47 deletions

diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/README b/Master/texmf-dist/doc/latex/biblatex-apa/README
index 12b88b8a703..c2d9e78f827 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/README
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/README
@@ -1,4 +1,4 @@
-Version 0.9
+Version 1.0
 
 Permission is granted to copy, distribute and/or modify this software under
 the terms of the LaTeX Project Public License, version
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-citations.bib b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-citations.bib
index 332dcc9bbd8..dd783fbbb4f 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-citations.bib
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-citations.bib
@@ -124,6 +124,9 @@
 % (APA 6.14)
 % The second example from this section is repeated in the APA manual in section 7.01
 % and the bib entry for that example is given below
+% The second entry below is a dummy to show the initials disambiguation in the examples
+% text. Disambiguation only works on single names, hence the dummy entry to force
+% disambiguation.
 @BOOK{6.14,
   AUTHOR         = {I. Light},
   TITLE          = {Deflecting Immigration},
@@ -134,6 +137,13 @@
   KEYWORDS       = {noinclude}
 }
 
+@BOOK{6.14a,
+  AUTHOR         = {D. Light},
+  TITLE          = {Some title},
+  YEAR           = {2009},
+  KEYWORDS       = {noinclude}
+}
+
 % (APA 6.15)
 @ARTICLE{6.15a,
   TITLE          = {Study Finds Something Interesting},
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-references.bib b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-references.bib
index 566badd0045..4a732df971b 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-references.bib
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test-references.bib
@@ -1,4 +1,5 @@
 % (APA 7.01 Example 1)
+% Note that the URL is suppressed if there is a DOI
 @ARTICLE{7.01:1,
   AUTHOR         = {K. L. Herbst-Damm and J. A. Kulik},
   TITLE          = {Volunteer Support, Marital Status, and the Survival Times of Terminally Ill Patients},
@@ -6,7 +7,9 @@
   VOLUME         = {24},
   PAGES          = {225--229},
   YEAR           = {2005},
-  DOI            = {10.1037/0278-6133.24.2.225}
+  DOI            = {10.1037/0278-6133.24.2.225},
+  URL            = {http://some.url}
+
 }
 
 % (APA 7.01 Example 2)
@@ -59,7 +62,7 @@
   TITLE          = {Optimizing Knowledge Transfer by New Employees in Companies},
   JOURNALTITLE   = {Knowledge Management Research and Practice},
   YEAR           = {2007},
-  NOTE           = {Advance online publication},
+  PUBSTATE       = {Advance online publication},
   DOI            = {10.1057/palgrave.kmrp.8500141}
 }
 
@@ -231,10 +234,11 @@
   YEAR           = {1991}
 }
 
-% Note use of ABSTRACT to get the "Abstract retrieved from" instead of just
-% "retrieved from"
+% Note use of special USERB field value to specify that the URL is for the abstract
+% and so the entry gets "Abstract retrieved from" instead of just "retrieved from"
+% USERB must equal "urlisabstract" to do this
 @ARTICLE{7.01:16b,
-  ABSTRACT       = {yes},
+  USERB          = {urlisabstract},
   AUTHOR         = {S. R. Lassen and M. M. Steele and W. Sailor},
   TITLE          = {The Relationship of School-wide Positive Behavour Support to Academic Achievement in an Urban Middle School},
   JOURNALTITLE   = {Psychology in the Schools},
@@ -255,7 +259,7 @@
   VOLUME         = {31},
   PAGES          = {24--53},
   YEAR           = {2000},
-  NOTE           = {Abstract retrieved from  {S}ociological {A}bstracts database. (Accession No. 200010185)}
+  NOTE           = {Abstract retrieved from {S}ociological {A}bstracts database. (Accession No. 200010185)}
 }
 
 % (APA 7.02 Example 18)
@@ -415,12 +419,14 @@
 }
 
 % (APA 7.03 Example 31)
-% NUMBER contains report specifics in parentheses after title
+% NUMBER contains report number, "No." is added automatically and TYPE contains the
+% report type
 @REPORT{7.03:31,
   AUTHOR         = {{U.S. Department of Health and Human Services, National Institute of Mental Health, National Heart, Lung and Blood Institute}},
   TITLE          = {Managing Asthma},
   SUBTITLE       = {A Guide for Schools},
-  NUMBER         = {NIH Publication No. 02-2650},
+  TYPE           = {NIH Publication},
+  NUMBER         = {02-2650},
   YEAR           = {2003},
   URL            = {http://www.nhlbi.nih.gov/health/prof/lung/asthma/asth_sch.pdf}
 }
@@ -439,7 +445,8 @@
 @REPORT{7.03:33,
   AUTHOR         = {S. S. A. Kessy and F. M. Urio},
   TITLE          = {The Contribution of Microfinance Institutions to Poverty Reduction in {T}anzania},
-  NUMBER         = {Research Report No. 06.3},
+  TYPE           = {Research Report},
+  NUMBER         = {06.3},
   YEAR           = {2006},
   ORGANIZATION   = {Poverty Alleviation website},
   URL            = {http://www.repoa.or.tz/documents_storage/Publications/Reports/06.3_Kessey_and_Urio.pdf}
@@ -447,21 +454,25 @@
 
 % (APA 7.03 Example 34)
 % Use the ORGANIZATION field to describe the URL
+% This example is an anomaly as it doesnt' have "No." before the report number.
+% This style does this consistently for all reports with numbers
 @REPORT{7.03:34,
   AUTHOR         = {J. E. McDaniel and C. G. Miskel},
   TITLE          = {The Effect of Groups and Individuals on National Decisionmaking},
   SUBTITLE       = {Influence and Domination in the Reading Policymaking Environment},
-  NUMBER         = {CIERA Report 3-025},
+  TYPE           = {CIERA Report},
+  NUMBER         = {3-025},
   YEAR           = {2002},
   ORGANIZATION   = {University of Michigan, Center for Improvement of Early Reading Achievement website},
   URL            = {http://www.ciera.org/library/reports/inquiry-3/3-025/3-025.pdf}
 }
 
 % (APA 7.03 Example 35)
-@REPORT{7.03:35,
+@TECHREPORT{7.03:35,
   AUTHOR         = {{Employee Benefit Research Institute}},
   TITLE          = {Sources of health Insurance and Characteristics of the Uninsured},
-  NUMBER         = {Issue Brief No. 123},
+  TYPE           = {Issue Brief},
+  NUMBER         = {123},
   DATE           = {1992-02},
   LOCATION       = {Washington, DC},
   PUBLISHER      = {Author}
@@ -481,7 +492,7 @@
 % (APA 7.04 Example 37)
 % Unpublished conference papers are UNPUBLISHED type
 @UNPUBLISHED{7.04:37,
-  ABSTRACT       = {yes},  
+  USERB          = {urlisabstract},
   AUTHOR         = {S. Liu},
   TITLE          = {Defending Against Business Crises with the Help of Inteligent Agent Based Early Warning Solutions},
   DATE           = {2005-05},
@@ -518,30 +529,29 @@
 }
 
 % (APA 7.05 Example 40)
-@THESIS{7.05:40,
+% The PHDTHESIS and MASTERSTHESIS are the same as THESIS but they supply a default
+% TYPE field automatically
+@MASTERSTHESIS{7.05:40,
   AUTHOR         = {D. S. McNiel},
   TITLE          = {Meaning Through Narrative},
   SUBTITLE       = {A Personal Narrative Discussing Growing Up with an Alchoholic Mother},
-  TYPE           = {Master's thesis},
   YEAR           = {2006},
   NOTE           = {Available from ProQuest Dissertations and These database. (UMI No. 1434728)}
 }
 
 % (APA 7.05 Example 41)
-@THESIS{7.05:41,
+@PHDTHESIS{7.05:41,
   AUTHOR         = {R. J. Adams},
   TITLE          = {Building a Foundation for Evaluation of Instruction in Higher Education and Continuing Education},
-  TYPE           = {Doctoral dissertation},
   YEAR           = {1973},
   URL            = {http://www.ohiolink.edu/etd/}
 }
 
 % (APA 7.05 Example 42)
-@THESIS{7.05:42,
+@PHDTHESIS{7.05:42,
   AUTHOR         = {A. Bruckman},
   TITLE          = {{MOOSE} Crossing},
   SUBTITLE       = {Construction, Community, and Learning in a Networked Virtual World for Kids},
-  TYPE           = {Doctoral dissertation},
   INSTITUTION    = {Massachusetts Institute of Technology},
   YEAR           = {1977},
   URL            = {http://www-static.cc.gatech.edu/~asb/thesis/}
@@ -549,10 +559,10 @@
 
 % (APA 7.05 Example 43)
 % VOLUME and NUMBER can be used in a thesis entry to specify the DAI volume and number
-% The ABSTRACT field indicates that this is a reference to an abstract, not the actual
-% work and thus the title is not emphasised
+% The USERB having the special value "isabstract" field indicates that this is a
+% reference to an abstract, not the actual work and thus the title is not emphasised
 @THESIS{7.05:43,
-  ABSTRACT       = {yes},
+  USERB          = {isabstract},
   AUTHOR         = {L. G. Appelbaum},
   TITLE          = {Three Studies of Human Information Processing},
   SUBTITLE       = {Texture Amplification, Motion Representation, and Figure-Ground Segregation},
@@ -564,11 +574,15 @@
 }
 
 % (APA 7.05 Example 44)
-@THESIS{7.05:44,
+% Note we're overriding TYPE here which is usually automatically set for PHDTHESIS since,
+% for some reason, this entry has "Doctoral thesis" instead of the usual "Doctoral
+% dissertation"
+@PHDTHESIS{7.05:44,
   AUTHOR         = {P. Carlbom},
   TITLE          = {Carbody and Passengers in Rail Vehicle Dynamics},
   TYPE           = {Doctoral thesis},
-  INSTITUTION    = {Royal Institute of Technology, Stockholm, Sweden},
+  INSTITUTION    = {Royal Institute of Technology, Stockholm},
+  LOCATION       = {Sweden},
   YEAR           = {2000},
   URL            = {http://urn.kb.se/resolve?urn=urn:nbn:se:kth:diva-3029}
 }
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.pdf b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.pdf
index bbb9a767f7c..c4e3cb59833 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.pdf
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.pdf
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.tex b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.tex
index 2355a5d85c0..056e8831330 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.tex
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.tex
@@ -11,8 +11,7 @@
 
 % Biblatex
 \usepackage[style=apa,%
-            bibencoding=inputenc,%
-            uniquename=false]{biblatex}
+            bibencoding=inputenc]{biblatex}
 
 \newcommand\apa[2][]{\ifthenelse{\equal{#1}{}}%
                        {\textcolor{blue}{\texttt{(APA #2)}}}%
@@ -171,7 +170,9 @@ and\\
 \textcolor{red}{Note: The second citation key here is taken from the APA
   references section as it is repeated there. This example is currently impossible to automate as
   it is, due to the nature of name list parsing in BibTeX. Disambiguation
-  works between single names and not names within lists at the moment. See
+  works between single names and not names within lists at the moment. The
+  first example works due to a dummy single-name entry with the same
+  surname in the |.bib| for the citation examples. See
  |biblatex-apa| docs. This is planned to be fully supported with |biblatex|
  2.x which should include the necessary underlying functionality}.
 
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.pdf b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.pdf
index ccaec66898e..6bb6d29303b 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.pdf
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.pdf
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex
index 5951fd29281..6c9c0670a6d 100644
--- a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex
+++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex
@@ -19,7 +19,7 @@
   url={http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex-contrib/biblatex-apa/},
   author={Philip Kime},
   email={Philip@kime.org.uk},
-  revision={0.9},
+  revision={1.0},
   date={\today}}
 
 \hypersetup{%
@@ -51,7 +51,7 @@ rely on each other, macro-wise, in places.
 
 In this document and in the code, the specific APA requirements are
 referred to by the section and (if appropriate) the example number of the
-APA Style Guide (5th Edition).
+APA Style Guide (6th Edition).
 
 \subsection{Requirements}\label{ref:req}
 
@@ -87,8 +87,10 @@ references specifications run to about 60 pages and are very specific in
 terms of formatting. They are also not entirely consistent but then again,
 it is rare to have such a thorough specification to work from. There are
 some parts of the requirements which are impossible to automatically
-satisfy given the current reliance of \sty{biblatex} (as of version
-\texttt{0.8}) on \bibtex . These limitations are described below.
+satisfy given the limitations of the |.bib| format and \bibtex. These
+limitations are described below and will be addressed in a future
+\sty{biblatex} version which supports the more advanced features of the
+|biber| backend.
 
 \subsection{Acknowledgments}
 
@@ -254,12 +256,14 @@ accompanying \path{.bib} files:
   References section style. To see how the style deals with a particular
   example from \apa{7.x}, look it up in here. Every example is marked with
   the APA example number and has explanatory notes.
-\item[\path{biblatex-apa.cbx}] The |biblatex-apa| citations style. It is
+\item[\path{apa.cbx}] The |biblatex-apa| citations style. It is
   decently structured with comments but shouldn't need to be read for
   normal use.
-\item[\path{biblatex-apa.bbx}] The |biblatex-apa| references style. It is
+\item[\path{apa.bbx}] The |biblatex-apa| references style. It is
   decently structured with comments but shouldn't need to be read for
   normal use.
+\item[\path{*.lbx}] The |biblatex-apa| localisation files. These files
+  override some language-specific macros for some fixed strings.
 \end{description}
 
 \subsection{Citations}
@@ -282,7 +286,10 @@ commas. See examples using this command in \path{biblatex-apa-test.tex}.
 
 The references style was based on the \sty{biblatex} default
 |authoryear-comp| style but is so heavily modified, it's almost
-unrecognisable. Some general notes:
+unrecognisable. If in doubt read the example references |.bib| as it is
+commented and you can learn a lot from he examples by picking something
+close to what you need from the APA examples and then looking in this file
+to see how it was implemented. Some general notes:
 \begin{itemize}
 \setlength{\itemsep}{0pt}
 \item There are occasions where there is no sensible \path{.bib} key to
@@ -299,6 +306,9 @@ unrecognisable. Some general notes:
   \emph{not} the |SERIES| field.
 \item |VOLUME|, |NUMBER| and |CHAPTER| are forced into arabic numerals if
   they are given as roman numerals, as required by \apa{6.22}.
+\item |USERB| is sometimes used to specify that a URL is for an abstract
+  rather than the paper itself. Not very portable but that's because of |bibtex| data
+  model limtations.
 \item |USERD| is sometimes used to specify information that indicates
   special formatting. Not very portable but that's because of |bibtex| data
   model limtations.
@@ -311,6 +321,17 @@ unrecognisable. Some general notes:
 
 \begin{changelog}
 
+\begin{release}{1.0}{2010-05-12}
+\item Fixed |TYPE| and |NUMBER| fields in |REPORT| entries. Now more
+  flexible.
+\item |PUBSTATE| is now valid for articles.
+\item |DOI|, if present, suppresses any |URL| field.
+\item Abstract retrieval string is now conditional on |USERB| field, not on
+  the existence of an abstract.
+\item Default strings for |PHDTHESIS| and |MASTERSTHESIS| entries corrected.
+\item |LOCATION| is now valid for thesis entries and comes after |INSTITUTION|.
+\end{release}
+
 \begin{release}{0.9}{2010-03-08}
 \item Update for APA manual 6th edition and |biblatex| 0.9
 \end{release}
diff --git a/Master/texmf-dist/tex/latex/biblatex-apa/american-apa.lbx b/Master/texmf-dist/tex/latex/biblatex-apa/american-apa.lbx
index b25c394e5f3..91a4c1210ba 100644
--- a/Master/texmf-dist/tex/latex/biblatex-apa/american-apa.lbx
+++ b/Master/texmf-dist/tex/latex/biblatex-apa/american-apa.lbx
@@ -47,6 +47,8 @@
   october          = {{October}{October}},
   november         = {{November}{November}},
   december         = {{December}{December}},
+  mathesis         = {{Master's thesis}{Master's\addabbrvspace thesis}},
+  phdthesis        = {{Doctoral\addabbrvspace dissertation}{Doctoral\addabbrvspace dissertation}},
   origyear         = {{original\space work\space published}{original\space work\space published}},
   typechair        = {{Chair}{Chair}},
   typechairs       = {{Chairs}{Chairs}},
diff --git a/Master/texmf-dist/tex/latex/biblatex-apa/apa.bbx b/Master/texmf-dist/tex/latex/biblatex-apa/apa.bbx
index 2192505ccf1..be98aeef1d3 100644
--- a/Master/texmf-dist/tex/latex/biblatex-apa/apa.bbx
+++ b/Master/texmf-dist/tex/latex/biblatex-apa/apa.bbx
@@ -721,7 +721,10 @@
                                {\apanum{#1}}}
                              {\mkbibemph{\apanum{#1}}}}
 
-\DeclareFieldFormat[report]{number}{\mkbibparens{\apanum{#1}}}
+\DeclareFieldFormat[report]{number}{\mkbibparens{\iffieldundef{type}
+                                                  {}
+                                                  {\printfield{type}\setunit{\addspace}}%
+                                                  \bibcpstring{number}~\apanum{#1}}}
 
 \newbibmacro*{apa:reportnum}{%
   \iffieldundef{number}%
@@ -758,7 +761,7 @@
 % (APA 7.02 Example 40--44) Theses titles and volume
 %                           Titles are not emph if only an abstract
 
-\DeclareFieldFormat[thesis]{title}{\iffieldundef{abstract}{\mkbibemph{#1}}{#1}}
+\DeclareFieldFormat[thesis]{title}{\iffieldequalstr{userb}{isabstract}{#1}{\mkbibemph{#1}}}
 \DeclareFieldFormat[thesis]{volume}{\mkbibemph{\apanum{#1}}\addspace}
 \DeclareFieldFormat[thesis]{number}{\mkbibparens{\apanum{#1}}\addspace}
 \DeclareFieldFormat[thesis]{eprinttype}{\mkbibemph{#1}\addspace}
@@ -952,13 +955,13 @@
 
 \renewbibmacro*{url+urldate}{%
      \def\@apaar{retrieved}% default
-     \iffieldundef{url}
+     \ifthenelse{\iffieldundef{url}\OR\NOT\iffieldundef{doi}}
        {}
        {\iffieldundef{usera}{}{\patchcmd{\@apaar}{retrieved}{\thefield{usera}}{}{}}%
-         \iffieldundef{abstract}
-         {\printtext{\bibcpstring{\@apaar}}}
+         \iffieldequalstr{userb}{urlisabstract}
          {\printtext{\bibcpstring{abstract}}\addspace%
-           \printtext{\bibstring{\@apaar}}}%
+           \printtext{\bibstring{\@apaar}}}
+         {\printtext{\bibcpstring{\@apaar}}}%
         \setunit{\addspace}%
         \iffieldundef{urlyear}
           {}
@@ -975,10 +978,10 @@
      \iffieldundef{eprint}
        {}
        {\iffieldundef{usera}{}{\patchcmd{\@apaar}{retrieved}{\thefield{usera}}{}{}}%
-         \iffieldundef{abstract}
-         {\printtext{\bibcpstring{\@apaar}}}
+         \iffieldequalstr{userb}{urlisabstract}
          {\printtext{\bibcpstring{abstract}}\addspace%
-           \printtext{\bibstring{\@apaar}}}%
+           \printtext{\bibstring{\@apaar}}}
+         {\printtext{\bibcpstring{\@apaar}}}%
         \setunit{\addspace}%
         \printtext{\bibstring{from}}%
         \setunit*{\addspace}%
@@ -1045,6 +1048,8 @@
   \setunit{\bibpagespunct}%
   \printfield{pages}%
   \newunit\newblock
+  \printfield{pubstate}%
+  \newunit\newblock
   \printfield{note}%
   \newunit\newblock
   \usebibmacro{doi+eprint+url}%
@@ -1346,7 +1351,7 @@
   \setunit{\labelnamepunct}\newblock
   \usebibmacro{title}%
   \ifthenelse{\NOT\iffieldundef{title}\OR\boolean{bbx:titleinauthpos}}{\newunit}{\setunit{\addspace}}\newblock
-  \usebibmacro{type+institution+year}%
+  \usebibmacro{type+institution}%
   \newunit\newblock
   \usebibmacro{thesis:retrinfo}
   \newunit\newblock
@@ -1605,7 +1610,7 @@
   \printlist{publisher}%
   \newunit}
 
-\newbibmacro*{type+institution+year}{%
+\newbibmacro*{type+institution}{%
   \ifthenelse{\iffieldundef{type}\AND\iffieldundef{institution}}
     {}
     {\printtext[parens]{%
@@ -1614,7 +1619,9 @@
          {\setunit*{\addcolon\space}}%
        \printfield{type}%
        \setunit*{\addcomma\space}%
-       \printlist{institution}}%
+       \printlist{institution}%
+       \setunit*{\addcomma\space}%
+       \printlist{location}}%
      \newunit}}
 
 %