diff options
author | Karl Berry <karl@freefriends.org> | 2012-02-16 00:09:07 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-02-16 00:09:07 +0000 |
commit | b9fea4534c20a6dc688733f8759babf1aa2c181d (patch) | |
tree | fad0fc4e4367c99562b5d10b40b803f46559cb4c /Master/texmf-dist/source | |
parent | 22c52d8f8c1c659c2fa41aeb08bf3948b709ec91 (diff) |
apacite (15feb12)
git-svn-id: svn://tug.org/texlive/trunk@25402 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/bibtex/apacite/apacite.drv (renamed from Master/texmf-dist/source/latex/apacite/apacite.drv) | 30 | ||||
-rw-r--r-- | Master/texmf-dist/source/bibtex/apacite/apacite.dtx (renamed from Master/texmf-dist/source/latex/apacite/apacite.dtx) | 7708 | ||||
-rw-r--r-- | Master/texmf-dist/source/bibtex/apacite/apacite.ins (renamed from Master/texmf-dist/source/latex/apacite/apacite.ins) | 37 |
3 files changed, 5701 insertions, 2074 deletions
diff --git a/Master/texmf-dist/source/latex/apacite/apacite.drv b/Master/texmf-dist/source/bibtex/apacite/apacite.drv index 0f4de95051f..cbd31bef776 100644 --- a/Master/texmf-dist/source/latex/apacite/apacite.drv +++ b/Master/texmf-dist/source/bibtex/apacite/apacite.drv @@ -8,7 +8,7 @@ %% %% This is a generated file. %% -%% Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +%% Copyright (C) 1994-8888 Erik Meijer and any individual authors listed %% elsewhere in this file. %% %% This file is part of the `apacite' package. @@ -26,10 +26,12 @@ %% %% The `apacite' package consists of the files apacite.dtx and %% apacite.ins, and the following generated files: -%% apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -%% apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -%% english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -%% ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +%% apacite.sty, apacdoc.sty, apacite.drv, +%% apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +%% apa5ex.bib, apacxmpl.tex, +%% english.apc, dutch.apc, finnish.apc, french.apc, +%% german.apc, ngerman.apc, greek.apc, norsk.apc, +%% spanish.apc, swedish.apc. %% %% This work has the LPPL maintenance status `maintained' %% @@ -46,13 +48,25 @@ %% do not change apacite.dtx for this purpose. %% \ProvidesFile{apacite.drv} - [2009/03/01 v4.05 apacite documentation driver file] + [2012/02/14 v6.00 apacite documentation driver file] \documentclass{ltxdoc} %\documentclass[twoside]{ltxdoc} %\documentclass[a4paper]{ltxdoc} %\documentclass[twoside,a4paper]{ltxdoc} %% -\usepackage{apacdoc}[2009/03/01 v4.05] +\usepackage{apacdoc}[2012/02/14 v6.00] +%% The |\providecommand|s make sure we don't get an error during +%% installation. +%% Define document-specific macros that are not interesting for +%% users. +\providecommand{\SetupAPACdoc}{}% +\SetupAPACdoc +%% Document page layout. +\providecommand{\APACdocPageLayout}{}% +\APACdocPageLayout +%% Index styles for the source code documentation +\providecommand{\SetupAPACdocPrologues}{}% +\SetupAPACdocPrologues %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% LOADING OF PACKAGES %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -72,7 +86,7 @@ %% \usepackage{german} %% %% Loading apacite with author index option. -\usepackage[ltxemindex,bibnewpage]{apacite}[2009/03/01 v4.05] +\usepackage[ltxemindex,bibnewpage]{apacite}[2012/02/14 v6.00] %% \raggedbottom %% diff --git a/Master/texmf-dist/source/latex/apacite/apacite.dtx b/Master/texmf-dist/source/bibtex/apacite/apacite.dtx index ac15490aefd..1fc67a07e8d 100644 --- a/Master/texmf-dist/source/latex/apacite/apacite.dtx +++ b/Master/texmf-dist/source/bibtex/apacite/apacite.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +% Copyright (C) 1994-2012 Erik Meijer and any individual authors listed % elsewhere in this file. % % This file is part of the `apacite' package. @@ -18,10 +18,12 @@ % % The `apacite' package consists of the files apacite.dtx and % apacite.ins, and the following generated files: -% apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -% apacite.drv, apacdoc.sty, -% english.apc, dutch.apc, finnish.apc, german.apc, ngerman.apc, -% greek.apc, norsk.apc, spanish.apc, swedish.apc. +% apacite.sty, apacdoc.sty, apacite.drv, +% apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +% apa5ex.bib, apacxmpl.tex, +% english.apc, dutch.apc, finnish.apc, french.apc, +% german.apc, ngerman.apc, greek.apc, norsk.apc, +% spanish.apc, swedish.apc. % % This work has the LPPL maintenance status `maintained' % @@ -54,7 +56,7 @@ % \iffalse %<*dtx> \ProvidesFile{apacite.dtx} - [2009/03/01 v4.05 apacite dtx file] + [2012/02/14 v6.00 apacite dtx file] %</dtx> %<driver>\ProvidesFile{apacite.drv} %<package|docpkg>\NeedsTeXFormat{LaTeX2e}[1999/12/01] @@ -69,6 +71,7 @@ %<norsk>\ProvidesFile{norsk.apc} %<spanish>\ProvidesFile{spanish.apc} %<swedish>\ProvidesFile{swedish.apc} +%<xmpl>%% apacxmpl.tex %<bibdb>%% apa5ex.bib %<bibstyle&!annotated>%% apacite.bst %<bibstyle&annotated>%% apacann.bst @@ -79,26 +82,27 @@ %^^A command such that the value of the command is written to the file instead %^^A of the name. %^^A -%<driver> [2009/03/01 v4.05 apacite documentation driver file] -%<package> [2009/03/01 v4.05 APA citation] -%<docpkg> [2009/03/01 v4.05 apacite documentation style] -%<english> [2009/03/01 v4.05 apacite language file] -%<dutch> [2009/03/01 v4.05 apacite language file] -%<finnish> [2009/03/01 v4.05 apacite language file] -%<german> [2009/03/01 v4.05 apacite language file] -%<ngerman> [2009/03/01 v4.05 apacite language file] -%<greek> [2009/03/01 v4.05 apacite language file] -%<norsk> [2009/03/01 v4.05 apacite language file] -%<spanish> [2009/03/01 v4.05 apacite language file] -%<swedish> [2009/03/01 v4.05 apacite language file] -%<bibdb>%% [2009/03/01 v4.05 bibliography database for apacite manual] -%<bibstyle&!annotated>%% [2009/03/01 v4.05 APA bibliography style] +%<driver> [2012/02/14 v6.00 apacite documentation driver file] +%<package> [2012/02/14 v6.00 APA citation] +%<docpkg> [2012/02/14 v6.00 apacite documentation style] +%<english> [2012/02/14 v6.00 apacite language file] +%<dutch> [2012/02/14 v6.00 apacite language file] +%<finnish> [2012/02/14 v6.00 apacite language file] +%<german> [2012/02/14 v6.00 apacite language file] +%<ngerman> [2012/02/14 v6.00 apacite language file] +%<greek> [2012/02/14 v6.00 apacite language file] +%<norsk> [2012/02/14 v6.00 apacite language file] +%<spanish> [2012/02/14 v6.00 apacite language file] +%<swedish> [2012/02/14 v6.00 apacite language file] +%<xmpl>%% [2012/02/14 v6.00 LaTeX file for examples] +%<bibdb>%% [2012/02/14 v6.00 bibliography database for examples] +%<bibstyle&!annotated>%% [2012/02/14 v6.00 APA bibliography style] %<*xbibstyle&!annotated> -%% [2009/03/01 v4.05 APA bibl. style with author index info] +%% [2012/02/14 v6.00 APA bibl. style with author index info] %</xbibstyle&!annotated> -%<bibstyle&annotated>%% [2009/03/01 v4.05 APA annotated bibliography style] +%<bibstyle&annotated>%% [2012/02/14 v6.00 APA annotated bibliography style] %<*xbibstyle&annotated> -%% [2009/03/01 v4.05 APA annotated bibl. style with author index info] +%% [2012/02/14 v6.00 APA annotated bibl. style with author index info] %</xbibstyle&annotated> % %<*install> @@ -112,7 +116,7 @@ %% This file will generate fast loadable files and documentation %% driver files from apacite.dtx when run through LaTeX. %% -%% Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +%% Copyright (C) 1994-2012 Erik Meijer and any individual authors listed %% elsewhere in this file. %% %% This file is part of the `apacite' package. @@ -130,10 +134,12 @@ %% %% The `apacite' package consists of the files apacite.dtx and %% apacite.ins, and the following generated files: -%% apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -%% apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -%% english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -%% ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +%% apacite.sty, apacdoc.sty, apacite.drv, +%% apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +%% apa5ex.bib, apacxmpl.tex, +%% english.apc, dutch.apc, finnish.apc, french.apc, +%% german.apc, ngerman.apc, greek.apc, norsk.apc, +%% spanish.apc, swedish.apc. %% %% This work has the LPPL maintenance status `maintained' %% @@ -151,7 +157,7 @@ This is a generated file. -Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +Copyright (C) 1994-2012 Erik Meijer and any individual authors listed elsewhere in this file. This file is part of the `apacite' package. @@ -169,10 +175,12 @@ LaTeX version 2005/12/01 or later. The `apacite' package consists of the files apacite.dtx and apacite.ins, and the following generated files: -apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +apacite.sty, apacdoc.sty, apacite.drv, +apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +apa5ex.bib, apacxmpl.tex, +english.apc, dutch.apc, finnish.apc, french.apc, +german.apc, ngerman.apc, greek.apc, norsk.apc, +spanish.apc, swedish.apc. This work has the LPPL maintenance status `maintained' @@ -189,7 +197,7 @@ the generated files. This is a generated file. -Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +Copyright (C) 1994-2012 Erik Meijer and any individual authors listed elsewhere in this file. This file is part of the `apacite' package. @@ -207,10 +215,12 @@ LaTeX version 2005/12/01 or later. The `apacite' package consists of the files apacite.dtx and apacite.ins, and the following generated files: -apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +apacite.sty, apacdoc.sty, apacite.drv, +apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +apa5ex.bib, apacxmpl.tex, +english.apc, dutch.apc, finnish.apc, french.apc, +german.apc, ngerman.apc, greek.apc, norsk.apc, +spanish.apc, swedish.apc. This work has the LPPL maintenance status `maintained' @@ -248,6 +258,7 @@ do not change apacite.dtx for this purpose. \file{norsk.apc}{\from{apacite.dtx}{norsk}} \file{spanish.apc}{\from{apacite.dtx}{spanish}} \file{swedish.apc}{\from{apacite.dtx}{swedish}} + \file{apacxmpl.tex}{\from{apacite.dtx}{xmpl}} \usepreamble\drvpreamble \file{apacite.drv}{\from{apacite.dtx}{driver}} \usepreamble\mainpreamble @@ -419,7 +430,19 @@ do not change apacite.dtx for this purpose. %<driver>%\documentclass[a4paper]{ltxdoc} %<driver>%\documentclass[twoside,a4paper]{ltxdoc} %% -\usepackage{apacdoc}[2009/03/01 v4.05] +\usepackage{apacdoc}[2012/02/14 v6.00] +%% The |\providecommand|s make sure we don't get an error during +%% installation. +%% Define document-specific macros that are not interesting for +%% users. +\providecommand{\SetupAPACdoc}{}% +\SetupAPACdoc +%% Document page layout. +\providecommand{\APACdocPageLayout}{}% +\APACdocPageLayout +%% Index styles for the source code documentation +\providecommand{\SetupAPACdocPrologues}{}% +\SetupAPACdocPrologues %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% LOADING OF PACKAGES %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -439,7 +462,7 @@ do not change apacite.dtx for this purpose. %% \usepackage{german} %% %% Loading apacite with author index option. -\usepackage[ltxemindex,bibnewpage]{apacite}[2009/03/01 v4.05] +\usepackage[ltxemindex,bibnewpage]{apacite}[2012/02/14 v6.00] %% \raggedbottom %% @@ -471,8 +494,8 @@ do not change apacite.dtx for this purpose. % % ^^A (I have to find out how to get the following remark in the right % ^^A place in the documentation.) -% ^^A The version numbers have been assigned afterwards; originally, -% ^^A apacite had only release dates. +% ^^A The earlier version numbers have been assigned retroactively; +% ^^A originally, apacite had only release dates. % % \changes{v1.0}{1994/11/30}{First public version} % \changes{v2.0}{2000/09/22}{Second packaged version, the result of @@ -500,6 +523,9 @@ do not change apacite.dtx for this purpose. % and extended language support; more extensive customizability.} % \changes{v4.05}{2009/03/01}{Some bug fixes; extended language support; % annotated bibliographies.} +% \changes{v6.00}{2012/02/14}{First step towards compliance with v6 of +% the APA manual; version number now indicates which version of the APA +% manual is implemented.} % % \GetFileInfo{apacite.sty} % @@ -514,7 +540,6 @@ do not change apacite.dtx for this purpose. % \fi \MakePercentComment % -% Previously apacite.tex : % User's reference manual and test of the apacite package. % Written by Erik Meijer % @@ -558,8 +583,8 @@ do not change apacite.dtx for this purpose. The American Psychological Association (APA) is very strict about the style in which manuscripts submitted to its journals are written and formatted. The requirements of the APA are described in the \emph{Publication Manual of the -American Psychological Association}, the latest version of which is the 5th -edition \cite{APAManual}. In the sequel, this is simply called the \emph{APA +American Psychological Association}, the latest version of which is the 6th +edition \cite{APAManual6}. In the sequel, this is simply called the \emph{APA manual}. The APA manual discusses how candidate authors should write their manuscripts: @@ -578,162 +603,35 @@ structure from specific formatting is one of the basic elements of \LaTeX{} \cite[p.~7]{LaTeXbook}. An implementation of the formatting rules of the APA manual for use with -\LaTeX{} is the \pkg{apa} class of Athanassios Protopapas. This handles all -kinds of issues about general document formatting, title page, section -headings, figures and tables, and so forth. Therefore, if you intend to submit -a manuscript to an APA journal, I strongly recommend using the \pkg{apa} -class. +\LaTeX{} is the \pkg{apa6} class by Brian Beitzel, which is a continuation of +the earlier \pkg{apa} class by Athanassios Protopapas. This handles all kinds of +issues about general document formatting, title page, section headings, figures +and tables, and so forth. Therefore, if you intend to submit a manuscript to an +APA journal, I strongly recommend using the \pkg{apa6} class. An important part of the APA style is the way citations and the reference list -should be formatted. This takes 75 pages in the APA manual (pp.~207--281, -excluding the references to legal materials). This part is not handled by the -\pkg{apa} class, but by the \pkg{apacite} package. The \pkg{apa} class -requires the \pkg{apacite} package, but \pkg{apacite} can be used without -\pkg{apa}. The current document, for example, does not use the \pkg{apa} -class, because I find it desirable that possible users can study the -\pkg{apacite} package and its documentation without having to install several -other classes and packages first. Therefore, the current document uses -standard \LaTeX{} as much as possible. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection*{Some history} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -Before the advent of the first version of \pkg{apacite} in 1994, several -authors have written \TeX{} and \LaTeX{} packages (\fname{.sty}) and \BibTeX{} -style files (\fname{.bst}) with suggestive names as \pkg{apalike}, -\pkg{newapa}, and \pkg{theapa} to try to capture some of the requirements of -the APA manual. A severe problem with the APA citations is that, if the number -of authors is between three and five, inclusive, the first citation must -include all authors, whereas subsequent citations should refer to the first -author ``et al.''. This problem had been solved by the \pkg{newapa} and -\pkg{theapa} packages. - -A lot of APA peculiarities, however, were not covered by these citation -styles. Examples are: -\begin{itemize} -\item In the reference list, authors should be formatted with - their initials after their surnames. Editors, however, - should be formatted with their initials \emph{before} their - surnames if they are not in the author position. -\item If the work referred to is a non-English-language source, - the English translation of the title should be given in - brackets after the title. -\item Edition and volume of a book and the pages of an article - in that book should be gathered between a single pair - of parentheses. -\item The publisher of a book and its address should be given as - ``address: publisher'', and not as ``publisher, address''. -\item When the work used is a reprint or translation of an - earlier work, this should be mentioned in the reference - list. In text, the year must be given in the form - ``1923/1961''. -\item There are several ``tricky'' things with brackets and - parentheses, for example, with the type of an article - (e.g., ``Letter to the editor'', - ``Review of the book \emph{The social life of information}'', - ``Abstract'', ``Special issue''). Furthermore, magazine and - newspaper articles are treated differently than journal - articles; papers presented at meetings must be treated - differently; translators of articles and books and chairs - of symposia must be introduced; an article can have editors - instead of authors (e.g., with a special issue); a PhD thesis - can be abstracted in \emph{Dissertation Abstracts International}; - a (technical) report of some institution can be an (edited) - collection of articles. -\end{itemize} -The \pkg{apacite} package is devised to get (much) closer to the APA rules -than the abovementioned other packages and styles. - -The original version of the \fname{apacite.sty} \LaTeX{} package consisted for -a large part of the citation part of \fname{theapa.sty}. The current version, -however, has been changed and extended in many ways and can therefore not be -considered a straightforward adaptation of \fname{theapa.sty} anymore, -although it provides largely the same commands, such as \cmd{\citeA}, and -peculiarities in the command definitions, such as the use of \verb+<...>+ for -a prefix note and \verb+[...]+ for a postfix note. - -Although the \fname{apacite.bst} \BibTeX{} style started out as a slightly -adapted version of \fname{theapa.bst}, the number of changes became so large -and things became so unmanageable that I decided to write a completely new -bibstyle, although using some small parts of the original. The -\fname{apacite.bst} file can therefore not anymore be seen as an adaptation of -\fname{theapa.bst}. Due to the complex rules of the APA manual, it has become -a large file. In the original process of writing (back in 1994), the error -\begin{verbatim} -You've exceeded BibTeX's wizard-defined function space -\end{verbatim} -was very hard to overcome. It appears that later versions of \BibTeX{} allowed -much more space, because I have not received this message anymore in recent -years, although the bibstyle has been expanded considerably. However, if you -run an old \BibTeX{}, you may encounter this (and similar) error messages. - -In the ``dark years'' between 1994 and 2003, in which there was no official -new version of \pkg{apacite}, I have been fixing small bugs, discovered either -by me or by users who sent in their bug reports, and adding some small options -that were easy to incorporate and that I found useful or that were requested -by a user. Furthermore, in 1998, I spent considerable effort in adding an -(almost) automatic author indexing option, first used for my PhD thesis -\cite{meijer1998}. - -In the first few months of 2003, I fixed a number of problems with the -compatibility between \pkg{apacite} and some other important packages. -Although I had been planning (or wishing, rather) to release a proper official -update of \pkg{apacite} for some time, I had not done so, mainly because I had -not yet taken the time to update the documentation. The compatibility issues -were so severe, however, that I decided in March 2003 to release an -intermediate update, which thus became the first official release since the -original version. This version contained a lot of files with compatibility -patches and tests. The main shortcomings of that version were the lack of -up-to-date documentation and the lack of agreement with the latest version of -the APA manual (5th ed., 2001). - -In September 2003, I finally released a complete, fully updated and -significantly extended version of \pkg{apacite}, including extensive -documentation. However, that version still was not able to format some -citations correctly. The \APACversiondate{2004/07/01} version was a small -improvement of the \APACversiondate{2003/09/05} version, but fixed the -important inadequacies of previous versions. - -The \APACversiondate{2005/06/08} version introduced (limited) support of -non-English languages. This is clearly a non-APA direction, because all -APA publications are in English. However, many journals, universities, -etc.\ in non-English speaking countries base their rules on the APA rules, -and thus it may be useful to have the possibility to use \pkg{apacite} -in combination with documents in non-English languages as well. This -language feature has been further extended in the \APACversiondate{2007/09/03} -version. See section~\ref{sec:compat-babel} for a description of the -implementation of this feature. - -The most salient change in the \APACversiondate{2007/09/03} version was the -shift of many formatting decisions from \BibTeX\ to \LaTeX, so that they are -easier to change by the user. - -The current version adds some further improvements in customizability and -language support, and adds support for annotated bibliographies. - -Apart from the language support and the facilities for customization, the -current version of \pkg{apacite} is aimed at conforming with the 5th edition -of the APA manual. It remains, however, imperfect, although the instances of -incorrectly formatted cases will be rare. The problems can be solved by -``tricking'' the style (e.g., by defining the \fieldname{number} field as -``\verb+2, Serial No. 186+'' if the issue number and serial number of a -journal are both important), but this makes the \fname{.bib} file less -compatible with other styles. In the test examples in section~\ref{sec:xmpl} -below, many tricks are used and discussed. Remaining problems, omissions, and -things-to-be-done can be found in section~\ref{sec:todo}. +should be formatted. This takes 56 pages in the APA manual (pp.~169--224). This +part is not handled by the \pkg{apa6} class, but by the \pkg{apacite} package. +\pkg{apacite} can be used without \pkg{apa6}. The current document, for example, +does not use the \pkg{apa6} class, because I find it desirable that possible +users can study the \pkg{apacite} package and its documentation without having +to install several other classes and packages first. Therefore, the current +document uses standard \LaTeX{} as much as possible. (The \pkg{apa} class used +to require the \pkg{apacite} package, but this was dropped because there is now +also the \pkg{biblatex-apa} citation package as an alternative to +\pkg{apacite}.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection*{Philosophy of \pkg{apacite}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -As can be deduced from the discussion thus far, the first priority of -\pkg{apacite} is to implement the rules of the APA manual with regard to -citation and reference list as closely as possible. However, just like its -predecessors, and actually expanding much beyond their realm, -\pkg{apacite} offers many possibilities for customization as -well. Many details of \pkg{apacite}, particularly punctuation and some fixed -texts (e.g., ``Tech.\ Rep.'') can be changed easily by the user by redefining -some commands in \LaTeX{}. Furthermore, \pkg{apacite} also offers several -proper options to change some of its settings. +The first priority of \pkg{apacite} is to implement the rules of the APA manual +with regard to citation and reference list as closely as possible. However, just +like its predecessors (culminating in Young U. Ryu's \pkg{theapa} package), and +actually expanding much beyond their realm, \pkg{apacite} offers many +possibilities for customization as well. Many details of \pkg{apacite}, +particularly punctuation and some fixed texts (e.g., ``Tech.\ Rep.'') can be +changed easily by the user by redefining some commands in \LaTeX{}. Furthermore, +\pkg{apacite} also offers several proper options to change some of its settings. Whether certain options or customizable aspects are implemented depends on two criteria: (1) Is it possible, easy (enough), and convenient to implement them @@ -749,34 +647,171 @@ will be inconvenient to other users, then I will not pursue it. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection*{New in this version} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -The changes since the \APACversiondate{2007/09/03} version are: +The previous version \APACversiondate{2009/03/01} of \pkg{apacite} +implemented the rules in the 5th edition of the APA manual. The current +version aims to conform with the new (2009) 6th edition of the APA manual. +It does not completely succeed in this yet, although the instances of +incorrectly formatted cases will be rare. Most problems can be solved by +using \LaTeX{} or \BibTeX{} tricks in the \fname{.bib} file, but this +makes the \fname{.bib} file less compatible with other styles. In the +test examples in section~\ref{sec:xmpl} below, many tricks are used and +discussed. Remaining problems, omissions, and things-to-be-done can be +found in section~\ref{sec:todo}. + +The changes since the \APACversiondate{2009/03/01} version are: \begin{itemize} \item -Addition of \fname{french.apc} to the list of language-specific files. +Changes in order to conform to the 6th edition of the APA Manual: (a) added +\fieldname{doi} field and \pkgoption{doi} and \pkg{nodoi} options; (b) +added examples (but not all yet) from the 6th edition to the bibliography +database; (c) changed formatting of reference list entry with more than +7 authors (the first 6, then dots, then the last, instead of the first 6 and +``et al.'') and correspondingly added the \cmd{\BDBL} command; +(d) added the new command \cmd{\BRetrievedFrom} for ``Retrieved from'' +without date and replaced uses of \cmd{\BAvailFrom} by \cmd{\BRetrievedFrom} +(although \cmd{\BAvailFrom} is still defined). + +\item +Introduced the examples \LaTeX{} file \fname{apacxmpl.tex}, which makes +it easier to test \pkg{apacite} and get insight in how nonstandard +cases can be formatted according to APA rules. (Far from finished.) + +\item +Added a style command for authors in the reference list +(\cmd{\APACrefauthstyle}). + +\item +Introduced the \cmd{\usespanishe} command to \fname{spanish.apc} to +support cases in which ``and'' should be ``e'' instead of ``y''. \item -Improvements in various \fname{.apc} files. In particular, in addition -to some small changes in various files, all of the \fname{.apc} files -are greatly extended, supporting more language-specific elements. +Changed some internal code so that \pkg{apacite} can now be used with +the \pkg{bibentry} package. \item -Added support for annotated bibliographies through the \fname{apacann.bst} -and \fname{apacannx.bst} \BibTeX{} style files. See section~\ref{sec:annotate} -for details. +Changed handling of ``von parts''. Corresponding to examples in +earlier editions of the APA manual, \pkg{apacite} used to format +names with von parts as ``Helmholtz, H. L. F. von'' in the reference +list and as ``Helmholtz'' in the text, but in arguably the vast +majority of situations encountered by \pkg{apacite} users, it +is more desirable to format von parts as ``de Waal, E.'' in the +reference list and as ``de Waal'' in the text. This change implies +that it is no longer necessary to include the name in an additional +pair of braces in the \fname{.bib} file, and that, with \pkg{natbib}, +capitalization of the von part (at the beginning of a sentence) with +\cmd{\Citet} and its siblings now works as well. The flipside that +it is now more difficult to obtain the previous behavior. + +\item +Added options to select different citation commands: +\begin{itemize} +\item[(a)] +\pkgoption{apaciteclassic} (default) defines the ``classic'' +\pkg{apacite} citation commands \cmd{\cite}, \cmd{\citeA}, +\cmd{\citeNP}, etc., with the angled bracket prenotes, e.g., +|\citeA<see>[for more details]{ex1}|. +\item[(b)] +\pkgoption{natbibapa} loads \pkg{natbib} and thus defines the +\pkg{natbib} citation commands \cmd{\citet}, \cmd{\citep}, etc., +with the double square bracket notes, e.g., +|\citep[see][for more details]{ex1}|. \pkg{apacite} +now contains some improved compatibility code so that the +combination of \pkg{natbib} and \pkg{apacite} better follows +the APA rules. In particular, the standard \pkg{natbib} style +``(2008a,b)'' is now replaced by the APA style ``(2008a, 2008b)'' +and the usage of ``and'' versus ``\&'' also satisfies the APA +rules. \pkg{apacite} defines a few additional commands that are +missing from \pkg{natbib}, but useful for \pkg{apacite} users. +In particular, \pkg{apacite} defines \cmd{\citeauthort} and +\cmd{\citeauthorp}. The former uses ``and'' and the latter uses +``\&''. \pkg{natbib}'s \cmd{\citeauthor} is configured such that +it is the same as \cmd{\citeauthort}. + +Note that \pkg{natbib} also supports sorting the citations +within a citation command and has commands to capitalize the +first letter of a citation (e.g., \cmd{\Citet}), which should +be used when names with von parts such as ``de Waal'' start a +sentence. +\item[(c)] +\pkgoption{nocitation}, which does not define any citation +commands at all. +\end{itemize} \item -Introduction of the \cmd{\APACstdindex}, \cmd{\APACtocindex}, -\cmd{\APACemindex}, and \cmd{\APACltxemindex} commands, which change the -style of the index. +Added masked citation commands and the \pkgoption{mask} and +\pkgoption{unmask} options to activate or deactivate them. +With the \pkgoption{apaciteclassic} option, the following +masked citation commands are defined: +\cmd{\maskcite}, +\cmd{\maskfullcite}, +\cmd{\maskshortcite}, +\cmd{\maskciteNP}, +\cmd{\maskfullciteNP}, +\cmd{\maskshortciteNP}, +\linebreak[4]\cmd{\maskciteA}, +\cmd{\maskfullciteA}, +\cmd{\maskshortciteA}, +\cmd{\maskciteauthor}, +\linebreak[4]\cmd{\maskfullciteauthor}, +\cmd{\maskshortciteauthor}, +\cmd{\maskciteauthorNP}, +\linebreak[4]\cmd{\maskfullciteauthorNP}, +\cmd{\maskshortciteauthorNP}, +\cmd{\maskciteauthorA}, +\cmd{\maskfullciteauthorA}, +\cmd{\maskshortciteauthorA}, +\cmd{\maskciteyear}, and +\linebreak[4]\cmd{\maskciteyearNP}. +They have exactly the same syntax as the corresponding commands +without ``|mask|''. With the \pkgoption{unmask} option (default), +their definitions are also identical to the non-|mask| commands. +In contrast, with the \pkgoption{mask} option, a message of the form +``\emph{(2 citations removed for masked review)}'' is printed. +The actual message is defined in \cmd{\onemaskedcitationmsg} and +\cmd{\maskedcitationsmsg}, depending on whether one or more citations +are masked. + +In addition to these commands, \cmd{\masknocite} is defined, which +is the same as \cmd{\nocite} with \pkgoption{unmask} and does nothing +with \pkgoption{mask}, and \cmd{\masktext} is defined. The latter has +one mandatory argument, which is the text included in the document +when the \pkgoption{unmask} option is chosen, and one optional +argument (the default being empty), which is the text inserted when +the \pkgoption{mask} option is chosen. + +Similarly, with the \pkgoption{natbibapa} option selected, the +following commands are provided: +\cmd{\masknocite}, +\cmd{\maskcitep}, +\cmd{\maskcitealp}, +\cmd{\maskcitet}, +\cmd{\maskcitealt}, +\cmd{\maskciteauthor}, +\cmd{\maskcitefullauthor}, +\cmd{\maskciteyearpar}, +\cmd{\maskciteyear}, +\cmd{\maskcite}, +\cmd{\maskcitetalias}, +\cmd{\maskcitepalias}, +\cmd{\maskCitet}, +\cmd{\maskCitep}, +\cmd{\maskCitealt}, +\cmd{\maskCitealp}, +\cmd{\maskCiteauthor}, +\cmd{\maskcitenum}, +\cmd{\maskciteauthort}, +\cmd{\maskciteauthorp}, +\cmd{\maskCitefullauthor}, +\cmd{\maskCiteauthort}, +\cmd{\maskCiteauthorp}, and +\cmd{\masktext}. \item Improved source code documentation in the \fname{.dtx} file. \item -Some minor changes and bug fixes. In particular, a few problems that showed up -when the reference list contains multiple works by the same author(s) published -in the same year, have been resolved. +Some minor changes and bug fixes. \end{itemize} @@ -785,7 +820,7 @@ in the same year, have been resolved. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The current document describes how to use \pkg{apacite} and largely assumes knowledge of or access to the standard \BibTeX{} documentation, such as -\citeA{Pata88}, \citeA[chap.~12]{KoDa04}, or \citeA[chap.~12 and~13]{TLC2}. +\citeA{Pata88}, \citeA[Chapter~12]{KoDa04}, or \citeA[Chapters~12 and~13]{TLC2}. Hence, this document does not always describe how to use some of the citation commands or how to construct a bibliography database file in detail if there is no \pkg{apacite}-specific element to it. This document comes in two @@ -799,6 +834,11 @@ source code can be included in this manual. \citeA{meijer07} contains some simple examples in which \pkg{apacite} is compared to standard \LaTeX/\BibTeX{} citation, as well as a description of how \pkg{apacite} works technically. +{\bfseries Note that this manual is not completely up to date.} +This is primarily the case for the specific discussion of the examples +in section~\ref{sec:xmpl}, which focus on the 5th edition of the APA +manual, but there may be some obsolete discussions or omissions elsewhere +in the document as well. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Installation, package loading, and running \BibTeX{}} @@ -834,9 +874,12 @@ This generates the following files: probably, some time in the future, the four \fname{.bst} files will be combined in \fname{apacite.bst}, with the desired behavior induced by options, but this is nontrivial and currently not implemented yet. +\item[\fname{apacxmpl.tex}] \LaTeX{} file that (with the bibliography + database) implements the examples from the APA manual. + This can best be kept in the same directory as \fname{apacite.dtx}. \item[\fname{apa5ex.bib}] The file with bibliographic information - about the references used in the user's manual (i.e., the - current document). This is also useful for users to find out how + of the examples from the APA manual, this user's manual. + This is useful for users to find out how certain nontrivial problems can be solved. This can best be kept in the same directory as \fname{apacite.dtx}. \item[\fname{apacite.drv}] Documentation driver. Run \LaTeX{} on this @@ -862,17 +905,13 @@ This generates the following files: \fname{apacite.dtx}. See section~\ref{sec:apacdoc} for a further discussion of this package. \end{description} -Previous versions of \pkg{apacite} provided the file \fname{apacite.tex}, -which contained the user's manual, but this is now included in -\fname{apacite.dtx} and can be formatted by running \LaTeX{} on -\fname{apacite.drv}. The \fname{apacite.sty} \LaTeX{} package is loaded by putting \mbox{}\vspace{0.7\baselineskip}\\ \cmdthreealt{usepackage}{options}{apacite} \mbox{}\vspace{0.7\baselineskip}\\ somewhere in your document between \cmd{\documentclass} and -\verb+\begin{document}+, or putting +|\begin{document}|, or putting \mbox{}\vspace{0.7\baselineskip}\\ \cmdthreealt{RequirePackage}{options}{apacite} \mbox{}\vspace{0.7\baselineskip}\\ @@ -882,25 +921,22 @@ that is loaded by your document. To load the \fname{apacite.bst} or \fname{apacitex.bst} bibliography style in \BibTeX{}, put \mbox{}\vspace{0.7\baselineskip}\\ -\verb+\bibliographystyle{apacite}+ +|\bibliographystyle{apacite}| \mbox{}\vspace{0.7\baselineskip}\\ -or -\mbox{}\vspace{0.7\baselineskip}\\ -\verb+\bibliographystyle{apacitex}+ -\mbox{}\vspace{0.7\baselineskip}\\ -respectively, in your document before the \cmd{\bibliography} command. The +(or |apacitex|, |apacann|, or |apacannx|) in your document +before the \cmd{\bibliography} command. The position of the bibliography (reference list) is determined by the line \mbox{}\vspace{0.7\baselineskip}\\ \cmdtwo{bibliography}{bibfiles} \mbox{}\vspace{0.7\baselineskip}\\ where \opt{bibfiles} is a list of filenames with \fname{.bib} extension, which -contain the bibliographic information that is used by \BibTeX{} to construct -the reference list. Usually, the \cmd{\bibliographystyle} and -\cmd{\bibliography} are kept together (immediately follow each other) in the -document, although when you are using the \pkg{apa} document class, -\pkg{apacite} is used by definition and you are not supposed to use the -\cmd{\bibliographystyle} command yourself. See the documentation of the -\pkg{apa} documentclass for details about this. +contain the bibliographic information that is used by \BibTeX{} to construct the +reference list. Usually, the \cmd{\bibliographystyle} and \cmd{\bibliography} +are kept together (immediately follow each other) in the document, although when +you are using the \pkg{apa6} document class with \pkg{apacite} support, the +\cmd{\bibliographystyle} is defined by the class and you are not supposed to use +the \cmd{\bibliographystyle} command yourself. See the documentation of the +\pkg{apa6} documentclass for details about this. If you use one of the author indexing options, the author index is put in the \LaTeX{} output by the line @@ -929,6 +965,48 @@ everything right may become large. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following options are recognized by \pkg{apacite}: \begin{description} +\item[\pkgoption{apaciteclassic}] +\item[\pkgoption{natbibapa}] +\item[\pkgoption{nocitation}] \mbox{}\\ + These three option determine which citation commands are defined in + \pkg{apacite}. \pkgoption{apaciteclassic} defines the ``classic'' + \pkg{apacite} citation commands \cmd{\cite}, \cmd{\citeA}, \cmd{\citeNP}, + and so forth, which use angled bracket syntax for prenotes, for example, + |\cite<see>[for more details]{ex1}|. These are the commands + described in section~\ref{sec:cite} below. This is the default in the + current version, but this may change in the future. + + \pkgoption{natbibapa} + loads the \pkg{natbib} package for the citation commands. These + commands, such as \cmd{\citet} and \cmd{\citep}, use double square + brackets, for example, |\citep[see][for more details]{ex1}|. + Because these commands are not defined by \pkg{apacite} but by + \pkg{natbib}, they are not documented in this manual. See the + \pkg{natbib} documentation for their usage. Using \pkg{natbib} has a + few advantages over using the classic \pkg{apacite} commands: + (i) the citation commands are robust, which means they can be used + inside other commands, such as \cmd{\caption}, whereas the \pkg{apacite} + commands, like the traditional \LaTeX{} \cmd{\cite} command, are + fragile and must be \cmd{\protect}ed when used inside other commands; + (ii) the angled brackets do not normally occur in text mode and when + they do, they have special meaning; this may lead to incompatibilities; + (iii) \pkg{natbib} supports sorting citations within a citation + command, and has commands such as \cmd{\Citet} that capitalize the + first letter of a citation; the classic \pkg{apacite} commands lack + this functionality; + (iv) it is easier to switch to other styles, even to numbered styles. + + When the \pkgoption{nocitation} option is requested, no citation + commands (except for \cmd{\nocitemeta}) are defined in \pkg{apacite}. + This may be useful if you want to use another citation package and + want to avoid potential compatibility conflicts. + + The option \pkgoption{natbibapa} is different from + \pkgoption{nocitation} combined with loading of \pkg{natbib} by the + user, because \pkgoption{natbibapa} modifies \pkg{natbib}'s and + \pkg{apacite}'s behavior in a way that better satisfies the APA + rules and fixes some compatibility problems. + \item[\pkgoption{BCAY}] \mbox{}\\ This is a technical option for backwards compatibility with old versions (pre-\APACversiondate{2003/09/05}) of \pkg{apacite}. In those versions of @@ -946,9 +1024,21 @@ The following options are recognized by \pkg{apacite}: that is generated by an old version of \pkg{apacite}, you can turn this option on. +\item[\pkgoption{mask}] +\item[\pkgoption{unmask}] \mbox{}\\ + Many journals use a double blind refereeing process. To conceal the + author's identity in such a masked review, it may be necessary to + suppress some citations, for example, to the working paper version + of the manuscript under review. \pkg{apa6} introduced masked citation + commands, which are now included in \pkg{apacite} as well. These + work as ordinary citations when the \pkgoption{mask} option is not + requested (or when the \pkgoption{unmask} option is chosen, which + is the default) and print a message mentioning suppression of citations + when \pkg{apacite} is loaded with the \pkgoption{mask} option. + \item[\pkgoption{index}] \item[\pkgoption{indexpackage}] -\item[\pkgoption{noindexpackage}] +\item[\pkgoption{noindexpackage}] \mbox{}\\ The \pkgoption{index} option turns author indexing on. See section~\ref{sec:autindex} for a discussion of the author indexing facility. The \pkgoption{index} option should be used with the \fname{apacitex.bst} @@ -1039,17 +1129,77 @@ The following options are recognized by \pkg{apacite}: thus is the only time a non-APA setting is used as default instead of an available APA setting. Therefore, to satisfy the APA rules, you have to request the \pkgoption{bibnewpage} option explicitly. + +\item[\pkgoption{doi}] \mbox{}\\ + Includes doi information in the reference list; the default. + +\item[\pkgoption{nodoi}] \mbox{}\\ + Suppresses doi information in the reference list. + \end{description} % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{The citation commands} \label{sec:cite} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -In this section, the commands are described that can be used to cite a work. -Their default behavior will be explained. In section~\ref{sec:custom}, -customization of this behavior will be discussed. Extensive examples are given -in section~\ref{sec:xmpl}. Table~\ref{tab:basic-cite} gives a brief -impression of the usage and results of the most common citation commands. +This section describes the commands that can be used to cite a work. +Section~\ref{sec:classic} describes the commands available with the +\pkgoption{apaciteclassic} option selected. Section~\ref{sec:natbibapa} +is devoted to the citation commands with the \pkgoption{natbibapa} +command selected. Apart from differences in syntax, there are a few +important differences between these sets of commands: +\begin{itemize} +\item +The \pkgoption{apaciteclassic} commands are \emph{fragile}, like the +standard \LaTeX{} \cmd{\cite} command. This means that they cannot be +used in other commands, like \cmd{\caption}, unless they are protected +by putting \cmd{\protect} before them, for example, +\begin{verbatim} +\caption{Theoretical constructs from \protect\citeA{Jones01}} +\end{verbatim} +In contrast, the \pkg{natbib}/\pkgoption{natbibapa} commands are +\emph{robust}, so they can be used in other commands without the +need for \cmd{\protect}. +\item +The use of the angled brackets (`|<|' and `|>|') in the +\pkgoption{apaciteclassic} commands sometimes causes compatibility +problems, for example, with certain options of the \pkg{babel} +package, such as \pkgoption{spanish}. +\item +With the \pkgoption{sort} option, \pkg{natbib} sorts citations +within the same citation command in the same order as in the reference +list, as required by the APA manual (p.~178). Therefore, when +\pkg{apacite} is loaded with the \pkgoption{natbibapa} option, it +loads \pkg{natbib} with the \pkgoption{sort} option. +Sorting is not implemented in the \pkgoption{apaciteclassic} commands, +and thus the user will need to manually order the citations +alphabetically. +\item +\pkg{natbib} provides a set of commands (e.g., \cmd{\Citet}) that +capitalize the first letter of a citation. This can be used when +a citation, of which the first author's name starts with a lowercase +letter, starts a sentence (APA manual, p.~101). This behavior would +be very hard to reproduce with the \pkgoption{apaciteclassic} +commands. +\end{itemize} +Overall, I believe that the \pkg{natbibapa} option will be preferred +by most users, and I expect that I will make this the default in a +future release of \pkg{apacite}. However, because most users of +\pkg{apacite} will still be working on documents that use the +\pkgoption{apaciteclassic} commands, this is still the default in the +current version. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{The ``classic'' \pkg{apacite} citation commands} +\label{sec:classic} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +This section describes the default behavior of the citation commands +that are avilable with the \pkgoption{apaciteclassic} option. +In section~\ref{sec:custom}, customization of this behavior will be +discussed. Extensive examples are given in section~\ref{sec:xmpl} +and the new examples file described there. Table~\ref{tab:basic-cite} +gives a brief impression of the usage and results of the most common +citation commands. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{table}[tp] @@ -1060,185 +1210,457 @@ impression of the usage and results of the most common citation commands. \hline Command & Result \\ \hline -\verb+\cite<e.g.,>[p.~11]{Jone01,Ross87}+ & +|\cite<e.g.,>[p.~11]{Jone01,Ross87}| & (e.g., Jones, 2001; Ross, 1987, p.~11) \\ -\verb+\citeNP<e.g.,>[p.~11]{Jone01,Ross87}+ & - e.g., Jones, 2001; Ross, 1987, p.~11 \\ -\verb+\citeA<e.g.,>[p.~11]{Jone01,Ross87}+ & +|\citeA<e.g.,>[p.~11]{Jone01,Ross87}| & e.g., Jones (2001); Ross (1987, p.~11) \\ -\verb+\citeauthor<e.g.,>[p.~11]{Jone01,Ross87}+ & +|\citeauthor<e.g.,>[p.~11]{Jone01,Ross87}| & e.g., Jones; Ross, p.~11 \\ -\verb+\citeyear<e.g.,>[p.~11]{Jone01,Ross87}+ & +|\citeyear<e.g.,>[p.~11]{Jone01,Ross87}| & (e.g., 2001; 1987, p.~11) \\ -\verb+\citeyearNP<e.g.,>[p.~11]{Jone01,Ross87}+ & +|\citeyearNP<e.g.,>[p.~11]{Jone01,Ross87}| & e.g., 2001; 1987, p.~11 \\ +|\citeNP<e.g.,>[p.~11]{Jone01,Ross87}| & + e.g., Jones, 2001; Ross, 1987, p.~11 \\ \hline \end{tabular} \end{center} \end{table} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -If the \pkg{apacite} package is loaded, the following citation commands can be -used. -\begin{description} - \item[\cmdfour{cite}{prefix}{postfix}{keys}] - \item[\cmdfour{fullcite}{prefix}{postfix}{keys}] - \item[\cmdfour{shortcite}{prefix}{postfix}{keys}] \mbox{}\\ - These three commands produce parenthetical citations of the - following form: - ``(\opt{prefix} \opt{Authors1}, \opt{Year1}; - \opt{Authors2}, \opt{Year2}; \ldots; \opt{AuthorsN}, \opt{YearN}, - \opt{postfix})''. - The command \cmd{\fullcite} uses the ``full'' author list, and - the \cmd{\shortcite} command uses the abbreviated author list. - The \cmd{\cite} command uses the ``full'' list the first time - a work is referenced and the ``short'' list the second and - subsequent times. In accordance with the APA manual, the - ``full'' list consists of all authors if their number is five - or less, and the first author suffixed with ``et al.{}'' - if their number is six or more. Similarly, the ``short'' list - consists of all authors if their number is two or less and the - first author with ``et al.{}'' if their number is three or more. - There are some nuances for complicated situations. These will - be discussed in section~\ref{sec:xmpl}. - - If the (full) author lists of subsequent citations within the - same citation command are the same, they are not repeated; only - the years of the later citations are given. - This holds for all analogous cases as well. - - The prefix and postfix are optional. Thus, e.g., - \cmdtwo{cite}{keys}, \cmdthree{cite}{postfix}{keys}, - and \cmdthreepre{cite}{prefix}{keys} are also allowed. - This holds for all analogous cases as well. - - \item[\cmdfour{citeNP}{prefix}{postfix}{keys}] - \item[\cmdfour{fullciteNP}{prefix}{postfix}{keys}] - \item[\cmdfour{shortciteNP}{prefix}{postfix}{keys}] \mbox{}\\ - ``No parentheses'' versions of \cmd{\cite}, \cmd{\fullcite}, - and \cmd{\shortcite}. They produce citations of the form - ``\opt{prefix} \opt{Authors1}, \opt{Year1}; - \opt{Authors2}, \opt{Year2}; \ldots; \opt{AuthorsN}, \opt{YearN}, - \opt{postfix}''. Can be used for complex citations within - parenthetical material, see the discussion of - \cmd{\citeyearNP} below. - - \item[\cmdfour{citeA}{prefix}{postfix}{keys}] - \item[\cmdfour{fullciteA}{prefix}{postfix}{keys}] - \item[\cmdfour{shortciteA}{prefix}{postfix}{keys}] \mbox{}\\ - These commands are similar to the commands without the - ``\verb+A+'' suffix. They produce in-text citations of the form - ``\opt{prefix} \opt{Authors1} (\opt{Year1}), - \opt{Authors2} (\opt{Year2}), \ldots, - \opt{AuthorsN} (\opt{YearN}, \opt{postfix})''. - Typically, the \opt{prefix} will be empty, because it is - part of the main text, and there typically will only be - one citation in \opt{keys} (unless the authors of - multiple citations are the same), because the authors' - names are also part of the main text. But it was easy - to provide the additional options, and this enhances - the similarity with the other citation commands, which - I found desirable. - - \item[\cmdfour{citeauthor}{prefix}{postfix}{keys}] - \item[\cmdfour{fullciteauthor}{prefix}{postfix}{keys}] - \item[\cmdfour{shortciteauthor}{prefix}{postfix}{keys}] - \item[\cmdfour{citeauthorNP}{prefix}{postfix}{keys}] - \item[\cmdfour{fullciteauthorNP}{prefix}{postfix}{keys}] - \item[\cmdfour{shortciteauthorNP}{prefix}{postfix}{keys}] \mbox{}\\ - These commands are similar to their \cmd{\cite}-type - counterparts, except that they produce citations of the form - ``\opt{prefix} \opt{Authors1}, \opt{Authors2}, \ldots, - \opt{AuthorsN}, \opt{postfix}'' - (the years and parentheses are left out). - This is typically used in a paragraph when a proper - citation (incl.\ year) to the same work has already been - given in the paragraph.% - \footnote{Note that a paragraph is not - a section. Nor does it need to be declared as a - \cmd{\paragraph}. A reminder for Dutch readers: - ``section'' = ``paragraaf'' and ``paragraph'' = ``alinea''.} - In such a case, according to the APA manual, the year must not be - repeated for repeated references to the same work in the same - paragraph. - - A second important application of these commands is - when some complex citations must be constructed, like - ``\citeauthor{4.05-1}'s \citeyear{4.05-1} theory'', - which makes combined use of \cmd{\citeauthor} and - \cmd{\citeyear}, see below. - - Normally, I would expect only one citation per - \cmd{\citeauthor}-type command, and no \opt{prefix} - or \opt{postfix}. - - The difference between the ``non-\verb+NP+'' versions and the - ``\verb+NP+'' versions is that the latter are intended to - be used parenthetically, like \cmd{\cite}, whereas the former - are intended to be used in the running text, like \cmd{\citeA}. - Neither of these generate the parentheses, though. Thus, the - only real difference is that the ``non-\verb+NP+'' versions - use ``and'' between authors and the ``\verb+NP+'' versions - use ``\&''. - - Following the \cmd{\cite}--\cmd{\citeNP}--\cmd{\citeA} logic, - \cmd{\citeauthor} should actually be called \cmd{\citeauthorA} - and a \cmd{\citeauthor} command should be supplied that is the - same as the current \cmd{\citeauthorNP} but with parentheses - added. For historical reasons and some compatibility with - other citation packages, this is currently not the case. I may - try to invent a decent solution for a next release of - \pkg{apacite}. - - \item[\cmdfour{citeyear}{prefix}{postfix}{keys}] \mbox{}\\ - Produces citations of the form - ``(\opt{prefix} \opt{Year1}, \opt{Year2}, \ldots, \opt{YearN}, - \opt{postfix})''. - See the discussion of \cmd{\citeauthor} above. Typically, - the \opt{prefix} would be empty and multiple citations - would only be used if they have the same authors. - - \item[\cmdfour{citeyearNP}{prefix}{postfix}{keys}] \mbox{}\\ - A ``no parentheses'' version of \cmd{\citeyear}. - Produces citations of the form - ``\opt{prefix} \opt{Year1}, \opt{Year2}, \ldots, \opt{YearN}, - \opt{postfix}''. Can be used for complex citations within - parenthetical material, like - ``the work of \citeauthor{3.99-15} (\citeyearNP{3.99-15}; - but see also \citeNP{3.99-16,3.99-17})'', - which also uses the \cmd{\citeNP} command. - - \item[\cmdtwo{nocite}{keys}] \mbox{}\\ - The entries are included in the bibliography without - being cited in text. This is standard \LaTeX. - Note that the APA manual normally does not allow this. - The only exception concerns works that are studied in a - meta-analysis, but for these the \cmd{\nocitemeta} - command should be used. - - \item[\cmdtwo{nocitemeta}{keys}] \mbox{}\\ - This is similar to \cmd{\nocite}. It is used to get the - list of works included in a meta-analysis in the - bibliography. This command has the additional effect that - the corresponding items in the bibliography are preceded - by an asterisk (\APACmetastar) and a remark explaining this - is inserted just before the bibliography, as required - by the APA manual. -\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Structure of the citation commands; + parenthetical citations} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\cite} +The traditional \LaTeX{} citation command is \cmd{\cite}, and +\pkg{apacite} reimplements this command. This command is used for +\emph{parenthetical} citations. For example, +``|\cite{Jone01}|'' results in ``(Jones, 2001)''. Here, +|Jone01| is the \emph{key} that identifies the reference; it is +defined in the \fname{.bib} file, see section~\ref{sec:bib}. +An optional postfix---text that follows the actual citation---can +be added as a standard \LaTeX{} optional argument in square brackets: +``|\cite[p.~11]{Jone01}|'' results in ``(Jones, 2001, p.~11)''. +Similarly, an optional prefix can be added between angled brackets: +``|\cite<e.g.,>{Jone01}|'' results in ``(e.g., Jones, 2001)''. +Finally, there can be both a prefix and a postfix (in that order): +``|\cite<e.g.,>[p.~11]{Jone01}|'' results in +``(e.g., Jones, 2001, p.~11)''. As usual, multiple references +can be included within the same citation: +``|\cite<e.g.,>[p.~11]{Jone01, Ross87}|'' results in +(e.g., Jones, 2001; Ross, 1987, p.~11). The citation keys of multiple +citations must be separated by commas, with optional spaces after the +commas. + +By default, \pkg{apacite} follows the APA rules and includes the +citation in round parentheses, separates the author and year by a +comma, the different references by a semicolon, and the year and +the postfix by a comma, but this can all be changed by the user; +see section~\ref{sec:custom}. + +\pkg{apacite} defines a large number of alternative citation +commands, but they all have this same structure: +\cmdfour{command}{prefix}{postfix}{keys}. However, the prefix, and to +a lesser extent the postfix, are most useful with the parenthetical +citation commands. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Text citations; splitting author and year; no +parentheses} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\citeA} +The \cmd{\citeA} command produces text citations: +``|\citeA{Jone01}|'' results in ``Jones (2001)'' and. +``|\citeA[p.~11]{Jone01}|'' results in ``Jones (2001, p.~11)''. +Prefixes are generally not useful for text citations (you can simply +include the prefix in the text), but supported. Multiple citations +are also supported. These are typically only useful for cases in which +the authors are the same and only the year is repeated: +``|\citeA{Jone01, Jone02}|'' results in ``Jones (2001, 2002)''. +Corresponding with the APA rules, an ``and'' before the last author +is formatted as ``and'' in text citations, whereas it is formatted +as ``\&'' in parenthetical citations: +``|\citeA{SmJo03}|'' gives ``Smith and Jones (2003)'', whereas +``|\cite{SmJo03}|'' gives ``(Smith \& Jones, 2003)''. + +\DescribeMacro{\citeauthor} +If a proper citation has been given in a paragraph,\footnote{Note that +a paragraph is not a section. Nor does it need to be declared as a +\cmd{\paragraph}. A reminder for Dutch readers: ``section'' = +``paragraaf'' and ``paragraph'' = ``alinea''.} +the second reference to the source may omit the year if no ambiguity +can arise (APA manual, p.~174). The \cmd{\citeauthor} command can +be used for such purposes: +\begin{verbatim} +\citeA{Jone01} argued that [...]. The empirical results of +\citeauthor{Jone01} supported his argument. +\end{verbatim} +gives ``Jones (2001) argued that [\ldots]. The empirical results of +Jones supported his argument.'' + +\DescribeMacro{\citeyear} +The \cmd{\citeyear} command gives just the year part of a text +citation. This can be used for constructions like +``|\citeauthor{Jone01}' \citeyear{Jone01} method|'', which +gives ``Jones' (2001) method''. Note that \cmd{\citeyear} inserts the +parentheses. + +\DescribeMacro{\citeyearNP} +Some constructions may require even more flexibility. The +\cmd{\citeyearNP} command (NP = no parentheses) omits the +parentheses, which can be useful for a construction like +``|In \citeyearNP{Jone01},| |\citeauthor{Jone01}| |introduced| +|his method|'', which gives ``In 2001, Jones introduced his method''. + +\DescribeMacro{\citeauthorNP} +As mentioned above, text citations use ``and'' between authors, +whereas parenthetical citations use ``\&''. The, \cmd{\citeauthor} +command is a text citation command and thus should not be used +in a parenthetical citation; \cmd{\citeauthorNP} is the corresponding +parenthetical command, which gives just the authors, but now with +``\&'' when applicable. Note that neither \cmd{\citeauthor} nor +\cmd{\citeauthorNP} insert parentheses. In hindsight, it would have +been more logical---following \cmd{\cite} and \cmd{\citeA}---to use +\cmd{\citeauthorA} for what is now \cmd{\citeauthor} and +\cmd{\citeauthor} for what is now \cmd{\citeauthorNP}, but +\cmd{\citeauthor} already existed as a text citation command in +\pkg{apacite}'s predecessor \pkg{theapa}, it is used as such in +some other packages (e.g., \pkg{natbib}), and I didn't realize at +the time that \pkg{apacite} would need both. Therefore, the name +\cmd{\citeauthorNP} is modeled after \cmd{\citeNP} + +\DescribeMacro{\citeNP} +The \cmd{\citeNP} command is \cmd{\cite} without the parentheses. +This is useful for complex constructions like +\begin{verbatim} +\citeauthor{Jone01} (\citeyearNP{Jone01}; see also \citeNP{SmJo03}) +\end{verbatim} +which gives +``Jones (2001; see also Smith \& Jones, 2003)''. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{References without citation} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\nocite} +The standard \LaTeX{} command \cmd{\nocite} is also provided by +\pkg{apacite}; \cmdtwo{nocite}{keys} includes the references +corresponding with the keys in the reference list, but does not +generate a citation in the text. Therefore, it does not allow a pre- +or postfix. However, it does allow multiple citations. Like the +standard \LaTeX{} command, |\nocite{*}| includes all references +from the \fname{.bib} file in the reference list. In general, the APA +requires (p.~174) that each reference list entry should be cited in +the text, and thus this command will rarely be used in APA style +manuscripts. One potential application is a meta-analysis based +on more than 50 works. (See \cmd{\nocitemeta} below.) + +\DescribeMacro{\nocitemeta} +An exception to the one-to-one correspondence requirement between +citations and reference list is when a meta-analysis is reported. +This is a quantitative analysis with results, e.g., regression +coefficients, from published work used as data in the current work. +Studies that are included in the meta-analysis should be included +in the reference list, but do not need to be cited. They should, +however, be marked with an asterisk in the reference list. This +can be obtained by using \cmd{\nocitemeta}, which is otherwise +identical to \cmd{\nocite}: the syntax is \cmdtwo{nocitemeta}{keys} +and |\nocitemeta{*}| includes all entries from the \fname{.bib} file +in the reference list and flags all of them with an asterisk. This +is an unlikely situation, though. Because other packages, in particular +\pkg{natbib} do not define \cmd{\nocitemeta} or an analogous command, +\pkg{apacite} provides \cmd{\nocitemeta} regardless of whether the +\pkgoption{apaciteclassic}, \pkgoption{natbibapa}, or even +\pkgoption{nocitation} option is requested. + +If a meta-analysis includes more than 50 studies, these should not +be included in the main reference list, but in a separate online +supplemental archive (APA manual, p.~183). \pkg{apacite} currently +does not count the number of references included in the meta-analysis, +and thus does not check whether the references should be included in +a separate online supplemental archive, it does not disable the +\cmd{\nocitemeta} command, and it does not automatically generate +the supplemental document. This is the responsibility of the user. +If there is demand for it, I might implement such a counter so that +\pkg{apacite} can give a warning at the end of the \LaTeX{} run that +there are more than 50 references included in the meta-analysis. +Presumably, in the online supplemental archive, the references are +not marked with an asterisk, so this would be an example where +\cmd{\nocite} can be useful. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Full and short author lists} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\fullcite} +\DescribeMacro{\fullciteA} +\DescribeMacro{\fullciteNP} +\DescribeMacro{\fullciteauthor} +\DescribeMacro{\fullciteauthorNP} +When citing a work with one or two authors, all authors are included +in each citation. When citing a work with six or more authors, only +the first author's name is included in the text, followed by +``et al.\hbox{}''. With three to five authors, the full list is +included the first time the work is cited, and only the first with +``et al.\hbox{}'' in subsequent citations. + +\DescribeMacro{\shortcite} +\DescribeMacro{\shortciteA} +\DescribeMacro{\shortciteNP} +\DescribeMacro{\shortciteauthor} +\DescribeMacro{\shortciteauthorNP} +There are some special cases, where some of the authors and the year +are the same, but not the whole author list, in which more names are +retained on subsequent citations as well. Section~\ref{sec:xmpl} +includes some examples of complex situations and how to deal with +them. All of this is automatically handled by \pkg{apacite}. + +However, occasionally one may want to use the full +author list even after a first citation, or the short author list in +the first citation. For such (rare) cases, \pkg{apacite} provides +``full'' and ``short'' versions of all citation commands that include +an author (list) in the text. Other than forcing the full or short +author list in the text, these commands are identical to the versions +without ``|full|'' or ``|short|''. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Masked citations} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\maskcite} +\DescribeMacro{\maskciteA} +\DescribeMacro{\maskciteNP} +\DescribeMacro{\maskciteauthor} +\DescribeMacro{\maskciteauthorNP} +\DescribeMacro{\maskciteyear} +\DescribeMacro{\maskciteyearNP} +Many journals use a ``masked'' or double-blind review process, in +which the identities of the authors are concealed from the reviewers. +As the APA manual states (p.~226), it is the responsibility of the +authors to ensure that the content of the manuscript does not reveal +their identities. This may include suppressing citations to other +work by the authors, in particular unpublished material, such as +the working paper version of the manuscript under review. To this +end, the \pkg{apa6} class introduced ``masked'' citation commands, +which produce the desired citation for the unmasked mode, but +insert a message stating that citations have been masked in masked +mode. Because these are citation commands, they are more properly +included in \pkg{apacite}, and they now are. I am coordinating with +\pkg{apa6}'s author Brian Beitzel on this issue (and other points +of interaction between \pkg{apa6} and \pkg{apacite}). + +\DescribeMacro{\maskfullcite} +\DescribeMacro{\maskfullciteA} +\DescribeMacro{\maskfullciteNP} +\DescribeMacro{\maskfullciteauthor} +\DescribeMacro{\maskfullciteauthorNP} +All the citation commands introduced in this section have a +corresponding masked version, which has the same syntax and the same +name, except that ``|mask|'' is inserted immediately after the +backslash. Thus, the masked version of \cmd{\cite} is \cmd{\maskcite}, +the masked version of \cmd{\fullciteauthorNP} is +\cmd{\maskfullciteauthorNP}, and so forth. + +\DescribeMacro{\maskshortcite} +\DescribeMacro{\maskshortciteA} +\DescribeMacro{\maskshortciteNP} +\DescribeMacro{\maskshortciteauthor} +\DescribeMacro{\maskshortciteauthorNP} +When \pkg{apacite} is loaded with the \pkgoption{mask} option, these +masked citation commands insert the message +``\emph{(1\ citation removed for masked review)}'', or +``\emph{(2\ citations removed for masked review)}'', and so forth, +depending on the number of citations included in the citation +command. When \pkg{apacite} is loaded with the \pkgoption{unmask} +option (the default), the masked citation commands are equivalent +to the same commands without the ``|mask|''. + +\DescribeMacro{\masknocite} +\DescribeMacro{\masktext} +%% \DescribeMacro{\maskcitations} +%% \DescribeMacro{\unmaskcitations} +In addition to the masked citation commands, \pkg{apacite} also +provides \cmd{\masknocite}, although its usefulness seems even more +remote than \cmd{\nocite} itself in APA style documents. Because +\cmd{\nocite} does not insert a citation, \cmd{\masknocite} does +not remove citations in \pkgoption{mask} mode. It only prevents an +entry in the reference list. Therefore, this command does not +insert a message about removed citations in the text either. Hence, +it does nothing in \pkgoption{mask} mode. An additional command +provided by \pkg{apacite} is \cmd{\masktext}. This has one mandatory +argument, the text that is to be masked. It also has an optional +argument, which is the text to be inserted in \pkgoption{mask} mode. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Ad-hoc citation commands} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% In order to format the examples from the APA manual correctly in section~\ref{sec:xmpl}, the \fname{apacdoc.sty} package defines the -following additional citation -commands: \cmd{\DSMcite}, \cmd{\biblecite}, and \cmd{\citesong}, and obvious -variations with \verb+full+, \verb+short+, \verb+A+, and \verb+NP+. I -have decided not to include these in \fname{apacite.sty}, primarily because -I find it unattractive to introduce different types of citation commands for -different types of citations. This also makes it more difficult to use the -same document with another citation package. Perhaps I'll be able to provide, -in a future version of \pkg{apacite}, more elegant solutions to the problems -for which these commands were defined. -See section~\ref{sec:apacdoc} for a description of the \fname{apacdoc.sty} +following additional citation commands: \cmd{\DSMcite}, +\cmd{\biblecite}, and \cmd{\citesong}, and obvious variations with +|full|, |short|, |A|, and |NP|. I have decided not to include these +in \fname{apacite.sty}, primarily because I find it unattractive to +introduce different types of citation commands for different types of +citations. This also makes it more difficult to use the same document +with another citation package. Perhaps I'll be able to provide, +in a future version of \pkg{apacite}, more elegant solutions to the +problems for which these commands were defined. See +section~\ref{sec:apacdoc} for a description of the \fname{apacdoc.sty} package and some brief usage instructions. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Using \pkg{natbib} for citations} +\label{sec:natbibapa} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +With the \pkgoption{natbibapa} option, \pkg{apacite} loads \pkg{natbib} +with the options \pkgoption{longnamesfirst} and \pkgoption{sort}. The +former inserts the full author lists in the first citation and the +short author lists in subsequent citations, in the same way the +\pkgoption{apaciteclassic} commands do. The \pkgoption{sort} option +sorts the citations within the same citation command in the same order +as in the reference list, as required by the APA manual (p.~178). +In addition to loading \pkg{natbib}, \pkg{apacite} includes some +code to improve the interoperability, and it defines some additional +commands that are specific to the \pkg{natbib}-\pkg{apacite} +combination. The latter will be described below. + +Because the citation commands are defined by \pkg{natbib}, this is +not the place for extensive documentation of them. See the \pkg{natbib} +documentation. However, for completeness, I provide very brief +information here. Table~\ref{tab:natbibapa} lists the commands and +a brief description. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{table}[tp] +\centering +\caption{The \pkg{natbib} citation commands.} +\label{tab:natbibapa} +\begin{tabular}{@{}ll@{}} +\hline +Command & Description \\ +\hline +\cmd{\citep} & Parenthetical citation \\ +\cmd{\citet} & Text citation \\ +\cmd{\citeauthor} & Author only (text citation) \\ +\cmd{\citeyear} & Year only (no parentheses) \\ +\cmd{\citeyearpar} & Year citation (with parentheses) \\ +\cmd{\citealp} & Parenthetical citation without the parentheses \\ +\cmd{\citealt} & Text citation without the parentheses \\ +\cmd{\citenum} & Number of the reference \\ +\cmd{\nocite} & No citation, only reference list entry \\ +\cmd{\Citep} etc. & Capitalized citation \\ +\cmd{\citep*} etc. & Full author lists \\ +\cmd{\shortcites} & Short author lists \\ +\cmd{\defcitealias} & Define alias (e.g., \emph{DSM-IV}) \\ +\cmd{\citepalias} & Parenthetical citation of alias \\ +\cmd{\citetalias} & Text citation of alias \\ +\cmd{\citetext} & Arbitrary text within citation parentheses \\ +\hline +\end{tabular} +\end{table} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Compared to the \pkgoption{apaciteclassic} commands, +the \pkg{natbib} commands use square brackets for both the prefix and +the postfix: ``|\command[prefix][postfix]{keys}|''. If only one +optional argument is present, it is interpreted as a postfix. A +citation with only a prefix is obtained by using both optional +arguments, but leaving the postfix empty: +``|\command[prefix][]{keys}|''. The full author list is obtained +by adding a star after the command, for example, |\citet*{key}|. +There is no separate command for the short author list, but it can +be obtained with the construction |\shortcites{key}\citet{key}|. +The first letter of the author list is capitalized with citation +commands that capitalize the first letter of the citation command, +such as \cmd{\Citet}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Filling some gaps and other additions} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\citeauthorp} +\DescribeMacro{\citeauthort} +\DescribeMacro{\Citeauthorp} +\DescribeMacro{\Citeauthort} +As mentioned in section~\ref{sec:classic}, the APA requires that +``and'' between authors is ``and'' in text citations and ``\&'' in +parenthetical citations, and therefore the \pkgoption{apaciteclassic} +option defines two author-citing commands: \cmd{\citeauthor} for +text citations and \cmd{\citeauthorNP} for parenthetical citations. +However, \pkg{natbib} only provides \cmd{\citeauthor}. For +consistency with \cmd{\citep} and \cmd{\citet}, when loaded with the +\pkgoption{natbibapa} option, \pkg{apacite} defines +\cmd{\citeauthorp} for parenthetical use and \cmd{\citeauthort} for +text use, and the corresponding capitalized versions \cmd{\Citeauthorp} +and \cmd{\Citeauthort}. The default command \cmd{\citeauthor} is a +text citation command, so it's equivalent to \cmd{\citeauthort}. + +%% \DescribeMacro{\citefullauthorp} +%% \DescribeMacro{\citefullauthort} +%% \DescribeMacro{\Citefullauthorp} +%% \DescribeMacro{\Citefullauthort} + +\DescribeMacro{\bibstyle@apacite} +\DescribeMacro{\bibstyle@apa} +The \pkg{natbib} package is also highly customizable, and one of +the ways it allows customization is by the \cmd{\bibstyle@xxx} +commands, which typically define the desired punctuation through +\cmd{\bibpunct} and may define other customizations. These are +executed by using the command |\citestyle{xxx}|. Furthermore, when +\pkg{natbib} is loaded, it checks the bibliography style and if it +is \fname{xxx.bst}, then it tries to execute |\citestyle{xxx}| if +defined. With the \pkgoption{natbibapa} option, \pkg{apacite} +defines \cmd{\bibstyle@apacite}, and as a synonym, \cmd{\bibstyle@apa}. +Thus, the APA punctuation defaults can be obtained with +|\citestyle{apacite}| or |\citestyle{apa}|, which are executed +by \pkg{apacite}, so the user only needs to do this if the style +has been changed. + +\DescribeMacro{\maskcitep} +\DescribeMacro{\maskcitet} +\DescribeMacro{\maskciteauthor} +\DescribeMacro{\maskciteyear} +\DescribeMacro{\maskciteyearpar} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Masked citations} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\maskcitealp} +\DescribeMacro{\maskcitealt} +\DescribeMacro{\maskcitenum} +\DescribeMacro{\maskcitetalias} +\DescribeMacro{\maskcitepalias} +Section~\ref{sec:classic} described masked citation commands that +can be used in double-blind review processes in an effort to conceal +the identity of the authors. Because \pkg{natbib} itself does not +define such commands, \pkg{apacite} with the \pkgoption{natbibapa} +option defines a full set of \pkg{natbib}-style masked citation +commands. Again, these are identical to the un-|mask| version if +the \pkgoption{mask} option is not requested, but insert a message +about removed citations when the \pkgoption{mask} option is requested. + +\DescribeMacro{\maskCitep} +\DescribeMacro{\maskCitet} +\DescribeMacro{\maskCiteauthor} +\DescribeMacro{\maskCitealp} +\DescribeMacro{\maskCitealt} +%% The |\mbox{}| is necessary to avoid errors about too many +%% unprocessed floats. This gives some ugly vertical whitespace, but +%% the only alternative would be to write some superfluous paragraphs, +%% which is equally unattractive. +\mbox{} + +\DescribeMacro{\maskciteauthorp} +\DescribeMacro{\maskciteauthort} +\DescribeMacro{\maskCiteauthorp} +\DescribeMacro{\maskCiteauthort} +\DescribeMacro{\masknocite} +\DescribeMacro{\masktext} +\mbox{} + +%% \DescribeMacro{\maskcite} +%% \DescribeMacro{\maskcitefullauthor} +%% \DescribeMacro{\maskCitefullauthor} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Contents of the bibliography database file} \label{sec:bib} @@ -1338,13 +1760,13 @@ by putting the relevant information between double quotes To be able to obey the rules of the APA manual, \pkg{apacite} provides several fields and reference types that are not described in the standard \BibTeX{} documentation -\cite<e.g.,>[chap.~13]{TLC2}. Furthermore, +\cite<e.g.,>[Chapter~13]{TLC2}. Furthermore, the meaning and usage of many fields and reference types that \emph{are} described there have been altered somewhat. Therefore, a complete description is given here. The symbol \LC{} will be used to indicate that the field or reference type is also described in \citeA[Appendix~B]{LaTeXbook}, -\citeA[chap.~12]{KoDa04}, or \citeA[chap.~13]{TLC2}, although, as +\citeA[Chapter~12]{KoDa04}, or \citeA[Chapter~13]{TLC2}, although, as mentioned above, the specific meaning of the item may have been changed. @@ -1403,6 +1825,7 @@ booktitle & & &\X& &\X& & & & & \\ chair & & & & & &\X& & & & \\ chapter & & &\X& & & & & & & \\ day &\X& &\X&\X&\X&\X& &\X&\X& \\ +doi &\X&\X&\X&\X&\X&\X&\X&\X&\X&\X\\ edition & &\X&\X&\X&\X& &\X& &\X& \\ editor &\X&\X&\X&\X&\X& & &\X&\X& \\ englishtitle &\X&\X&\X&\X&\X&\X&\X&\X&\X& \\ @@ -1436,6 +1859,7 @@ title &\X&\X&\X&\X&\X&\X&\X&\X&\X& \\ translator &\X&\X&\X&\Y&\X&\Y&\Y&\Y&\Y&\Y\\ type &\X&\X&\X&\X&\X&\X&\X&\X&\X& \\ url &\X&\X&\X&\X&\X&\X&\X&\X&\X& \\ +urldate &\X&\X&\X&\X&\X&\X&\X&\X&\X& \\ volume &\X&\X&\X&\X&\X& &\X& &\X& \\ year &\X&\X&\X&\X&\X&\X&\X&\X&\X&\Y\\ \hline @@ -1659,10 +2083,7 @@ The following fields can be used to describe a reference in the publisher, school, institution, or organization that published the item or at which the item was produced. The APA manual requires that the state or territory of a U.S.-city must be given - in the official two-letter U.S. Postal Services form. Only for - a specific list of 17 specific cities that are ``well known - for publishing'' can (must) the state and/or country - description be omitted. + in the official two-letter U.S. Postal Services form. \item[\fieldname{annote}\LC] \item[\fieldname{annotate}\LC] \mbox{}\\ @@ -1702,17 +2123,18 @@ The following fields can be used to describe a reference in the Therefore, I have only provided first names with a few examples for which I knew the authors' first names. - If there are more than 6 authors, the APA manual requires - that the first 6 should be named in the reference list, - followed by ``et al.''. Therefore, \pkg{apacite} uses - only the names of the first 6 authors, and inserts an - ``et al.\hbox{}'' when applicable. Therefore, in the \fname{.bib} - file, the first 6 (or more) authors may be given (separated by - ``\verb+and+''), followed by ``\verb+and others+''. This phrase - is recognized by \pkg{apacite}. - It is, however, better to give all authors in - the \fname{.bib} file, so that each style can select its - own truncation number. + Previous versions of the APA manual required that, if there + are more than six authors, only the first six should be named + in the reference list, followed by ``et al.'', which allowed + one to include only the first six plus ``|and others|'' in the + \fname{.bib} file. In the 6th edition, however, the APA changed + this. Now, when there are up to seven authors, they should + all be listed, but with eight or more, the first six should + be listed, plus dots (\ldots), plus the last author. Therefore, + ``|and others|'' should not be used anymore in the \fname{.bib} + file. (It was already discouraged in earlier versions of the + \pkg{apacite} documentation.) Thus, one should list all authors + in the \fname{.bib} file. \item[\fieldname{booktitle}\LC] \mbox{}\\ The title of the larger work, typically book, but sometimes @@ -1765,6 +2187,10 @@ The following fields can be used to describe a reference in the weekly magazines or newspapers, for lectures (although the APA manual only specifies the month), and electronic documents. + \item[\fieldname{doi}] \mbox{}\\ + Digital object identifier (DOI). The 6th edition of the APA manual + asks authors to supply this whenever available. + \item[\fieldname{edition}\LC] \mbox{}\\ The edition of the book or report. Traditionally, this is of the form ``1st'', ``2nd'', ``3rd'', etc., or ``Rev.'' for a revised edition. @@ -2202,6 +2628,11 @@ Amsterdam: North-Holland. and `|#|' should be entered without a backslash, unlike the normal situation if they would be used in the text. + \item[\fieldname{urldate}] \mbox{}\\ + See \fieldname{lastchecked}. This one is apparently defined in the + \pkg{jurabib} package. It is unfortunate that different packages define + different fields for the same function. + \item[\fieldname{volume}\LC] \mbox{}\\ The volume or volumes of the referenced book(s) or of the book in which the referenced article was published, @@ -2261,6 +2692,7 @@ the APA, numbers should be sorted as if they were spelled in words: ``2003'' must be sorted as if it says ``\mbox{twothousandandthree}''; see example~4.04 in section~\ref{sec:xmpl} below. +\DescribeMacro{\APACSortNoop} Overriding the default sorting order can be done by using the \cmd{\APACSortNoop} command in the \fname{.bib} file. This is a \LaTeX{} command provided by \pkg{apacite}. It has one mandatory argument, but it @@ -2312,219 +2744,250 @@ definitions before starting the bibliography. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following punctuation commands are provided and used for the citations and reference list. -\begin{description} - \item[\cmd{\BAstyle}] This defines the text style of the authors - (or whatever takes their place) for an in-text citation. It - defaults to nothing: The authors use the same fonts as the - text surrounding it. Introduced because some journals use - a different style. For example, \emph{Statistica Neerlandica} - uses small-caps, so for that journal, you would define + +\DescribeMacro{\BAstyle} +\DescribeMacro{\BAastyle} +\cmd{\BAstyle} defines the text style of the authors (or whatever +takes their place) for an in-text citation. It defaults to nothing: +The authors use the same fonts as the text surrounding it. Introduced +because some journals use a different style. For example, +\emph{Statistica Neerlandica} uses small caps, so for that journal, +you would define \begin{verbatim} \renewcommand{\BAstyle}{\scshape} \end{verbatim} - Do not use the \cmd{\textsc}-type commands, but \cmd{\scshape}, - \cmd{\bfseries}, etc. The \cmd{\BAstyle} command is used for - the author-part by the citation commands - \cmd{\cite}, \cmd{\shortcite}, \cmd{\fullcite}, - \cmd{\citeA}, \cmd{\shortciteA}, \cmd{\fullciteA}, - \cmd{\citeNP}, \cmd{\shortciteNP}, and \cmd{\fullciteNP}. - - \item[\cmd{\BAastyle}] This is the same as \cmd{\BAstyle}, except that - \cmd{\BAastyle} is used for \cmd{\citeauthor}, \cmd{\shortciteauthor}, - and \cmd{\fullciteauthor}. - - \item[\cmd{\BBOP}] Open parenthesis, used for parentheses opening - a citation, as in ``(Rao, 1973)'' or ``Rao (1973)'', and the - year in the reference list, as in ``Rao, C. R. (1973).'' - Default is ``\verb+(+''. - - \item[\cmd{\BBCP}] The corresponding closing parenthesis. - Default is ``\verb+)+''. - - \item[\cmd{\BAP}] This command is inserted after the prefix and before - the first citation in a \cmd{\cite} command. It defaults to an - ordinary space. - - \item[\cmd{\BBAA}] Last ``and'' between authors in a citation - between parentheses and in the reference list, as in - ``(Mooijaart \& Bentler, 1986)'' or ``Mooijaart, A., \& - Bentler, P. M. (1986).''. Default is ``\verb+\&+''. - - \item[\cmd{\BBAB}] Last ``and'' between authors in a citation in text, - as in ``Mooijaart and Bentler (1986)''. Default is ``\verb+and+''. - - \item[\cmd{\BBAY}] Punctuation between author(s) and year in a citation - between parentheses, as in ``(Rao, 1973)''. Default is ``\verb+, +''. - - \item[\cmd{\BBYY}] \label{cmd:BBYY} - Punctuation between two subsequent years, if two works - by the same author(s) are referenced in a single citation command, - as in ``(Rao, 1965, 1973)'' or ``Rao (1965, 1973)''. - Default is ``\verb+, +''. - - \item[\cmd{\BBC}] Punctuation between multiple cites, as in - ``(Rao, 1973; Mooijaart \& Bentler, 1986)''. - Default is ``\verb+; +''. - - \item[\cmd{\BBN}] Punctuation before a note (postfix) after - a citation, as in ``(Rao, 1973, chap.~2)''. - Default is ``\verb+, +''. - - \item[\cmd{\BBOQ}] Opening quote for an article title in the - reference list, as in - ``\flqq Random polynomial factor analysis.\frqq'' Default is - the empty string: no quotes used. - - \item[\cmd{\BBCQ}] Closing quote for an article title in the - reference list. Default is the empty string. - (The \pkg{theapa} package required the closing period to be part - of the closing quote, but this has been - changed, because the period must be left out if title comments, - such as type, English translation of non-English title, or - translator follow the title.) - - \item[\cmd{\BPBI}] Period between initials. Default is ``\verb+.~+'', - i.e., a period and a non-breaking space, as required by the APA - manual. However, many users prefer removing or reducing the space - and in some non-English speaking countries this is customary. This - can be achieved by redefining this command to, e.g., ``\verb+.+'' - (no space) or ``\verb+.\,+'' (small space). This command cannot - be used to remove periods altogether, because there is still a - period at the end. I.e., redefining it as an empty string gives - awkward results like ``Bentler, PM., \& Mooijaart, A.''. - - \item[\cmd{\BHBI}] Hyphen between initials. Introduced for analogy with - \cmd{\BPBI} and used for authors who have two or more first names - with a hyphen between them, e.g., Jean-Paul Sartre. Default is - ``\verb+.-+'', i.e., a period and a hyphen. Unlike \cmd{\BPBI}, - I think this one will not be changed often, although \BibTeX{} - suppresses hyphens when it suppresses spaces between initials - as well, so there are people who have different preferences. - (Hence, \pkg{apacite} partly bypasses the standard \BibTeX{} - formatting functions to make this work.) - - \item[\cmd{\BCBT}] Comma between authors in the reference section when - the number of authors is two, as in - ``Mooijaart, A., \& Bentler, P.~M. (1986).'' The comma - after the ``A.'' is this one. Default is ``\verb+,+''. - The APA manual requires it, but other styles leave out this - comma. In such a case, you would redefine this ``comma'' to - be the empty string: +Do not use the \cmd{\textsc}-type commands, but \cmd{\scshape}, +\cmd{\bfseries}, and so forth. The \cmd{\BAstyle} command is used for +the author part by the \pkgoption{apaciteclassic} citation commands, +except the author-only citation commands. \cmd{\BAastyle} is the same +as \cmd{\BAstyle}, except that \cmd{\BAastyle} is used for the +author-only citation commands. + +\DescribeMacro{\APACrefauthstyle} +\cmd{\APACrefauthstyle} is similar to \cmd{\BAstyle}, except +that this one is used for formatting authors in the reference list. +In the current implementation, it also applies to editors in the +author position, but not to editors in the editor position and +not to titles and other elements that take the position of authors +if there are no authors and editors. + +\DescribeMacro{\BBAA} +\DescribeMacro{\BBAB} +\DescribeMacro{\BAnd} +\cmd{\BBAA} is the ``and'' between authors in a parenthetical +citation and in the reference list, as in +``(Mooijaart \& Bentler, 1986)'' or ``Mooijaart, A., \& +Bentler, P.~M. (1986).''. Its default is ``\&''. +\cmd{\BBAB} is the same ``and'' in a text citation, as in +``Mooijaart and Bentler (1986)''. Its default is ``and''. +The third ``and'', \cmd{\BAnd}, is used in the reference list +if someone is both editor and translator: +``In J. Strachey (Ed. \& Trans.),''. Default is ``\&''. + +\DescribeMacro{\BBOP} +\DescribeMacro{\BBCP} +\cmd{\BBOP} (opening parenthesis) and \cmd{\BBCP} (closing parenthesis) +are used for the parentheses in a citation, as in ``(Rao, 1973)'' or +``Rao (1973)'', and the year in the reference list, as in +``Rao, C.~R. (1973).'' By default, they are round parentheses +``('' and ``)''. + +\DescribeMacro{\BAP} +\cmd{\BAP} is inserted after the prefix and before the first citation +in a parenthetical citation. It defaults to an ordinary space. Note +that if the prefix ends with a period, \TeX{} interprets this as a +sentence ending and typically inserts a larger space, which is often +not desirable. The standard way to avoid this would be to insert an +explicit space (``|\ |''), but this does not work in a prefix. The +solution is to insert an empty |\hbox{}| after the period: +|\cite<cf.\hbox{}>{Jone01}|. + +\DescribeMacro{\BBAY} +\DescribeMacro{\BBYY} +\DescribeMacro{\BBN} +\cmd{\BBAY} is the punctuation between author(s) and year in a +parenthetical citation, as in ``(Rao, 1973)''. \cmd{\BBYY} is the +punctuation between two subsequent years, if two works by the same +author(s) are referenced in a single citation command, as in +``(Rao, 1965, 1973)'' or ``Rao (1965, 1973)''. \cmd{\BBN} is the +punctuation before a note (postfix) after a citation, as in +``(Rao, 1973, p.~25)''. Default for all three is a comma and a +space (``, ''). + +\DescribeMacro{\BBC} +\cmd{\BBC} is the punctuation between multiple cites, as in +``(Rao, 1973; Mooijaart \& Bentler, 1986)''. Default is a semicolon +and a space (``; ''). + +\DescribeMacro{\BBOQ} +\DescribeMacro{\BBCQ} +\cmd{\BBOQ} (opening quote) and \cmd{\BBCQ} (closing quote) are the +quotes around an article title in the reference list, for example the +double quotes in ``Random polynomial factor analysis.'' Default is +the empty string: no quotes are used. (The \pkg{theapa} package +required the closing period to be part of the closing quote, but this +has been changed, because the period must be left out if title +comments, such as type, English translation of non-English title, or +translator follow the title.) + +\DescribeMacro{\BPBI} +\cmd{\BPBI} is the period between initials. Default is a period and a +non-breaking space (``.~''), as required by the APA manual. However, +many users prefer removing or reducing the space and in some +non-English speaking countries this is customary. This can be achieved +by redefining this command to, for example, just a period (no space), +or ``|.\,|'' (small space). This command cannot be used to remove +periods altogether, because there is still a period at the end. That +is, redefining it as an empty string gives awkward results like +``Bentler, PM., \& Mooijaart, A.''. + +\DescribeMacro{\BHBI} +\cmd{\BHBI} is the hyphen between initials. Introduced for analogy with +\cmd{\BPBI} and used for authors who have two or more first names +with a hyphen between them, e.g., Jean-Paul Sartre. Default is +a period and a hyphen. Unlike \cmd{\BPBI}, I think this one will not be +changed often, although \BibTeX{} suppresses hyphens when it suppresses +spaces between initials as well, so there are people who have different +preferences. (Hence, \pkg{apacite} partly bypasses the standard +\BibTeX{} formatting functions to make this work.) + +\DescribeMacro{\BCBT} +\DescribeMacro{\BCBL} +\cmd{\BCBT} is the comma between authors in the reference section when +there are two authors, as in +``Mooijaart, A., \& Bentler, P.~M. (1986).'' The comma after the ``A.'' +is this one. Default is a comma. The APA manual requires it, but other +styles leave out this comma. In such a case, you would redefine this +``comma'' to be the empty string: \begin{verbatim} \renewcommand{\BCBT}{} \end{verbatim} - - \item[\cmd{\BCBL}] Comma before the last author (for 3 or more authors) - in a citation and in the reference section, as in ``(Gill, Murray, - \& Wright, 1981)'' or ``Gill, P.~E., Murray, W., \& Wright, M.~H. - (1981).'' Default is ``\verb+,+''. The APA manual requires it, - which is standard U.S. usage, but other styles, particularly - European, such as British English, leave out this comma. Again, - in such a case, you would redefine this ``comma'' to - be the empty string. - - \item[\cmd{\BAnd}] This is the ``and'' that is used in the reference list - if someone is both editor and translator: - ``In J. Strachey (Ed. \& Trans),''. Default is ``\verb+\&+''. - - \item[\cmd{\theBibCnt}] If there are multiple citations with the same - author and year, a letter should be added to the year to distinguish - the references. For example, one may refer to two or more articles - by J. Smith published in 1982. They should be referred to as - ``Smith (1982a)'', ``Smith (1982b)'', and so forth. To accomplish - this, the counter \verb+BibCnt+ is defined in \fname{apacite.sty}. - The \cmd{\theBibCnt} command defines how the value of \verb+BibCnt+ - is formatted. The default is ``\verb+\alph{BibCnt}+''. To - emphasize (italicize) the ``a'', ``b'', etc., you can redefine - this as +Analogously, \cmd{\BCBL} is the comma before the last author when there +are three or more authors in a citation and in the reference section, +as in ``(Gill, Murray, \& Wright, 1981)'' or +``Gill, P.~E., Murray, W., \& Wright, M.~H. (1981).'' Its default is +also a comma, as required by the APA manual, which is standard U.S. +usage. Other styles, particularly European, such as British English, +omit this comma. Again, in such a case, you would redefine this +``comma'' to be the empty string. (This is in fact done in several of +the language files. See section~\ref{sec:language}.) + +\DescribeMacro{\BDBL} +\cmd{\BDBL} is the dots before the last author in the reference +section when the reference has more than seven authors. The default +is ``|, \dots{} |''. The APA manual seems to imply that there +shouldn't be space around the dots, but I think it's better to have +the space and I assume editors won't mind. However, if they insist on +removing the space, you can redefine \cmd{\BDBL} accordingly. + +\DescribeMacro{\theBibCnt} +\DescribeMacro{\BCnt} +\DescribeMacro{\BCntIP} +\DescribeMacro{\BCntND} +If there are multiple citations with the same author and year, a +letter should be added to the year to distinguish the references. +For example, one may refer to two or more articles by J.~Smith +published in 1982. They should be referred to as ``Smith (1982a)'', +``Smith (1982b)'', and so forth. To accomplish this, the counter +|BibCnt| is defined in \fname{apacite.sty}. The \cmd{\theBibCnt} +command defines how the value of |BibCnt| is formatted. The default +is ``|\alph{BibCnt}|'', that is, as a plain lowercase letter. To +emphasize (italicize) the ``a'', ``b'', and so forth, you can redefine +this as \begin{verbatim} \renewcommand{\theBibCnt}{{\em\alph{BibCnt}\/}} \end{verbatim} - (This presumably works better than ``\verb+\emph{\alph{BibCnt}}+''.) - To control this behavior, redefining the \cmd{\theBibCnt} command - should normally be sufficient. However, the complete formatting - commands are \cmd{\BCnt}, \cmd{\BCntIP}, and \cmd{\BCntND}. The - second of these is for ``in press'' works, which need an extra hyphen - between ``in press'' and the ``a'' and ``b'' suffixes. The third is - similar, for works without a date. Their default definitions - in \fname{apacite.sty} are +(This presumably works better than ``\verb+\emph{\alph{BibCnt}}+''.) +To control this behavior, redefining the \cmd{\theBibCnt} command +should normally be sufficient. However, the complete formatting +commands are \cmd{\BCnt}, \cmd{\BCntIP}, and \cmd{\BCntND}. The +second of these is for ``in press'' works, which need an extra hyphen +between ``in press'' and the ``a'' and ``b'' suffixes. The third is +similar, for works without a date, which is formatted as +``n.d.\hbox{}'' in APA style. Their default definitions +in \fname{apacite.sty} are \begin{verbatim} \DeclareRobustCommand{\BCnt}[1]{\setcounter{BibCnt}{#1}\theBibCnt} \DeclareRobustCommand{\BCntIP}[1]{\setcounter{BibCnt}{#1}\mbox{-\theBibCnt}} \DeclareRobustCommand{\BCntND}[1]{\setcounter{BibCnt}{#1}\mbox{-\theBibCnt}} \end{verbatim} - \item[\cmd{\APACciteatitle}] The formatting of the title of an - article (or similar work) - when used as a citation in the text when no author or editor - is available for that purpose. Its default definition - in \fname{apacite.sty} is +\DescribeMacro{\APACciteatitle} +\DescribeMacro{\APACcitebtitle} +\cmd{\APACciteatitle} determines the formatting of the title of an +article (or similar work) when used as a citation in the text when no +author or editor is available for that purpose. Its default definition +is \begin{verbatim} \newcommand{\APACciteatitle}[1]{``#1''} \end{verbatim} - i.e., the title is put between double quotes. - - \item[\cmd{\APACcitebtitle}] The formatting of the title of a book - (or other independent work) - when used as a citation in the text when no author or editor - is available for that purpose. Its default definition - in \fname{apacite.sty} is +that is, the title is put between double quotes. Similarly, +\cmd{\APACcitebtitle} determines the formatting of the title of a book +(or other independent work) when used as a citation in the text when no +author or editor is available for that purpose. Its default definition +is \begin{verbatim} \newcommand{\APACcitebtitle}[1]{{\em #1\/}} \end{verbatim} - i.e., the title is emphasized (in italics) but not put between - double quotes. - - \item[\cmd{\APACmetastar}] The asterisk that precedes an item in the - bibliography to denote that it is included in the meta-analysis. - The default value is ``\verb+\ensuremath{{}^\ast}+'', which - prints as ``\APACmetastar''. - - \item[\cmd{\bibnewpage}] If the \pkgoption{bibnewpage} option - is chosen, this command is included before the bibliography. - Its default definition is \cmd{\clearpage}, but \fname{apa.cls} - uses a similar construction with its \pkgoption{man} option - through \cmd{\newpage}. - See \citeA[p.~215]{LaTeXbook} or \citeA[p.~37]{KoDa04} for the - differences between \cmd{\clearpage} and \cmd{\newpage}. - - \item[\cmd{\bibliographytypesize}] This command is used before - the reference list, but after the section or chapter heading. - It is intended for the font size of the reference list: - For \citeA{WaMe00}, I defined it as \cmd{\small} (and even then - the reference list took up 34 pages). The default value is - \cmd{\normalsize}. - - \item[\cmd{\bibleftmargin}] This gives the indentation of the second - and subsequent lines of a reference list entry, relative to the - usual left margin. It is not a proper command, but a - ``skip'' (rubber length), which means that it cannot be changed by - \cmd{\renewcommand}, but by \cmd{\setlength}. Its default - value is \verb+2.5em+. - - \item[\cmd{\bibindent}] This gives the indentation of the first - line of a reference list entry, relative to the second line. - It is also a ``skip''. Its default value is \verb+-\bibleftmargin+, - which means that the first line starts at the original left margin, - and the second and subsequent lines are indented by 2.5em. - - \item[\cmd{\bibitemsep}] This gives the vertical separation - between two reference list entries. It is also a ``skip'', with - default value ``\verb+\z@ \@plus .3\p@\relax+'', i.e., 0pt, - but it may be stretched a little to fill the page nicely. - This is an old (Plain \TeX) style definition, I will probably - change that in a next version. If you want to change it, - e.g., to get a blank line between reference list entries, - you can use +that is, the title is emphasized (in italics) but not put between +double quotes. + +\DescribeMacro{\APACmetastar} +\cmd{\APACmetastar} is the asterisk that precedes an item in the +bibliography to denote that it is included in the meta-analysis. +The default value is ``\verb+\ensuremath{{}^\ast}+'', which +prints as ``\APACmetastar''. + +\DescribeMacro{\bibnewpage} +If the \pkgoption{bibnewpage} option is chosen, \cmd{\bibnewpage} is +included before the bibliography. Its default definition is +\cmd{\clearpage}, but \fname{apa.cls} used \cmd{\newpage} in a +similar construction with its \pkgoption{man} option. See +\citeA[p.~215]{LaTeXbook} or \citeA[p.~37]{KoDa04} for the differences +between \cmd{\clearpage} and \cmd{\newpage}. + +\DescribeMacro{\bibliographytypesize} +\cmd{\bibliographytypesize} is used before the reference list, but +after the section or chapter heading. It is intended for the font size +of the reference list: For \citeA{WaMe00}, I defined it as \cmd{\small} +(and even then the reference list took up 34 pages). The default value +is \cmd{\normalsize}. + +\DescribeMacro{\bibleftmargin} +\DescribeMacro{\bibindent} +\DescribeMacro{\bibitemsep} +\DescribeMacro{\bibparsep} +\DescribeMacro{\biblabelsep} +Several parameters determine the layout of the reference list. +\cmd{\bibleftmargin} gives the indentation of the second and subsequent +lines of a reference list entry, relative to the usual left margin. It +is not a proper command, but a rubber length, which means that it is +not changed by \cmd{\renewcommand} but by \cmd{\setlength}. Its default +value is 2.5em. \cmd{\bibindent} gives the indentation of the +first line of a reference list entry, relative to the second line. It +is also a rubber length, with default value is |-\bibleftmargin|, which +means that the first line starts at the original left margin, and the +second and subsequent lines are indented by 2.5em. \cmd{\biblabelsep} +gives the horizontal separation between the reference list label and +the rest of the entry. Normally, there are no reference list labels +when using \pkg{apacite}, but this command allows one to define them +through redefining \cmd{\@biblabel} and \cmd{\@lbibitem} without having +to redefine the whole \envirname{bibliography} environment. I once used +this to generate a numbered reference list for my CV. It is a rubber +length in principle, but the default is a fixed length of 0pt. +\cmd{\bibitemsep} gives the vertical separation between two reference +list entries. It is also a rubber length, with default value +``|0pt plus .3pt|'', i.e., 0pt, but it may be stretched a little to +fill the page nicely. If you want to change it, e.g., to get a blank +line between reference list entries, you can use \begin{verbatim} \setlength{\bibitemsep}{\baselineskip} \end{verbatim} - \item[\cmd{\bibparsep}] This gives the vertical separation - between two paragraphs in the same reference list entry. Such a - situation does not occur in the default setup, so it is not - used, but it is conceivable that certain customizations lead - to its use. It is a ``skip'' with default value 0pt. -\end{description} +Finally, \cmd{\bibparsep} gives the vertical separation between two +paragraphs within the same reference list entry. Such a situation does +not occur in the default setup, so it is not used, but it is +conceivable that certain customizations lead to its use. It is a +rubber length with default value 0pt. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Labels} @@ -2541,7 +3004,19 @@ discuss how these commands are changed if another language is used. The following label commands are used: \begin{description} - \item[\cmd{\bibmessage}] This is the first of 9 specific type + + \item[\cmd{\onemaskedcitationmsg}] \DescribeMacro{\onemaskedcitationmsg} + \item[\cmd{\maskedcitationsmsg}] \DescribeMacro{\maskedcitationsmsg} + These commands have one mandatory argument (which should always + be 1 for \cmd{\onemaskedcitationmsg}) and define a message + stating that citations are removed for a masked review. The + default messages are + ``\emph{(1\ citation removed for masked review)}'' and + ``\emph{(}|#1|\emph{\ citations removed for masked review)}'', + respectively. + + \item[\cmd{\bibmessage}] \DescribeMacro{\bibmessage} + This is the first of 9 specific type commands that are recognized by \pkg{apacite}. If you define the \fieldname{type} field of a \entryname{misc} entry as ``\cmd{\bibmessage}'', the formatting of the @@ -2551,28 +3026,28 @@ The following label commands are used: messages in newsgroups, internet forums, etc. Default is ``\verb+Msg+''. - \item[\cmd{\bibcomputerprogram}] + \item[\cmd{\bibcomputerprogram}] \DescribeMacro{\bibcomputerprogram} Default is ``\verb+Computer program+''. - \item[\cmd{\bibcomputerprogrammanual}] + \item[\cmd{\bibcomputerprogrammanual}] \DescribeMacro{\bibcomputerprogrammanual} Default is ``\verb+Computer program manual+''. - \item[\cmd{\bibcomputerprogramandmanual}] + \item[\cmd{\bibcomputerprogramandmanual}] \DescribeMacro{\bibcomputerprogramandmanual} Default is ``\verb+Computer program and manual+''. - \item[\cmd{\bibcomputersoftware}] + \item[\cmd{\bibcomputersoftware}] \DescribeMacro{\bibcomputersoftware} Default is ``\verb+Computer software+''. - \item[\cmd{\bibcomputersoftwaremanual}] + \item[\cmd{\bibcomputersoftwaremanual}] \DescribeMacro{\bibcomputersoftwaremanual} Default is ``\verb+Computer software manual+''. - \item[\cmd{\bibcomputersoftwareandmanual}] + \item[\cmd{\bibcomputersoftwareandmanual}] \DescribeMacro{\bibcomputersoftwareandmanual} Default is ``\verb+Computer software and manual+''. - \item[\cmd{\bibprogramminglanguage}] + \item[\cmd{\bibprogramminglanguage}] \DescribeMacro{\bibprogramminglanguage} Default is ``\verb+Programming language+''. - \item[\cmd{\bibnotype}] + \item[\cmd{\bibnotype}] \DescribeMacro{\bibnotype} This one is a bit different from the previous 8. It is used for \entryname{techreport} entries to indicate that the type specifier should be suppressed. Its default value is the empty string, but this @@ -2581,7 +3056,8 @@ The following label commands are used: as the empty string, formatting may become better (i.e., closer to the desired formatting) with other styles. - \item[\cmd{\bibnodate}] Used in the \fieldname{year} and + \item[\cmd{\bibnodate}] \DescribeMacro{\bibnodate} + Used in the \fieldname{year} and \fieldname{originalyear} fields to indicate that no publication date has been given. Default value is ``\verb+n.d.\hbox{}+''. The ``\verb+\hbox{}+'' ensures that \TeX{} does not treat @@ -2589,7 +3065,8 @@ The following label commands are used: more space is inserted. This also applies to several other labels discussed below. - \item[\cmd{\BOthers}] Used for ``others'' if the number of authors + \item[\cmd{\BOthers}] \DescribeMacro{\BOthers} + Used for ``others'' if the number of authors or editors is too large, as in ``(Gill et al., 1981)''. The default is ``\verb+et al.\hbox{}+''. @@ -2628,13 +3105,15 @@ The following label commands are used: \cmd{\finishsentence}, and insert it in an appropriate place. Then, this command should be changed along with \cmd{\BOthers}. - \item[\cmd{\BOthersPeriod}] Also used for ``others'' if the number of + \item[\cmd{\BOthersPeriod}] \DescribeMacro{\BOthersPeriod} + Also used for ``others'' if the number of authors or editors is too large, as in ``Gill, P. E., et al.\hbox{} (1981)''. But this one is used for situations when it should always end with a period. The default is ``\verb+et al.\hbox{}+''. - \item[\cmd{\bibcorporate}] This command can be used in the \fieldname{author} + \item[\cmd{\bibcorporate}] \DescribeMacro{\bibcorporate} + This command can be used in the \fieldname{author} field (and \fieldname{editor} and \fieldname{translator}) to tell \pkg{apacite} that the author is a corporate author. See section~\ref{subsec:fields} for an example of its usage. In combination @@ -2648,120 +3127,167 @@ The following label commands are used: i.e., it does nothing in \LaTeX{} and exerts its influence at the \BibTeX{} stage. - \item[\cmd{\BIP}] ``In press'', the string to be used as year for + \item[\cmd{\BIP}] \DescribeMacro{\BIP} + ``In press'', the string to be used as year for in-press references. In the \fname{.bib} file, the \fieldname{year} field should be ``\verb+\BIP+'', so that \pkg{apacite} can recognize this and use appropriate formatting and sorting. The default value is ``\verb+in press+''. - \item[\cmd{\BIn}] Used for \entryname{incollection} and + \item[\cmd{\BIn}] \DescribeMacro{\BIn} + Used for \entryname{incollection} and \entryname{intechreport}, for ``In \opt{editor} (Ed.\hbox{}), \opt{booktitle}'', and similar phrases. Default value is ``\verb+In+''. - \item[\cmd{\BCHAP}] Used for \entryname{incollection} if the + \item[\cmd{\BCHAP}] \DescribeMacro{\BCHAP} + Used for \entryname{incollection} if the \fieldname{pages} field is empty, to denote the chapter number of the referenced work in the collection. Used primarily for internet documents, where there are no page numbers. - Default value is ``\verb+chap.\hbox{}+''. - - \item[\cmd{\BCHAPS}] Just like \cmd{\BCHAP}, but this one is used + Default value is ``chap.\hbox{}''. Note that in the text, in + particular in a citation, the APA (p.~179) prescribes ``Chapter'': + ``(Shimamura, 1989, Chapter~3)''. This is, however, something that + would be typed by the author of the manuscript, not inserted by + \pkg{apacite}, and thus \pkg{apacite} does not have a command + for this. + + \item[\cmd{\BCHAPS}] \DescribeMacro{\BCHAPS} + Just like \cmd{\BCHAP}, but this one is used if the \fieldname{chapter} field refers to more than 1 chapter. - Default value is ``\verb+chap.\hbox{}+''. + Default value is ``chap.\hbox{}''. - \item[\cmd{\BED}] Editor in reference list, as in + \item[\cmd{\BED}] \DescribeMacro{\BED} + Editor in reference list, as in ``In P. R. Krishnaiah (Ed.\hbox{})''. Default is ``\verb+Ed.\hbox{}+''. - \item[\cmd{\BEDS}] Editors (more than one editor) in reference list, + \item[\cmd{\BEDS}] \DescribeMacro{\BEDS} + Editors (more than one editor) in reference list, as in ``In C.~R. Rao \& J.~K. Ghosh (Eds.\hbox{})''. Default is ``\verb+Eds.\hbox{}+''. - \item[\cmd{\BTRANS}] Translator, as in ``(J. Strachey, Trans.\hbox{})''. + \item[\cmd{\BTRANS}] \DescribeMacro{\BTRANS} + Translator, as in ``(J. Strachey, Trans.\hbox{})''. Default is ``\verb+Trans.\hbox{}+''. - \item[\cmd{\BTRANSS}] Translators. Default is ``\verb+Trans.\hbox{}+''. + \item[\cmd{\BTRANSS}] \DescribeMacro{\BTRANSS} + Translators. Default is ``\verb+Trans.\hbox{}+''. - \item[\cmd{\BTRANSL}] Translation. Used in a text citation when + \item[\cmd{\BTRANSL}] \DescribeMacro{\BTRANSL} + Translation. Used in a text citation when referring to a translated work for which there is no date for the original work. This is then formatted as ``Aristotle (trans.\hbox{} 1931)''. Default is ``\verb+trans.\hbox{}+''. - \item[\cmd{\BCHAIR}] Chair of a symposium, etc. + \item[\cmd{\BCHAIR}] \DescribeMacro{\BCHAIR} + Chair of a symposium, etc. Default is ``\verb+Chair+''. - \item[\cmd{\BCHAIRS}] Chairs. Default is ``\verb+Chairs+''. + \item[\cmd{\BCHAIRS}] \DescribeMacro{\BCHAIRS} + Chairs. Default is ``\verb+Chairs+''. - \item[\cmd{\BVOL}] Volume, as in ``Vol.\hbox{}~1''. + \item[\cmd{\BVOL}] \DescribeMacro{\BVOL} + Volume, as in ``Vol.\hbox{}~1''. Default is ``\verb+Vol.\hbox{}+''. - \item[\cmd{\BVOLS}] Volumes, as in ``Vols.\hbox{} 1--4''. + \item[\cmd{\BVOLS}] \DescribeMacro{\BVOLS} + Volumes, as in ``Vols.\hbox{} 1--4''. Default is ``\verb+Vols.\hbox{}+''. - \item[\cmd{\BNUM}] Number, as in ``Tech.\ Rep.\hbox{} + \item[\cmd{\BNUM}] \DescribeMacro{\BNUM} + Number, as in ``Tech.\ Rep.\hbox{} No.\hbox{}~12''. Default is ``\verb+No.\hbox{}+''. - \item[\cmd{\BNUMS}] Numbers, as in ``Nos.\hbox{} 3--5''. + \item[\cmd{\BNUMS}] \DescribeMacro{\BNUMS} + Numbers, as in ``Nos.\hbox{} 3--5''. Default is ``\verb+Nos.\hbox{}+''. - \item[\cmd{\BEd}] Edition, as in ``2nd ed.\hbox{}''. + \item[\cmd{\BEd}] \DescribeMacro{\BEd} + Edition, as in ``2nd ed.\hbox{}''. Default is ``\verb+ed.\hbox{}+''. - \item[\cmd{\BPG}] Page, default is ``\verb+p.\hbox{}+''. + \item[\cmd{\BPG}] \DescribeMacro{\BPG} + Page, default is ``\verb+p.\hbox{}+''. - \item[\cmd{\BPGS}] Pages, default is ``\verb+pp.\hbox{}+''. + \item[\cmd{\BPGS}] \DescribeMacro{\BPGS} + Pages, default is ``\verb+pp.\hbox{}+''. - \item[\cmd{\BTR}] The (default) technical report type name, which can be + \item[\cmd{\BTR}] \DescribeMacro{\BTR} + The (default) technical report type name, which can be overridden by the \fieldname{type} field. Default is ``\verb+Tech.\ Rep.\hbox{}+'' - \item[\cmd{\BPhD}] The (default) PhD thesis type name, which can be + \item[\cmd{\BPhD}] \DescribeMacro{\BPhD} + The (default) PhD thesis type name, which can be overridden by the \fieldname{type} field. Default is ``\texttt{Doctoral dissertation}''. - \item[\cmd{\BUPhD}] The (default) Unpublished PhD thesis type name, + \item[\cmd{\BUPhD}] \DescribeMacro{\BUPhD} + The (default) Unpublished PhD thesis type name, which can be overridden by the \fieldname{type} field. Default is ``\texttt{Unpublished doctoral dissertation}''. - \item[\cmd{\BMTh}] The (default) master's thesis type name, which can be + \item[\cmd{\BMTh}] \DescribeMacro{\BMTh} + The (default) master's thesis type name, which can be overridden by the \fieldname{type} field. Default is ``\texttt{Master's thesis}''. - \item[\cmd{\BUMTh}] The (default) unpublished master's thesis type name, + \item[\cmd{\BUMTh}] \DescribeMacro{\BUMTh} + The (default) unpublished master's thesis type name, which can be overridden by the \fieldname{type} field. Default is ``\texttt{Unpublished master's thesis}''. - \item[\cmd{\BOWP}] ``Original work published'', default is + \item[\cmd{\BOWP}] \DescribeMacro{\BOWP} + ``Original work published'', default is ``\texttt{Original work published}''. - \item[\cmd{\BREPR}] ``Reprinted from'', default is + \item[\cmd{\BREPR}] \DescribeMacro{\BREPR} + ``Reprinted from'', default is ``\texttt{Reprinted from}''. - \item[\cmd{\Bby}] ``by'' in the construction + \item[\cmd{\Bby}] \DescribeMacro{\Bby} + ``by'' in the construction ``by P.~R. Krishnaiah, Ed.\hbox{}'' referring to the original editor of a reprinted work. Default is ``\verb+by+''. - \item[\cmd{\BAuthor}] ``Author'' as a description of the publisher + \item[\cmd{\BAuthor}] \DescribeMacro{\BAuthor} + ``Author'' as a description of the publisher if the author and publisher are the same. Default is ``\verb+Author+'' - \item[\cmd{\BAvailFrom}] ``Available from'', used if the \fieldname{url} + \item[\cmd{\BAvailFrom}] \DescribeMacro{\BAvailFrom} + ``Available from''. This is used in versions + of \pkg{apacite} up to [2009/03/01] if the \fieldname{url} field is specified but the \fieldname{lastchecked} field is not. + This is now superseded by \cmd{\BRetrievedFrom}. Default is ``\verb+Available from\ +''. Note the extra space. This construction allows customization by redefining this command as being empty, thereby omitting the phrase altogether, without undesirable extra space. - \item[\cmd{\BRetrieved}] ``Retrieved from'', used if both the + \item[\cmd{\BRetrieved}] \DescribeMacro{\BRetrieved} + ``Retrieved from'', used if both the \fieldname{url} field and the \fieldname{lastchecked} field are specified. It has one argumnt: the date, i.e., the contents of the \fieldname{lastchecked} field. The default is ``\verb+Retrieved {#1}, from\ +'', again with extra space. - \item[\cmd{\BMsgPostedTo}] Used for messages to newsgroups and the like. + \item[\cmd{\BRetrievedFrom}] \DescribeMacro{\BRetrievedFrom} + ``Retrieved from'', used if the \fieldname{url} + field is specified but the \fieldname{lastchecked} field is not. + This was introduced, because the APA manual (p.~192) now states + that retrieval dates should be omitted ``unless the source + material may change over time'', and prescribes ``Retrieved from'' + (p.~199). + Default is ``\verb+Retrieved from\ +'', again with extra space. + + \item[\cmd{\BMsgPostedTo}] \DescribeMacro{\BMsgPostedTo} + Used for messages to newsgroups and the like. Default is ``\verb+Message posted to\ +'', with space. - \item[\cmd{\refname}] Name of the reference list if it's a section. + \item[\cmd{\refname}] \DescribeMacro{\refname} + Name of the reference list if it's a section. (So it's the section name.) Default is ``\verb+References+''. A problem with the current implementation is, that if you use \pkg{babel}'s \cmd{\selectlanguage} command, then \cmd{\refname} @@ -2773,10 +3299,12 @@ The following label commands are used: \cmd{\selectlanguage}. I hope to provide a fix in a next version of \pkg{apacite}. - \item[\cmd{\bibname}] Name of the reference list if it's a chapter. + \item[\cmd{\bibname}] \DescribeMacro{\bibname} + Name of the reference list if it's a chapter. Default is ``\verb+References+''. See also \cmd{\refname}. - \item[\cmd{\bibliographyprenote}] This command is used before + \item[\cmd{\bibliographyprenote}] \DescribeMacro{\bibliographyprenote} + This command is used before the reference list, but after the section or chapter heading, and immediately after \cmd{\bibliographytypesize}. It is intended for an optional note just before the references @@ -2784,7 +3312,8 @@ The following label commands are used: to a list of commands (e.g., if some commands should be different in the reference list than in the text) and/or some text. - \item[\cmd{\APACmetaprenote}] If a meta-analysis is reported, the + \item[\cmd{\APACmetaprenote}] \DescribeMacro{\APACmetaprenote} + If a meta-analysis is reported, the works included in the meta-analysis should in the bibliography be preceded by an asterisk, see the description of \cmd{\APACmetastar} above. This should then be explained in a note before the references. @@ -2792,8 +3321,14 @@ The following label commands are used: ``\texttt{References marked with an asterisk indicate studies included in the meta-analysis.}''. - \item[\cmd{\authorindexname}] Name (heading) of the author index. + \item[\cmd{\authorindexname}] \DescribeMacro{\authorindexname} + Name (heading) of the author index. Default is ``\verb+Author Index+''. + + \item[\cmd{\doiprefix}] \DescribeMacro{\doiprefix} + String that is printed before a DOI. + Default is ``\verb+doi:+''. + \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2814,11 +3349,11 @@ the same adaptations again. In the early days of \pkg{apacite}, wasting disk space was another drawback, but this is not important anymore. To overcome the most salient of these problems, \pkg{apacite} has always -deferred some formatting choices to the \LaTeX{} stage, by using -tailor-made formatting commands instead of explicit formatting, -as discussed in sections~\ref{sec:custom-punct} and~\ref{subsec:labels} -above. The amount of formatting thus handled has slightly grown over -time, but still most choices were hard wired in the \BibTeX{} styles. +deferred some formatting choices to the \LaTeX{} stage, by using tailor-made +formatting commands instead of explicit formatting, as discussed in +sections~\ref{sec:custom-punct} and~\ref{subsec:labels} above. The amount of +formatting thus handled has slightly grown over time, but still most choices +were hard wired in the \BibTeX{} styles. Since the \APACversiondate{2007/09/03} version of \pkg{apacite}, a big step has been made in transferring these choices to the \LaTeX{} domain. Hence, @@ -2882,41 +3417,80 @@ not seem useful to disconnect these choices by handing them over to \LaTeX. The following commands are currently implemented to format the reference list. If you want to customize them, you can study the source code in the file \fname{apacite.sty}, copy it to you own package file, and adapt -the code as desired. -\mbox{}\vspace{0.7\baselineskip}\\ -\begin{tabular}{@{}ll@{}} -\cmd{\APACmonth} & Month name (as function of a number) \\ -\cmd{\APACrefYear} & Year in the reference list \\ -\cmd{\APACrefYearMonthDay} & Year + month + day \\ -\cmd{\APACrefatitle} & Title (article style, default upright) \\ -\cmd{\APACrefbtitle} & Title (book style, default italicized) \\ -\cmd{\APACrefaetitle} & English translation of title (article) \\ -\cmd{\APACrefbetitle} & English translation of title (book) \\ -\cmd{\APACjournalVolNumPages} & Journal, volume, number, and pages \\ -\cmd{\APACaddressPublisher} & Address and publisher \\ -\cmd{\APACaddressInstitution} & Address and institution (for technical reports) \\ -\cmd{\APACaddressPublisherEqAuth} & Address and publisher if the publisher is the author \\ -\cmd{\APACaddressInstitutionEqAuth} & Address and institution if the latter is the author \\ -\cmd{\APAChowpublished} & \fieldname{howpublished} field \\ -\cmd{\APACorigED} & Original editor for reprints and translations \\ -\cmd{\APACorigEDS} & Ditto, multiple editors \\ -\cmd{\APACrefnote} & Formatting of \fieldname{note} field \\ -\cmd{\APACorigyearnote} & Original year + optional note \\ -\cmd{\APACorigjournalnote} & Original journal (+ volume, number, pages) + optional note \\ -\cmd{\APACorigbooknote} & Formatting of ``original'' information if the original is a book \\ -\cmd{\APACbVolEdTR} & Technical report information \\ -\cmd{\APACbVolEdTRpgs} & Ditto, for \entryname{intechreport} -\end{tabular} -\mbox{}\vspace{0.7\baselineskip}\\ -In addition, the following environments are used: -\mbox{}\vspace{0.7\baselineskip}\\ -\begin{tabular}{@{}ll@{}} -\envirname{APACrefURL} & Formatting of \fieldname{url} field \\ -\envirname{APACrefURLmsg} & Formatting of \fieldname{url} field for messages \\ -\envirname{APACrefannotation} & Formatting of \fieldname{annote} or - \fieldname{annotate} fields for annotated bibliographies. -\end{tabular} -\mbox{}\vspace{0.7\baselineskip}\\ +the code as desired.\\[-0.3\baselineskip] +\par\noindent\DescribeMacro{\APACmonth} +\makebox[2.1in][l]{\cmd{\APACmonth}} +\makebox{Month name (as function of a number)} +\par\noindent\DescribeMacro{\APACrefYear} +\makebox[2.1in][l]{\cmd{\APACrefYear}} +\makebox{Year in the reference list} +\par\noindent\DescribeMacro{\APACrefYearMonthDay} +\makebox[2.1in][l]{\cmd{\APACrefYearMonthDay}} +\makebox{Year + month + day} +\par\noindent\DescribeMacro{\APACrefatitle} +\makebox[2.1in][l]{\cmd{\APACrefatitle}} +\makebox{Title (article style, default upright)} +\par\noindent\DescribeMacro{\APACrefbtitle} +\makebox[2.1in][l]{\cmd{\APACrefbtitle}} +\makebox{Title (book style, default italicized)} +\par\noindent\DescribeMacro{\APACrefaetitle} +\makebox[2.1in][l]{\cmd{\APACrefaetitle}} +\makebox{English translation of title (article)} +\par\noindent\DescribeMacro{\APACrefbetitle} +\makebox[2.1in][l]{\cmd{\APACrefbetitle}} +\makebox{English translation of title (book)} +\par\noindent\DescribeMacro{\APACjournalVolNumPages} +\makebox[2.1in][l]{\cmd{\APACjournalVolNumPages}} +\makebox{Journal, volume, number, and pages} +\par\noindent\DescribeMacro{\APACaddressPublisher} +\makebox[2.1in][l]{\cmd{\APACaddressPublisher}} +\makebox{Address and publisher} +\par\noindent\DescribeMacro{\APACaddressInstitution} +\makebox[2.1in][l]{\cmd{\APACaddressInstitution}} +\makebox{Address and institution (for technical reports)} +\par\noindent\DescribeMacro{\APACaddressPublisherEqAuth} +\makebox[2.1in][l]{\cmd{\APACaddressPublisherEqAuth}} +\makebox{Address and publisher if the publisher is the author} +\par\noindent\DescribeMacro{\APACaddressInstitutionEqAuth} +\makebox[2.1in][l]{\cmd{\APACaddressInstitutionEqAuth}} +\makebox{Address and institution if the latter is the author} +\par\noindent\DescribeMacro{\APAChowpublished} +\makebox[2.1in][l]{\cmd{\APAChowpublished}} +\makebox{\fieldname{howpublished} field} +\par\noindent\DescribeMacro{\APACorigED} +\makebox[2.1in][l]{\cmd{\APACorigED}} +\makebox{Original editor for reprints and translations} +\par\noindent\DescribeMacro{\APACorigEDS} +\makebox[2.1in][l]{\cmd{\APACorigEDS}} +\makebox{Ditto, multiple editors} +\par\noindent\DescribeMacro{\APACrefnote} +\makebox[2.1in][l]{\cmd{\APACrefnote}} +\makebox{Formatting of \fieldname{note} field} +\par\noindent\DescribeMacro{\APACorigyearnote} +\makebox[2.1in][l]{\cmd{\APACorigyearnote}} +\makebox{Original year + optional note} +\par\noindent\DescribeMacro{\APACorigjournalnote} +\makebox[2.1in][l]{\cmd{\APACorigjournalnote}} +\makebox{Original journal (+ volume, number, pages) + optional note} +\par\noindent\DescribeMacro{\APACorigbooknote} +\makebox[2.1in][l]{\cmd{\APACorigbooknote}} +\makebox{Formatting of ``original'' information if the original is a book} +\par\noindent\DescribeMacro{\APACbVolEdTR} +\makebox[2.1in][l]{\cmd{\APACbVolEdTR}} +\makebox{Technical report information} +\par\noindent\DescribeMacro{\APACbVolEdTRpgs} +\makebox[2.1in][l]{\cmd{\APACbVolEdTRpgs}} +\makebox{Ditto, for \entryname{intechreport}} +\par\noindent\DescribeMacro{\doi} +\makebox[2.1in][l]{\cmd{\doi}} +\makebox{Formatting of DOI string}\\[0.7\baselineskip] +In addition, the following environments are used:\\[-0.3\baselineskip] +\par\noindent\DescribeEnv{APACrefauthors} \makebox[1.3in][l]{\envirname{APACrefauthors} } \makebox{Formatting of authors (or editors acting as authors) in the reference list.} +\par\noindent\DescribeEnv{APACrefURL} \makebox[1.3in][l]{\envirname{APACrefURL} } \makebox{Formatting of \fieldname{url} field} +\par\noindent\DescribeEnv{APACrefDOI} \makebox[1.3in][l]{\envirname{APACrefDOI} } \makebox{Formatting of \fieldname{doi} field} +\par\noindent\DescribeEnv{APACrefURLmsg} \makebox[1.3in][l]{\envirname{APACrefURLmsg} } \makebox{Formatting of \fieldname{url} field for messages} +\par\noindent\DescribeEnv{APACrefannotation}\makebox[1.3in][l]{\envirname{APACrefannotation}} \makebox{Formatting of \fieldname{annote} or \fieldname{annotate} fields for annotated bibliographies.} +\\[0.7\baselineskip] It is likely that these lists will be expanded in future versions of \pkg{apacite}. @@ -2964,8 +3538,7 @@ is processed. Then the corresponding \fname{.apc} file, when available, is read. In this way, language-specific elements are changed to the relevant language. This is done fully automatically, the user does not have to do anything explicitly. However, sometimes an \fname{.apc} file makes some -assumptions (such as \fname{greek.apc}, which assumes ISO-8859-7 encoding) -or makes some choices that are nontrivial. Therefore, look at the source +assumptions or choices that are nontrivial. Therefore, look at the source code of the \fname{.apc} file (or in the Implementation section of this manual if you have generated this manual with the \cmd{\AlsoImplementation} option) if you obtain unexpected results. These files contain some brief @@ -2981,18 +3554,87 @@ available for the language you need, you can use one of the supplied ones as a template and write your own. If you send it to me, I can include it in a next version of \pkg{apacite}. -Note, however, that this form of language support is still very limited. -There are many aspects that are not yet covered, like different forms of -dates (month-day vs.\ day-month). As is clear from this manual, some -facilities for expanded language support have been implemented in -\pkg{apacite}, but this has often not yet been applied in the \fname{.apc} -files. Thus, future versions of \pkg{apacite} need to improve on this. - The \pkg{babelbib} package offers very sophisticated support of different languages. Perhaps some of the features that it offers are -useful additions to \pkg{apacite} as well, and this these may be included +useful additions to \pkg{apacite} as well, and these may be included in a future version of \pkg{apacite}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Language-specific issues} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +This section lists issues that are specific to one or more language +files. It is currently very incomplete. Again, I suggest you study +the \fname{.apc} file of your language for more information. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Spanish} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\pkg{apacite}'s usage of |<| and |>| for pre-notes, as in +|\cite<e.g.,>{jones06}| (inherited from its predecessor, \fname{theapa.sty}), +conflicts with \pkg{babel}'s \pkgoption{spanish} option, which makes |<| and |>| +active characters. Hence, either you must avoid using prenotes with +\pkg{apacite}'s construction or you must disable \pkg{babel}'s behavior by +inserting the command \cmd{\deactivatequoting} after loading \pkg{babel}. + +\DescribeMacro{\usespanishe} +The default ``and'' between authors in Spanish is `y', but when the +subsequent author's last name starts with an `I', this should be `e'. +Therefore, \fname{spanish.apc} introduces the command \cmd{\usespanishe}, +which takes a comma-separated list of citation keys as argument. The ``and'' +in these citations is then formatted as `e'. So +\begin{verbatim} +\citeA{AnIn93}, +\citeA{AnIn95}, +\usespanishe{AnIn93, AnIn95} +\citeA{AnIn93}, +\citeA{AnIn95}. +\end{verbatim} +gives as output ``Anderson y Ingram (1993), Anderson y Ingram (1995), +Anderson e Ingram (1993), Anderson e Ingram (1995).'' + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Setting up \MiKTeX} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\MiKTeX{} preloads the \pkg{babel} package and often uses \pkgoption{french} +as the default language. The result is that \pkg{apacite} formats +the heading of the reference list and other text strings in French. +(Other distributions also preload \pkg{babel} but use +\pkgoption{english} or \pkgoption{nohyphenation} as default.) +I have received many reports from \pkg{apacite} users who use \MiKTeX{}, +who just want the default English, but get French output and don't +know how to turn this off. Therefore, even though I believe this is a +\MiKTeX{} issue and not an \pkg{apacite} issue, I\footnote{Actually, +most of this investigation, testing, etc., was done by David Huffer, +because I don't have \MiKTeX. Thanks, David!} have reluctantly +decided to investigate this issue, and as a result of my investigation, +provide this section. + +So here is the way to solve this problem (for \MiKTeX{} version 2.7; +presumably it works similar for other versions): +\begin{enumerate} +\item +Click Start $\rightarrow$ Programs $\rightarrow$ MiKTeX 2.7 $\rightarrow$ +Settings to open the \MiKTeX{} Options window. Click on the Languages tab. +\item +Select ``\pkgoption{english}'', ``\pkgoption{nohyphenation}'', or whatever +else you'd like to be the default language, and use the Down button to move +this to the bottom. The \emph{last} checked language is the default main +document language. +\item +Click on the General tab and click on Update Formats. +\end{enumerate} +If you do this with ``\pkgoption{english}'' or ``\pkgoption{nohyphenation}'' +as default language, \pkg{apacite} will use English strings and punctuation. + +If you want to override the default (and/or you are not able to set the +default, perhaps because you don't have the administrative permissions), +you can also insert the line +\begin{verbatim} +\usepackage[english]{babel} +\end{verbatim} +in your document, before loading \pkg{apacite}. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Compatibility} \label{sec:compat} @@ -3055,10 +3697,8 @@ manual are: \item The APA has specific rules about the address: For a U.S. city, the state (or territory) should be given as a 2-letter code from the U.S. Postal Services, and the province and country - should be given if it is a non-U.S. city, unless it is one of - the 17 (U.S. and non-U.S.) cities that are ``well-known for - publishing''. Then, only the city should be mentioned. There - are similar exceptions if the name of the state (and sometimes + should be given if it is a non-U.S. city. There + are some exceptions if the name of the state (and sometimes even city) is already mentioned in the university name and the university acts as publisher; \item Yearbooks like \emph{Annual Review of Psychology} should be treated @@ -3092,25 +3732,22 @@ is tailor-made for \pkg{apacite} is likely to be suitable enough for the styles of most relevant alternative journals. Point~\ref{compat2} above is currently not fulfilled. The \pkg{apacite} -citation commands are directly based on those of its immediate predecessor, -\pkg{theapa}. But the use of `\verb+<+' and `\verb+>+' for prefixes is not -used by other packages. The influential \pkg{natbib} package uses \cmd{\citep} -and \cmd{\citet} instead of \cmd{\cite} and \cmd{\citeA}, and uses many more -alternative commands, see section~\ref{sec:compat-natbib} below. The -\pkg{chicago} package uses \cmd{\citeA} instead of \cmd{\citeauthor}, many -``numerical'' citation styles only recognize \cmd{\cite}, and so forth. As -discussed below, I now consider \pkg{natbib} as the standard with which other -packages should comply. Therefore, future versions of \pkg{apacite} will -support the \pkg{natbib} citation commands, but the current version does not -do that. - -I think that points~\ref{compat3} and~\ref{compat4} are not that important. It -seems to me that there is not much wrong with defining a style through a -combination of a \fname{.sty} and \fname{.bst} file, each requiring the other -to work. However, given the possibilities and philosophy of the \pkg{natbib} -package, it would be desirable that \fname{natbib.sty} can be used with -\fname{apacite.bst}. As discussed below, this works, although it requires -\fname{apacite.sty} to be loaded as well, before \fname{natbib.sty}. +citation commands are directly based on those of its immediate +predecessor, \pkg{theapa}. But the use of `|<|' and `|>|' for prefixes +is not used by other packages. The \pkg{chicago} package uses +\cmd{\citeA} instead of \cmd{\citeauthor}, many ``numerical'' citation +styles only recognize \cmd{\cite}, and so forth. Because \pkg{natbib} +is widely used and versatile, the \pkgoption{natbibapa} option loads +\pkg{natbib} for the citation commands, thereby allowing at least a +little ``compatibility'' (actuallu, borrowing) of citation commands. + +I think that points~\ref{compat3} and~\ref{compat4} are not that +important. It seems to me that there is not much wrong with defining +a style through a combination of a \fname{.sty} and \fname{.bst} file, +each requiring the other to work. However, given the possibilities and +philosophy of the \pkg{natbib} package, it is desirable that +\fname{natbib.sty} can be used with \fname{apacite.bst}. This is the +case, especially with the \pkgoption{natbibapa} option. Point~\ref{compat5} is very important, especially with other packages that are complementary to \pkg{apacite} in some sense. It would be very annoying having @@ -3120,6 +3757,7 @@ purposes, cannot usefully be compared, and are more valuable when they can be used jointly. The rest of this section addresses this issue for a number of packages with which compatibility problems are known to exist or have existed. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\pkg{natbib}} \label{sec:compat-natbib} @@ -3133,90 +3771,6 @@ packages that would otherwise be incompatible with \pkg{natbib} to write code to resolve these incompatibilities. I will mention some of these packages below. -I consider \pkg{natbib} as the \emph{de facto} standard with which -other packages should be compatible. Unfortunately, \pkg{apacite} is still -not entirely compatible with \pkg{natbib}. The main incompatibility is that -different citation commands are used, so that it is not possible to use the -same document with \pkg{natbib} or \pkg{apacite}. - -\pkg{apacite}, building on its predecessors, uses \cmd{\cite} for -parenthetical citations and \cmd{\citeA} for in-text citations, whereas -\pkg{natbib} uses \cmd{\citep} and \cmd{\citet} for these purposes. Moreover, -text that should precede the citation is entered between \verb+<+ and \verb+>+ -marks and text that should follow the citation is entered between square -brackets (\verb+[+ and \verb+]+, i.e., a standard \LaTeX{} optional argument) -in \pkg{apacite}, whereas \pkg{natbib} uses \emph{two} optional arguments -between brackets. If there is one optional argument, \pkg{natbib} interprets -this as text following the citation (just like \pkg{apacite}). If there is -text that should precede the citation, but not text that should follow the -citation, two optional arguments must be used in \pkg{natbib}, the second -being empty. - -Furthermore, both packages have defined some alternative citation commands, -such as \cmd{\citeNP} (\pkg{apacite}) and \cmd{\citealp} (\pkg{natbib}), some -of which serve the same purpose and could therefore be mapped onto each other -easily, but some others have no equivalent in the other package. - -A partial conversion table, listing the main \pkg{apacite} commands and their -(closest) \pkg{natbib} equivalent is given in Table~\ref{tab:APAnatConv}. The -APA requirement and \pkg{apacite} behavior of listing the full author list for -the first citation (if there are at most 5 authors) and the short author list -in subsequent citations is accomplished by loading \pkg{natbib} with the -\pkgoption{longnamesfirst} option. This is assumed in the table. An example of -better APA-like behavior of \pkg{natbib} is that, by using the -\pkgoption{sort} option, \pkg{natbib} is able to sort the references within -the same citation command, as required by the APA manual, whereas -\pkg{apacite} does not have this option yet. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\begin{table}[htp] -\caption{Partial conversion table of the main \pkg{apacite} - citation commands and their (closest) \pkg{natbib} equivalents.} -\label{tab:APAnatConv} -\begin{tabular}{lcl} -\hline -\pkg{apacite} & $\mbox{}\qquad\qquad\mbox{}$ & \pkg{natbib} \\ -\cline{1-1}\cline{3-3} -\cmd{\cite} & & \cmd{\citep} \\ -\cmd{\citeNP} & & \cmd{\citealp} \\ -\cmd{\citeA} & & \cmd{\citet} \\ -\cmd{\citeauthor} & & \cmd{\citeauthor} \\ -\cmd{\citeauthorNP} & & \cmd{\citeauthor} \\ -\\ -\cmd{\fullcite} & & \cmd{\citep*} \\ -\cmd{\fullciteNP} & & \cmd{\citealp*} \\ -\cmd{\fullciteA} & & \cmd{\citet*} \\ -\cmd{\fullciteauthor} & & \cmd{\citeauthor*} \\ -\cmd{\fullciteauthorNP} & & \cmd{\citeauthor*} \\ -\\ -\cmd{\shortcite} & & \cmdtwo{shortcites}{keys}\cmd{\citep} \\ -\cmd{\shortciteNP} & & \cmdtwo{shortcites}{keys}\cmd{\citealp} \\ -\cmd{\shortciteA} & & \cmdtwo{shortcites}{keys}\cmd{\citet} \\ -\cmd{\shortciteauthor} & & \cmdtwo{shortcites}{keys}\cmd{\citeauthor} \\ -\cmd{\shortciteauthorNP} & & \cmdtwo{shortcites}{keys}\cmd{\citeauthor} \\ -\\ -\cmd{\citeyear} & & \cmd{\citeyearpar} \\ -\cmd{\citeyearNP} & & \cmd{\citeyear} \\ -\cmd{\nocite} & & \cmd{\nocite} \\ -\hline -\end{tabular} -\end{table} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -Many labeling and punctuation commands are also different but similar between -\pkg{natbib} and \pkg{apacite}. I haven't studied the \pkg{natbib} commands -in detail, but will do so in the future. It is my intention to add -\pkg{natbib}-compatible commands to apacite in the future, so that the same -document can be processed either with \pkg{natbib} or with \pkg{apacite}. - -When you want to use \pkg{natbib} for citation and \pkg{apacite} for the -reference list, you still need to load the \LaTeX{} package \fname{apacite.sty} -(with \cmd{\usepackage}), because of the commands that are included in the -\BibTeX{} output (as defined in section~\ref{sec:custom} above). The -\fname{apacite.sty} file must be loaded \emph{before} \fname{natbib.sty}, -otherwise you will get lots of error messages. I may try to fix that for -a future version of \pkg{apacite}. - Using \pkg{natbib} for the citations has some advantages over using \pkg{apacite} for the citations. Apart from the abovementioned sorting of citations within a single citation command, these are mainly @@ -3224,111 +3778,86 @@ of citations within a single citation command, these are mainly although many compatibility problems with \pkg{apacite} have now been solved. -However, \pkg{natbib} does not fully comply with the APA rules. -Known incompatibilities between \pkg{natbib} and the APA rules are: (1) -Multiple adjacent citations with the same author and year are formatted -as ``Johnson, 1991a,b'' by \pkg{natbib}, whereas the APA manual requires -this to be ``Johnson, 1991a, 1991b''; (2) The APA manual requires ``and'' -between authors to be ``and'' in text and ``\&'' in parenthetical citation, -but \pkg{natbib} does not make this distinction. - -I could change the \fname{apacite.bst} and \fname{apacitex.bst} \BibTeX{} -style files so that \pkg{natbib} would be ``fooled'' and the first -problem would be resolved. However, this has the drawback of imposing APA -style citations when you request \pkg{natbib} style citations, and you -may actually want the behavior mentioned above. I am only able to provide -one of these possibilities. It would be better to add an option to -\pkg{natbib} with which the desired behavior can be chosen. Thus, you -could try to put pressure on the author of \pkg{natbib} to achieve this. -Alternatively, I might attempt to provide an option to \pkg{apacite} -in the future that controls this behavior of \pkg{natbib}. - -The second incompatibility between \pkg{natbib} and the APA rules mentioned -above occurs because \pkg{apacite} uses the re-definable \cmd{\BBA} -command for this usage of ``and''. The \pkg{natbib} citation commands -do not redefine \cmd{\BBA}, so you can choose only one of these, or you -must redefine \cmd{\BBA} explicitly before each citation. +When you want to use \pkg{natbib} for citation and \pkg{apacite} for the +reference list, you still need to load the \LaTeX{} package \fname{apacite.sty} +(with \cmd{\usepackage}), because of the commands that are included in the +\BibTeX{} output (as defined in section~\ref{sec:custom} above). The best +interoperability is obtained by loading \pkg{apacite} with the +\pkgoption{natbibapa} option. There is then no need to load +\pkg{natbib} explicitly, because \pkg{apacite} already does this. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\pkg{hyperref}, \pkg{backref}, and \pkg{url}} \label{sec:compat-hyper} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The \pkg{hyperref} package turns (\mbox{cross-}) references into hypertext -links. This can be used in conjunction with a program such as \latextohtml{} -to compose \fname{.html} files with clickable links, to internet pages or -within the same document, or it can be used to create a \fname{.pdf} document -with clickable crossreferences. Evidently, citations are also references. -Therefore, the \pkg{hyperref} package transforms these into hypertext links as -well, and needs to redefine the citation commands and reference list commands -in order to do so. These redefinitions have caused severe incompatibility -problems between \pkg{apacite} and \pkg{hyperref} in the past. Previous -versions of \pkg{apacite} contained an experimental \pkgoption{hyper} -option that solved some problems, but left others. In the current version -of \pkg{apacite}, the incompatibility problems have been solved, and -the \pkgoption{hyper} and \pkgoption{nohyper} options are now obsolete. -However, some of the ``dirty tricks'' I needed for complicated examples -in section~\ref{sec:xmpl} still conflict with \pkg{hyperref}. You will -probably not encounter these problems very often, but if you do these can -be easily solved by editing the \fname{.bbl} file instead of using -dangerous tricks; see also section~\ref{sec:autindex} below. - -The \pkg{backref} package adds to each entry in the bibliography a list -of pages (or sections) on which it is referenced. Hence, it serves as -an alternative to an author index, in which not the entries themselves -are backreferenced, but the authors of these entries, see -section~\ref{sec:autindex}. Note that \pkg{natbib} offers yet another -possibility, viz.\ the citations in the standard index, or a separate -citation index, see the \pkg{natbib} documentation. In my opinion, -the \pkg{backref} way of indexing the page numbers of the citations -is more logical. Moreover, it is more condensed as well. - -Obviously, the \pkg{backref} package has to change the citation commands -and reference list to be able to do its backreferencing. -Because \pkg{apacite} redefines these as well, they are conflicting -to some degree. A similar compatibility problem between \pkg{backref} -and \pkg{natbib} was noticed by the author of \pkg{backref}. Therefore, -\pkg{backref} contains some code to make it compatible with \pkg{natbib}. -This code has been adapted for \pkg{apacite} and incorporated in -\pkg{apacite}. Thus, \pkg{backref} as a standalone package has been made -compatible with \pkg{apacite}. The drawback of this solution is that if -changes are made in the \pkg{backref} package, this may result in new -incompatibilities with \pkg{apacite} unless \pkg{apacite} is changed as -well. Whether, and if so, when, this will occur will be a question for -the future. - -Apart from being a standalone package, \pkg{backref} can also be -combined with \pkg{hyperref}. It is then not loaded separately, -but through the \pkgoption{backref} or \pkgoption{pagebackref} -option of the \pkg{hyperref} package. In this case, the backreferences -become hypertext links. See the discussion of the \pkg{hyperref} -package above. - -The \pkg{url} package provides the \cmd{\url} command for formatting URLs, -i.e., web addresses. It is typically loaded if \pkg{hyperref} is also -loaded, but it is very useful on its own as well. There are no -compatibility problems with \pkg{apacite} and it is not required when -using \pkg{apacite}. However, if you use the \fieldname{url} field, -\pkg{apacite} puts it into a \cmd{\url} command. If the \cmd{\url} -command is not defined by another package, \pkg{apacite} provides a -crude definition, so that no errors are generated. But the formatting +links. This can be used in conjunction with a program such as \latextohtml{} to +compose \fname{.html} files with clickable links, to internet pages or within +the same document, or it can be used to create a \fname{.pdf} document with +clickable crossreferences. Evidently, citations are also references. Therefore, +the \pkg{hyperref} package transforms these into hypertext links as well, and +needs to redefine the citation commands and reference list commands in order to +do so. These redefinitions have caused severe incompatibility problems between +\pkg{apacite} and \pkg{hyperref} in the past. These incompatibility +problems have been solved and \pkg{apacite} is compatible with \pkg{hyperref}, +provided that \pkg{apacite} is loaded \emph{after} \pkg{hyperref}. +However, some of the ``dirty tricks'' I needed for +complicated examples in section~\ref{sec:xmpl} still conflict with +\pkg{hyperref}. You will probably not encounter these problems very often, but +if you do these can be easily solved by editing the \fname{.bbl} file instead of +using dangerous tricks; see also section~\ref{sec:autindex} below. + +The \pkg{backref} package adds to each entry in the bibliography a list of pages +(or sections) on which it is referenced. Hence, it serves as an alternative to +an author index, in which not the entries themselves are backreferenced, but the +authors of these entries, see section~\ref{sec:autindex}. Note that \pkg{natbib} +offers yet another possibility, viz.\ the citations in the standard index, or a +separate citation index, see the \pkg{natbib} documentation. In my opinion, the +\pkg{backref} way of indexing the page numbers of the citations is more logical. +Moreover, it is more condensed as well. + +Obviously, the \pkg{backref} package has to change the citation commands and +reference list to be able to do its backreferencing. Because \pkg{apacite} +redefines these as well, they are conflicting to some degree. A similar +compatibility problem between \pkg{backref} and \pkg{natbib} was noticed by the +author of \pkg{backref}. Therefore, \pkg{backref} contains some code to make it +compatible with \pkg{natbib}. This code has been adapted for \pkg{apacite} and +incorporated in \pkg{apacite}. Thus, \pkg{backref} as a standalone package has +been made compatible with \pkg{apacite}. The drawback of this solution is that +if changes are made in the \pkg{backref} package, this may result in new +incompatibilities with \pkg{apacite} unless \pkg{apacite} is changed as well. +Whether, and if so, when, this will occur will be a question for the future. + +Apart from being a standalone package, \pkg{backref} can also be combined with +\pkg{hyperref}. It is then not loaded separately, but through the +\pkgoption{backref} or \pkgoption{pagebackref} option of the \pkg{hyperref} +package. In this case, the backreferences become hypertext links. See the +discussion of the \pkg{hyperref} package above. + +The \pkg{url} package provides the \cmd{\url} command for formatting URLs, i.e., +web addresses. It is typically loaded if \pkg{hyperref} is also loaded, but it +is very useful on its own as well. There are no compatibility problems with +\pkg{apacite} and it is not required when using \pkg{apacite}. However, if you +use the \fieldname{url} field, \pkg{apacite} puts it into a \cmd{\url} command. +If the \cmd{\url} command is not defined by another package, \pkg{apacite} +provides a crude definition, so that no errors are generated. But the formatting thus obtained usually does not satisfy the APA rules about formatting, -especially its rules about line breaking within a URL. The default -line breaking rules of the \pkg{url} package are fairly close to the -APA rules, but there are some differences. Therefore, \pkg{apacite} -provides several URL-styles that adhere to the APA line breaking -rules, supplemented by the additional suggestions in -\citeA[p.~645]{chicago}. These styles apply to URL formatting through the -\cmd{\url} command anywhere in the document, not only in the reference -list and not only in the \fieldname{url} field. - -The only difference between the URL styles defined by \pkg{apacite} -is which font family they use: \verb+APACtt+ uses \cmd{\ttfamily}, -\verb+APACsf+ uses \cmd{\sffamily}, \verb+APACrm+ uses \cmd{\rmfamily}, -and \verb+APACsame+ does not define a font family, and thus uses the -font family that is active at the start of the URL. \verb+APACtt+ is -selected by default, but you can select another URL style by inserting -the command \cmd{\urlstyle}\marg{style} in your document, after -\verb+\begin{document}+. See the documentation of the \pkg{url} +especially its rules about line breaking within a URL. The default line breaking +rules of the \pkg{url} package are fairly close to the APA rules, but there are +some differences. Therefore, \pkg{apacite} provides several URL-styles that +adhere to the APA line breaking rules, supplemented by the additional +suggestions in \citeA[p.~645]{chicago}. These styles apply to URL formatting +through the \cmd{\url} command anywhere in the document, not only in the +reference list and not only in the \fieldname{url} field. + +The only difference between the URL styles defined by \pkg{apacite} is which +font family they use: \verb+APACtt+ uses \cmd{\ttfamily}, \verb+APACsf+ uses +\cmd{\sffamily}, \verb+APACrm+ uses \cmd{\rmfamily}, and \verb+APACsame+ does +not define a font family, and thus uses the font family that is active at the +start of the URL. \verb+APACtt+ is selected by default, but you can select +another URL style by inserting the command \cmd{\urlstyle}\marg{style} in your +document, after \verb+\begin{document}+. See the documentation of the \pkg{url} package for more details. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3402,10 +3931,9 @@ seems like these packages are primarily intended to work with numbered citation styles, or otherwise labeled citation styles, so that unique cross-bibliography numbers or labels can be generated at the \LaTeX{} stage. -Second, I wrote the compatibility code in early 2006 (sorry about the long -delay for this release) and have only superficially tested it recently. -It seems to work, apart from minor details, but there may be problems I am -not aware of. Please let me know if you encounter such problems. Then I'll +Second, I wrote the compatibility code in early 2006 and have not +recently tested it thoroughly. +Please let me know if you encounter problems. Then I'll try to fix them or at the least mention them in the next version of the manual. In particular, I believe that usage of \cmd{\nocitemeta} is not prefectly integrated yet: You may get the ``References marked\dots'' message @@ -3425,6 +3953,18 @@ then study changes and/or test compatibility again. Instead, I only take action when a user notifies me of a problem, or I coincidentally find out myself. Therefore, again, please let me know if you encounter problems. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\pkg{bibentry}} +\label{sec:compat-bibentry} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\pkg{bibentry} is a package that allows including a complete reference +list entry in the text (or a footnote, which is arguably more common). +Previous versions of \pkg{apacite} were incompatible with \pkg{bibentry}, +but I believe this has been fixed now. However, the APA reference format, +which uses periods to separate the elements of a reference list entry and +not commas, does not appear to be very suitable for in-text use, so this +is most likely only useful for footnotes that do not contain any other text. +Also note that the final period of the reference entry is not suppressed. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Programs for conversion to html, rtf, etc.} @@ -3442,28 +3982,12 @@ Please let me know if there are major changes that I should be aware of. \latextohtml{} is a \Perl{} program that converts a \LaTeX{} input file into one or more \fname{.html} files, so that a document that is prepared -with \LaTeX{} can be used as a (user-friendly) internet document. For papers, -lecture notes, and transparencies of classes, I always convert the -\fname{.dvi} file output by \LaTeX{} to a \fname{.pdf} file (through the -\pkg{dvipdfm} program), which can be read by most people, e.g., using the -\pkg{Adobe Reader} program or browser plug-in. I find \fname{.pdf} files -more convenient, because I can download a whole paper or presentation -with a single click and then print it and read it when and where I desire, -whereas typical examples of conversions to \fname{.html} use many -\fname{.html} files, which can only be conveniently read from the computer -screen when and where you're connected to the internet. Nevertheless, I can -imagine that someone would like to convert a document to \fname{.html}, e.g., -because it loads faster and reads easier from the screen, because for some -documents most people will have to use only a small part and can easier browse -or search through it, or just because you want to make a home page and do not -want to learn the html-language. - +with \LaTeX{} can be used as a (user-friendly) internet document. Similarly, \LaTeXrtf{} is a standalone program that converts a \LaTeX{} document to \fname{.rtf} format, which can be read by most word processors. This may be convenient if you (a \LaTeX{} user) want to share a document with someone who does not work with \LaTeX{}, or as mentioned above, if you are required to send a ``Word'' file to a journal. - Both \latextohtml{} and \LaTeXrtf{} implement \LaTeX{} macros etc.\ in another programming language (\latextohtml{}: \Perl{}; \LaTeXrtf{}: C) and process the \fname{.tex} files directly. This design implies that the @@ -3480,7 +4004,6 @@ define a \LaTeX{} macro, you could adapt \LaTeXrtf{}'s source code and recompile \LaTeXrtf{}. It is obvious that this is very inconvenient, especially if \LaTeX{} macros are defined differently for different styles or if they are defined differently in different parts of the same document. - Version~1.9.15 and higher of \LaTeXrtf{} contains some support for \pkg{apacite}, but lags a few versions of \pkg{apacite} behind and thus doesn't work with recent versions of \pkg{apacite}. Moreover, even if this @@ -3495,20 +4018,8 @@ corresponding \opt{package}\fname{.perl} \Perl{} script. \latextohtml{} is shipped with many such \Perl{} scripts. There is not one for \pkg{apacite}, but there is one for \pkg{natbib}, which could possibly be adapted for \pkg{apacite}. Alternatively, you could use the \pkg{natbib} citation commands -and use the \pkg{natbib} package, which should work. This will become more -straightforward when, in a future version, \pkg{apacite} also supports the -\pkg{natbib} citation commands. Then the \fname{natbib.perl} script may -possibly be copied to \fname{apacite.perl} without having to adapt much. -However, I have never studied \Perl{}, and I do not particularly like the -idea of having to learn that language for this purpose, so it is not very -likely that in the near future \latextohtml{} will work well with -\pkg{apacite}. - -Note, however, that the design with the \Perl{} scripts has the advantage -that, if you customize the usage of \pkg{apacite} by writing your own -\fname{.sty} file that renews the definitions of some macros, you can also -supply a corresponding \Perl{} script, so that your customizations are -processed. +and use the \pkg{natbib} package (e.g., through loading \pkg{apacite} +with the \pkgoption{natbibapa} option), which should work. An alternative to both \latextohtml{} and \LaTeXrtf{} is \TeXht{}. This is a collection of programs and style files that convert \LaTeX{} to @@ -3541,6 +4052,7 @@ large number of different converters. Because I prefer the design of \TeXht{} and because this converter seems to work best at the moment, I will give a bit more attention to this one. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Generating an author index} \label{sec:autindex} @@ -3549,16 +4061,16 @@ The \pkg{apacite} package contains an option to (almost) automatically generate an author index. This is done by using the \fname{apacitex.bst} \BibTeX{} style file instead of \fname{apacite.bst} and loading the \fname{apacite.sty} \LaTeX{} package with the \pkgoption{index} option, -either explicitly or implicitlt through one of the \pkgoption{stdindex}, +either explicitly or implicitly through one of the \pkgoption{stdindex}, \pkgoption{tocindex}, \pkgoption{emindex}, or \pkgoption{ltxemindex} options. -In previous versions of \pkg{apacite}, the \pkgoption{index} option +In earlier versions of \pkg{apacite}, the \pkgoption{index} option automatically loaded the \pkg{index} package for multiple indexes, so that you can have a subject index as well as an author index. However, the current document uses the standard \pkg{ltxdoc} class for documenting \LaTeX{} packages, and this class uses another method for supporting multiple indexes, which appears incompatible with the \pkg{index} package. -I have yet been unable to resolve these compatibility problems and, +I have been unable to resolve these compatibility problems and, therefore, have implemented another way to generate an author index in addition to other indexes. This uses the same principles as \pkg{ltxdoc} and thus does work for this user's manual. As a consequence, @@ -3595,11 +4107,12 @@ processed by \LaTeX{}. So, if the main document is \fname{filename.tex}, then \begin{verbatim} makeindex -o filename.and filename.adx \end{verbatim} -although the command with which the \MakeIndex{} program must be called may on -some systems be slightly different, e.g., \fname{makeinde} or -\fname{makeindx}. Furthermore, several additional options may be chosen on the -\MakeIndex{} command line. Fifth, run \LaTeX{} again, which (finally) includes -the formatted author index in the \fname{.dvi} file. +although the command with which the \MakeIndex{} program must be called +may on some systems be slightly different, e.g., \fname{makeinde} or +\fname{makeindx}. Furthermore, several additional options may be chosen +on the \MakeIndex{} command line. Fifth, run \LaTeX{} again, which +(finally) includes the formatted author index in the typeset document +(\fname{.dvi} or \fname{.pdf} file). The \pkg{apacite} package provides some options to change the appearance of the index somewhat. With (only) the \pkgoption{index} option, the indexing @@ -3628,22 +4141,22 @@ exceptional cases, the extra line in de table of contents may cause the text to be moved as well, so that it may be necessary to run \MakeIndex{} a second time, followed by yet one or two more \LaTeX{} runs. -The definitions of the index discussed apply to all indexes in the document, -so to, e.g., the subject index as well as the author index. This may be -undesirable, and therefore \pkg{apacite} provides the following commands -to switch index styles: -\begin{description} - \item[\cmd{\APACstdindex}] - \item[\cmd{\APACtocindex}] - \item[\cmd{\APACemindex}] - \item[\cmd{\APACltxemindex}] -\end{description} +\DescribeMacro{\APACstdindex} +\DescribeMacro{\APACtocindex} +\DescribeMacro{\APACemindex} +\DescribeMacro{\APACltxemindex} +The definitions of the index discussed apply to all indexes in the +document, so to, for example, the subject index as well as the author +index. This may be undesirable, and therefore \pkg{apacite} provides +the \cmd{\APACstdindex}, \cmd{\APACtocindex}, \cmd{\APACemindex}, and +\cmd{\APACltxemindex} commands to switch index styles. These correspond to the package options \pkgoption{stdindex}, \pkgoption{tocindex}, \pkgoption{emindex}, and \pkgoption{ltxemindex}, -respectively. Note, however, that the \pkgoption{ltxemindex} option and/or the -\cmd{\APACltxemindex} command generally cannot be used in a document that uses -one of the other styles, and vice versa, because the way \pkg{index} works is -incompatible with how standard \LaTeX{} indexing works. +respectively. Note, however, that the \pkgoption{ltxemindex} option +and/or the \cmd{\APACltxemindex} command generally cannot be used in +a document that uses one of the other styles, and vice versa, because +the way \pkg{index} works is incompatible with how standard \LaTeX{} +indexing works. If you want a different index style, either for all indexes in your document or only for some indexes, you can define such a style using the @@ -3664,7 +4177,7 @@ into the \fname{.ist} file. As discussed in sections~\ref{sec:options}, \ref{subsec:fields}, and \ref{subsec:labels}, the \pkgoption{suppresscorporate} and \pkgoption{includecorporate} options can be used to either -excludes corporate authors from the author index or include them in it. +exclude corporate authors from the author index or include them in it. The \cmd{\bibcorporate} command must be used in the \fname{.bib} file to denote a corporate author. @@ -3684,31 +4197,37 @@ to edit the \fname{.bbl} file manually. This should be done at a time when \BibTeX{} will not have to be run again. Otherwise, the changes would be overwritten by the next \BibTeX{} run. This editing of the \fname{.bbl} file is not in the \TeX-spirit, but in my experience---I used it for two books -with lots of references \cite{meijer1998,WaMe00}, with a previous version of +with lots of references \cite{meijer1998, WaMe00}, with a previous version of \pkg{apacite} that caused a fair amount of problematic cases---this takes very -little time, usually only minutes (compare that with the time spent on writing +little time, usually only minutes. Compare that with the time spent on writing a book, or with the time that would be necessary to manually make an author -index). - +index. I also used it more recently for an edited book \cite{dLMe08a} +with an adapted version of \pkg{apacite}, with essentially the current +author indexing code, and had to do very little editing. The author index +of the current document is automatically generated and does not contain +any manual editing, although it does contain some advanced \LaTeX{} code +to fix some issues. + +\DescribeMacro{\AX} The connection between the \fname{.bbl} file and the author index is through \cmd{\AX} commands that are entered by \fname{apacitex.bst} in the \fname{.bbl} file. These are responsible for the author indexing facilities. -By looking at the contents of the \fname{.bbl} file, some changes that lead to -correct formatting are immediately obvious. For example, the entry for Bender +By looking at the contents of the \fname{.bbl} file, it is not difficult +to see how problematic cases must be edited. For example, the entry for Bender is generated by the following lines: \begin{verbatim} \AX{bender jdirector @Bender, J\BPBI {\protect\bibliteral{(Director)}\protect\indexskipbracenodot}.}% \end{verbatim} -It is immediately clear that this can be changed to +This can be changed to \begin{verbatim} \AX{bender j @Bender, J.}% \end{verbatim} -Then, this author will be formatted correctly in the author index, -and conflicts with \pkg{hyperref} are resolved. -Note that \pkg{apacite} uses the \opt{key}\verb+@+\opt{visual} form of +which is formatted correctly in the author index without the need for +advanced \LaTeX{} code, and conflicts with \pkg{hyperref} are resolved. +Note that \pkg{apacite} uses the \opt{key}|@|\opt{visual} form of indexing. This form is used in \MakeIndex{} to distinguish between the actual representation in the index and the place where it should occur. The \opt{key} is used by \MakeIndex{} to sort the entry, but the entry actually appearing in @@ -3718,7 +4237,7 @@ punctuation are removed. Furthermore, \pkg{apacite} inserts \emph{two} spaces between surname and initials, and to \MakeIndex{}, two spaces are different from one space. Spaces between surnames are removed, as well as spaces between initials. Finally, note that \pkg{apacite} always inserts a new line before -the ``\verb+@+''. This is to avoid bad line breaks by \BibTeX. To \MakeIndex, +the ``|@|''. This is to avoid bad line breaks by \BibTeX. To \MakeIndex, this means that each citation \opt{key} ends with a space. The author index of the current document does not contain entries for the authors @@ -3739,11 +4258,12 @@ and if we change this into \end{verbatim} then citations to her are included in the author index. +\DescribeMacro{\corporateAX} For corporate authors, the \cmd{\corporateAX} command is used instead of the \cmd{\AX} command. Depending on whether the \pkgoption{suppresscorporate} option or the \pkgoption{includecorporate} option is requested, either explicitly or implicitly, \cmd{\corporateAX} either swallows its argument or is equivalent -to \cmd{AX}. To make sure that this ends up correctly in the author index, +to \cmd{\AX}. To make sure that this ends up correctly in the author index, it is important that this command as entered in the \fieldname{key} and/or \fieldname{firstkey} field is exactly as output by \fname{apacite.bst} for the \fieldname{author} field. The easiest way to accomplish this is to start @@ -3794,7 +4314,7 @@ behavior has now become less likely, because \pkg{apacite} inserts numerous line breaks in the \fname{.bbl} file to avoid this problem and, more importantly, line breaks inserted by \BibTeX{} at undesired locations (e.g., in the middle of a command name or in the argument of -a \cmd{url} command), but is still a possibility. +a \cmd{\url} command), but is still a possibility. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Annotated bibliographies} @@ -3831,13 +4351,15 @@ someone wants to make a file that is compatible with both the \pkg{annotate} and \pkg{annotation} styles and thus duplicates the information. In such a case, the contents of the \fieldname{annote} field is included in the output. +\DescribeEnv{APACrefannotation} The annotation is inserted in the \fname{.bbl} file within a \envirname{APACrefannotation} environment. Hence, its formatting can be changed by the user by redefining this environment. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{\fname{apacdoc.sty}} +\section{Auxiliary, ad hoc, and experimental commands in + \fname{apacdoc.sty}} \label{sec:apacdoc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Section~\ref{sec:xmpl} below cites all examples from the APA manual. @@ -3851,7 +4373,7 @@ specifically tailored for a certain reference, or ad hoc in other ways, or more generally experimental and not well tested, and likely to lead to more (compatibility) errors. Therefore, I do not consider these commands suitable for inclusion in the -\pkg{apacite} package proper, i.e., the file \fname{apacite.sty}. +\pkg{apacite} package proper, that is, the file \fname{apacite.sty}. They are not important enough for that, and thus you would rarely need them, and for most of them I anticipated (or hoped) at one point that @@ -3860,23 +4382,15 @@ quite likely that major changes in these commands would be made, and I didn't want to feel obliged to keep supporting them for backwards compatibility. Rather, I considered these as illustrations of the power of \LaTeX{} and templates that users can base their own tricks -upon. Accordingly, these commands were defined in the preamble of -previous versions of the user's manual, which used to be the file -\fname{apacite.dtx}. - -I still largely feel the same way about these commands, although +upon. I still largely feel the same way about these commands, although I'm not convinced anymore that within reasonable time I will come up with elegant solutions that make them obsolete. Nevertheless, I still -make improvements in this direction, and the support of the -\fieldname{url} and \fieldname{lastchecked} fields in his version of -\pkg{apacite} is an example of this. +make improvements in this direction. -With the restructuring of the distribution in a \fname{.dtx} file, -I have reconsidered the position of these commands, and have decided -to put them in a supplementary package file, \fname{apacdoc.sty}. As +These auxiliary, ad hoc, and experimental commands are defined in a +supplementary package file, \fname{apacdoc.sty}. As this name indicates, it is a package that is intended to be used for the \pkg{apacite} documentation (i.e., the current document). - It contains several commands and settings (like page margins) that are not interesting outside this document. However, as mentioned above, I needed many of the commands defined in this file for the @@ -3884,13 +4398,11 @@ examples in section~\ref{sec:xmpl}. Thus, you might encounter similar situations as well, and these commands may be useful for you. Because most of the commands in \fname{apacdoc.sty} will not be -useful for you (or may even interfere with your document), and -because the settings defined in it will most likely not be what you -want, it is generally not a good idea to load this file with +useful for you, it is generally not a good idea to load this file with \cmd{\usepackage} to use the commands that are useful to you. Instead, if you want to use them, you can copy their definitions to the top of your own document or personal style file (say, -\fname{mysettings.sty}, study their behavior, and perhaps improve +\fname{mysettings.sty}), study their behavior, and perhaps improve them. This reflects the ``illustration'' or ``template'' nature of these commands. @@ -3906,39 +4418,51 @@ problems as I do with proper \pkg{apacite} issues. The list below mentions (some of) the numbered examples in section~\ref{sec:xmpl} in which the commands are used. \begin{description} -\item[\cmd{\bibleciteA}] -\item[\cmd{\fullbibleciteA}] -\item[\cmd{\shortbibleciteA}] + \item[\cmd{\biblecite}] -\item[\cmd{\fullbiblecite}] -\item[\cmd{\shortbiblecite}] -\item[\cmd{\bibleciteNP}] -\item[\cmd{\fullbibleciteNP}] -\item[\cmd{\shortbibleciteNP}] \mbox{}\\ -Citing the Bible. One mandatory argument: relevant chapter and verse, e.g., -\verb+\biblecite{1~Cor.\ 13:1}+ (ex.~3.100-3). - -\item[\cmd{\bibleversion}] \mbox{}\\ -Defines the version of the Bible used: -\verb+\bibleversion{Revised Standard Version}+. Use this before using +\DescribeMacro{\biblecite} +\DescribeMacro{\bibleciteA} +\DescribeMacro{\bibleciteNP} +\DescribeMacro{\fullbiblecite} +\DescribeMacro{\fullbibleciteA} +\DescribeMacro{\fullbibleciteNP} +\DescribeMacro{\shortbiblecite} +\DescribeMacro{\shortbibleciteA} +\DescribeMacro{\shortbibleciteNP} +This command, and its siblings \cmd{\bibleciteA}, \cmd{\bibleciteNP}, +\cmd{\fullbiblecite}, \cmd{\fullbibleciteA}, \cmd{\fullbibleciteNP}, +\cmd{\shortbiblecite}, \cmd{\shortbibleciteA}, and +\cmd{\shortbibleciteNP} are commands for citing the Bible. They +have one mandatory argument: the relevant chapter and verse, for +example, |\biblecite{1~Cor.\ 13:1}| (ex.~3.100-3). + +\item[\cmd{\bibleversion}] +\DescribeMacro{\bibleversion} +This defines the version of the Bible used: +|\bibleversion{Revised Standard Version}|. Use this before using the bible citing commands, typically in the preamble of your document. Note that the Bible is not included in the reference list. You can use these commands as templates for references to other ``classic'' works. See ex.~3.100-3. \item[\cmd{\citesong}] -\item[\cmd{\fullcitesong}] -\item[\cmd{\shortcitesong}] -\item[\cmd{\citeAsong}] -\item[\cmd{\fullciteAsong}] -\item[\cmd{\shortciteAsong}] -\item[\cmd{\citesongNP}] -\item[\cmd{\fullcitesongNP}] -\item[\cmd{\shortcitesongNP}] \mbox{}\\ -These cite a song as required by the APA (except for the relative +\DescribeMacro{\citesong} +\DescribeMacro{\citeAsong} +\DescribeMacro{\citesongNP} +\DescribeMacro{\fullcitesong} +\DescribeMacro{\fullciteAsong} +\DescribeMacro{\fullcitesongNP} +\DescribeMacro{\shortcitesong} +\DescribeMacro{\shortciteAsong} +\DescribeMacro{\shortcitesongNP} +This command and its siblings \cmd{\citeAsong}, \cmd{\citesongNP}, +\cmd{\fullcitesong}, \cmd{\fullciteAsong}, \cmd{\fullcitesongNP}, +\cmd{\shortcitesong}, \cmd{\shortciteAsong}, and \cmd{\shortcitesongNP} +cite a song as required by the APA (except for the relative placement of closing quotes and comma). See ex.~69. -\item[\cmd{\bibsong}] \mbox{}\\ +\item[\cmd{\bibsong}] +\DescribeMacro{\bibsong} For \cmd{\citesong} and its siblings, the \fieldname{key} field (and possibly \fieldname{firstkey}) should contain the relevant information in the form of a protected \cmd{\bibsong} command: @@ -3947,26 +4471,32 @@ information in the form of a protected \cmd{\bibsong} command: \end{verbatim} See ex.~69. -\item[\cmd{\bibInstring}] \mbox{}\\ +\item[\cmd{\bibInstring}] +\DescribeMacro{\bibInstring} This command has one argument. The macro changes the definition of the macro \cmd{\BIn} to the argument and then immediately changes the definition back to the old definition. So it makes a one-time change. Used to change ``In'' a book to ``On'' a CD for citing songs. See ex.~69. -\item[\cmd{\BOn}] \mbox{}\\ +\item[\cmd{\BOn}] +\DescribeMacro{\BOn} ``On'', for citing songs ``On'' a CD. See ex.~69. \item[\cmd{\DSMcite}] -\item[\cmd{\DSMfullcite}] -\item[\cmd{\DSMshortcite}] -\item[\cmd{\DSMciteA}] -\item[\cmd{\DSMfullciteA}] -\item[\cmd{\DSMshortciteA}] -\item[\cmd{\DSMciteNP}] -\item[\cmd{\DSMfullciteNP}] -\item[\cmd{\DSMshortciteNP}] \mbox{}\\ -Commands to cite the DSM. See ex.~29. Can also be used for other +\DescribeMacro{\DSMcite} +\DescribeMacro{\DSMciteA} +\DescribeMacro{\DSMciteNP} +\DescribeMacro{\DSMfullcite} +\DescribeMacro{\DSMfullciteA} +\DescribeMacro{\DSMfullciteNP} +\DescribeMacro{\DSMshortcite} +\DescribeMacro{\DSMshortciteA} +\DescribeMacro{\DSMshortciteNP} +This command and its siblings \cmd{\DSMciteA}, \cmd{\DSMciteNP}, +\cmd{\DSMfullcite}, \cmd{\DSMfullciteA}, \cmd{\DSMfullciteNP}, +\cmd{\DSMshortcite}, \cmd{\DSMshortciteA}, and \cmd{\DSMshortciteNP} +cite the DSM. See ex.~29. They can also be used for other ``named'' works. \pkg{natbib} offers a similar functionality through the definition of an \emph{alias}, but I think that to get this working in the way the APA wants (i.e., the alias is not @@ -3975,7 +4505,8 @@ citations), it cannot be directly used. But the technical implementation of its functionality may form a useful basis for a better (more elegant) solution for this type of citation. -\item[\cmd{\bibDSM}] \mbox{}\\ +\item[\cmd{\bibDSM}] +\DescribeMacro{\bibDSM} For \cmd{\DSMcite} and its siblings, the \fieldname{key} field (and possibly \fieldname{firstkey}) should contain the relevant \cmd{\bibDSM} command: @@ -3986,15 +4517,19 @@ For \cmd{\DSMcite} and its siblings, the \fieldname{key} field \end{verbatim} See ex.~29. -\item[\cmd{\DSMauthor}] -\item[\cmd{\DSMfulltitle}] -\item[\cmd{\DSMedition}] -\item[\cmd{\DSMshorttitle}] \mbox{}\\ +\item[\cmd{\DSMauthor}, +\cmd{\DSMfulltitle}, +\cmd{\DSMedition}, +\cmd{\DSMshorttitle}] +\DescribeMacro{\DSMauthor} +\DescribeMacro{\DSMfulltitle} +\DescribeMacro{\DSMedition} +\DescribeMacro{\DSMshorttitle} These four commands extract the four elements of a \cmd{\bibDSM} command. They are used in the \cmd{\DSMcite} command and its siblings, but may occasionally be useful by themselves. -\item[\cmd{\bibliteral}] \mbox{}\\ +\item[\cmd{\bibliteral}] \DescribeMacro{\bibliteral} This command is used in some of the examples in section~\ref{sec:xmpl} to put some literal text into the reference list that would otherwise be abbreviated to a @@ -4010,7 +4545,7 @@ the meaning of this command before and after the reference list is used to suppress this text, as well as an additional period, there. Used in examples 4.08, 65, 66, 68, and 70. -\item[\cmd{\bibinitial}] \mbox{}\\ +\item[\cmd{\bibinitial}] \DescribeMacro{\bibinitial} This command is similar to \cmd{\bibliteral}. It is used in one example (ex.~67), where the ``author'' is a ``(Producer)'', but the initial of the author is put in the text because there @@ -4024,19 +4559,19 @@ version of the \cmd{\bibliteral} command, so perhaps in the next release I'll use \cmd{\bibinitial} for all the examples in which now \cmd{\bibliteral} is used. -\item[\cmd{\bibreftext}] \mbox{}\\ +\item[\cmd{\bibreftext}] \DescribeMacro{\bibreftext} This command takes two arguments. By default, it ignores the first and inserts the second in the output. In this manual, it is redefined before the reference list to ignore its second argument and insert the first argument in the output. This is used in ex.~17, where the year in the in-text citation should be ``1992/1993'', whereas in the reference -list, it should be 1992 (and the 1993 is listed elsewhere). +list, it should be 1992 (and the 1993 is mentioned elsewhere). For reprints and translations, this is handled automatically by \pkg{apacite} if you use the \fieldname{original*} fields, but this one is different. -\item[\cmd{\Dutchvon}] \mbox{}\\ +\item[\cmd{\Dutchvon}] \DescribeMacro{\Dutchvon} This command is equivalent to \cmd{\bibreftext}, but is used for a different situation, and therefore, depending on language, subtle style differences, and other preferences, @@ -4047,7 +4582,7 @@ in ex.~B-2, although it is not actually used in the examples, because the Dutch way to treat ``von'' parts is not APA style. -\item[\cmd{\SwapArgs}] \mbox{}\\ +\item[\cmd{\SwapArgs}] \DescribeMacro{\SwapArgs} This command takes two arguments and swaps their order. This is useful if you cite a work whose title, (corporate) author, or other element starts with an article that should be @@ -4059,16 +4594,16 @@ obviously English. For French, you could say \end{verbatim} which is thus alphabetized under M. (Not used in the examples.) -\item[\cmd{\swallownext}] \mbox{}\\ +\item[\cmd{\swallownext}] \DescribeMacro{\swallownext} Eats up the next character. Dangerous but sometimes useful. Used in the definitions of some of the following commands. -\item[\cmd{\swallowdot}] \mbox{}\\ +\item[\cmd{\swallowdot}] \DescribeMacro{\swallowdot} Eats up the next character, but only if it's a dot (`.'). Used in the definitions of some of the following commands. -\item[\cmd{\bibnodot}] \mbox{}\\ -Used as \verb+\bibnodot{.}+. Eats the period, but prevents \BibTeX{} +\item[\cmd{\bibnodot}] \DescribeMacro{\bibnodot} +Used as |\bibnodot{.}|. Eats the period, but prevents \BibTeX{} from adding one. Used in examples 78, 79, 87, 91, and 95. This is likely to be useful for many users, and is stable, so it may be upgraded to \fname{apacite.sty} in the next release of @@ -4079,7 +4614,7 @@ description of a reference to a website in a would require either adding another idiosyncratic field or even less elegant trickery in the \fname{.bib} file. -\item[\cmd{\bibskipbracenodot}] \mbox{}\\ +\item[\cmd{\bibskipbracenodot}] \DescribeMacro{\bibskipbracenodot} Suppresses the period after a subsequent closing brace. Quickly leads to errors because it uses very low level \TeX{} code that (locally) changes some fundamental settings. This is used in some examples @@ -4090,7 +4625,7 @@ name, and thus it adds a period to make it into an initial. This period is the one that's eaten by this command. Used in examples 65 and 68. -\item[\cmd{\indexskipbracenodot}] \mbox{}\\ +\item[\cmd{\indexskipbracenodot}] \DescribeMacro{\indexskipbracenodot} This serves the same purpose as \cmd{\bibskipbracenodot}, and it uses the same code, but whereas \cmd{\bibskipbracenodot} is activated for the reference list, \cmd{\indexskipbracenodot} @@ -4098,7 +4633,7 @@ is only activated for the author index. This has technical reasons and it does not work under all circumstances. Used in examples 4.08-3, 65, 66, and 68. -\item[\cmd{\bibeditortype}] \mbox{}\\ +\item[\cmd{\bibeditortype}] \DescribeMacro{\bibeditortype} This has one argument. The macro changes the definitions of the macros \cmd{\BED} and \cmd{\BEDS} to the argument and then immediately changes the definitions back to their old definitions. So it makes a @@ -4106,7 +4641,7 @@ one-time change. This is used when there is someone in an ``editor-type'' role, but with another designation, such as ``producer'' or ``director''. Ex.\ 36, 67, and 68. -\item[\cmd{\renewbibeditortype}] \mbox{}\\ +\item[\cmd{\renewbibeditortype}] \DescribeMacro{\renewbibeditortype} The above-mentioned definition of \cmd{\bibeditortype} is only relevant in the reference list: In the citations in the text and in the author index, the command should do nothing. Therefore, the command is @@ -4115,22 +4650,23 @@ initialized by \cmd{\renewbibeditortype}. This command is executed just before the reference list in the current document. (After the reference list, \cmd{\bibeditortype} becomes ``nothing'' again.) -\item[\cmd{\BAbstractRetrieved}] \mbox{}\\ +\item[\cmd{\BAbstractRetrieved}] \DescribeMacro{\BAbstractRetrieved} This command is similar to \cmd{\BRetrieved}, except that it inserts ``Abstract retrieved'' instead of ``Retrieved''. Used in examples 82 and 83. -\item[\cmd{\BmakeAbstractRetrieved}] \mbox{}\\ +\item[\cmd{\BmakeAbstractRetrieved}] +\DescribeMacro{\BmakeAbstractRetrieved} This command functions much like \cmd{\bibeditortype}: It replaces the next instance of \cmd{\BRetrieved} by \cmd{\BAbstractRetrieved}. Used in examples 82 and 83. -\item[\cmd{\noedition}] \mbox{}\\ +\item[\cmd{\noedition}] \DescribeMacro{\noedition} Suppresses the ``ed.'' (or ``\cmd{\BEd}'', rather) of an \fieldname{edition}. Used in examples 92 and 94 to format a string like ``Version~4'' as an \fieldname{edition}. -\item[\cmd{\APACmanBeforeBib}] \mbox{}\\ +\item[\cmd{\APACmanBeforeBib}] \DescribeMacro{\APACmanBeforeBib} Illustrates how some of the commands defined above are used in practice: This command is given just before the \cmd{\bibliography} command, and redefines some of the commands above, so that their meaning @@ -4161,97 +4697,93 @@ like to do with \pkg{apacite} follows below. Several items of this list are the direct result of the tricks I had to use for the examples in section~\ref{sec:xmpl} below. \begin{itemize} -\item Support \pkg{natbib} citation commands (\cmd{\citet}, \cmd{\citep}, - etc.). -\item Redefine citation commands (and other commands) as ``robust'' commands - so that they can be used in other commands, such as \cmd{\caption}, - without having to use an explicit \cmd{\protect}. - The \pkg{natbib} package does this, but \pkg{apacite} still adheres - to the older ``fragile'' setup of its predecessors. -\item Sort entries within a single citation command. The \pkg{natbib} - package already offers this option. -\item Swap (optionally) the order of closing quotes and various other - punctuation marks (\verb+.,;!?+) in a citation, for articles where - there is no named author and the title (between quotes) takes the - role of the author. -\item Add an option that disables \pkg{apacite}'s citation commands (and - perhaps a few others) to further improve inter-operability with - \pkg{natbib}. -\item Add options and/or commands for easier customization of reference - list and author index. -\item Continue with transferring reference list formatting code from - \BibTeX{} to \LaTeX. -\item Introduce options for the \BibTeX{} part, e.g., index vs.\ noindex (so - that \fname{apacitex.bst} becomes superfluous); full first names - instead of only initials, or perhaps options for putting initials - in front of (2nd and later) author names; unsorted reference lists - or lists sorted chronologically (forward or reverse; for CVs); etc. -\item Give explicit support for citation to the Bible and other - ``classic'' works and the \emph{DSM}. -\item Give explicit support for music recordings in \entryname{incollection} - entries. -\item Perhaps study referencing legal materials (Appendix~D of the APA - manual). This is actually not high on my priority list. Perhaps - you can use the \pkg{camel} package if you do this often. \item Fix a bug (which is unlikely to show up) in the \fname{.bst} file: If there are two or more references, published in the same year, each with 6 authors, the first 5 of which are the same but the 6th authors are different, then these lead to ambiguous citations. The same thing happens when one has 6 authors and another 7, with the same first 6 authors. -\item Extend the \cmd{\bibcorporate} command with an optional argument that - gives the abbreviated form, so that the \fieldname{firstkey} and - \fieldname{key} fields do not have to be used for this common situation. +\item In an \entryname{unpublished} entry, if \fieldname{author} and + \fieldname{organization} are equivalent, replace the latter with + ``Author'' in the output, analogous to the situation where + \fieldname{publisher} or \fieldname{institution} are equal to + \fieldname{author} in several of the other entry types. +\item Solve several other rare cases where \pkgoption{apacite} does not + correctly implement the APA rules: (p.~175) If additional authors + are needed to resolve an ambiguity, end with ``et al.\hbox{}'', + even if this is only one author; (p.~179) citing the Qur'an; + (p.~184) same last name and same initials, but different first name; + (p.~185) ``ca.\hbox{}''; (p.~198) Advance online publication; + (p.~202) Abstract retrieved from; (pp.~208, 212) better deal with + named archives; (p.~208) treat theses with a + URL as published theses; (p.~208) ``Doctoral thesis'' instead of + ``Doctoral dissertation'', form a university outside the United + States; (p.~214) uncertain author; + update the language files (\fname{.apc}) with correct definitions + of new text string commands; finish the examples file. + Many of these cases will not be a feature, but an ad-hoc workaround, + similar to the tricks that are described in section~\ref{sec:xmpl}. + Please contact me if you encounter any of these (or other + formatting errors) and need a workaround. +\item Study referencing legal materials (Appendix~7.1). \item Support nonstandard types of authors, like ``Director'' and ``Series Ed.\hbox{}''. This currently must be tricked in a nonelegant way. Perhaps I (or you) can think of a better solution. \item If a work is authored by someone, ``with'' someone else: This currently must be tricked in a nonelegant way. Perhaps I (or you) can think of a better solution. +\item Add more options and/or commands for easier customization of reference + list and author index. +\item Continue with transferring reference list formatting code from + \BibTeX{} to \LaTeX. +\item Introduce options for the \BibTeX{} part, e.g., index vs.\ noindex (so + that \fname{apacitex.bst} becomes superfluous); full first names + instead of only initials, or perhaps options for putting initials + in front of (2nd and later) author names; unsorted reference lists + or lists sorted chronologically (forward or reverse; for CVs); etc. +\item Extend the \cmd{\bibcorporate} command with an optional argument that + gives the abbreviated form, so that the \fieldname{firstkey} and + \fieldname{key} fields do not have to be used for this common situation. \item Define \BibTeX{} macros or strings for commonly encountered journals (at least the APA journals). -\item In an \entryname{unpublished} entry, if \fieldname{author} and - \fieldname{organization} are equivalent, replace the latter with - ``Author'' in the output, analogous to the situation where - \fieldname{publisher} or \fieldname{institution} are equal to - \fieldname{author} in several of the other entry types. \item Allow \fieldname{lastchecked} fields of the form |2009-02-01| and/or |2009/02/01| and/or other schemes, and translate these into language-specific date strings. -\item Perhaps study the 24-page electronic document - \APACcitebtitle{APA Style Guide to Electronic References}, - see \url{http://books.apa.org/books.cfm?id=4210509}, and incorporate - my findings in the next version of \pkg{apacite}. \item Rewrite and reorganize the documentation; perhaps create a ``getting started'' document. -\item Transform the examples section below into a test document. (You can - already extract its contents from the file \fname{apacite.dtx} and - copy it into a \fname{.tex} file for this purpose, but you'll have - to edit a few things in and out.) \item Improve the source code documentation, esp.\ the formatting, indexing, and cross-referencing. (You only see this if you regenerate this manual with the \cmd{\AlsoImplementation} flag set.) \end{itemize} Quite likely, other problems will come up when using the current version of -\pkg{apacite}, but at least I got it working on the APA manual examples, see -section~\ref{sec:xmpl} below. I have lots of ideas for improvements, -extensions, options, etc., but not much time to devote to it. Therefore, it is -difficult to give a good estimate of when I will release a new update. -However, in the meantime, if you have questions, remarks, suggestions, or bug -reports, you can e-mail them to me. +\pkg{apacite}. I have lots of ideas for improvements, extensions, options, and +so forth, but not much time to devote to it. Therefore, it is difficult to give +a good estimate of when I will release a new update. However, in the meantime, +if you have questions, remarks, suggestions, or bug reports, you can e-mail them +to me. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Examples of the APA manual} \label{sec:xmpl} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +{\bfseries Note: the text of this section has not been updated and +reflects the working of the [2009/03/01] version of \pkg{apacite} +vis-\`a-vis the 5th edition of the APA manual. The actual formatting +is done by the current version of \pkg{apacite} and thus may not +correspond to the text. This section is retained for the moment, because +the majority may still be relevant and I haven't finished incorporating +the examples from the 6th edition yet, and because it describes various +workarounds and tips that may still be useful.} + In this section, the \pkg{apacite} package is tested by citing the examples of -the APA manual (5th ed., pp.~207--281), and some additional references for -additional purposes. +the 5th edition of the APA manual \cite[pp.~207--281]{APAManual5}, and some +additional references for additional purposes. -The following list gives the examples from chapter~3 of the APA manual, with +The following list gives the examples from chapter~3 of the 5th edition of +the APA manual, with section number. For these and all later examples, whenever I thought it necessary or desirable, I added some comments. These are indicated by the \EM{} -symbol. Especially for later examples (from chap.~4), the comments frequently +symbol. Especially for later examples (from Chapter~4), the comments frequently pertain to the corresponding reference list entry. \begin{itemize} @@ -4366,7 +4898,7 @@ pertain to the corresponding reference list entry. Maybe I will try to construct a tentative example of this in a future release. \item[3.101] \cite[p.~332]{3.101-1}\\ - \cite[chap.~3]{3.101-2}\\ + \cite[Chapter~3]{3.101-2}\\ \EM If you like, you can use the \pkg{apacite}-defined abbreviation commands \verb+\BPG+ and \verb+\BCHAP+.\\ \cite[\P~5]{3.101-3}\\ @@ -4938,7 +5470,7 @@ short form, of the examples. \item \cite{ex55} \\ \cite{ex55}\\ \fullciteA{ex55}\\ \citeA{ex55}\\ \EM It seems logical to suppress the original year in the citation if it's the same as the year of the abstract, cf.\ - the comment to ex.~17 in the APA manual (p.~245). + the comment to ex.~17 in the APA manual (5th ed., p.~245). \EM According to example 54 and the text below it, an ``A'' or ``B'' should be added to the volume number of \emph{DAI} @@ -5019,9 +5551,9 @@ short form, of the examples. \cite{ex65-3} \\ \cite{ex65-3}\\ \fullciteA{ex65-3}\\ \citeA{ex65-3}\\ \EM Here, I simply let ``(Producer)'' be part of the author name, but because of this addendum, the entry is not sorted correctly - in the reference list: It should be before \citeA{APAManual}, + in the reference list: It should be before \citeA{APAManual6}, but because of the addendum, the authors are different to \BibTeX{} - and this one comes after \citeA{APAManual}. The ordering can be + and this one comes after \citeA{APAManual6}. The ordering can be corrected by using the \cmd{\APACSortNoop} command as discussed in section~\ref{subsec:sort}. However, the authors of these entries will still be different. If it's important that they are the same (e.g., @@ -5275,6 +5807,8 @@ short form, of the examples. Services''. \end{enumerate} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \StopEventually{% \MakePercentComment % @@ -5367,13 +5901,164 @@ short form, of the examples. % \end{macrocode} % \end{macro} % +% \subsubsection{Citation} +% +% \begin{macro}{\if@APAC@classic@cite} +% \begin{macro}{\if@APAC@natbib@emu} +% \begin{macro}{\if@APAC@natbib@apa} +% \begin{macro}{\if@APAC@classic@or@emu} +% \begin{macro}{\if@APAC@any@natbib} +% \begin{macro}{\if@APAC@anycitation} +% Allow different sets of citation commands through different options, +% implemented through |\if| commands that enable and disable the relevant +% parts of the code. \pkgoption{apaciteclassic} is the default, but this +% may change in the future. +% \begin{macrocode} +\newif\if@APAC@classic@cite +\newif\if@APAC@natbib@emu +\newif\if@APAC@natbib@apa +\newif\if@APAC@classic@or@emu +\newif\if@APAC@any@natbib +\newif\if@APAC@anycitation +\DeclareOption{apaciteclassic}{% + \@APAC@classic@citetrue + \@APAC@natbib@emufalse + \@APAC@natbib@apafalse + \@APAC@classic@or@emutrue + \@APAC@any@natbibfalse + \@APAC@anycitationtrue +} +\DeclareOption{natbibemu}{% + \@APAC@classic@citefalse + \@APAC@natbib@emutrue + \@APAC@natbib@apafalse + \@APAC@classic@or@emutrue + \@APAC@any@natbibtrue + \@APAC@anycitationtrue +} +\DeclareOption{natbibapa}{% + \@APAC@classic@citefalse + \@APAC@natbib@emufalse + \@APAC@natbib@apatrue + \@APAC@classic@or@emufalse + \@APAC@any@natbibtrue + \@APAC@anycitationtrue +} +\DeclareOption{nocitation}{% + \@APAC@classic@citefalse + \@APAC@natbib@emufalse + \@APAC@natbib@apafalse + \@APAC@classic@or@emufalse + \@APAC@any@natbibfalse + \@APAC@anycitationfalse +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% The \pkgoption{mask} option masks citations that are flagged as +% self-citations with the |\mask|-citation commands. The +% \pkgoption{unmask} option (default) ignores the masking. +% +% \begin{macrocode} +\newif\if@APAC@mask +\DeclareOption{mask}{\@APAC@masktrue} +\DeclareOption{unmask}{\@APAC@maskfalse} +% \end{macrocode} +% +% \subsubsection{Bibliography} +% +% Various options for changing the formatting of the reference list. Most of +%% ^^A \cmd{\if} somehow gives an error +% these are implemented through |\if| commands, deferring the actual +% implementation. +% \begin{macro}{\if@numberedbib} +% Should the bibliography section or chapter be numbered? +% \begin{macrocode} +\newif\if@numberedbib +% \end{macrocode} +% \end{macro} +% The bibliography is a section or chapter with a number (e.g., +% section~6 or chapter~10). This does not work properly when the section or +% chapter is in the backmatter. +% \begin{macrocode} +\DeclareOption{numberedbib}{\@numberedbibtrue} +% \end{macrocode} +% The bibliography is a section or chapter without a number (i.e., +% a section* or chapter*). This is the default. +% \begin{macrocode} +\DeclareOption{unnumberedbib}{\@numberedbibfalse} +% \end{macrocode} +% The next options determine whether the bibliography should be a section or +% a chapter. +% \begin{macro}{\if@sectionbib} +% With the \pkgoption{sectionbib} option, the bibliography is a section. This +% is typically used with the \pkg{chapterbib} package; then each chapter has a +% bibliography section. The \pkgoption{nosectionbib} option makes the +% bibliography a chapter (if chapters are defined). If none of these options +% are requested, \pkg{apacite} tries to guess the most logical choice. The +% bibliography is a section if chapters are not defined or if we are in the +% ``mainmatter'' of a document. Otherwise, i.e., in the ``backmatter'' of a +% document that has chapters, it is a chapter. +% \begin{macrocode} +\DeclareOption{sectionbib}{% + \@ifundefined{@sectionbibtrue}{\newif\if@sectionbib}{}% + \@sectionbibtrue +} +\DeclareOption{nosectionbib}{% + \@ifundefined{@sectionbibfalse}{\newif\if@sectionbib}{}% + \@sectionbibfalse +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\if@tocbib} +% These options determine whether the bibliography should be in the table of +% contents. +% \begin{macrocode} +\newif\if@tocbib +% \end{macrocode} +% The bibliography in the table of contents, even if it's unnumbered. This is +% the default. +% \begin{macrocode} +\DeclareOption{tocbib}{\@tocbibtrue} +% \end{macrocode} +% The bibliography not in the table of contents if it's unnumbered. This is +% ignored if it's numbered. +% \begin{macrocode} +\DeclareOption{notocbib}{\@tocbibfalse} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@bibnewpage} +% Start the bibliography on a new page? This is ignored if it's a chapter. +% \begin{macrocode} +\DeclareOption{bibnewpage}{\def\@bibnewpage{\bibnewpage}} +\DeclareOption{nobibnewpage}{\let\@bibnewpage\relax} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\if@doi} +% Should DOI information be printed in the reference list? +% \begin{macrocode} +\newif\if@doi +\DeclareOption{doi}{\@doitrue} +\DeclareOption{nodoi}{\@doifalse} +% \end{macrocode} +% \end{macro} +% % \subsubsection{Author indexing} % % \begin{macro}{\if@APAC@index} % No author index. %% ^^A \cmd{\if} somehow gives an error % The |\if| is necessary because packages can not be required here, so -% we must handle the consequences of the index and noindex options later. +% we must handle the consequences of the \pkgoption{index} and +% \pkgoption{noindex} options later. % \begin{macrocode} \newif\if@APAC@index \DeclareOption{noindex}{\@APAC@indexfalse}% @@ -5452,78 +6137,6 @@ short form, of the examples. % \end{macrocode} % \end{environment} % -% \subsubsection{Bibliography} -% -% Various options for changing the formatting of the reference list. Most of -%% ^^A \cmd{\if} somehow gives an error -% these are again implemented through |\if| commands, deferring the -% actual implementation. -% \begin{macro}{\if@numberedbib} -% Should the bibliography section or chapter be numbered? -% \begin{macrocode} -\newif\if@numberedbib -% \end{macrocode} -% \end{macro} -% The bibliography is a section or chapter with a number (e.g., -% section~6 or chapter~10). This does not work properly when the section or -% chapter is in the backmatter. -% \begin{macrocode} -\DeclareOption{numberedbib}{\@numberedbibtrue} -% \end{macrocode} -% The bibliography is a section or chapter without a number (i.e., -% a section* or chapter*). This is the default. -% \begin{macrocode} -\DeclareOption{unnumberedbib}{\@numberedbibfalse} -% \end{macrocode} -% The next options determine whether the bibliography should be a section or -% a chapter. -% \begin{macro}{\if@sectionbib} -% With the \pkgoption{sectionbib} option, the bibliography is a section. This -% is typically used with the \pkg{chapterbib} package; then each chapter has a -% bibliography section. The \pkgoption{nosectionbib} option makes the -% bibliography a chapter (if chapters are defined). If none of these options -% are requested, \pkg{apacite} tries to guess the most logical choice. The -% bibliography is a section if chapters are not defined or if we are in the -% ``mainmatter'' of a document. Otherwise, i.e., in the ``backmatter'' of a -% document that has chapters, it is a chapter. -% \begin{macrocode} -\DeclareOption{sectionbib}{% - \@ifundefined{@sectionbibtrue}{\newif\if@sectionbib}{}% - \@sectionbibtrue -} -\DeclareOption{nosectionbib}{% - \@ifundefined{@sectionbibfalse}{\newif\if@sectionbib}{}% - \@sectionbibfalse -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\if@tocbib} -% These options determine whether the bibliography should be in the table of -% contents. -% \begin{macrocode} -\newif\if@tocbib -% \end{macrocode} -% The bibliography in the table of contents, even if it's unnumbered. This is -% the default. -% \begin{macrocode} -\DeclareOption{tocbib}{\@tocbibtrue} -% \end{macrocode} -% The bibliography not in the table of contents if it's unnumbered. This is -% ignored if it's numbered. -% \begin{macrocode} -\DeclareOption{notocbib}{\@tocbibfalse} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\@bibnewpage} -% Start the bibliography on a new page? This is ignored if it's a chapter. -% \begin{macrocode} -\DeclareOption{bibnewpage}{\def\@bibnewpage{\bibnewpage}} -\DeclareOption{nobibnewpage}{\let\@bibnewpage\relax} -% \end{macrocode} -% \end{macro} -% % \subsubsection{Obsolete compatibility options} % % For compatibility with older versions of \pkg{apacite}. @@ -5546,8 +6159,8 @@ short form, of the examples. % % Execute default options. % \begin{macrocode} -\ExecuteOptions{noindex,indexpackage,unnumberedbib,tocbib,% - nobibnewpage,suppresscorporate} +\ExecuteOptions{apaciteclassic,noindex,indexpackage,unnumberedbib,tocbib,% + nobibnewpage,suppresscorporate,doi,unmask} % \end{macrocode} % Execute user-requested options. % \begin{macrocode} @@ -5556,10 +6169,37 @@ short form, of the examples. % % \subsection{Citation commands} % -% These must be cleaned up, robustified, made optional, etc., and the most -% important \pkg{natbib} commands must be supported as well. This is for the -% todo-list. +% \begin{macro}{\citeauthoryear} +% The \cmd{\citeauthoryear} command is defined within the citation commands, +% but some packages (\pkg{splitbib}, \pkg{bibentry}) choke if it has not +% been defined. Therefore, we start with defining it to do nothing. However, +% \pkg{natbib} defines this with a \cmd{\newcommand}, so if \pkg{natbib} is +% loaded after \pkg{apacite}, defining it here would give an error. Therefore, +% we postpone this to |\begin{document}| and only initialize it then if it +% hasn't been defined before. +% \begin{macrocode} +\AtBeginDocument{% + \@ifundefined{citeauthoryear}{\def\citeauthoryear#1#2#3{}}{}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\themaskedRefs} +% A counter for the number of masked citations, which should be +% defined for all the citation options. +% This construction ensures that there is no conflict if the +% |maskedRefs| counter has already been defined (in \fname{apa6.cls}). +% \begin{macrocode} +\AtBeginDocument{% + \@ifundefined{themaskedRefs}{\newcounter{maskedRefs}}{}} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Shared code between the \pkgoption{apaciteclassic} and +% \pkgoption{natbibemu} options} % +% Define a few |\if|s outside the main |\if|, because \TeX{} otherwise +% chokes. % \begin{macro}{\if@F@cite} % First citation in a multi-citation. % \begin{macrocode} @@ -5578,6 +6218,133 @@ short form, of the examples. % \end{macro} % \end{macro} % +% \begin{macrocode} +\if@APAC@classic@or@emu +% \end{macrocode} +% +% \begin{macro}{\nocite} +% This induces an entry in the reference list, but not in the text. It is +% also called by the other citation commands to handle some bookkeeping. +% \begin{macrocode} +\def\nocite#1{% +% \end{macrocode} +% No flag-setting in \cmd{\nocite}: a no-cite is not a citation, so a +% subsequent citation may be the first one. +% \begin{macrocode} + \@bsphack + \ifx\@onlypreamble\document +% \end{macrocode} +% We are after |\begin{document}|, so we can do the citations. +% \begin{macrocode} + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% +% \end{macrocode} +% The \cmd{\@newciteauxhandle} is for compatibility with \pkg{multibib}. +% \begin{macrocode} + \if@filesw + \immediate\write\@newciteauxhandle{\string\citation{\@citeb}}% + \fi + \@ifundefined{b@\@citeb\APAC@extra@b@citeb}{% +% \end{macrocode} +% Check for |\nocite{*}|. +% \begin{macrocode} + \edef\B@my@dummy{*}% + \ifx\@citeb\B@my@dummy + \else + \G@refundefinedtrue + \@latex@warning{Citation `\@citeb' undefined}% + \fi + }{}% + }% + \else +% \end{macrocode} +% \pkg{apacite} has no compatibility problems with \LaTeX~2.09, because it +% does not work with \LaTeX~2.09 anyway, so we can do the following, +% suggested in \fname{ltbibl.dtx}: +% \begin{macrocode} + \AtBeginDocument{\nocite{#1}}% + \fi + \@esphack +% \end{macrocode} +% For compatibility with \pkg{multibib}. +% \begin{macrocode} + \@restore@auxhandle +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\B@my@dummy} +% This needs to be initialized to avoid errors with \pkg{tex4ht}. +% \begin{macrocode} +\global\def\B@my@dummy{*}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@ifauthorsequalc@de} +% Code to be executed if current author(s) equal(s) previous. +% \begin{macrocode} +\def\@ifauthorsequalc@de#1{% + \if@F@cite + \@F@citefalse + \else + \if@Y@cite + {\@BBY}% + \fi + \fi + \if@Y@cite + \hyper@natlinkstart{#1}% + {\csname Y@\@citeb\APAC@extra@b@citeb\endcsname}% + \hyper@natlinkend + \fi +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@ifauthorsunequalc@de} +% Code to be executed if current author(s) do(es) not equal previous. +% \begin{macrocode} +\def\@ifauthorsunequalc@de#1{% + \if@F@cite + \@F@citefalse + \else + \if@Y@cite + {\@BAY}% + \fi + {\@BBC}% + \fi + \edef\@cite@undefined{?}% + \def\BBA{\@BBA}% + \if@A@cite + \hyper@natlinkstart{#1}% + {\csname b@\@citeb\APAC@extra@b@citeb\endcsname}% + \hyper@natlinkend + \if@Y@cite + {\@BBAY}% + \fi + \fi + \if@Y@cite + \hyper@natlinkstart{#1}% + {\csname Y@\@citeb\APAC@extra@b@citeb\endcsname}% + \hyper@natlinkend + \fi + \let\BBA\relax +} +% \end{macrocode} +% \end{macro} +% +% End of shared code. +% \begin{macrocode} +\fi +% \end{macrocode} +% +% \subsubsection{\pkg{apacite} ``classic'' commands} +% +% This defines the citation commands and syntax with angled brackets that +% have traditionally been used by \pkg{apacite}. +% \begin{macrocode} +\if@APAC@classic@cite +% \end{macrocode} +% % \begin{macro}{\cite} % \begin{macro}{\fullcite} % \begin{macro}{\shortcite} @@ -5895,58 +6662,6 @@ short form, of the examples. % \cmd{\@BAstyle} & formatting style of authors (e.g., \cmd{\scshape}) % \end{tabular} % -% \begin{macro}{\@ifauthorsequalc@de} -% Code to be executed if current author(s) equal(s) previous. -% \begin{macrocode} -\def\@ifauthorsequalc@de#1{% - \if@F@cite% - \@F@citefalse% - \else% - \if@Y@cite% - {\@BBY}% - \fi% - \fi% - \if@Y@cite% - \hyper@natlinkstart{#1}% - {\csname Y@\@citeb\APAC@extra@b@citeb\endcsname}% - \hyper@natlinkend - \fi% -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\@ifauthorsunequalc@de} -% Code to be executed if current author(s) do(es) not equal previous. -% \begin{macrocode} -\def\@ifauthorsunequalc@de#1{% - \if@F@cite% - \@F@citefalse% - \else% - \if@Y@cite% - {\@BAY}% - \fi% - {\@BBC}% - \fi% - \edef\@cite@undefined{?}% - \def\BBA{\@BBA}% - \if@A@cite% - \hyper@natlinkstart{#1}% - {\csname b@\@citeb\APAC@extra@b@citeb\endcsname}% - \hyper@natlinkend - \if@Y@cite% - {\@BBAY}% - \fi% - \fi% - \if@Y@cite% - \hyper@natlinkstart{#1}% - {\csname Y@\@citeb\APAC@extra@b@citeb\endcsname}% - \hyper@natlinkend - \fi% - \let\BBA\relax% -} -% \end{macrocode} -% \end{macro} -% % \begin{macro}{\@@cite} % The core citation command. Standard \LaTeX{} and other packages use % \cmd{\@citex} for this. It may be useful to change this as well, to increase @@ -5980,7 +6695,7 @@ short form, of the examples. % \begin{macrocode} \edef\@citeb{\expandafter\@firstofone\@citeb}% % \end{macrocode} -% For backref. +% For \pkg{backref}. % \begin{macrocode} \back@cite{\@citeb}% % \end{macrocode} @@ -6052,83 +6767,1225 @@ short form, of the examples. % \end{macrocode} % \end{macro} % -% \begin{macro}{\nocite} -% This induces an entry in the reference list, but not in the text. It is -% also called by the other citation commands to handle some bookkeeping. +% \begin{macro}{\maskcitations} +% \begin{macro}{\unmaskcitations} +% \begin{macro}{\masknocite} +% \begin{macro}{\maskcite} +% \begin{macro}{\maskfullcite} +% \begin{macro}{\maskshortcite} +% \begin{macro}{\maskciteNP} +% \begin{macro}{\maskfullciteNP} +% \begin{macro}{\maskshortciteNP} +% \begin{macro}{\maskciteA} +% \begin{macro}{\maskfullciteA} +% \begin{macro}{\maskshortciteA} +% \begin{macro}{\maskciteauthor} +% \begin{macro}{\maskfullciteauthor} +% \begin{macro}{\maskshortciteauthor} +% \begin{macro}{\maskciteauthorNP} +% \begin{macro}{\maskfullciteauthorNP} +% \begin{macro}{\maskshortciteauthorNP} +% \begin{macro}{\maskciteyear} +% \begin{macro}{\maskciteyearNP} +% \begin{macro}{\masktext} +% These commands allow masking of (self-)citations for a masked +% review. +% The \cmd{maskcitations} command defines the masked citation commands; +% \cmd{unmaskcitations} does the same, but lets them be equal to the +% non-mask versions. The advantage of putting these definitions within +% a command is that we can switch between masked and unmasked within +% the same document. This is not likely to be used very often in +% practice, but is useful for writing tutorials. +% \begin{macrocode} +\newcommand{\maskcitations}{% + \def\masknocite##1{}% + \def\maskcite{% + \@ifnextchar<% % > + {\mask@cite}% + {\mask@cite<>}% + }% + \def\mask@cite<##1>{% + \@ifnextchar[% % ] + {\mask@@cite<##1>}% + {\mask@@cite<##1>[]}% + }% + \def\mask@@cite<##1>[##2]##3{% + \relax +% \end{macrocode} +% Count number of masked references. % \begin{macrocode} -\def\nocite#1{% + \setcounter{maskedRefs}{0}% + \@for\@citeb:=##3\do{% + \addtocounter{maskedRefs}{1}% + }% + \ifnum\value{maskedRefs} = 1% + \onemaskedcitationmsg{\themaskedRefs}% + \else + \maskedcitationsmsg{\themaskedRefs}% + \fi + }% % \end{macrocode} -% No flag-setting in \cmd{\nocite}: a no-cite is not a citation, so a -% subsequent citation may be the first one. +% Let all other citation commands be identical to \cmd{\maskcite}. +% We could try to do fancy things with parentheses, but it's unlikely +% we will be able to cover all cases of interest, and users can easily +% change their document if they don't like how this comes out. +% \begin{macrocode} + \let\maskfullcite\maskcite + \let\maskshortcite\maskcite + \let\maskciteNP\maskcite + \let\maskfullciteNP\maskciteNP + \let\maskshortciteNP\maskciteNP + \let\maskciteA\maskcite + \let\maskfullciteA\maskciteA + \let\maskshortciteA\maskciteA + \let\maskciteauthor\maskcite + \let\maskfullciteauthor\maskciteauthor + \let\maskshortciteauthor\maskciteauthor + \let\maskciteauthorNP\maskciteauthor + \let\maskfullciteauthorNP\maskciteauthorNP + \let\maskshortciteauthorNP\maskciteauthorNP + \let\maskciteyear\maskcite + \let\maskciteyearNP\maskciteyear +% \end{macrocode} +% A user command to flexibly mask or unmask certain pieces of text. +% An environment is technically more stable than a command, but less +% intuitive for users. Under masking, this command prints the optional +% alternative text |#1|, which defaults to nothing. +% \begin{macrocode} + \DeclareRobustCommand{\masktext}[2][]{##1}% +} +% \end{macrocode} +% +% The ``mask'' citation commands revert to the same commands without +% ``mask'' if the \pkgoption{mask} option is not set. +% \begin{macrocode} +\newcommand{\unmaskcitations}{% + \let\masknocite\nocite + \let\maskcite\cite + \let\maskfullcite\fullcite + \let\maskshortcite\shortcite + \let\maskciteNP\citeNP + \let\maskfullciteNP\fullciteNP + \let\maskshortciteNP\shortciteNP + \let\maskciteA\citeA + \let\maskfullciteA\fullciteA + \let\maskshortciteA\shortciteA + \let\maskciteauthor\citeauthor + \let\maskfullciteauthor\fullciteauthor + \let\maskshortciteauthor\shortciteauthor + \let\maskciteauthorNP\citeauthorNP + \let\maskfullciteauthorNP\fullciteauthorNP + \let\maskshortciteauthorNP\shortciteauthorNP + \let\maskciteyear\citeyear + \let\maskciteyearNP\citeyearNP +% \end{macrocode} +% Unmasked, this command prints the mandatory second argument |#2|. +% \begin{macrocode} + \DeclareRobustCommand{\masktext}[2][]{##2} +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% End of ``classic'' citation commands. % \begin{macrocode} - \@bsphack - \ifx\@onlypreamble\document +\fi % \end{macrocode} -% We are after |\begin{document}|, so we can do the citations. +% +% \subsubsection{Emulation of \pkg{natbib} citation commands} +% +% If requested, this section defines the \pkg{natbib} citation commands, +% using the same syntax, without actually loading \pkg{natbib}. We also +% define a few additional commands that \pkg{natbib} did not implement, +% but that fit the scheme and serve some useful purpose for APA style +% citation. +% +% |\if@APAC@alias@cite| needs to be defined outside the +% |\if@APAC@natbib@emu| because otherwise \TeX{} does not process the +% nested |\if|'s below correctly. % \begin{macrocode} - \@for\@citeb:=#1\do{% - \edef\@citeb{\expandafter\@firstofone\@citeb}% +\newif\if@APAC@alias@cite +\@APAC@alias@citefalse +\if@APAC@natbib@emu % \end{macrocode} -% The \cmd{\@newciteauxhandle} is for compatibility with \pkg{multibib}. +% +% \begin{macro}{\citep} +% \begin{macro}{\shortcitep} +% Parenthetical citation commands. % \begin{macrocode} - \if@filesw - \immediate\write\@newciteauxhandle{\string\citation{\@citeb}}% - \fi - \@ifundefined{b@\@citeb\APAC@extra@b@citeb}{% +\DeclareRobustCommand\citep{% + \@ifstar{% full cite + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \def\@BBOP{\BBOP}% % open parenthesis + \def\@BBCP{\BBCP}% % close parenthesis + \@ifnextchar[% % ] + {\APACNAT@citep}% + {\APACNAT@citep[]}% +} +\DeclareRobustCommand\shortcitep{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \def\@BBOP{\BBOP}% % open parenthesis + \def\@BBCP{\BBCP}% % close parenthesis + \@ifnextchar[% % ] + {\APACNAT@citep}% + {\APACNAT@citep[]}% +} % \end{macrocode} -% Check for |\nocite{*}|. +% \end{macro} +% \end{macro} +% +% \begin{macro}{\citealp} +% \begin{macro}{\shortcitealp} +% Parenthetical citation commands, but without the actual parentheses. % \begin{macrocode} - \edef\B@my@dummy{*}% - \ifx\@citeb\B@my@dummy +\DeclareRobustCommand\citealp{% + \@ifstar{% full cite + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \def\@BBOP{}% % open parenthesis + \def\@BBCP{}% % close parenthesis + \@ifnextchar[%% ] + {\APACNAT@citep}% + {\APACNAT@citep[]}% +} +\DeclareRobustCommand\shortcitealp{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \def\@BBOP{}% % open parenthesis + \def\@BBCP{}% % close parenthesis + \@ifnextchar[%% ] + {\APACNAT@citep}% + {\APACNAT@citep[]}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACNAT@citep} +% Second layer of the parenthetical and alp citation commands. +% \begin{macrocode} +\newcommand\APACNAT@citep{} +\def\APACNAT@citep[#1]{% + \def\@BAP{\BAP}% % after precitation [=#1] before first citation + \def\@BBA{\BBAA}% % `and' between authors + \def\@BBAY{\BBAY}% % between author and year + \def\@BAY{}% % after year + \def\@BBY{\BBYY}% % between years of multiple citations with same author + \def\@BBC{\BBC}% % between cites + \def\@BBN{\BBN}% % after last citation before note/postcitation [=#2] + \def\@BAstyle{\BAstyle}% text style of authors + \@A@citetrue% % cite authors + \@Y@citetrue% % cite years + \@ifnextchar[% % ] + {\@citex[#1]}% + {\@citex[][#1]}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\citet} +% \begin{macro}{\shortcitet} +% In-text citation commands. +% \begin{macrocode} +\DeclareRobustCommand\citet{% + \@ifstar{% + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \def\@BBAY{ \BBOP}%% between author and year + \@ifnextchar[% %] + {\APACNAT@citet}% + {\APACNAT@citet[]}% +} +\DeclareRobustCommand\shortcitet{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \def\@BBAY{ \BBOP}%% between author and year + \@ifnextchar[% %] + {\APACNAT@citet}% + {\APACNAT@citet[]}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\citealt} +% \begin{macro}{\shortcitealt} +% Text citation commands, but without the actual parentheses. Not sure when +% this would be useful, but \pkg{natbib} defines them. +% \begin{macrocode} +\DeclareRobustCommand\citealt{% + \@ifstar{% full cite + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \def\@BBOP{}% % open parenthesis + \def\@BBCP{}% % close parenthesis + \def\@BBAY{ }%% between author and year + \@ifnextchar[%% ] + {\APACNAT@citet}% + {\APACNAT@citet[]}% +} +\DeclareRobustCommand\shortcitealt{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \def\@BBOP{}% % open parenthesis + \def\@BBCP{}% % close parenthesis + \def\@BBAY{ }%% between author and year + \@ifnextchar[%% ] + {\APACNAT@citet}% + {\APACNAT@citet[]}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACNAT@citet} +% Second layer of in-text and alt citation commands. +% \begin{macrocode} +\newcommand\APACNAT@citet{} +\def\APACNAT@citet[#1]{% + \def\@BBOP{}% % open parenthesis. + \def\@BAP{\BAP}% % after precitation [=#1] before first citation + \def\@BBA{\BBAB}% % `and' between authors +%% \def\@BBAY{ \BBOP}%% between author and year + \def\@BAY{\BBCP}% % after year + \def\@BBY{\BBYY}% % between years of multiple citations with same author + \def\@BBC{\BBC}% % between cites + \def\@BBN{\BBN}% % after last citation before note/postcitation [=#2] + \def\@BBCP{}% % close parenthesis + \def\@BAstyle{\BAstyle}% text style of authors + \@A@citetrue% % cite authors + \@Y@citetrue% % cite years + \@ifnextchar[% % ] + {\@citex[#1]}% + {\@citex[][#1]}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\citeauthort} +% \begin{macro}{\shortciteauthort} +% \begin{macro}{\citeauthorp} +% \begin{macro}{\shortciteauthorp} +% \begin{macro}{\citeauthor} +% \begin{macro}{\citefullauthor} +% \begin{macro}{\shortciteauthor} +% Commands that only cite the author, for parenthetical and in-text citations, +% the difference being that `\&' is used in the parenthetical versions, +% whereas the in-text versions use `and' between the authors. Note that all +% are without parentheses. +% \begin{macrocode} +\DeclareRobustCommand\citeauthort{% + \@ifstar{% + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \@ifnextchar[% %] + {\APACNAT@citeauthort}% + {\APACNAT@citeauthort[]}% +} +\DeclareRobustCommand\shortciteauthort{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \@ifnextchar[% %] + {\APACNAT@citeauthort}% + {\APACNAT@citeauthort[]}% +} +\DeclareRobustCommand\citeauthorp{% + \@ifstar{% + \def\BCAY##1##2##3{\BCA{##1}{##1}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##1}}% + }{% else + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + }% + \@ifnextchar[% %] + {\APACNAT@citeauthorp}% + {\APACNAT@citeauthorp[]}% +} +\DeclareRobustCommand\shortciteauthorp{% + \def\BCAY##1##2##3{\BCA{##2}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##2}{##2}}% + \@ifnextchar[% %] + {\APACNAT@citeauthorp}% + {\APACNAT@citeauthorp[]}% +} +\DeclareRobustCommand\citeauthor{\citeauthort} +\DeclareRobustCommand\citefullauthor{\citeauthort*} +\DeclareRobustCommand\shortciteauthor{\shortciteauthort} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACNAT@citeauthort} +% \begin{macro}{\APACNAT@citeauthorp} +% Second layer of the author citation commands. +% \begin{macrocode} +\newcommand\APACNAT@citeauthort{} +\def\APACNAT@citeauthort[#1]{% + \def\@BBOP{}% % open parenthesis + \def\@BAP{\BAP}% % after precitation [=#1] before first citation + \def\@BBA{\BBAB}% % `and' between authors + \def\@BBAY{}% % between author and year + \def\@BAY{}% % after year + \def\@BBY{}% % between years of multiple citations with same author + \def\@BBC{\BBC}% % between cites + \def\@BBN{\BBN}% % after last citation before note/postcitation [=#2] + \def\@BBCP{}% % close parenthesis + \def\@BAstyle{\BAastyle}% text style of authors + \@A@citetrue% % cite authors + \@Y@citefalse% % do not cite years + \@ifnextchar[% % ] + {\@citex[#1]}% + {\@citex[][#1]}% +} +\newcommand\APACNAT@citeauthorp{} +\def\APACNAT@citep[#1]{% + \def\@BBOP{}% % open parenthesis + \def\@BAP{\BAP}% % after precitation [=#1] before first citation + \def\@BBA{\BBAA}% % `and' between authors + \def\@BBAY{}% % between author and year + \def\@BAY{}% % after year + \def\@BBY{}% % between years of multiple citations with same author + \def\@BBC{\BBC}% % between cites + \def\@BBN{\BBN}% % after last citation before note/postcitation [=#2] + \def\@BBCP{}% % close parenthesis + \def\@BAstyle{\BAastyle}% text style of authors + \@A@citetrue% % cite authors + \@Y@citefalse% % do not cite years + \@ifnextchar[% % ] + {\@citex[#1]}% + {\@citex[][#1]}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\citeyearpar} +% \begin{macro}{\citeyear} +% Cite only the year; parenthetical and without parentheses. Note that these +% are the \pkg{natbib} conventions, so unlike traditional \pkg{apacite} +% \cmd{\citeyear}, \cmd{\citeyear} here does not include the parentheses. +% \begin{macrocode} +\DeclareRobustCommand\citeyearpar{% + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + \def\@BBOP{\BBOP}% % open parenthesis + \def\@BBCP{\BBCP}% % close parenthesis + \@ifnextchar[% % ] + {\APACNAT@citeyear}% + {\APACNAT@citeyear[]}% +} +\DeclareRobustCommand\citeyear{% + \def\BCAY##1##2##3{\BCA{##1}{##2}}% kept for compat. with prev. versions + \def\citeauthoryear##1##2##3{\BCA{##1}{##2}}% + \def\@BBOP{}% % open parenthesis + \def\@BBCP{}% % close parenthesis + \@ifnextchar[% % ] + {\APACNAT@citeyear}% + {\APACNAT@citeyear[]}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACNAT@citeyear} +% Second layer of the year citation commands. +% \begin{macrocode} +\newcommand\APACNAT@citeyear{} +\def\APACNAT@citeyear[#1]{% + \def\@BAP{\BAP}% % after precitation [=#1] before first citation + \def\@BBA{}% % `and' between authors + \def\@BBAY{}% % between author and year + \def\@BAY{}% % after year + \def\@BBY{\BBYY}% % between years of multiple citations with same author + \def\@BBC{\BBC}% % between cites + \def\@BBN{\BBN}% % after last citation before note/postcitation [=#2] + \def\@BAstyle{}% % text style of authors + \@A@citefalse% % do not cite authors + \@Y@citetrue% % cite years + \@ifnextchar[% % ] + {\@citex[#1]}% + {\@citex[][#1]}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACNAT@citex} +% The core citation command. We will let \cmd{\@citex} revert to this. +% \begin{macrocode} +\newcommand\APACNAT@citex{} +\def\APACNAT@citex[#1][#2]#3{% +% \end{macrocode} +% Write citation(s) to \fname{.aux} file(s) +% \begin{macrocode} + \nocite{#3}% +% \end{macrocode} +% The previous cite, for multiple citations with same author. +% \begin{macrocode} + \edef\@citeP{}% +% \end{macrocode} +% Open parenthesis and pre-note. The \cmd{\mbox} is to avoid \pkg{hyperref} +% problems if a citation command follows an \cmd{\item}. Better to change +% this to using \cmd{\citetext}; for the todo list. +% \begin{macrocode} + \mbox{\@BBOP}% + \ifx\@empty#1\@empty + \else% + {\ignorespaces #1\@BAP}% + \fi% +% \end{macrocode} +% Loop over citation entries +% \begin{macrocode} + \@for\@citeb:=#3\do{% +% \end{macrocode} +% Removes a possible space before the citation key, so that, e.g., +% \verb*+\cite{key1, key2}+ can be done. +% \begin{macrocode} + \edef\@citeb{\expandafter\@firstofone\@citeb}% +% \end{macrocode} +% For \pkg{backref}. +% \begin{macrocode} + \back@cite{\@citeb}% +% \end{macrocode} +% If this is an alias cite, we should include the alias but not author +% or year, so the code is slightly different. +% \begin{macrocode} + \if@APAC@alias@cite +% \end{macrocode} +% Check whether the alias is defined. +% \begin{macrocode} + \@ifundefined{al@\@citeb\APAC@extra@b@citeb}% + {\PackageWarning{apacite}{Undefined alias for citation \@citeb} + \expandafter\def\csname al@\@citeb\APAC@extra@b@citeb\endcsname{?}% + }{}% +% \end{macrocode} +% Replace the authors by the alias and don't cite years. +% \begin{macrocode} + \@Y@citefalse % do not cite years + \def\BCA##1##2{{\@BAstyle \csname + al@\@citeb\APAC@extra@b@citeb\endcsname}}% +% \end{macrocode} +% Use the ``unequal'' code because the alias takes the place of the +% authors. +% \begin{macrocode} + \@ifauthorsunequalc@de{\@citeb\APAC@extra@b@citeb}% \else - \G@refundefinedtrue - \@latex@warning{Citation `\@citeb' undefined}% +% \end{macrocode} +% The usual author and/or year citation. Check whether the citation is +% defined. +% \begin{macrocode} + \@ifundefined{b@\@citeb\APAC@extra@b@citeb}% + {\expandafter\def\csname b@\@citeb\APAC@extra@b@citeb\endcsname{?}% + \expandafter\def\csname Y@\@citeb\APAC@extra@b@citeb\endcsname{?}% + }% +% \end{macrocode} +% If the citation is defined, check whether the flag has been set that +% identifies that this is not the first citation to the work. If this +% flag has not been set, it will be set to |DUMMY|. If this is the first +% citation to the work, the full citation is used; else the short version +% is used. +% \begin{macrocode} + {\@ifundefined{flag@\@citeb\APAC@extra@b@citeb}% + {\global\expandafter + \def\csname flag@\@citeb\APAC@extra@b@citeb\endcsname{DUMMY}% + \def\BCA##1##2{{\@BAstyle ##1}}% + }% + {\def\BCA##1##2{{\@BAstyle ##2}}% + }% + }% +% \end{macrocode} +% Check whether the current author(s) is (are) equivalent to the +% previous. If so, only the year is cited in the text and a \cmd{\@BBY} +% (probably comma and space) is inserted between the two years. The +% \cmd{\protected@edef} fixes the problem with authors with accents +% (e.g., J{\"{o}}reskog). Older versions of \pkg{apacite} solved this +% less elegantly (\pkgoption{accentfix} option). This fix was provided by +% Robert Schlicht. See also the new definition of \cmd{\@citeP} below. +% \begin{macrocode} + \protected@edef\B@my@dummy{\csname + b@\@citeb\APAC@extra@b@citeb\endcsname}% + \ifx\@citeP\B@my@dummy + \@ifauthorsequalc@de{\@citeb\APAC@extra@b@citeb}% + \else + \@ifauthorsunequalc@de{\@citeb\APAC@extra@b@citeb}% + \fi +% \end{macrocode} +% Store the current author(s) for comparison in the next citation (if +% any). +% \begin{macrocode} + \protected@edef\@citeP{\csname + b@\@citeb\APAC@extra@b@citeb\endcsname}% + \let\BCA\relax \fi - }{}% }% +% \end{macrocode} +% End of the loop over citation entries. Add the post-note and closing +% parenthesis. +% \begin{macrocode} + \ifx\@empty#2\@empty + \else% + {\@BBN #2}% + \fi% + \if@Y@cite% + {\@BAY}% + \fi% + {\@BBCP}% +% \end{macrocode} +% We're finished with this citation command. Initialize for the next +% \cmd{\APACNAT@citex} call. +% \begin{macrocode} + \@F@citetrue % +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\citetext} +% To place any arbitrary text inside the citation braces, use +% \cmd{\citetext}. +% \begin{macrocode} +\newcommand\citetext[1]{\mbox{}\BBOP{}#1\BBCP} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@citex} +% The core citation command. +% \begin{macrocode} +\let\@citex\APACNAT@citex +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\cite} +% The use of \cmd{\cite} is considered deprecated in \pkg{natbib}, but +% we provide it as a backwards compatibility definition just like \pkg{natbib}. +% Without optional arguments, it reverts to \cmd{\citep} and with optional +% arguments (even empty ones), it reverts to \cmd{\citet}. +% \begin{macrocode} +\DeclareRobustCommand\cite{% + \@ifstar{% + \@ifnextchar[% %] + {\citep*}% + {\citet*}% + }{% + \@ifnextchar[% %] + {\citep}% + {\citet}% + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\Citet} +% \begin{macro}{\Citep} +% \begin{macro}{\Citealt} +% \begin{macro}{\Citealp} +% \begin{macro}{\Citeauthort} +% \begin{macro}{\Citeauthorp} +% \begin{macro}{\Citeauthor} +% \begin{macro}{\Citefullauthor} +% \begin{macro}{\Cite} +% Commands that capitalize the first name in a citation, to be used at the +% beginning of a sentence. These are currently not implemented yet, so let's +% just define them to be equal to the non-capitalized versions. +% \begin{macrocode} +\DeclareRobustCommand\Citet{\citet} +\DeclareRobustCommand\Citep{\citep} +\DeclareRobustCommand\Citealt{\citealt} +\DeclareRobustCommand\Citealp{\citealp} +\DeclareRobustCommand\Citeauthort{\citeauthort} +\DeclareRobustCommand\Citeauthorp{\citeauthorp} +\DeclareRobustCommand\Citeauthor{\citeauthor} +\DeclareRobustCommand\Citefullauthor{\citefullauthor} +\DeclareRobustCommand\Cite{\cite} +\DeclareRobustCommand\shortCitet{\shortcitet} +\DeclareRobustCommand\shortCitep{\shortcitep} +\DeclareRobustCommand\shortCitealt{\shortcitealt} +\DeclareRobustCommand\shortCitealp{\shortcitealp} +\DeclareRobustCommand\shortCiteauthort{\shortciteauthort} +\DeclareRobustCommand\shortCiteauthorp{\shortciteauthorp} +\DeclareRobustCommand\shortCiteauthor{\shortciteauthor} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\shortcites} +% This declares a list of citations that should be cited in their +% short form. This can be overridden by using the starred form of +% the citation commands later. +% \begin{macrocode} +\newcommand\shortcites[1]{% + \@bsphack + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% + \global\expandafter + \def\csname flag@\@citeb\APAC@extra@b@citeb\endcsname{DUMMY}% + }% + \@esphack +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\defcitealias} +% \begin{macro}{\citetalias} +% \begin{macro}{\citepalias} +% Define an ``alias'', which can be an arbitrary text string, and use +% this instead of the author and year in a citation. Adapted from +% \fname{natbib.dtx}. +% \begin{macrocode} +\newcommand\defcitealias[2]{% + \@ifundefined{al@#1\APAC@extra@b@citeb}{} + {\PackageWarning{apacite}{Overwriting existing alias for citation #1}} + \@namedef{al@#1\APAC@extra@b@citeb}{#2}} +\DeclareRobustCommand\citetalias{% + \@APAC@alias@citetrue + \citet +} +\DeclareRobustCommand\citepalias{% + \@APAC@alias@citetrue + \citep +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% Define \cmd{\citeindextype}, |\citeindextrue|, and |\citeindexfalse| +% for compatibility with \pkg{natbib}. However, these don't do anything +% in \pkg{apacite}, which supports author indexes using one of the +% ``index'' options and back referencing of specific citations using +% the \pkg{backref} package. +% \begin{macrocode} +\newif\ifciteindex \citeindexfalse +\newcommand\citeindextype{default} +% \end{macrocode} +% +% \begin{macro}{\citenumfont} +% The \pkg{natbib} command \cmd{\citenum} is undefined and thus gives an +% error, but the \cmd{\citenumfont} declaration is harmless and can stay. +% \begin{macrocode} +\let\citenumfont=\@empty +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\bibpunct} +% This sets various punctuation commands equal to its arguments. +% In contrast with the \pkg{natbib} implementation, the 5th argument +% (4th mandatory argument) is ignored, because \pkg{apacite} currently +% only supports author-year citations. Also, in contrast to the +% \pkg{natbib} implementation, this does not disable subsequent +% \cmd{\bibstyle} commands. +% \begin{macrocode} +\newcommand\bibpunct[7][, ]% + {\gdef\BBOP{#2}\gdef\BBCP{#3}\gdef\BBC{#4}% + \gdef\BBAY{#6}\gdef\BBYY{#7}\gdef\BBN{#1}% + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\bibstyle@apacite} +% \begin{macro}{\bibstyle@apa} +% These commands define the punctuation to be the \pkg{apacite} +% default. This is normally not very useful, because this only +% defines things as they are by default in \pkg{apacite} anyway, but +% it may be useful as a simple reset if different parts of the +% document need to use different styles. +% \begin{macrocode} +\newcommand\bibstyle@apacite{% + \bibpunct[, ]{(}{)}{; }{a}{, }{, }% + \setlength{\bibhang}{2.5em}% + \setlength{\bibsep}{0pt}% +} +\let\bibstyle@apa=\bibstyle@apacite +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\citestyle} +% This command selects a predefined citation punctuation style. +% In contrast to the \pkg{natbib} implementation, this is not +% deactivated at |\begin{document}|, so it's possible to change +% to a different style in the document body. +% \begin{macrocode} +\newcommand\citestyle[1]{\csname bibstyle@#1\endcsname} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\setcitestyle} +% This sets individual punctuation parameters. Adapted from +% \fname{natbib.dtx}. +% \begin{macrocode} +\newcommand\setcitestyle[1]{% + \@for\@tempa:=#1\do + {\def\@tempb{round}\ifx\@tempa\@tempb + \renewcommand\BBOP{(}\renewcommand\BBCP{)}\fi + \def\@tempb{square}\ifx\@tempa\@tempb + \renewcommand\BBOP{[}\renewcommand\BBCP{]}\fi + \def\@tempb{angle}\ifx\@tempa\@tempb + \renewcommand\BBOP{$<$}\renewcommand\BBCP{$>$}\fi + \def\@tempb{curly}\ifx\@tempa\@tempb + \renewcommand\BBOP{\{}\renewcommand\BBCP{\}}\fi + \def\@tempb{semicolon}\ifx\@tempa\@tempb + \renewcommand\BBC{; }\fi + \def\@tempb{colon}\ifx\@tempa\@tempb + \renewcommand\BBC{: }\fi + \def\@tempb{comma}\ifx\@tempa\@tempb + \renewcommand\BBC{, }\fi +% \end{macrocode} +% \pkg{apacite} supports author-year citation only, so |authoryear|, +% |numbers|, and |super| are ignored. (Alternatively, we could have +% issued an error for |numbers| and |super|.) +% \begin{macrocode} + \def\@tempb{authoryear}\ifx\@tempa\@tempb + \fi + \def\@tempb{numbers}\ifx\@tempa\@tempb + \fi + \def\@tempb{super}\ifx\@tempa\@tempb + \fi + \expandafter\APAC@find@eq\@tempa=\relax\@nil + \if\@tempc\relax\else + \expandafter\APAC@rem@eq\@tempc + \def\@tempb{open}\ifx\@tempa\@tempb + \xdef\BBOP{\@tempc}\fi + \def\@tempb{close}\ifx\@tempa\@tempb + \xdef\BBCP{\@tempc}\fi + \def\@tempb{aysep}\ifx\@tempa\@tempb + \xdef\BBAY{\@tempc}\fi + \def\@tempb{yysep}\ifx\@tempa\@tempb + \xdef\BBYY{\@tempc}\fi + \def\@tempb{notesep}\ifx\@tempa\@tempb + \xdef\BBN{\@tempc}\fi + \def\@tempb{citesep}\ifx\@tempa\@tempb + \xdef\BBC{\@tempc}\fi + \fi + }% +} +\def\APAC@find@eq#1=#2\@nil{\def\@tempa{#1}\def\@tempc{#2}} +\def\APAC@rem@eq#1={\def\@tempc{#1}} +% \end{macrocode} +% \end{macro} +% +% End of \pkg{natbib} emulation code. +% \begin{macrocode} +\fi +% \end{macrocode} +% +% \subsubsection{Using \pkg{apacite} with \pkg{natbib} for citations} +% +% If requested, this section loads \pkg{natbib} with the options +% \pkgoption{longnamesfirst} and \pkgoption{sort}, which are +% necessary for APA-style adherence. Then, we redefine some +% \pkg{natbib} and \pkg{apacite} commands to improve APA adherence of +% the combination. We also define a few additional commands that +% \pkg{natbib} did not implement, but that fit the scheme and serve +% some useful purpose for APA style citation. Defer loading this part +% until the end of the package, after loading the bibliography part. +% (This needs to be fixed.) +% +% \begin{macrocode} +\newcommand{\BBA@nat}{% + \ifNAT@swa +% \end{macrocode} +% parenthetical; ``\&'' +% \begin{macrocode} + \BBAA \else % \end{macrocode} -% \pkg{apacite} has no compatibility problems with \LaTeX~2.09, because it -% does not work with \LaTeX~2.09 anyway, so we can do the following, -% suggested in \fname{ltbibl.dtx}: +% in-text; ``and'' % \begin{macrocode} - \AtBeginDocument{\nocite{#1}}% + \BBAB \fi - \@esphack +} +\if@APAC@natbib@apa +\AtEndOfPackage{% +\RequirePackage[longnamesfirst,sort]{natbib} % \end{macrocode} -% For compatibility with \pkg{multibib}. +% +% \begin{macro}{\NAT@parse@date} +% Redefine \pkg{natbib}'s date parsing function to avoid dropping the +% year in ``(2008a, 2008b)''. % \begin{macrocode} - \@restore@auxhandle +\renewcommand\NAT@parse@date{} +\def\NAT@parse@date#1#2#3#4#5#6@@{% + \def\NAT@year{#1#2}\def\NAT@exlab{{#3}}} +% \end{macrocode} +% \end{macro} +% ``and'' vs.\ ``\&''. +% \begin{macrocode} +\DeclareRobustCommand{\BBA}{\BBA@nat} +% \end{macrocode} +% In the reflist ``\&''. +% \begin{macrocode} +\let\orig@nat@@lbibitem\@lbibitem +\def\@lbibitem{\NAT@swatrue\orig@nat@@lbibitem} +% \end{macrocode} +% +% Make sure we're in parenthetical mode when in \cmd{\citetext} +% \begin{macrocode} +\renewcommand\citetext[1]{\NAT@open\begingroup\NAT@swatrue + #1\endgroup\NAT@close} +% \end{macrocode} +% +% \begin{macro}{\citeauthort} +% \begin{macro}{\citeauthorp} +% \begin{macro}{\citefullauthort} +% \begin{macro}{\citefullauthorp} +% \begin{macro}{\Citeauthort} +% \begin{macro}{\Citeauthorp} +% \begin{macro}{\Citefullauthort} +% \begin{macro}{\Citefullauthorp} +% There's only one \cmd{\citeauthor}, but we need to distinguish +% between parenthetical and in-text. The most common is in-text, so +% let \cmd{\citeauthor} be the in-text one, but define +% \cmd{\citeauthort} to be the same, and add \cmd{\citeauthorp}. +% \begin{macrocode} +\DeclareRobustCommand\citeauthort{\citeauthor} +\DeclareRobustCommand\Citeauthort{\Citeauthor} +\DeclareRobustCommand\citeauthorp + {\begingroup\NAT@swatrue\let\NAT@ctype\@ne\NAT@parfalse + \@ifstar{\NAT@fulltrue\NAT@citetp}{\NAT@fullfalse\NAT@citetp}} +\DeclareRobustCommand\Citeauthorp + {\begingroup\NAT@swatrue\let\NAT@ctype\@ne\NAT@parfalse + \let\NAT@up\NAT@Up + \@ifstar{\NAT@fulltrue\NAT@citetp}{\NAT@fullfalse\NAT@citetp}} +% \end{macrocode} +% For completeness of the system. +% \begin{macrocode} +\DeclareRobustCommand{\Citefullauthor}{\Citeauthor*} +\DeclareRobustCommand{\citefullauthort}{\citeauthort*} +\DeclareRobustCommand{\citefullauthorp}{\citeauthorp*} +\DeclareRobustCommand{\Citefullauthort}{\Citeauthort*} +\DeclareRobustCommand{\Citefullauthorp}{\Citeauthorp*} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibstyle@apacite} +% \begin{macro}{\bibstyle@apa} +% Other settings. I think the \pkg{natbib} defaults are good, but +% let's define this explicitly and allow the usual \pkg{apacite} +% customization options. +% \begin{macrocode} +\providecommand\bibstyle@apacite{% +% \end{macrocode} +% \pkg{natbib} is inconsistent with adding space. +% \begin{macrocode} + \renewcommand{\BBAY}{,\ignorespaces }% + \bibpunct[\BBN ]{\BBOP }{\BBCP }{\BBC }{a}{\BBAY }{\BBYY }% + \setlength{\bibhang}{2.5em}% + \setlength{\bibsep}{0pt}% } +\providecommand\bibstyle@apa{\bibstyle@apacite} +\citestyle{apacite} % \end{macrocode} % \end{macro} +% \end{macro} +% +% End of \pkg{natbib}--\pkg{apacite} code. +% \begin{macrocode} +}% end \cmd{\AtEndOfPackage} +\fi +% \end{macrocode} +% +% \subsubsection{Shared code for \pkgoption{natbibemu} and +% \pkgoption{natbibapa}} +% +% This section defines some extensions of \pkg{natbib} that are +% useful with both the \pkgoption{natbibemu} and \pkgoption{natbibapa} +% options. +% +% \begin{macrocode} +\if@APAC@any@natbib +% \end{macrocode} +% +% \begin{macro}{\maskcitations} +% \begin{macro}{\unmaskcitations} +% \begin{macro}{\masknocite} +% \begin{macro}{\maskcitep} +% \begin{macro}{\maskcitealp} +% \begin{macro}{\maskcitet} +% \begin{macro}{\maskcitealt} +% \begin{macro}{\maskciteauthor} +% \begin{macro}{\maskcitefullauthor} +% \begin{macro}{\maskciteyearpar} +% \begin{macro}{\maskciteyear} +% \begin{macro}{\maskcite} +% \begin{macro}{\maskcitetalias} +% \begin{macro}{\maskcitepalias} +% \begin{macro}{\maskCitet} +% \begin{macro}{\maskCitep} +% \begin{macro}{\maskCitealt} +% \begin{macro}{\maskCitealp} +% \begin{macro}{\maskCiteauthor} +% \begin{macro}{\maskcitenum} +% \begin{macro}{\maskciteauthort} +% \begin{macro}{\maskciteauthorp} +% \begin{macro}{\maskCitefullauthor} +% \begin{macro}{\maskCiteauthort} +% \begin{macro}{\maskCiteauthorp} +% \begin{macro}{\masktext} +% These commands allow masking of (self-)citations for a masked +% review. +% The \cmd{maskcitations} command defines the masked citation commands; +% \cmd{unmaskcitations} does the same, but lets them be equal to the +% non-mask versions. The advantage of putting these definitions within +% a command is that we can switch between masked and unmasked within +% the same document. This is not likely to be used very often in +% practice, but is useful for writing tutorials. +% \begin{macrocode} +\newcommand{\maskcitations}{% + \def\masknocite##1{}% + \DeclareRobustCommand\maskcite{% + \@ifnextchar[% % ] + {\mask@cite}% + {\mask@cite[]}% + }% + \def\mask@cite[##1]{% + \@ifnextchar[% % ] + {\mask@@cite[##1]}% + {\mask@@cite[##1][]}% + }% + \def\mask@@cite[##1][##2]##3{% + \relax +% \end{macrocode} +% Count number of masked references. +% \begin{macrocode} + \setcounter{maskedRefs}{0}% + \@for\@citeb:=##3\do{% + \addtocounter{maskedRefs}{1}% + }% + \ifnum\value{maskedRefs} = 1% + \onemaskedcitationmsg{\themaskedRefs}% + \else + \maskedcitationsmsg{\themaskedRefs}% + \fi + }% +% \end{macrocode} +% Let all other citation commands be identical to \cmd{\maskcite}. +% We could try to do fancy things with parentheses, but it's unlikely +% we will be able to cover all cases of interest, and users can easily +% change their document if they don't like how this comes out. +% \begin{macrocode} + \let\maskcitep\maskcite + \let\maskcitealp\maskcite + \let\maskcitet\maskcite + \let\maskcitealt\maskcite + \let\maskciteauthor\maskcite + \let\maskcitefullauthor\maskcite + \let\maskciteyearpar\maskcite + \let\maskciteyear\maskcite + \let\maskcitetalias\maskcite + \let\maskcitepalias\maskcite + \let\maskCitet\maskcite + \let\maskCitep\maskcite + \let\maskCitealt\maskcite + \let\maskCitealp\maskcite + \let\maskCiteauthor\maskcite + \let\maskcitenum\maskcite + \let\maskciteauthort\maskcite + \let\maskciteauthorp\maskcite + \let\maskCitefullauthor\maskcite + \let\maskCiteauthort\maskcite + \let\maskCiteauthorp\maskcite +% \end{macrocode} +% A user command to flexibly mask or unmask certain pieces of text. +% An environment is technically more stable than a command, but less +% intuitive for users. Under masking, this command prints the optional +% alternative text |#1|, which defaults to nothing. +% \begin{macrocode} + \DeclareRobustCommand{\masktext}[2][]{##1}% +} +% \end{macrocode} +% +% The ``mask'' citation commands revert to the same commands without +% ``mask'' if the \pkgoption{mask} option is not set. +% \begin{macrocode} +\newcommand{\unmaskcitations}{% + \let\masknocite\nocite + \let\maskcitep\citep + \let\maskcitealp\citealp + \let\maskcitet\citet + \let\maskcitealt\citealt + \let\maskciteauthor\citeauthor + \let\maskcitefullauthor\citefullauthor + \let\maskciteyearpar\citeyearpar + \let\maskciteyear\citeyear + \let\maskcite\cite + \let\maskcitetalias\citetalias + \let\maskcitepalias\citepalias + \let\maskCitet\Citet + \let\maskCitep\Citep + \let\maskCitealt\Citealt + \let\maskCitealp\Citealp + \let\maskCiteauthor\Citeauthor + \let\maskcitenum\citenum + \let\maskciteauthort\citeauthort + \let\maskciteauthorp\citeauthorp + \let\maskCitefullauthor\Citefullauthor + \let\maskCiteauthort\Citeauthort + \let\maskCiteauthorp\Citeauthorp +% \end{macrocode} +% Unmasked, this command prints the mandatory second argument |#2|. +% \begin{macrocode} + \DeclareRobustCommand{\masktext}[2][]{##2} +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% End of \pkg{natbib} code. +% \begin{macrocode} +\fi +% \end{macrocode} +% +% This is part of the shared code, but has to be put after loading +% of \pkg{natbib}, so we'll put it here for the moment. +% \begin{macrocode} +\if@APAC@anycitation + \AtEndOfPackage{% + \if@APAC@mask + \maskcitations + \else + \unmaskcitations + \fi + }% +\fi +% \end{macrocode} % +% \subsubsection{Meta analysis} +% +% To my knowledge. \cmd{\nocitemeta} is not defined by any other citation +% package, so we'll provide it here regardless of the citation option +% chosen. +% \begin{macro}{\definemetaflag} % \begin{macro}{\nocitemeta} % This induces an entry in the reference list, but not in the text, and % compared to \cmd{\nocite} defines an additional flag that indicates that the -% reference has been used in the meta-analysis reported. +% reference has been used in the meta-analysis reported. The construction +% with \cmd{\definemetaflag} is necessary to support \cmd{\nocitemeta} in +% an appendix \emph{after} the reference list. However, the previous version +% did not require the |\if@filesw|, which suggests that that would work if +% we can't write to the \fname{.aux} file, whereas the current one wouldn't. +% I don't know under what conditions this would happen or be useful, but it +% seems extremely rare. If somebody complains, I'll make a fix. +% \begin{macrocode} +\def\definemetaflag#1{% + \@bsphack +% \end{macrocode} +% Define the note that precedes the reference list. % \begin{macrocode} -\def\nocitemeta#1{% - \nocite{#1}% - \@bsphack% - \expandafter\global\expandafter\def - \csname APAC@metaprenote@\APAC@extra@b@citeb\endcsname{% - \APACmetaprenote}% - \@for\@citeb:=#1\do{% - \edef\@citeb{\expandafter\@firstofone\@citeb}% + \expandafter\global\expandafter\def + \csname APAC@metaprenote@\APAC@extra@b@citeb\endcsname{% + \APACmetaprenote}% + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% % \end{macrocode} -% Define the meta-analysis flag for the current item. +% Define the meta-analysis flag for the current item. % \begin{macrocode} - \@ifundefined{flagmeta@\@citeb\APAC@extra@b@citeb}% - {\global\expandafter - \def\csname flagmeta@\@citeb\APAC@extra@b@citeb\endcsname{DUMMY}% - }% - {}% + \@ifundefined{flagmeta@\@citeb\APAC@extra@b@citeb}% + {\global\expandafter + \def\csname flagmeta@\@citeb\APAC@extra@b@citeb\endcsname{DUMMY}% + }% + {}% + }% + \@esphack +} +\def\nocitemeta#1{% + \nocite{#1}% + \@bsphack + \if@filesw + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% + \immediate\write + \@newciteauxhandle{\string\definemetaflag{\@citeb}}% }% - \@esphack% + \fi + \@esphack + \@restore@auxhandle } % \end{macrocode} % \end{macro} +% \end{macro} % % \subsection{Bibliography structure} % @@ -6139,7 +7996,6 @@ short form, of the examples. % % \begin{macro}{\bibnewpage} % Macro for starting a new page before the bibliography, if requested. -% \fname{apa.cls} uses \cmd{\newpage} instead. % \begin{macrocode} \def\bibnewpage{\clearpage}% % \end{macrocode} @@ -6153,7 +8009,11 @@ short form, of the examples. % \end{macro} % % \begin{macro}{\@lbibitem} -% Label-bibitem +% Label-bibitem. If \pkg{natbib} is loaded after \pkg{apacite} (or +% \pkg{apacite} is loaded with the \pkgoption{natbibapa} option), +% this is overwritten. I should introduce an option that disables +% \pkg{apacite}'s bibliography-defining commands and/or senses whether +% \pkg{natbib} is loaded, so this is never defined in such cases. % \begin{macrocode} \def\@lbibitem[#1]#2{% \def\BBA{\BBAA}% ``\&'' @@ -6305,19 +8165,19 @@ short form, of the examples. % up to the user. The ``metaprenote'' is a fixed text indicating that % marked references are included in the meta-analysis reported. % \begin{macrocode} - \bibliographytypesize% e.g., to put the bibliography in \small type - \bibliographyprenote% some explanatory note before the references + \bibliographytypesize % e.g., to put the bibliography in \small type + \bibliographyprenote % some explanatory note before the references \@ifundefined{APAC@metaprenote@\APAC@extra@b@citeb}% {}% skip {\csname APAC@metaprenote@\APAC@extra@b@citeb\endcsname}% % \end{macrocode} % Initialize the list environment that holds the reference list. % \begin{macrocode} - \list{\relax}{\labelsep=0em% + \list{\relax}{\labelsep=\biblabelsep % \parskip\z@ \@plus .3\p@\relax - \parsep=\bibparsep% - \itemsep=\bibitemsep% - \leftmargin=\bibleftmargin% + \parsep=\bibparsep + \itemsep=\bibitemsep + \leftmargin=\bibleftmargin \itemindent=\bibindent}% changed to cope with 4th ed. % \end{macrocode} % \cmd{\newblock} is inserted between ``blocks'' of a reference entry and @@ -6415,6 +8275,18 @@ short form, of the examples. % \end{macro} % \end{macro} % +% \begin{environment}{APACrefauthors} +% An environment that allows some limited customization of author +% formatting in the reference list. In this implementation customization +% is handled through the \cmd{\APACrefauthstyle} macro, which allows some +% style definition, in particular font changes such as \cmd{\sc}. +% \begin{macrocode} +\newenvironment{APACrefauthors}{% + \begingroup \APACrefauthstyle +}{\endgroup } +% \end{macrocode} +% \end{environment} +% % \begin{macro}{\APACrefYear} % Formatting of the year in the reference list. Note that instead of redefining % this command, one can also redefine the parentheses themselves. The argument @@ -6538,14 +8410,36 @@ short form, of the examples. % \begin{macrocode} \newenvironment{APACrefURL}[1][]{% \ifx\@empty#1\@empty - \BAvailFrom % Available from + \BRetrievedFrom % Retrieved from \else - \BRetrieved{#1}% Retrieved <date>, from + \BRetrieved{#1}% Retrieved <date>, from \fi }{} % \end{macrocode} % \end{environment} % +% \begin{environment}{APACrefDOI} +% DOI formatting. Use an environment instead of a macro to avoid some problems +% with url's as arguments of macros. +% \begin{macrocode} +\newenvironment{APACrefDOI}{% + \global\let\old@doi\doi + \if@doi + \doiprefix + \else +% \end{macrocode} +% Suppression of DOIs. For non-APA styles. +% \begin{macrocode} + \global\let\doi\@gobble + \fi +% \end{macrocode} +% Restore definition of \cmd{\doi}, in case a user wants to use this +% command explicitly. +% \begin{macrocode} + }{\global\let\doi\old@doi } +% \end{macrocode} +% \end{environment} +% % \begin{environment}{APACrefURLmsg} % URLs of messages. % \begin{macrocode} @@ -6775,6 +8669,13 @@ short form, of the examples. % \end{macrocode} % \end{macro} % +% \begin{macro}{\APACrefauthstyle} +% Text style of authors in reference list. +% \begin{macrocode} +\newcommand{\APACrefauthstyle}{}% +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\APACciteatitle} % \begin{macro}{\APACcitebtitle} % Formatting of ``article'' and ``book'' titles when they are used in a @@ -6848,22 +8749,30 @@ short form, of the examples. % \begin{macro}{\bibindent} % \begin{macro}{\bibparsep} % \begin{macro}{\bibitemsep} -% Declare four length parameters for the reference list and give them default -% values. +% \begin{macro}{\biblabelsep} +% Declare a few length parameters for the reference list and give them +% default values. Supporting the \pkg{natbib} length \cmd{\bibhang} would +% be nice, but I don't see a way to do this in a user-friendly way that +% allows loading \pkg{apacite} both with and without \pkg{natbib} and +% also allows changing \cmd{\bibindent} and \cmd{\bibleftmargin} +% separately. % \begin{macrocode} \newskip{\bibleftmargin} \newskip{\bibindent} \newskip{\bibparsep} \newskip{\bibitemsep} -\bibleftmargin=2.5em -\bibindent=-\bibleftmargin -\bibparsep=0pt% -\bibitemsep\z@ \@plus .3\p@\relax +\newskip{\biblabelsep} +\setlength{\bibleftmargin}{2.5em} +\setlength{\bibindent}{-\bibleftmargin} +\setlength{\bibparsep}{0pt} +\setlength{\bibitemsep}{0pt plus .3pt} +\setlength{\biblabelsep}{0pt} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} +% \end{macro} % % \begin{macro}{\bibcorporate} % Formatting of corporate (group) authors. Its primary function is in the @@ -6920,7 +8829,7 @@ short form, of the examples. % Setting the catcode of the hash mark `|#|'. This is mainly useful in some % cases in which the bibliography contains urls containing `|#|' symbols. % These are analogous to \cmd{\makeatother} and \cmd{\makeatletter}. -% (They are undocumentedin the main documentation!) +% (They are undocumented in the main documentation!) % \begin{macrocode} \def\makehashother{\catcode`\#=12\relax} \def\makehashmacropar{\catcode`\#=6\relax} @@ -7422,6 +9331,21 @@ short form, of the examples. % \end{macrocode} % \end{macro} % +% \begin{macro}{\doi} +% \begin{macro}{\doiprefix} +% Similarly, define \cmd{\doi}. Adapted from code in \fname{plainnat.bst}. +% \begin{macrocode} +\AtBeginDocument{% + \expandafter\ifx\csname urlstyle\endcsname\relax + \providecommand{\doi}[1]{#1}\else + \providecommand{\doi}{\begingroup \urlstyle{APACsame}\Url}\fi +} +\@ifundefined{doiprefix}{% + \newcommand{\doiprefix}{doi:\penalty0{}}% +}{}% +% \end{macrocode} +% \end{macro} +% % \subsection{Compatibility code} % % Many other packages redefine citation commands and reference list commands, @@ -7451,7 +9375,13 @@ short form, of the examples. % % \subsubsection{\pkg{natbib}} % +% Above, we implemented some code for the \pkgoption{natbibapa} option. +% The code here is intended as a fix for more general cases, but we +% have to make sure not to conflict with the code above. This applies +% to the redefinition of the \cmd{\NAT@parse@date} command. % \begin{macrocode} +\if@APAC@natbib@apa +\else \AtBeginDocument{% \@ifpackageloaded{natbib}{% % \end{macrocode} @@ -7467,12 +9397,17 @@ short form, of the examples. \def\NAT@parse@date#1#2#3#4#5#6@@{% \def\NAT@year{{#1}}\def\NAT@exlab{{#2}}% }% + }{}% +} +\fi % \end{macrocode} % \pkg{natbib} redefines \cmd{\thebibliography}, which interferes a little with % our purposes. Therefore, add some patches. This goes wrong if % \cmd{\bibpreamble} is redefined later on, i.e., by the user, but I haven't % come up with a better hack yet. % \begin{macrocode} +\AtBeginDocument{% + \@ifpackageloaded{natbib}{% \let\@oldbibpreamble\bibpreamble \def\bibpreamble{% \@oldbibpreamble% @@ -7890,25 +9825,42 @@ short form, of the examples. % \end{macrocode} % List of citation commands. % \begin{macrocode} +\if@APAC@classic@cite \def\@mb@citenamelist{% cite,fullcite,shortcite,citeNP,fullciteNP,shortciteNP,% citeA,fullciteA,shortciteA,citeauthor,fullciteauthor,shortciteauthor,% citeauthorNP,fullciteauthorNP,shortciteauthorNP,% - citeyear,citeyearNP,nocite,nocitemeta% -}% + citeyear,citeyearNP,nocite,nocitemeta,% + maskcite,maskfullcite,maskshortcite,maskciteNP,maskfullciteNP,% + maskshortciteNP,maskciteA,maskfullciteA,maskshortciteA,% + maskciteauthor,maskfullciteauthor,maskshortciteauthor,% + maskciteauthorNP,maskfullciteauthorNP,maskshortciteauthorNP,% + maskciteauthorA,maskfullciteauthorA,maskshortciteauthorA,% + maskciteyear,maskciteyearNP,masknocite% +} +\fi % \end{macrocode} -% -% \subsubsection{\pkg{splitbib}} -% -% Presumably, this wouldn't hurt without \pkg{splitbib} as well. +% Only handle the commands \pkg{apacite} defines. The rest is +% \pkg{natbib}'s purview. % \begin{macrocode} -\AtBeginDocument{% - \@ifpackageloaded{splitbib}{% - \def\citeauthoryear{\string\citeauthoryear}% - }{}% +\if@APAC@natbib@apa +\AtEndOfPackage{% +\let\orig@mb@citenamelist\@mb@citenamelist +\edef\@mb@citenamelist{% + \orig@mb@citenamelist,% + citeauthort,citeauthorp,citefullauthort,citefullauthorp,Citeauthort,% + Citeauthorp,Citefullauthort,Citefullauthorp,% + masknocite,maskcitep,maskcitealp,maskcitet,maskcitealt,% + maskciteauthor,maskcitefullauthor,maskciteyearpar,maskciteyear,% + maskcite,maskcitetalias,maskcitepalias,maskCitet,maskCitep,% + maskCitealt,maskCitealp,maskCiteauthor,maskcitenum,maskciteauthort,% + maskciteauthorp,maskCitefullauthor,maskCiteauthort,maskCiteauthorp% } +} +\fi % \end{macrocode} % +% % \subsection{Language-specific macros and loading of language file} % \label{sec:language-code} % @@ -7922,6 +9874,24 @@ short form, of the examples. % % \subsubsection{Literal text strings} % +% \begin{macro}{\onemaskedcitationmsg} +% \begin{macro}{\maskedcitationsmsg} +% Messages that are inserted in the text if citations are masked. +% Put these messages in separate commands so that they're easily +% changed; e.g., for different languages. We use \cmd{\emph} instead +% of \cmd{\textit}, so that this is put upright if it's executed +% within an italic surrounding, and the parentheses are included +% within the \cmd{\emph}, which looks better if this is included in +% another pair of parentheses. But all of this is easily changed. +% \begin{macrocode} +\newcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}} +\newcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}{\refname} % \begin{macro}{\bibname} % \begin{macro}{\authorindexname} @@ -8141,6 +10111,7 @@ short form, of the examples. % % \begin{macro}{\BAvailFrom} % \begin{macro}{\BRetrieved} +% \begin{macro}{\BRetrievedFrom} % \begin{macro}{\BMsgPostedTo} % Strings that indicate where on the internet the referenced document was % obtained. @@ -8148,11 +10119,13 @@ short form, of the examples. \newcommand{\BAvailFrom}{Available from\ }% Websites; note the space. %% The argument is the date on which it was last checked. \newcommand{\BRetrieved}[1]{Retrieved {#1}, from\ }% Websites; note the space. +\newcommand{\BRetrievedFrom}{Retrieved from\ }% Websites; note the space. \newcommand{\BMsgPostedTo}{Message posted to\ }% Messages; note the space. % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} +% \end{macro} % % \subsubsection{Punctuation} % @@ -8223,8 +10196,9 @@ short form, of the examples. % \begin{macro}{\BBYY} % \begin{macro}{\BBC} % \begin{macro}{\BBN} -% \begin{macro}{\BAP} -% \begin{macro}{\BAP} +% \begin{macro}{\BCBT} +% \begin{macro}{\BCBL} +% \begin{macro}{\BDBL} % Punctuation between various parts of citations and reference list entries. % \begin{macrocode} \newcommand{\BAP}{ } % after prefix, before first citation @@ -8235,6 +10209,7 @@ short form, of the examples. \newcommand{\BCBT}{,} % comma between authors in ref. list when no. of %% authors = 2 \newcommand{\BCBL}{,} % comma before last author when no. of authors > 2 +\newcommand{\BDBL}{, \dots{} }% dots before last author when no. of authors > 7 % \end{macrocode} % \end{macro} % \end{macro} @@ -8243,6 +10218,7 @@ short form, of the examples. % \end{macro} % \end{macro} % \end{macro} +% \end{macro} % % \subsubsection{Date formatting} % @@ -8524,56 +10500,85 @@ short form, of the examples. %% %% apacdoc.sty : Style package that is used for the apacite documentation. %% Written by Erik Meijer - -% Generate Author Index? +% \end{macrocode} +% \subsection{Options} +% \begin{macro}{\if@APACdoc@AX} +% Generate author index? +% \begin{macrocode} \newif\if@APACdoc@AX \DeclareOption{makeAX}{\@APACdoc@AXtrue}% \@APACdoc@AXfalse \ProcessOptions - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%% DOCUMENT-SPECIFIC DEFINITIONS THAT MAY BE USEFUL FOR WIDER USE. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - +% \end{macrocode} +% \end{macro} +% +% \subsection{Document-specific definitions that may be useful for wider use} +% \begin{macro}{\bibliteral} +% \begin{macro}{\bibinitial} % Echo argument literally. Can be used to define a certain author type % (``Producer'') in a place where \BibTeX{} expects a first name. % Using this command between a pair of braces makes sure that the text % is not abbreviated into an initial. -%%\DeclareRobustCommand{\bibliteral}[1]{\string\bibliteral{#1}} -%%\newcommand{\bibliteral}[1]{#1} -%%\newcommand{\bibliteral}[1]{\string\bibliteral{#1}} -%% This is the result of lots of trial and error. If I change something -%% in another part, I typically have to change something here as well. -%% The \space is necessary because in the current setup, an additional -%% space is inserted in the bibliography, and MakeIndex is space-sensitive. +% This is the result of lots of trial and error. If I change something +% in another part, I typically have to change something here as well. +% The \verb+\space+ is necessary because in the current setup, an additional +% space is inserted in the bibliography, and \MakeIndex{} is space-sensitive. +% \begin{macrocode} +%% \DeclareRobustCommand{\bibliteral}[1]{\string\bibliteral{#1}} +%% \newcommand{\bibliteral}[1]{#1} +%% \newcommand{\bibliteral}[1]{\string\bibliteral{#1}} \newcommand{\bibliteral}[1]{\string\bibliteral\space{#1}} \DeclareRobustCommand{\bibinitial}[1]{\string#1} -%\newcommand{\bibinitial}{\string\bibinitial\space} - -% If the argument is a period (`.'), \BibTeX{} puts no period after it. +%% \newcommand{\bibinitial}{\string\bibinitial\space} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibnodot} +% If the argument is a period (`|.|'), \BibTeX{} puts no period after it. +% \begin{macrocode} \newcommand{\bibnodot}[1]{} - -% For ``On cdtitle [CD]'' etc., to be used instead of ``In''. -\newcommand{\BOn}{On} - -% Reverse order. Can be used for various reasons. +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SwapArgs} +% Reverse order of the two arguments. Can be used for various reasons, +% mostly related to sorting in the reference list. +% \begin{macrocode} \newcommand{\SwapArgs}[2]{#2#1} - -% The following macro is esp. useful if the year field must be different -% in text and in reference list. E.g., if 1992/1993 in text and 1992 -% in reference list. Then year can be defined as \bibreftext{1992}{1992/1993}. +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\bibreftext} +% \begin{macro}{\Dutchvon} +% The following macro is especially useful if the \fieldname{year} +% field must be different in the text and the reference list, +% e.g., ``1992/1993'' in the text and ``1992'' in reference list. +% Then \fieldname{year} can be defined as |\bibreftext{1992}{1992/1993}|. % The definition below displays only the second argument (``text''). -% Just before the reference list, this can then be changed to +% Just before the reference list, this can then be redefined to % display only the first argument (``ref''). +% \begin{macrocode} \newcommand{\bibreftext}[2]{#2} - -% The same command, but now intended for Dutch-style ``von'' parts. +% \end{macrocode} +% The same command, but now intended for Dutch-style ``von'' parts, +% so in order to create some flexibility in formatting items from +% a \fname{.bib} file, it is useful to have a separate macro for +% this application. +% \begin{macrocode} \newcommand{\Dutchvon}[2]{#2} - -% The following macro changes the definitions of the macros \BED and \BEDS -% to the argument and then immediately changes the definitions back to their -% old definitions. So it makes a one-time change. Can be used to use -% ``Producer'' instead of ``Ed.'' etc. +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibeditortype} +% \begin{macro}{\renewbibeditortype} +% The following macro changes the definitions of the macros \cmd{\BED} +% and \cmd{\BEDS} to the argument of this macro and then immediately +% changes the definitions back to their old definitions. So it makes a +% one-time change. Can be used to use ``Producer'' instead of ``Ed.'' +% etc. +% \begin{macrocode} \DeclareRobustCommand{\bibeditortype}[1]{\relax }% \def\renewbibeditortype{% \def\oldBED{}% @@ -8585,18 +10590,32 @@ short form, of the examples. \global\def\BEDS{##1\global\let\BED\oldBED \global\let\BEDS\oldBEDS}% }% } - -% The following macro changes the definition of the macro \BIn to the +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibInstring} +% \begin{macro}{\BOn} +% The following macro changes the definition of the macro \cmd{\BIn} to the % argument and then immediately changes the definition back to the old % definition. So it makes a one-time change. Can be used to use ``On'' -% instead of ``In'' for a CD-track. +% instead of ``In'' for a CD-track, for which \cmd{\BOn} is supplied. +% \begin{macrocode} \newcommand{\bibInstring}[1]{% \global\let\oldBIn\BIn \global\def\BIn{#1\global\let\BIn\oldBIn}% } - +\newcommand{\BOn}{On} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\BAbstractRetrieved} +% \begin{macro}{\BmakeAbstractRetrieved} % The following macros are used to change ``Retrieved'' into -% ``Abstract retrieved''. They use the same principle as \renewbibeditortype. +% ``Abstract retrieved''. They use the same principle as +% \cmd{\renewbibeditortype}. +% \begin{macrocode} \global\def\BAbstractRetrieved#1{Abstract retrieved {#1}, from\ }% \DeclareRobustCommand{\BmakeAbstractRetrieved}{% \global\def\oldBRetrieved{}% @@ -8606,8 +10625,14 @@ short form, of the examples. \global\let\BRetrieved\oldBRetrieved% }% } - -% Suppress ``ed.'' to format ``Version 4.0'' in an edition field. +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\noedition} +% Suppress ``ed.'' to format ``Version 4.0'' in an \fieldname{edition} +% field. +% \begin{macrocode} \DeclareRobustCommand{\noedition}{% \global\def\oldBEd{}% \global\let\oldBEd\BEd @@ -8616,32 +10641,50 @@ short form, of the examples. \global\let\BEd\oldBEd }% } - -% The \bibskipbracenodot macro suppresses the period after a following closing -% brace. It does not work entirely well at the moment. In particular, it -% works differently in an \AX macro in text and an \AX macro in the -% reference list. This has something to do with robust vs. fragile macros -% and/or expansion of the macro. I have experimented a lot with many -% variations, but don't seem to get it right. I don't understand these -% issues well yet. +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\swallownext} +% \begin{macro}{\swallowdot} +% \begin{macro}{\bibskipbracenodot} +% \begin{macro}{\indexskipbracenodot} +% The \cmd{\bibskipbracenodot} macro suppresses the period after a +% following closing brace. It does not work entirely well at the +% moment. In particular, it works differently in an \cmd{\AX} macro +% in text and an \cmd{\AX} macro in the reference list. This probably +% has something to do with robust vs.\ fragile macros and/or expansion +% of the macro. I have experimented a lot with many variations, but +% don't seem to get it right. I don't understand these issues well yet. +% \cmd{\swallownext} swallows its argument; \cmd{\swallowdot} swallows +% the next character if it's a period. +% \begin{macrocode} \def\swallownext#1{\relax} \def\swallowdot{% \@ifnextchar.% {\swallownext}% {\relax}% } - -% When the above does not work, \bibskipbracenodot should reduce to nothing. -% This is the current definition. Just before the bibliography, it is -% redefined. -%\def\bibskipbracenodot{\string\bibskipbracenodot} +% \end{macrocode} +% When the above does not work, \cmd{\bibskipbracenodot} should reduce +% to nothing. This is the current definition. Just before the +% bibliography, it is redefined. \cmd{\indexskipbracenodot} has the +% same purpose, but for the author index instead of the reference list. +% \begin{macrocode} +%% \def\bibskipbracenodot{\string\bibskipbracenodot} +%% \def\bibskipbracenodot{\aftergroup\swallowdot} +%% \let\bibskipbracenodot\relax \def\bibskipbracenodot{\noexpand\bibskipbracenodot} -%\def\bibskipbracenodot{\aftergroup\swallowdot} -%\let\bibskipbracenodot\relax \def\indexskipbracenodot{\noexpand\indexskipbracenodot} - +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACmanBeforeBib} +% Redefine commands that should be different in the bibliography. +% \begin{macrocode} \newcommand{\APACmanBeforeBib}{% - % Redefine commands that should be different in the bibliography. \renewcommand{\bibreftext}[2]{##1}% \renewcommand{\Dutchvon}[2]{##1}% \renewbibeditortype @@ -8652,9 +10695,14 @@ short form, of the examples. \global\let\oldbibinitial\bibinitial \renewcommand{\bibinitial}[1]{##1}% } - -% Dirty trick: request apacitex.bst if apacite is loaded with one of the -% index options, and request apacite.bst otherwise. +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACbibstyle} +% Dirty trick: request \fname{apacitex.bst} if \pkg{apacite} is loaded +% with one of the index options, and request \fname{apacite.bst} +% otherwise. +% \begin{macrocode} \def\APACbibstyle{% \if@APAC@index apacitex% with index option @@ -8662,54 +10710,72 @@ short form, of the examples. apacite% without index option \fi } - +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACmanBeforeIndex} +% Redefine commands that should be different in the author index. +% \begin{macrocode} \newcommand{\APACmanBeforeIndex}{% \clearpage - % Redefine commands that should be different in the author index. \renewcommand{\bibeditortype}[1]{}% \renewcommand{\bibliteral}[1]{\unskip}% \global\let\indexskipbracenodot\bibskipbracenodot } - +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACmanAfterIndex} +% Revert to the old definitions of commands after the index. +% \begin{macrocode} \newcommand{\APACmanAfterIndex}{% - % Revert to old definitions of commands. \global\let\bibskipbracenodot\oldbibskipbracenodot \global\def\indexskipbracenodot{\noexpand\indexskipbracenodot}% \APACdocindex } - -% Redefine some indexing-related commands from doc.sty and ltxdoc.cls -% Unfortunately, I couldn't get the code index and change history -% working with the index package, so I have to tweak everything so -% that the apacite manual does not use the index package (which is -% loaded by apacite when an index option is requested). - -\@ifundefined{IndexPrologue}{}{% - \IndexPrologue{\clearpage\section*{{Code Index}}% - \addcontentsline{toc}{section}{Code Index}% - \markboth{{Code Index}}{{Code Index}}% - Numbers written in italic refer to the page - where the corresponding entry is described; - numbers underlined refer to the - \ifcodeline@index - code line of the - \fi - definition; numbers in roman refer to the - \ifcodeline@index - code lines - \else - pages - \fi - where the entry is used. - }% -} -\@ifundefined{GlossaryPrologue}{}{% - \GlossaryPrologue{\section{{Change History}}% - \markboth{{Change History}}{{Change History}}% - }% -} - -% From doc.dtx +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\SetupAPACdocPrologues} +% Redefine some indexing-related commands from \fname{doc.sty} and +% \fname{ltxdoc.cls}. Unfortunately, I couldn't get the code index +% and change history working with the \pkg{index} package, so I have +% to tweak everything so that the \pkg{apacite} manual does not use the +% \pkg{index} package (which is loaded by apacite when an +% \pkgoption{index} option is requested). +% \begin{macrocode} +\newcommand{\SetupAPACdocPrologues}{% + \@ifundefined{IndexPrologue}{}{% + \IndexPrologue{% + \clearpage\section*{{Code Index}}% + \addcontentsline{toc}{section}{Code Index}% + \markboth{{Code Index}}{{Code Index}}% + Numbers written in italic refer to the page where the corresponding + entry is described; numbers underlined refer to the + \ifcodeline@index + code line of the + \fi + definition; numbers in roman refer to the + \ifcodeline@index + code lines + \else + pages + \fi + where the entry is used. + }% + }% + \@ifundefined{GlossaryPrologue}{}{% + \GlossaryPrologue{\section{{Change History}}% + \markboth{{Change History}}{{Change History}}% + }% + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACdocindex} +% From \fname{doc.dtx}. +% \begin{macrocode} \def\APACdocindex{% \ifhave@multicol \renewenvironment{theindex} @@ -8726,105 +10792,132 @@ short form, of the examples. \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi} \fi } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%% CITATIONS TO THE BIBLE -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% The APA manual gives some rules how the Bible and other classic -% works should be cited. These rules are not implemented in standard -% apacite, so I provide a workaround here. - -%%% To define which Bible version you used. +% \end{macrocode} +% \end{macro} +% +% \subsection{Citations to the Bible} +% The \emph{APA manual} gives some rules how the Bible and other +% classic works should be cited. These rules are not implemented +% in standard \pkg{apacite}, so I provide a workaround here. This +% needs to be fixed and generalized because the \emph{APA manual} +% now also gives a Qur'an example. +% +% \begin{macro}{\bibleversion} +% \begin{macro}{\@bibleversion} +% To define which Bible version one has used. +% \begin{macrocode} \def\bibleversion#1{\gdef\@bibleversion{#1}} \def\@bibleversion{Revised Standard Version} - +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibleciteA} +% \begin{macro}{\fullbibleciteA} +% \begin{macro}{\shortbibleciteA} +% \begin{macro}{\biblecite} +% \begin{macro}{\fullbiblecite} +% \begin{macro}{\shortbiblecite} +% \begin{macro}{\bibleciteNP} +% \begin{macro}{\fullbibleciteNP} +% \begin{macro}{\shortbibleciteNP} +% The Bible citation commands follow the same names and syntax as the +% ordinary citation commands, except that ``|bible|'' is inserted in +% the command names. +% \begin{macrocode} \def\bibleciteA#1{% - % If this is the first citation, add bible version. {\@ifundefined{flag@bible}% {\fullbibleciteA{#1}}% {\shortbibleciteA{#1}}% }% } - \def\fullbibleciteA#1{% - % Insert relevant chapter and verse. +% \end{macrocode} +% Insert chapter and verse. +% \begin{macrocode} {#1}% +% \end{macrocode} +% Add Bible version. +% \begin{macrocode} { \BBOP\@bibleversion\BBCP}% - % Flag that bible has been cited. +% \end{macrocode} +% Flag that the Bible has been cited. +% \begin{macrocode} {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - \def\shortbibleciteA#1{% - % Insert relevant chapter and verse. {#1}% - % Flag that bible has been cited (is this appropriate?). +% \end{macrocode} +% Is this appropriate to flag that Bible has been cited, given that +% we don't give the version here? +% \begin{macrocode} {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - \def\biblecite#1{% - % If this is the first citation, add bible version. {\@ifundefined{flag@bible}% {\fullbiblecite{#1}}% {\shortbiblecite{#1}}% }% } - \def\fullbiblecite#1{% - % Open parenthesis. {\BBOP}% - % Insert relevant chapter and verse. {#1}% - % Add bible version. {\BBAY{} \@bibleversion}% - % Close parenthesis. {\BBCP}% - % Flag that bible has been cited. {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - \def\shortbiblecite#1{% - % Open parenthesis. {\BBOP}% - % Insert relevant chapter and verse. {#1}% - % Close parenthesis. {\BBCP}% - % Flag that bible has been cited (is this appropriate?). {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - \def\bibleciteNP#1{% - % If this is the first citation, add bible version. {\@ifundefined{flag@bible}% {\fullbibleciteNP{#1}}% {\shortbibleciteNP{#1}}% }% } - \def\fullbibleciteNP#1{% - % Insert relevant chapter and verse. {#1}% - % Add bible version. {\BBAY{} \@bibleversion}% - % Flag that bible has been cited. {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - \def\shortbibleciteNP#1{% - % Insert relevant chapter and verse. {#1}% - % Flag that bible has been cited (is this appropriate?). {\global\expandafter\def\csname flag@bible\endcsname{DUMMY}}% } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%% COMMANDS TO CITE SONGS. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% The APA manual gives some rules how songs should be cited. These -% rules require some tweaking of standard apacite. This is done here. - +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Citing songs} +% The \emph{APA manual} gives some rules how songs should be cited. +% These rules require some tweaking of standard \pkg{apacite}. This is +% done here. +% +% \begin{macro}{\bibsong} +% \begin{macro}{\citeAsong} +% \begin{macro}{\fullciteAsong} +% \begin{macro}{\shortciteAsong} +% \begin{macro}{\citesong} +% \begin{macro}{\fullcitesong} +% \begin{macro}{\shortcitesong} +% \begin{macro}{\citesongNP} +% \begin{macro}{\fullcitesongNP} +% \begin{macro}{\shortcitesongNP} +% The names of these macros are a bit internally inconsistent and +% inconsistent with the \cmd{\biblecite} and \cmd{DSMcite} suites. +% Fix this in a next version. +% \begin{macrocode} \newcommand{\bibsong}[4]{} - \newcommand{\citeAsong}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3} {\BBOP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% @@ -8832,7 +10925,6 @@ short form, of the examples. \citeauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\fullciteAsong}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3} {\BBOP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% @@ -8840,7 +10932,6 @@ short form, of the examples. \fullciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\shortciteAsong}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3} {\BBOP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% @@ -8848,31 +10939,30 @@ short form, of the examples. \shortciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\citesong}[1]{% \def\bibsong##1##2##3##4{% - {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% + {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% + {\BBCP}% }% \citeauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\fullcitesong}[1]{% \def\bibsong##1##2##3##4{% - {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% + {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% + {\BBCP}% }% \fullciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\shortcitesong}[1]{% \def\bibsong##1##2##3##4{% - {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}{\BBCP}% + {\BBOP}\APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% + {\BBCP}% }% \shortciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\citesongNP}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% @@ -8880,7 +10970,6 @@ short form, of the examples. \citeauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\fullcitesongNP}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% @@ -8888,7 +10977,6 @@ short form, of the examples. \fullciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - \newcommand{\shortcitesongNP}[1]{% \def\bibsong##1##2##3##4{% \APACciteatitle{##3},{\BAP}{##1}{\BBAY}{##2}{\BBN}{##4}% @@ -8896,58 +10984,92 @@ short form, of the examples. \shortciteauthor{#1}% \def\bibsong##1##2##3##4{}% } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%% COMMANDS TO CITE DSM. -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% The APA manual gives some rules how the DSM should be cited, which -% is a bit different from ordinary citations. These rules are not -% implemented in standard apacite, so I provide a workaround here. - +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Commands to cite the \emph{DSM}} +% The \emph{APA manual} gives some rules how the \emph{DSM} should be +% cited, which is a bit different from ordinary citations. These rules +% are not implemented in standard \pkg{apacite}, so I provide a +% workaround here. +% +% \begin{macro}{\bibDSM} +% \begin{macro}{\origbibDSM} +% \begin{macro}{\DSMauthor} +% \begin{macro}{\DSMfulltitle} +% \begin{macro}{\DSMshorttitle} +% \begin{macro}{\DSMedition} +% The \cmd{\bibDSM} macro has four arguments: (1) author, (2) full +% title, (3) edition, (4) abbreviated title. The default definition +% prints the author, so this gives something decent if an ordinary +% citation command is used. The other macros extract the separate +% arguments. +% \begin{macrocode} \DeclareRobustCommand{\bibDSM}[4]{#1} -% author, title, edition, abbreviated title -% Default prints author, so you get something decent if -% an ordinary cite is used. -\def\origbibDSM{} +\newcommand\origbibDSM{} \let\origbibDSM\bibDSM - \newcommand{\DSMauthor}[1]{% \def\bibDSM##1##2##3##4{##1}% \citeauthor{#1}% \let\bibDSM\origbibDSM } - \newcommand{\DSMfulltitle}[1]{% \def\bibDSM##1##2##3##4{##2}% \citeauthor{#1}% \let\bibDSM\origbibDSM } - \newcommand{\DSMshorttitle}[1]{% \def\bibDSM##1##2##3##4{##4}% \citeauthor{#1}% \let\bibDSM\origbibDSM } - \newcommand{\DSMedition}[1]{% \def\bibDSM##1##2##3##4{##3}% \citeauthor{#1}% \let\bibDSM\origbibDSM } - +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\DSMciteA} +% \begin{macro}{\DSMfullciteA} +% \begin{macro}{\DSMshortciteA} +% \begin{macro}{\DSMcite} +% \begin{macro}{\DSMfullcite} +% \begin{macro}{\DSMshortcite} +% \begin{macro}{\DSMciteNP} +% \begin{macro}{\DSMfullciteNP} +% \begin{macro}{\DSMshortciteNP} +% The \emph{DSM} citation commands follow the same names and syntax as the +% ordinary citation commands, except that ``|DSM|'' is inserted in +% the command names. +% \begin{macrocode} \newcommand{\DSMciteA}[1]{% \@for\@citeb:=#1\do{% - % Removes a possible space before the citation key \edef\@citeb{\expandafter\@firstofone\@citeb}% - % Is this the first citation? \@ifundefined{flag@\@citeb\APAC@extra@b@citeb}% {\DSMfullciteA{#1}}% {\DSMshortciteA{#1}}% }% } - \newcommand{\DSMfullciteA}[1]{% - % \emph{Full Title} (edition; \emph{Short Title}; author, year) +% \end{macrocode} +% \emph{Full Title} (edition; \emph{Short Title}; author, year) +% \begin{macrocode} \APACcitebtitle{\DSMfulltitle{#1}} \BBOP \DSMedition{#1}; @@ -8955,25 +11077,21 @@ short form, of the examples. \citeNP{#1}% \BBCP } - \newcommand{\DSMshortciteA}[1]{% - % \emph{Short Title} +% \end{macrocode} +% \emph{Short Title} +% \begin{macrocode} \APACcitebtitle{\DSMshorttitle{#1}}% } - \newcommand{\DSMcite}[1]{% \@for\@citeb:=#1\do{% - % Removes a possible space before the citation key \edef\@citeb{\expandafter\@firstofone\@citeb}% - % Is this the first citation? \@ifundefined{flag@\@citeb\APAC@extra@b@citeb}% {\DSMfullcite{#1}}% {\DSMshortcite{#1}}% }% } - \newcommand{\DSMfullcite}[1]{% - % (\emph{Full Title}, edition; \emph{Short Title}; author, year) \BBOP \APACcitebtitle{\DSMfulltitle{#1}}, \DSMedition{#1}; @@ -8981,170 +11099,274 @@ short form, of the examples. \citeNP{#1}% \BBCP } - \newcommand{\DSMshortcite}[1]{% - % (\emph{Short Title}) \BBOP\APACcitebtitle{\DSMshorttitle{#1}}\BBCP } - \newcommand{\DSMciteNP}[1]{% \@for\@citeb:=#1\do{% - % Removes a possible space before the citation key \edef\@citeb{\expandafter\@firstofone\@citeb}% - % Is this the first citation? \@ifundefined{flag@\@citeb\APAC@extra@b@citeb}% {\DSMfullciteNP{#1}}% {\DSMshortciteNP{#1}}% }% } - \newcommand{\DSMfullciteNP}[1]{% - % (\emph{Full Title}, edition; \emph{Short Title}; author, year) \APACcitebtitle{\DSMfulltitle{#1}}, \DSMedition{#1}; \APACcitebtitle{\DSMshorttitle{#1}}; \citeNP{#1}% } - \newcommand{\DSMshortciteNP}[1]{% - % (\emph{Short Title}) \APACcitebtitle{\DSMshorttitle{#1}}% } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%%% DOCUMENT-SPECIFIC DEFINITIONS -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% These are some commands that are used in this document, but are -% presumably not especially relevant for users. - -\@ifundefined{BibTeX}{% - \def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em - T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}% copied from bibtex.web -}{} -\newcommand{\MakeIndex}{\textit{MakeIndex}} -\newcommand{\latextohtml}{\textup{\LaTeX2\texttt{HTML}}}% from html.sty -\newcommand{\LaTeXrtf}{\textup{\LaTeX2RTF}}% -\newcommand{\TeXht}{\textup{\TeX4ht}}% -\newcommand{\Perl}{\textsl{Perl}}% - -% My comments accompanying the examples. -\newcommand{\EM}{\ensuremath{\triangleright\quad}} - -% The date of a version of apacite. Makes it easy to search the document -% for these dates. The \relax is a safety measure (probably not needed), -% which ensures that the square brackets are never interpreted as an -% optional argument. -\newcommand{\APACversiondate}[1]{\relax [#1]} - -\newcommand{\LC}{\mbox{${}^{\dag}$}}% \LaTeX{} Companion -\newcommand{\X}{\ensuremath{\times}}% for one table -\newcommand{\Y}{\ensuremath{c}}% for one table -\newcommand{\A}{\ensuremath{a}}% for one table - -\newcommand{\pkg}[1]{\textsf{#1}}% package name -\newcommand{\fname}[1]{\texttt{#1}}% file name -\newcommand{\fieldname}[1]{\texttt{#1}}% field name -\newcommand{\entryname}[1]{\texttt{#1}}% entry type name -\newcommand{\pkgoption}[1]{\texttt{#1}}% package option -\newcommand{\envirname}[1]{\texttt{#1}}% environment name - -\AtBeginDocument{% - \@ifundefined{cmd}{% - \newcommand{\cmd}[1]{\texttt{\string#1}}% command, incl. `\' - }{}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Document-specific definitions} +% +% \begin{macro}{\SetupAPACdoc} +% These are some commands that are used in the \pkg{apacite} manual, +% but are presumably not especially relevant for users. +% +% \begin{macro}{\MiKTeX} +% \begin{macro}{\BibTeX} +% \begin{macro}{\MakeIndex} +% \begin{macro}{\latextohtml} +% \begin{macro}{\LaTeXrtf} +% \begin{macro}{\TeXht} +% \begin{macro}{\Perl} +% Names of programs and packages. +% \begin{macrocode} +\newcommand{\SetupAPACdoc}{% + \newcommand{\MiKTeX}{MiK\TeX} + \@ifundefined{BibTeX}{% + \def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}% from bibtex.web + }{} + \newcommand{\MakeIndex}{\textit{MakeIndex}} + \newcommand{\latextohtml}{\textup{\LaTeX2\texttt{HTML}}}% from html.sty + \newcommand{\LaTeXrtf}{\textup{\LaTeX2RTF}}% + \newcommand{\TeXht}{\textup{\TeX4ht}}% + \newcommand{\Perl}{\textsl{Perl}}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\EM} +% My comments accompanying the examples. To be removed with better +% source code documentation. +% \begin{macrocode} + \newcommand{\EM}{\ensuremath{\triangleright\quad}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACversiondate} +% The date of a version of \pkg{apacite}. Makes it easy to search the +% document for these dates. The \cmd{\relax} is a safety measure +% (probably not needed), which ensures that the square brackets are +% never interpreted as an optional argument. +% \begin{macrocode} + \newcommand{\APACversiondate}[1]{\relax [##1]} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\LC} +% \begin{macro}{\X} +% \begin{macro}{\Y} +% \begin{macro}{\A} +% Some symbols that are used in the \pkg{apacite} manual. +% \begin{macrocode} + \newcommand{\LC}{\mbox{${}^{\dag}$}}% \LaTeX{} Companion + \newcommand{\X}{\ensuremath{\times}}% for one table + \newcommand{\Y}{\ensuremath{c}}% for one table + \newcommand{\A}{\ensuremath{a}}% for one table +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\pkg} +% \begin{macro}{\fname} +% \begin{macro}{\fieldname} +% \begin{macro}{\entryname} +% \begin{macro}{\pkgoption} +% \begin{macro}{\envirname} +% Formatting of package names, options, etc. +% \begin{macrocode} + \newcommand{\pkg}[1]{\textsf{##1}}% package name + \newcommand{\fname}[1]{\texttt{##1}}% file name + \newcommand{\fieldname}[1]{\texttt{##1}}% field name + \newcommand{\entryname}[1]{\texttt{##1}}% entry type name + \newcommand{\pkgoption}[1]{\texttt{##1}}% package option + \newcommand{\envirname}[1]{\texttt{##1}}% environment name +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cmd} +% \begin{macro}{\bs} +% \begin{macro}{\opt} +% \begin{macro}{\cmdtwo} +% \begin{macro}{\cmdthree} +% \begin{macro}{\cmdthreepre} +% \begin{macro}{\cmdthreealt} +% \begin{macro}{\cmdfour} +% Formatting of macros. +% \begin{macrocode} + \AtBeginDocument{% + \@ifundefined{cmd}{% + \newcommand{\cmd}[1]{\texttt{\string##1}}% command, incl. `\' + }{}% + } +% \end{macrocode} +% Some trickery with backslashes and |@| signs. +% \begin{macrocode} + \newcommand{\bs}{{\ttfamily \@backslashchar}}% backslash + \newcommand{\opt}[1]{$\langle${\itshape ##1}$\rangle$}% generic text +% \end{macrocode} +% For \cmdtwo{nocite}{keys}: +% \begin{macrocode} + \newcommand{\cmdtwo}[2]{{\mdseries\bs\texttt{##1\{}\opt{##2}% + \texttt{\}}}}% +% \end{macrocode} +% For \cmdthree{cite}{post}{keys}: +% \begin{macrocode} + \newcommand{\cmdthree}[3]{{\mdseries\bs\texttt{##1[}\opt{##2}% + \texttt{]\{}\opt{##3}% + \texttt{\}}}}% +% \end{macrocode} +% For \cmdthreepre{cite}{pre}{keys}: +% \begin{macrocode} + \newcommand{\cmdthreepre}[3]{{\mdseries\bs\texttt{##1<}\opt{##2}% + \texttt{>\{}\opt{##3}% + \texttt{\}}}}% +% \end{macrocode} +% For \cmdthreealt{usepackage}{options}{apacite}: +% \begin{macrocode} + \newcommand{\cmdthreealt}[3]{{\mdseries\bs\texttt{##1[}\opt{##2}% + \texttt{]\{##3\}}}}% +% \end{macrocode} +% For all \cmdfour{cite}{pre}{post}{keys} variants: +% \begin{macrocode} + \newcommand{\cmdfour}[4]{{\mdseries\bs\texttt{##1<}\opt{##2}% + \texttt{>[}\opt{##3}% + \texttt{]\{}\opt{##4}% + \texttt{\}}}}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\flqq} +% \begin{macro}{\frqq} +% \begin{macro}{\simpleguillemots} +% It is not clear where and how the \cmd{\flqq} command is defined, so +% provide an escape if it is not available. Use definitions from +% \fname{fguill.sty} included here to avoid requiring a package that +% may not be available. This can probably be improved by using +% \cmd{\providecommand}. +% \begin{macrocode} + \AtBeginDocument{% + \@ifundefined{flqq}{% + \newcommand{\flqq}{% + {\fontencoding{T1}\fontfamily{cmr}\selectfont\symbol{19}}}% + \newcommand{\frqq}{% + {\fontencoding{T1}\fontfamily{cmr}\selectfont\symbol{20}}}% + }{}% + }% + \newcommand{\simpleguillemots}{% + \renewcommand{\flqq}{\raisebox{2.5pt}{% + \tiny{\ensuremath{\mathord{<\!\!<}}}}}% + \renewcommand{\frqq}{\raisebox{2.5pt}{% + \tiny{\ensuremath{\mathord{>\!\!>}}}}}% + }% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\APACdocPageLayout} +% The basic page setup of the \pkg{apacite} manual. +% \begin{macrocode} + \newcommand{\APACdocPageLayout}{% + \normalsize + \let\oldhoffset\hoffset + \let\oldvoffset\voffset + \let\oldoddsidemargin\oddsidemargin + \let\oldevensidemargin\evensidemargin + \let\oldtopmargin\topmargin + \let\oldheadheight\headheight + \let\oldheadsep\headsep + \let\oldtextheight\textheight + \let\oldfootskip\footskip + \let\oldtextwidth\textwidth + \let\oldlinewidth\linewidth + \let\oldmarginparsep\marginparsep + \let\oldmarginparwidth\marginparwidth + \let\oldmarginparpush\marginparpush + %% + %% \setlength{\hoffset}{-1in} % top-left reference point is + \setlength{\voffset}{-1in} % the top-left corner of the page + %% \setlength{\oddsidemargin}{1.3in} + %% \setlength{\evensidemargin}{1.3in} + \setlength{\topmargin}{1.35in} + %% %% \setlength{\headheight}{\baselineskip} + \setlength{\headheight}{0.12in} + \setlength{\headsep}{0.24in} + \setlength{\textheight}{7.9in} + \setlength{\footskip}{30pt} + %% \setlength{\textwidth}{5.9in} + %% \setlength{\linewidth}{\textwidth} + %% \setlength{\marginparsep}{0pt} + %% \setlength{\marginparwidth}{0pt} + %% \setlength{\marginparpush}{0pt} + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\APACcodePageLayout} +% The page setup of the source code documentation part of the +% \pkg{apacite} manual. +% \begin{macrocode} + \newcommand{\APACcodePageLayout}{% + \let\hoffset\oldhoffset + \let\oddsidemargin\oldoddsidemargin + \let\evensidemargin\oldevensidemargin + \let\textwidth\oldtextwidth + \let\linewidth\oldlinewidth + \let\marginparsep\oldmarginparsep + \let\marginparwidth\oldmarginparwidth + \let\marginparpush\oldmarginparpush + } } - -% Some trickery with backslashes and @ signs. -\newcommand{\bs}{{\ttfamily \@backslashchar}}% backslash -\newcommand{\opt}[1]{$\langle${\itshape #1}$\rangle$}% generic text - -% For \nocite{keys}: -\newcommand{\cmdtwo}[2]{{\mdseries\bs\texttt{#1\{}\opt{#2}% - \texttt{\}}}}% -% For \cite[post]{keys}: -\newcommand{\cmdthree}[3]{{\mdseries\bs\texttt{#1[}\opt{#2}% - \texttt{]\{}\opt{#3}% - \texttt{\}}}}% -% For \cite<pre>{keys}: -\newcommand{\cmdthreepre}[3]{{\mdseries\bs\texttt{#1<}\opt{#2}% - \texttt{>\{}\opt{#3}% - \texttt{\}}}}% -% For \usepackage[options]{apacite}: -\newcommand{\cmdthreealt}[3]{{\mdseries\bs\texttt{#1[}\opt{#2}% - \texttt{]\{#3\}}}}% -% For all \cite<pre>[post]{keys} variants: -\newcommand{\cmdfour}[4]{{\mdseries\bs\texttt{#1<}\opt{#2}% - \texttt{>[}\opt{#3}% - \texttt{]\{}\opt{#4}% - \texttt{\}}}}% - -% It is not clear where and how the \flqq command is defined, so provide -% an escape if it is not available. Use definitions from fguill.sty, -% included here to avoid requiring a package that may not be available. -\AtBeginDocument{% - \@ifundefined{flqq}{% - \newcommand{\flqq}{% - {\fontencoding{T1}\fontfamily{cmr}\selectfont\symbol{19}}}% - \newcommand{\frqq}{% - {\fontencoding{T1}\fontfamily{cmr}\selectfont\symbol{20}}}% - }{}% -}% -\newcommand{\simpleguillemots}{% - \renewcommand{\flqq}{\raisebox{2.5pt}{\tiny{\ensuremath{\mathord{<\!\!<}}}}}% - \renewcommand{\frqq}{\raisebox{2.5pt}{\tiny{\ensuremath{\mathord{>\!\!>}}}}}% -}% - - -\newcommand{\APACdocPageLayout}{% - \normalsize - \let\oldhoffset\hoffset - \let\oldvoffset\voffset - \let\oldoddsidemargin\oddsidemargin - \let\oldevensidemargin\evensidemargin - \let\oldtopmargin\topmargin - \let\oldheadheight\headheight - \let\oldheadsep\headsep - \let\oldtextheight\textheight - \let\oldfootskip\footskip - \let\oldtextwidth\textwidth - \let\oldlinewidth\linewidth - \let\oldmarginparsep\marginparsep - \let\oldmarginparwidth\marginparwidth - \let\oldmarginparpush\marginparpush -% - \setlength{\hoffset}{-1in} % top-left reference point is - \setlength{\voffset}{-1in} % the top-left corner of the page - \setlength{\oddsidemargin}{1.3in} - \setlength{\evensidemargin}{1.3in} - \setlength{\topmargin}{1.35in} - %\setlength{\headheight}{\baselineskip} - \setlength{\headheight}{0.12in} - \setlength{\headsep}{0.24in} - \setlength{\textheight}{7.9in} - \setlength{\footskip}{30pt} - \setlength{\textwidth}{5.9in} - \setlength{\linewidth}{\textwidth} - \setlength{\marginparsep}{0pt} - \setlength{\marginparwidth}{0pt} - \setlength{\marginparpush}{0pt} -} - -\newcommand{\APACcodePageLayout}{% - \let\hoffset\oldhoffset - \let\oddsidemargin\oldoddsidemargin - \let\evensidemargin\oldevensidemargin - \let\textwidth\oldtextwidth - \let\linewidth\oldlinewidth - \let\marginparsep\oldmarginparsep - \let\marginparwidth\oldmarginparwidth - \let\marginparpush\oldmarginparpush -} - -% Start with doc page layout -\APACdocPageLayout %% %</docpkg> % \end{macrocode} +% \end{macro} +% \end{macro} % % % \section{Language definition files} @@ -9164,7 +11386,18 @@ short form, of the examples. %% english.apc - english version of apacite elements %% Written by Erik Meijer %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% \renewcommand{\refname}{References}% Name of ref. list if it's a section. \renewcommand{\bibname}{References}% Name of ref. list if it's a chapter. \renewcommand{\authorindexname}{Author Index}% Name of Author Index @@ -9224,6 +11457,7 @@ short form, of the examples. \renewcommand{\BAvailFrom}{Available from\ }% Websites; note the space. %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Retrieved {#1}, from\ }% Websites; note the space. +\renewcommand{\BRetrievedFrom}{Retrieved from\ }% Websites; note the space. \renewcommand{\BMsgPostedTo}{Message posted to\ }% Messages; note the space. %% %% Punctuation @@ -9372,15 +11606,16 @@ short form, of the examples. \fi {\BBCP}% closing parenthesis }% -\else - \immediate\typeout{NOT AUSTRALIAN!!!}% for checking that it works \fi % \end{macrocode} % Clear up some macros that are no longer needed. % \begin{macrocode} \let\APAC@tempa\@undefined \let\APAC@tempb\@undefined -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</english> % \end{macrocode} % @@ -9423,6 +11658,13 @@ short form, of the examples. %% NTPG = Nederlands Tijdschrift voor de Psychologie en haar Grensgebieden %% SW = Schrijfwijzer %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter %% % \end{macrocode} @@ -9447,6 +11689,10 @@ short form, of the examples. % \end{itemize} % % \begin{macrocode} +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE \renewcommand{\refname}{Literatuur}% Name of ref. list if it's a section. \renewcommand{\bibname}{Literatuur}% Name of ref. list if it's a chapter. \renewcommand{\authorindexname}{Auteursindex}% Name of author index @@ -9566,11 +11812,13 @@ short form, of the examples. \renewcommand{\BOWP}{Oorspronkelijke editie}% Original work published \renewcommand{\BREPR}{Overgenomen uit}% Reprinted from %% +%% THE NEXT FOUR ARE MY OWN TRANSLATIONS. CHECK!!! %% Websites and newsgroups; note the spaces. -\newcommand{\BAvailFrom}{Available from\ }% ??? CHECK!!! +\renewcommand{\BAvailFrom}{Verkrijgbaar van\ }% %% The argument is the date on which it was last checked. -\newcommand{\BRetrieved}[1]{Retrieved {#1}, from\ }% ??? CHECK!!! -\newcommand{\BMsgPostedTo}{Message posted to\ }% ??? CHECK!!! +\renewcommand{\BRetrieved}[1]{Op {#1} verkregen van\ }% +\renewcommand{\BRetrievedFrom}{Verkregen van\ }% +\renewcommand{\BMsgPostedTo}{Bericht geplaatst op\ }% %% %% Punctuation \renewcommand{\BBOP}{(}% opening parenthesis @@ -9591,7 +11839,7 @@ short form, of the examples. %% No commas according to DP and SW. NTPG uses the US/APA comma. \renewcommand{\BCBT}{}% comma between authors in ref. list when no. of %% authors = 2 -\newcommand{\BCBL}{}% comma before last author when no. of authors > 2 +\renewcommand{\BCBL}{}% comma before last author when no. of authors > 2 %% %% Date formatting \renewcommand{\APACmonth}[1]{\ifcase #1\or januari\or februari\or maart\or @@ -9654,7 +11902,10 @@ short form, of the examples. \ifcase#1e\else e\fi \fi }% -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</dutch> % \end{macrocode} % @@ -9669,9 +11920,20 @@ short form, of the examples. %<*finnish> %% %% finnish.apc - finnish version of apacite elements -%% Written by Kari Pyykk\"o +%% Written by Kari Pyykk\"o, with some minor edits by Erik Meijer. %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE \renewcommand{\refname}{Viitteet}% Name of ref. list if it's a section. \renewcommand{\bibname}{Viitteet}% Name of ref. list if it's a chapter. \renewcommand{\authorindexname}{Tekij\"ahakemisto}% Name of Author Index @@ -9805,6 +12067,7 @@ short form, of the examples. %% (websites) Retrieved ... from; note the space. %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Lainattu {#1}, saatavilla\ }% +\renewcommand{\BRetrievedFrom}{Lainattu saatavilla\ }% %% %% (newsgroups \& forums) Message posted to; note the space. \renewcommand{\BMsgPostedTo}{Viesti l\"ahetetty\ }% @@ -9897,8 +12160,10 @@ short form, of the examples. \ifcase#1.\else .\fi \fi }% -% -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</finnish> % \end{macrocode} % @@ -9915,7 +12180,18 @@ short form, of the examples. %% french.apc - french version of apacite elements %% Adapted from english.apc by \'Eric Raufaste %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE %% \renewcommand{\refname}{R\'ef\'erences}% Name of ref. list if it's a section. \renewcommand{\bibname}{R\'ef\'erences}% Name of ref. list if it's a chapter. @@ -9978,6 +12254,7 @@ short form, of the examples. %% Websites; note the space. %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Consult\'e le {#1}, sur\ }% +\renewcommand{\BRetrievedFrom}{Consult\'e sur\ }% \renewcommand{\BMsgPostedTo}{Message post\'e sur\ }% Messages; note the space. %% %% Punctuation @@ -10128,7 +12405,10 @@ short form, of the examples. \fi }% \let\APACaddressInstitutionEqAuth\APACaddressPublisherEqAuth -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</french> % \end{macrocode} % @@ -10151,7 +12431,18 @@ short form, of the examples. %% Written by Andreas Poege %% Some additions and adaptations by Erik Meijer. %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE %% Bezeichnung fuer das Literaturverzeichnis, falls Section \renewcommand{\refname}{Literatur}% %% Bezeichnung fuer das Literaturverzeichnis, falls Chapter @@ -10221,6 +12512,7 @@ short form, of the examples. \renewcommand{\BAvailFrom}{Verf\"ugbar unter\ }% %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Zugriff am {#1} auf\ }% +\renewcommand{\BRetrievedFrom}{Zugriff auf\ }% %% Note that here the English phrase is left untranslated in German. \renewcommand{\BMsgPostedTo}{Message posted to\ }% %% @@ -10234,7 +12526,7 @@ short form, of the examples. \renewcommand{\BAnd}{\&}%% Zwischen Hg. und Uebers., falls gleich (default "\&") \DeclareRobustCommand{\BPBI}{.~}% Period between initials \DeclareRobustCommand{\BHBI}{.-}% Hyphen between initials -\renewcommand{\BAP}{}% % Zeichen zw. Prefix und Zitat (default Leerzeichen) +\renewcommand{\BAP}{ }% % Zeichen zw. Prefix und Zitat (default Leerzeichen) \renewcommand{\BBAY}{, }% Zwischen Autoren und Jahr(en) (default ", ") \renewcommand{\BBYY}{, }% Zwischen Jahren, wenn ein Author und mehrere Jahre \renewcommand{\BBC}{; }% Zwischen Autoren (mehrere Zitate) (default "; ") @@ -10367,7 +12659,10 @@ short form, of the examples. Winter\or Fr\"uhjahr\or Sommer\or Herbst\else {#1}\fi}% \fi \let\APACaustrian\undefined -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</german> % \end{macrocode} % @@ -10417,7 +12712,18 @@ short form, of the examples. %% greek.apc - Greek version of apacite elements %% Greek translations by Athanassios Protopapas and Ioannis Dimakos %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE %% Name of ref. list if it's a section. \renewcommand{\refname}{\textgreek{Bibliograf'ia}}% %% Name of ref. list if it's a chapter. @@ -10504,6 +12810,8 @@ short form, of the examples. %% Correct only when ``date'' is full, not just month or year \renewcommand{\BRetrieved}[1]{% \textgreek{Anakt'hjhke stis} {#1}, \textgreek{ap'o}\ }% +\renewcommand{\BRetrievedFrom}{% + \textgreek{Anakt'hjhke stis} \textgreek{ap'o}\ }% % \end{macrocode} % If a URL follows without any leading words/phrase then this string % should be OK. If there is any other word before the URL then we @@ -10595,7 +12903,10 @@ short form, of the examples. \ifcase#1\textgreek{h}\or \textgreek{h}\else \textgreek{h}\fi \fi }% -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</greek> % \end{macrocode} % @@ -10619,7 +12930,18 @@ short form, of the examples. %% Version 1.1. %% Written by Karl Ove Hufthammer. %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE \renewcommand{\refname}{Referanser}% Name of ref. list if it's a section. \renewcommand{\bibname}{Referanser}% Name of ref. list if it's a chapter. %% The name (heading) of the Author Index @@ -10680,6 +13002,7 @@ short form, of the examples. \renewcommand{\BAvailFrom}{Tilgjengelig fra\ }% Websites; note the space. %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Hentet {#1} fra\ }% Websites; note the space. +\renewcommand{\BRetrievedFrom}{Hentet fra\ }% Websites; note the space. \renewcommand{\BMsgPostedTo}{Innlegg p\aa \ }% Messages; note the space. % \end{macrocode} % To be in line with Norwegian rules of punctuation, a comma is never @@ -10798,7 +13121,10 @@ short form, of the examples. {#1}\fi}% \fi \let\APACnynorsk\undefined -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</norsk> % \end{macrocode} % @@ -10820,6 +13146,13 @@ short form, of the examples. %% spanish.apc - Versi\'on espa\~nola de elementos en apacite %% Escrito por Jorge L\'opez Puga %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter %% El nombre (del encabezado) de la Lista Referencias %% Nombre de la lista de ref. si es una secci\'on. @@ -10892,6 +13225,7 @@ short form, of the examples. \renewcommand{\BAvailFrom}{Disponible en\ }% Available from %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{Descargado {#1}, de\ }% Retrieved ... from +\renewcommand{\BRetrievedFrom}{Descargado de\ }% Retrieved from \renewcommand{\BMsgPostedTo}{Mensaje colgado en\ }% Message posted to %% %% Punctuation @@ -10978,7 +13312,72 @@ short form, of the examples. \ifcase#1\sptext{a}\else \sptext{a}\fi \fi }% -%% +% \end{macrocode} +% Some code for using `e' instead of `y' in Spanish if the following +% name starts with `I'. +% \begin{macrocode} +\def\usespanishe#1{% + \@bsphack + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% + \@ifundefined{spanishe@\@citeb\APAC@extra@b@citeb}% + {\global\expandafter + \def\csname spanishe@\@citeb\APAC@extra@b@citeb\endcsname{DUMMY}% + }% + {}% + }% + \@esphack +} +\def\APACinsertmetastar#1{% + \@for\@citeb:=#1\do{% + \edef\@citeb{\expandafter\@firstofone\@citeb}% + \@ifundefined{flagmeta@\@citeb\APAC@extra@b@citeb}% + {}% skip + {{\APACmetastar}}% + \@ifundefined{spanishe@\@citeb\APAC@extra@b@citeb}% + {}% skip + {{% Use `e' instead of `y' in Spanish + \global\let\oldBBA\BBA + \global\def\BBA{e\global\let\BBA\oldBBA}% + }}% + }% +}% +\def\@ifauthorsunequalc@de#1{% + \if@F@cite + \@F@citefalse + \else + \if@Y@cite + {\@BAY}% + \fi + {\@BBC}% + \fi + \edef\@cite@undefined{?}% + \def\BBA{\@BBA}% + \@ifundefined{spanishe@\@citeb\APAC@extra@b@citeb}% + {}% skip + {{% Use `e' instead of `y' in Spanish + \global\let\oldBBA\BBA + \global\def\BBA{e\global\let\BBA\oldBBA}% + }}% + \if@A@cite + \hyper@natlinkstart{#1}% + {\csname b@\@citeb\APAC@extra@b@citeb\endcsname}% + \hyper@natlinkend + \if@Y@cite + {\@BBAY}% + \fi + \fi + \if@Y@cite + \hyper@natlinkstart{#1}% + {\csname Y@\@citeb\APAC@extra@b@citeb\endcsname}% + \hyper@natlinkend + \fi + \let\BBA\relax +}% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</spanish> % \end{macrocode} % @@ -10986,7 +13385,7 @@ short form, of the examples. % \subsection{\fname{swedish.apc}} % % This file redefines the language-specific elements of \pkg{apacite} -% for the Swedish language. Translation of APA elements into Swedish +% for the Swedish language. Translation of APA elements into Swedish % is not obvious. Ideas of which terms to use have been taken from % \citeA{Erik01}, \citeA{Johnsson}, and \citeA{GU94}. % @@ -10997,14 +13396,25 @@ short form, of the examples. %% Written by Stefan Bjork. %% Small adaptations by Erik Meijer %% +% \end{macrocode} +% A fancy way to store and restore the category code of the |@| sign, +% per Heiko Oberdiek. +% \begin{macrocode} +\edef\APACrestoreAtCode{% + \catcode`@=\the\catcode`@\relax +}% \makeatletter +\renewcommand{\onemaskedcitationmsg}[1]{% + \emph{(#1\ citation removed for masked review)}}% !!! CHANGE +\renewcommand{\maskedcitationsmsg}[1]{% + \emph{(#1\ citations removed for masked review)}}% !!! CHANGE %% %% Name of ref. list if it's a section. \renewcommand{\refname}{Referenser}% %% Name of ref. list if it's a chapter. \renewcommand{\bibname}{Litteraturf\"orteckning}% %% Author Index -\renewcommand{\authorindexname}{F\"orfattarindex}% +\renewcommand{\authorindexname}{F\"orfattarindex}% %% %% A note before the references if a meta-analysis is reported. \renewcommand{\APACmetaprenote}{% @@ -11061,6 +13471,7 @@ short form, of the examples. \renewcommand{\BAvailFrom}{Tillg\"anglig fr{\aa}n\ }% Websites; note the space. %% The argument is the date on which it was last checked. \renewcommand{\BRetrieved}[1]{H\"amtad {#1}, fr{\aa}n\ }% Websites; note the space. +\renewcommand{\BRetrievedFrom}{H\"amtad fr{\aa}n\ }% Websites; note the space. \renewcommand{\BMsgPostedTo}{Meddelande postat till\ }% Messages; note the space. %% %% Punctuation @@ -11078,7 +13489,7 @@ short form, of the examples. \renewcommand{\BBYY}{, }% between years of multiple citations with same author \renewcommand{\BBC}{; }% between cites \renewcommand{\BBN}{, }% before note -\renewcommand{\BCBT}{}% no comma between authors in ref. list when no. of +\renewcommand{\BCBT}{}% no comma between authors in ref. list when no. of %% authors = 2 \renewcommand{\BCBL}{}% no comma before last author when no. of authors > 2 %% @@ -11098,14 +13509,14 @@ short form, of the examples. \renewcommand{\APACrefYearMonthDay}[3]{% {\BBOP}{#1}% year (+ addendum); should not be empty \ifx\@empty#3\@empty - \ifx\@empty#2\@empty + \ifx\@empty#2\@empty \else %% Use full month if there is no day. \unskip, {#2}% month \fi \else \unskip, {#3}% day - \ifx\@empty#2\@empty + \ifx\@empty#2\@empty \else %% Use numbered month if there is a day as well. \let\APACorigmonth\APACmonth @@ -11155,16 +13566,24 @@ short form, of the examples. :e\else :e\fi \fi }% -%% +% \end{macrocode} +% Restore category code of |@| sign. +% \begin{macrocode} +\APACrestoreAtCode %</swedish> % \end{macrocode} % % \section{Bibliography database (\fname{apa5ex.bib})} +% % This file includes the reference entries of all examples in the % APA manual, which are all formatted in the \pkg{apacite} reference % manual. As such, it shows how ordinary and (especially) difficult % items can be formatted. % +% \subsection{References from the 5th edition of the Publication Manual} +% +% This includes some additional references that test some rules that are +% mentioned in the text. % \begin{macrocode} %<*bibdb> %% @@ -13080,11 +15499,909 @@ short form, of the examples. howpublished = {Available from National Technical Information Service Web site, \url{http://www.ntis.gov}\bibnodot{.}}, } +%</bibdb> +% \end{macrocode} +% +% \subsection{The examples \LaTeX{} file (\fname{apacxmpl.tex})} +% +% The file \fname{apacxmpl.tex} contains the \LaTeX{} code for formatting +% the examples from the APA manual. It can be studied to see how certain +% nonstandard references can be formatted according to the APA rules, +% to test \pkg{apacite}, and in particular to test compatibility with +% other packages. We start with a standard head. +% \begin{macrocode} +%<*xmpl> +\documentclass{article} +\usepackage{url} +\usepackage{apacite} +\usepackage{apacdoc} + +\title{Testing \textsf{apacite}: Examples from the APA manual} +\author{Erik Meijer\\ + \textsf{apacite at gmail.com} +} +\date{2012/02/14} +\begin{document} +\maketitle +\begin{abstract} +This document tests \textsf{apacite} [2012/02/14 v6.00]. See the +\textsf{apacite} documentation for more information. +\end{abstract} + +%</xmpl> +% \end{macrocode} % -% Additional references. +% \subsection{References from the 6th edition of the Publication Manual} % +% These examples are from chapter~7 of the 6th edition of the APA manual. +% \begin{macrocode} +%<*xmpl> +\section{Examples from chapter~7} + +\begin{enumerate} +\item +\cite{apa6:ch7-ex1} \\ +\cite{apa6:ch7-ex1} \\ +\fullciteA{apa6:ch7-ex1} \\ +\citeA{apa6:ch7-ex1} +\item +\cite{apa6:ch7-ex2} \\ +\cite{apa6:ch7-ex2} \\ +\fullciteA{apa6:ch7-ex2} \\ +\citeA{apa6:ch7-ex2} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex1, + author = {Herbst-Damm, Kathryn L. and Kulik, James A.}, + year = {2005}, + title = {Volunteer Support, Marital Status, and the Survival Times of + Terminally Ill Patients}, + journal = {Health Psychology}, + volume = {24}, + pages = {225--229}, + doi = {10.1037/0278-6133.24.2.225}, +} + +@article{apa6:ch7-ex2, + author = {Gilbert, David G. and McClernon, F. Joseph and + Rabinovich, Norka E. and Sugai, Chihiro and + Plath, Louisette C. and Asgaard, Greg and Zuo, Yantao and + Huggenvik, Jodi and Botros, Nazeih}, + year = {2004}, + title = {Effects of Quitting Smoking on {EEG} Activation and Attention + Last for More than 31 Days and are More Severe with Stress, + Dependence, {DRD2~A1} Allele, and Depressive Traits}, + journal = {Nicotine \& Tobacco Research}, + volume = {6}, + pages = {249--267}, + doi = {10.1080/14622200410001676305}, +} +%</bibdb> +% \end{macrocode} +% Note that the page heading of the article itself gives the journal name with +% an ampersand (`\&': \emph{Nicotine \& Tobacco Research}) and not with ``and'' +% as in the APA manual. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex3-1} \\ +\cite{apa6:ch7-ex3-1} \\ +\fullciteA{apa6:ch7-ex3-1} \\ +\citeA{apa6:ch7-ex3-1}\\ +\mbox{}\\ +\cite{apa6:ch7-ex3-2} \\ +\cite{apa6:ch7-ex3-2} \\ +\fullciteA{apa6:ch7-ex3-2} \\ +\citeA{apa6:ch7-ex3-2} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex3-1, + author = {Sillick, Tamra J. and Schutte, Nicola S.}, + year = {2006}, + title = {Emotional Intelligence and Self-Esteem Mediate Between Perceived + Early Parental Love and Adult Happiness}, + journal = {E-Journal of Applied Psychology: Emotional Intelligence}, + volume = {2}, + number = {2}, + pages = {38--48}, + url = {http://ojs.lib.swin.edu.au/index.php/ejab}, +} + +@article{apa6:ch7-ex3-2, + author = {Light, Matthew A. and Light, Ivan H.}, + year = {2008}, + title = {The Geographic Expansion of {Mexican} Immigration in the + {United} {States} and its Implications for Local Law + Enforcement}, + journal = {Law Enforcement Executive Forum}, + volume = {8}, + number = {1}, + pages = {73--82}, +} +%</bibdb> +% \end{macrocode} +% This journal appears to prefer the name \emph{Law Enforcement Executive +% Forum} over \emph{Law Enforcement Executive Forum Journal} (see +% \url{http://www.iletsbei.com/lee_forum/}). +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex4} \\ +\cite{apa6:ch7-ex4} \\ +\fullciteA{apa6:ch7-ex4} \\ +\citeA{apa6:ch7-ex4} + +\item +\cite{apa6:ch7-ex5} \\ +\cite{apa6:ch7-ex5} \\ +\fullciteA{apa6:ch7-ex5} \\ +\citeA{apa6:ch7-ex5} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex4, + author = {Guimard, Philippe and Florin, Agn\`es}, + year = {2007}, + title = {Les \'Evaluations des Enseignants en Grande Section de + Maternelle Sont-Elles Pr\'edictives des Difficult\'es de + Lecture au Cours Pr\'eparatoire?}, + englishtitle = {Are Teacher Ratings in Kindergarten Predictive of + Reading Difficulties in First Grade?}, + journal = {Approche Neuropsychologique des Apprentissages chez l'Enfant}, + volume = {19}, + pages = {5--17}, +} + +@article{apa6:ch7-ex5, + author = {Von Ledebur, Sidonia C.}, + year = {2007}, + title = {Optimizing Knowledge Transfer by New Employees in Companies}, + journal = {Knowledge Management Research \& Practice}, + howpublished = {Advance online publication}, + doi = {10.1057/palgrave.kmrp.8500141}, +} +%</bibdb> +% \end{macrocode} +% Here again the page heading of the article itself gives the journal name with +% an ampersand (`\&') and not with ``and''. Note that the APA explicitly +% changes ``von'' to ``Von'' to satisfy U.S. conventions of names. In +% other languages, ``von'' would be retained. See elsewhere in this manual +% for a discussion of how to treat von-parts. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex6} \\ +\cite{apa6:ch7-ex6} \\ +\fullciteA{apa6:ch7-ex6} \\ +\citeA{apa6:ch7-ex6} + +\item +\cite{apa6:ch7-ex7} \\ +\cite{apa6:ch7-ex7} \\ +\fullciteA{apa6:ch7-ex7} \\ +\citeA{apa6:ch7-ex7} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex6, + author = {Briscoe, Robert}, + year = {\BIP}, + title = {Egocentric Spatial Representation in Action and Perception}, + journal = {Philosophy and Phenomenological Research}, + url = {http://cogprints.org/5780/1/ECSRAP.F07.pdf}, +} + +@magazine{apa6:ch7-ex7, + author = {Chamberlin, J. and Novotney, A. and Packard, E. + and Price, M.}, + year = {2008}, + month = may, + title = {Enhancing Worker Well-Being: Occupational Health + Psychologists Convene to Share Their Research on Work, + Stress, and Health}, + journal = {Monitor on Psychology}, + volume = {39}, + number = {5}, + pages = {26--29}, +} +%</bibdb> +% \end{macrocode} +% The online version (\url{http://www.apa.org/monitor/2008/05/workstress.aspx}) +% does not have a comma in the title before the ``and''. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex8} \\ +\cite{apa6:ch7-ex8} \\ +\fullciteA{apa6:ch7-ex8} \\ +\citeA{apa6:ch7-ex8} +%</xmpl> +%<*bibdb> +@magazine{apa6:ch7-ex8, + author = {Clay, Rebecca}, + year = {2008}, + month = jun, + title = {Science vs.\ Ideology: Psychologists Fight Back Against + the Misuse of Research}, + journal = {Monitor on Psychology}, + volume = {39}, + number = {6}, + url = {http://www.apa.org/monitor/}, +} +%</bibdb> +% \end{macrocode} +% The APA manual incorrectly says ``about'' instead of ``against''. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex9} \\ +\cite{apa6:ch7-ex9} \\ +\fullciteA{apa6:ch7-ex9} \\ +\citeA{apa6:ch7-ex9} + +\item +\cite{apa6:ch7-ex10} \\ +\cite{apa6:ch7-ex10} \\ +\fullciteA{apa6:ch7-ex10} \\ +\citeA{apa6:ch7-ex10} + +\item +\cite{apa6:ch7-ex11} \\ +\cite{apa6:ch7-ex11} \\ +\fullciteA{apa6:ch7-ex11} \\ +\citeA{apa6:ch7-ex11} + +\item +\cite{apa6:ch7-ex12-1} \\ +\cite{apa6:ch7-ex12-1} \\ +\fullciteA{apa6:ch7-ex12-1} \\ +\citeA{apa6:ch7-ex12-1}\\ +\mbox{}\\ +\cite{apa6:ch7-ex12-2} \\ +\cite{apa6:ch7-ex12-2} \\ +\fullciteA{apa6:ch7-ex12-2} \\ +\citeA{apa6:ch7-ex12-2}\\ +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex9, + key = {{\APACciteatitle{Six Sites Meet}}}, + title = {Six Sites Meet for Comprehensive Anti-Gang + Initiative Conference}, + year = {2006}, + month = nov # "/" # dec, + journal = {OJJDP News @ a Glance}, + url = + {http://www.ncjrs.gov/html/ojjdp/news_at_glance/216684/topstory.html}, +} + +@newspaper{apa6:ch7-ex10, + author = {Schwartz, John}, + year = {1993}, + month = sep, + day = {30}, + title = {Obesity Affects Economic, Social Status}, + journal = {The Washington Post}, + pages = {A1, A4}, +} + +@newspaper{apa6:ch7-ex11, + author = {Brody, Jane E.}, + year = {2007}, + month = dec, + day = {11}, + title = {Mental Reserves Keep Brain Agile}, + journal = {The New York Times}, + url = {http://www.nytimes.com}, +} + +@article{apa6:ch7-ex12-1, + editor = {Haney, Craig and Wiener, Richard L.}, + year = {2004}, + title = {Capital Punishment in the {United} {States}}, + type = {Special issue}, + journal = {Psychology, Public Policy, and Law}, + volume = {10}, + number = {4}, +} + +@article{apa6:ch7-ex12-2, + editor = {Yan, Zheng and Greenfield, Patricia}, + year = {2006}, + title = {Children, Adolescents, and the {Internet}}, + type = {Special section}, + journal = {Developmental Psychology}, + volume = {42}, + pages = {391--458}, +} +%</bibdb> +% \end{macrocode} +% The journal lists the editors as Yan and Greenfield (in this order), +% although the first article (editorial introduction/overview) has +% Greenfield and Yan. +% +% The following is an implementation of the second bullet point: a special +% issue with no editors. +% \begin{macrocode} +%<*xmpl> +\mbox{}\\ +\cite{apa6:ch7-ex12-3} \\ +\cite{apa6:ch7-ex12-3} \\ +\fullciteA{apa6:ch7-ex12-3} \\ +\citeA{apa6:ch7-ex12-3} + +\item +\cite{apa6:ch7-ex13-1} \\ +\cite{apa6:ch7-ex13-1} \\ +\fullciteA{apa6:ch7-ex13-1} \\ +\citeA{apa6:ch7-ex13-1}\\ +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex12-3, + key = {{\APACciteatitle{Capital Punishment}}}, + title = {Capital Punishment in the {United} {States}}, + year = {2004}, + type = {Special issue}, + journal = {Psychology, Public Policy, and Law}, + volume = {10}, + number = {4}, +} + +@article{apa6:ch7-ex13-1, + author = {Ganster, Daniel C. and Schaubroeck, John and + Sime, Wesley E. and Mayes, Bronston T.}, + year = {1991}, + title = {The Nomological Validity of the {Type~A} Personality Among + Employed Adults}, + type = {Monograph}, + journal = {Journal of Applied Psychology}, + volume = {76}, + pages = {143--168}, + doi = {10.1037/0021-9010.76.1.143}, +} +%</bibdb> +% \end{macrocode} +% The bullet points given here were explicit examples in the 5th edition. +% We have to be liberal with what goes in the \fieldname{number} field +% for these: +% \begin{macrocode} +%<*xmpl> +\mbox{}\\ +\cite{apa6:ch7-ex13-2} \\ +\cite{apa6:ch7-ex13-2} \\ +\fullciteA{apa6:ch7-ex13-2} \\ +\citeA{apa6:ch7-ex13-2}\\ +\mbox{}\\ +\cite{apa6:ch7-ex13-3} \\ +\cite{apa6:ch7-ex13-3} \\ +\fullciteA{apa6:ch7-ex13-3} \\ +\citeA{apa6:ch7-ex13-3} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex13-2, + author = {Harris, Paul L. and Kavanaugh, Robert D.}, + year = {1993}, + title = {Young Children's Understanding of Pretense}, + journal = {Monographs of the Society for Research in Child Development}, + volume = {58}, + number = {1, Serial No.~231}, +} + +@article{apa6:ch7-ex13-3, + author = {Battig, William F. and Montague, William E.}, + year = {1969}, + title = {Category Norms for Verbal Items in 56 Categories: + A Replication and Extension of the {Connecticut} + Category Norms}, + journal = {Journal of Experimental Psychology Monographs}, + volume = {80}, + number = {3, Pt.~2}, +} +%</bibdb> +% \end{macrocode} +% The 5th edition gives the journal as ``Journal of Experimental +% Psychology Monographs'' and its front cover says ``Journal of Experimental +% Psychology Monograph'', but the volume and issue number and online +% categorization (on JSTOR) suggests that this is just a special issue +% of \emph{Journal of Experimental Psychology}, which would argue in +% favor of dropping the ``Monographs''. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex14} \\ +\cite{apa6:ch7-ex14} \\ +\fullciteA{apa6:ch7-ex14} \\ +\citeA{apa6:ch7-ex14} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex14, + key = {{\APACciteatitle{Editorial}}}, + title = {Editorial: ``{What} Is a Disaster'' and Why Does This + Question Matter?}, + year = {2006}, + type = {Editorial}, + journal = {Journal of Contingencies and Crisis Management}, + volume = {14}, + pages = {1--2}, +} +%</bibdb> +% \end{macrocode} +% The doi is \doi{10.1111/j.1468-5973.2006.00475.x}; normally this would +% be added. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex15} \\ +\cite{apa6:ch7-ex15} \\ +\fullciteA{apa6:ch7-ex15} \\ +\citeA{apa6:ch7-ex15} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex15, + author = {Marshall-Pescini, Sarah and Whiten, Andrew}, + year = {2008}, + title = {Social Learning of Nut-Cracking Behavior in {East} {African} + Sanctuary-Living Chimpanzees (\emph{Pan troglodytes + schweinfurthii})}, + type = {Supplemental material}, + journal = {Journal of Comparative Psychology}, + volume = {122}, + pages = {186--194}, + doi = {10.1037/0735-7036.122.2.186.supp}, +} +%</bibdb> +% \end{macrocode} +% Enclosing ``\verb+Pan troglodytes schweinfurthii+'' in exactly one pair of +% braces (which happen to also be the delimiters for the \cmd{\emph} command) +% ensures that the correct capitalization is output. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex16-1} \\ +\cite{apa6:ch7-ex16-1} \\ +\fullciteA{apa6:ch7-ex16-1} \\ +\citeA{apa6:ch7-ex16-1} \\ +\mbox{}\\ +\cite{apa6:ch7-ex16-2} \\ +\cite{apa6:ch7-ex16-2} \\ +\fullciteA{apa6:ch7-ex16-2} \\ +\citeA{apa6:ch7-ex16-2} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex16-1, + author = {Woolf, Nancy J. and Young, Stacey L. and Fanselow, Michael S. + and Butcher, Larry L.}, + year = {1991}, + title = {{MAP-2} Expression in Cholinoceptive Pyramidal Cells of + Rodent Cortex and Hippocampus is Altered by {Pavlovian} + Conditioning}, + type = {Abstract}, + journal = {Society for Neuroscience Abstracts}, + volume = {17}, + pages = {480}, +} + +@article{apa6:ch7-ex16-2, + author = {Lassen, Stephen R. and Steele, Michael M. and Sailor, Wayne}, + year = {2006}, + title = {The Relationship of School-Wide {Positive} {Behavior} + {Support} to Academic Achievement in an Urban Middle School}, + journal = {Psychology in the Schools}, + volume = {43}, + pages = {701--712}, + url = {http://www.interscience.wiley.com}, +} +%</bibdb> +% \end{macrocode} +% The doi is \doi{10.1002/pits.20177}; normally this would be added. In +% the title and the abstract, ``Positive Behavior Support'' is capitalized, +% so presumably this is the proper name of an experimental program. +% Therefore I have enclosed it in braces here as well, so that this +% capitalization is preserved. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex17} \\ +\cite{apa6:ch7-ex17} \\ +\fullciteA{apa6:ch7-ex17} \\ +\citeA{apa6:ch7-ex17} +%</xmpl> +%<*bibdb> +@article{apa6:ch7-ex17, + author = {Hare, Linda R. and O'Neill, Kevin}, + year = {2000}, + title = {Effectiveness and Efficiency in Small Academic Peer Groups: + A Case Study}, + journal = {Small Group Research}, + volume = {31}, + pages = {24--53}, + howpublished = {Abstract retrieved from {Sociological} {Abstracts} + database}, + note = {(Accession No.\ 200010185)}, +} +%</bibdb> +% \end{macrocode} +% The construction using the \fieldname{howpublished} and \fieldname{note} +% fields does the job, but is not very elegant. +% The doi (of the whole article) is \doi{10.1177/104649640003100102}, which +% presumably normally would be added. The abstract is also freely available +% on the Sage website (\url{http://sgr.sagepub.com/content/31/1/24} on +% July 10, 2010), which is a lot more accessible than this database. +% Note that the APA manual omits the subtitle. It is remarkable how +% many such small errors there are in the APA manual. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex18} \\ +\cite{apa6:ch7-ex18} \\ +\fullciteA{apa6:ch7-ex18} \\ +\citeA{apa6:ch7-ex18} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex18, + author = {Shotton, Margaret A.}, + year = {1989}, + title = {Computer Addiction? {A} Study of Computer Dependency}, + address = {London, England}, + publisher = {Taylor \& Francis}, +} +%</bibdb> +% \end{macrocode} +% I am puzzled by ``England''; ``UK'' seems more appropriate to me and that's +% what I'm always using. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex19-1} \\ +\cite{apa6:ch7-ex19-1} \\ +\fullciteA{apa6:ch7-ex19-1} \\ +\citeA{apa6:ch7-ex19-1} \\ +\mbox{}\\ +\cite{apa6:ch7-ex19-2} \\ +\cite{apa6:ch7-ex19-2} \\ +\fullciteA{apa6:ch7-ex19-2} \\ +\citeA{apa6:ch7-ex19-2} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex19-1, + author = {Shotton, Margaret A.}, + year = {1989}, + title = {Computer Addiction? {A} Study of Computer Dependency}, + type = {DX Reader version}, + url = {http://www.ebookstore.tandf.co.uk/html/index.asp}, +} + +@book{apa6:ch7-ex19-2, + author = {Schiraldi, Glenn R.}, + year = {2000}, + title = {The Post-Traumatic Stress Disorder Sourcebook: + A Guide to Healing, Recovery, and Growth}, + type = {Adobe Digital Editions version}, + doi = {10.1036/0071393722}, +} +%</bibdb> +% \end{macrocode} +% The website that this doi refers to gives the publication date as 2000, +% so that's what I'm using here. (The APA uses 2001.) This is supposed to +% be a ``free eBook'', but even after installing the Adobe software, the +% link to the actual content gives a ``page not found'' error for me. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex20} \\ +\cite{apa6:ch7-ex20} \\ +\fullciteA{apa6:ch7-ex20} \\ +\citeA{apa6:ch7-ex20} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex20, + author = {O'Keeffe, Elton}, + year = {\bibnodate}, + title = {Egoism \& the Crisis in {Western} Values}, + url = {http://www.onlineoriginals.com/showitem.asp?itemID=135}, +} +%</bibdb> +% \end{macrocode} +% Note the typo in the last name of the author in the APA manual. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex21} \\ +\cite{apa6:ch7-ex21} \\ +\fullciteA{apa6:ch7-ex21} \\ +\citeA{apa6:ch7-ex21} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex21, + author = {Freud, Sigmund}, + year = {1953}, + title = {The Method of Interpreting Dreams: + An Analysis of a Specimen Dream}, + editor = {Strachey, James}, + translator = {Strachey, James}, + booktitle = {The Standard Edition of the Complete Psychological + Works of {Sigmund} {Freud}}, + volume = {4}, + pages = {96--121}, + originalyear = {1900}, + url = {http://books.google.com/books}, +} +%</bibdb> +% \end{macrocode} +% This url did not bring me very far. It took me quite some time and different +% search strings to find the volume referred to. Search for author = +% ``Strachey'', year = 1953, and then select ``The interpretation of dreams, +% first part (1900)''; this leads in my case to +% \url{http://books.google.com/books?id=moN_OQAACAAJ& +% dq=inauthor:%22James+Strachey%22&hl=en&ei=9E1FTOyVOsHflgems_DrAw& +% sa=X&oi=book_result&ct=result&resnum=8&ved=0CEcQ6AEwBw}, but there is +% no preview available, and there is no useful information other than the +% title and the author, so exactly what is ``retrieved'' is not clear to +% me. After some internet searching, I did find +% \url{http://www.pep-web.org/static.php?page=standardedition}, which has +% a clickable table of contents, and presumably if you have a registered +% IP address, the actual content. Apparently, my IP address is not registered, +% so I had no access to the actual content. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex22} \\ +\cite{apa6:ch7-ex22} \\ +\fullciteA{apa6:ch7-ex22} \\ +\citeA{apa6:ch7-ex22} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex22, + editor = {Thomas, Noreen}, + year = {2002}, + title = {Perspectives on the Community College: A Journey of Discovery}, + type = {Monograph}, + url = {http://eric.ed.gov}, +} +%</bibdb> +% \end{macrocode} +% The ERIC document number is ED\,463\,808. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex23} \\ +\cite{apa6:ch7-ex23} \\ +\fullciteA{apa6:ch7-ex23} \\ +\citeA{apa6:ch7-ex23} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex23, + editor = {Koch, Sigmund}, + year = {1959--1963}, + title = {Psychology: A Study of a Science}, + volume = {1--6}, + address = {New York, NY}, + publisher = {McGraw-Hill}, +} +%</bibdb> +% \end{macrocode} +% Note that the correct title has ``a'' before ``science''. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex24} \\ +\cite{apa6:ch7-ex24} \\ +\fullciteA{apa6:ch7-ex24} \\ +\citeA{apa6:ch7-ex24} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex24, + author = {Strong, Edward K., Jr. and Uhrbrock, Richard S.}, + year = {1923}, + title = {Bibliography on Job Analysis}, + editor = {Outhwaite{\bibeditortype{Series Ed.\hbox{}}}, Leonard}, + booktitle = {Personnel {Research} {Series}: Vol.~1. {Job} Analysis and the + Curriculum}, + pages = {140--146}, + doi = {10.1037/10762-000}, +} +%</bibdb> +% \end{macrocode} +% There are several notable things with this reference: (1) The whole book is +% written by the same authors, so I'd think we'd normally list the book title +% in the \fieldname{title} field and in the text refer to the specific chapter +% or pages, rather than single out the chapter in the reference list. (2) +% The doi of the actual chapter is \doi{10.1037/10762-006}; the doi given here +% is the one for the whole book. (3) It is unclear why we would mention the +% series in which the book appears or the series editor. My impression from +% earlier versions of the \emph{APA manual} is that this is only done if the +% ``series'' is to be considered a joint work (like an encyclopedia) where +% different volumes have different editors and there is a series editor. It is +% my impression that the current work is just a book in a series of books, like +% every publisher has its various series with their series editors. (4) It is +% unclear why the series title needs to be capitalized. So in summary, I would +% normally format this example as +% \begin{verbatim} +% @book{apa6:ch7-ex24, +% author = {Strong, Edward K., Jr. and Uhrbrock, Richard S.}, +% year = {1923}, +% title = {Job Analysis and the Curriculum}, +% doi = {10.1037/10762-000}, +% } +% \end{verbatim} +% where I'm using the url for the whole book, because I refer to the whole book. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex25} \\ +\cite{apa6:ch7-ex25} \\ +\fullciteA{apa6:ch7-ex25} \\ +\citeA{apa6:ch7-ex25} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex25, + author = {Haybron, Daniel M.}, + year = {2008}, + title = {Philosophy and the Science of Subjective Well-Being}, + editor = {Eid, Michael and Larsen, Randy J.}, + booktitle = {The Science of Subjective Well-Being}, + pages = {17--43}, + address = {New York, NY}, + publisher = {Guilford Press}, +} +%</bibdb> +% \end{macrocode} +% In previous versions of the \emph{APA manual} (e.g., 5th ed., p.~217), the +% states or countries of a list of cities ``well known for publishing'', +% including New York, were not given, but this has been abandoned in the 6th +% ed. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex26} \\ +\cite{apa6:ch7-ex26} \\ +\fullciteA{apa6:ch7-ex26} \\ +\citeA{apa6:ch7-ex26} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex26, + author = {Piaget, Jean}, + year = {1988}, + title = {Extracts from {Piaget}'s Theory}, + translator = {Gellerier, Guy and Langer, Jonas}, + editor = {Richardson, Ken and Sheldon, Sue}, + booktitle = {Cognitive Development to Adolescence: A Reader}, + pages = {3--18}, + address = {Hillsdale, NJ}, + publisher = {Erlbaum}, + originalbooktitle = {Manual of Child Psychology}, + originalpages = {703--732}, + originaleditor = {Mussen, Paul H.}, + originalyear = {1970}, + originaladdress = {New York, NY}, + originalpublisher = {Wiley}, +} +%</bibdb> +% \end{macrocode} +% It looks like the title of the Mussen book should be +% \emph{Carmichael's Manual of Child Psychology} and it's the third edition. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex27} \\ +\cite{apa6:ch7-ex27} \\ +\fullciteA{apa6:ch7-ex27} \\ +\citeA{apa6:ch7-ex27} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex27, + editor = {VandenBos, Gary R.}, + year = {2007}, + title = {{APA} Dictionary of Psychology}, + address = {Washington, DC}, + publisher = {American Psychological Association}, +} +%</bibdb> +%<*xmpl> +\item +\cite{apa6:ch7-ex28} \\ +\cite{apa6:ch7-ex28} \\ +\fullciteA{apa6:ch7-ex28} \\ +\citeA{apa6:ch7-ex28} +%</xmpl> +%<*bibdb> +@book{apa6:ch7-ex28, +author = {{\bibcorporate{Real Academia Espa\~{n}ola}}}, + year = {2001}, + title = {Diccionario de la Lengua Espa\~{n}ola}, + englishtitle = {Dictionary of the {Spanish} Language}, + edition = {22}, + address = {Madrid, Spain}, + publisher = {{\bibcorporate{Real Academia Espa\~{n}ola}}}, +} +%</bibdb> +%<*xmpl> +\item +\cite{apa6:ch7-ex29} \\ +\cite{apa6:ch7-ex29} \\ +\fullciteA{apa6:ch7-ex29} \\ +\citeA{apa6:ch7-ex29} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex29, + author = {Graham, George}, + year = {2007}, + title = {Behaviorism}, + editor = {Zalta, Edward N.}, + booktitle = {The {Stanford} Encyclopedia of Philosophy}, + edition = {Fall 2007}, + url = {http://plato.stanford.edu/entries/behaviorism/}, +} +%</bibdb> +% \end{macrocode} +% At the time of this writing (June 2011), this url contains the Fall 2010 +% version. The Fall 2007 version can be found at +% \url{http://plato.stanford.edu/archives/fall2007/entries/behaviorism/}. +% This is what the website itself says about citation: +% \begin{quote} +% Please note that you are being asked to cite a URL that is in a fixed, +% archived edition of the encyclopedia. The reason for this is that the +% Stanford Encyclopedia of Philosophy recommends that readers use a stable +% citation for scholarly purposes. You should not cite the dynamic portion +% of the encyclopedia. +% \end{quote} +% Furthermore, +% \begin{quote} +% There are over 50 \BibTeX{} styles and no standard format that is +% guaranteed to work for all 50. So, we suggest you use our string as a +% `useful suggestion' that might need to be adapted for your particular +% \BibTeX{} file. +% \end{quote} +% \begin{verbatim} +% @InCollection{sep-behaviorism, +% author = {Graham, George}, +% title = {Behaviorism}, +% booktitle = {The Stanford Encyclopedia of Philosophy}, +% editor = {Edward N. Zalta}, +% howpublished = {\url{http://plato.stanford.edu/archives/fall2007/entries/behaviorism/}}, +% year = {2007}, +% edition = {Fall 2007}, +% } +% \end{verbatim} +% which is pretty similar to what I did above. The only big difference is that +% that they put the url in the \fieldname{howpublished} field, which should +% work fine with \pkg{apacite}, except that the APA wants the ``Retrieved from'' +% string, which is generated by \pkg{apacite} if you put the url in the +% \fieldname{url} field but not if you put it in the \fieldname{howpublished} +% field, so you'll have to insert it yourself in the \fieldname{howpublished} +% field if you want to use that. +% \begin{macrocode} +%<*xmpl> +\item +\cite{apa6:ch7-ex30} \\ +\cite{apa6:ch7-ex30} \\ +\fullciteA{apa6:ch7-ex30} \\ +\citeA{apa6:ch7-ex30} +%</xmpl> +%<*bibdb> +@incollection{apa6:ch7-ex30, + title = {Heuristic}, + booktitle = {Merriam-{Webster}'s Online Dictionary}, + edition = {11}, + url = {http://www.m-w.com/dictionary/heuristic}, +} +%</bibdb> +% \end{macrocode} +% One could argue that if the online edition refers to the 11th edition of +% the print version, the year should also be the year of the print version, +% instead of ``n.d.''. +% \begin{macrocode} +%<*xmpl> +\end{enumerate} +\bibliographystyle{apacite} +\bibliography{apa5ex} +\end{document} +%</xmpl> +% \end{macrocode} +% +% \subsection{Additional references} +% +% \begin{macrocode} +%<*bibdb> @book{APAManual3, author = {{\bibcorporate{American Psychological Association}}}, firstkey = {{American Psychological Association [APA]}}, @@ -13098,7 +16415,7 @@ short form, of the examples. note = {with revisions}, } -@book{APAManual, +@book{APAManual5, author = {{\bibcorporate{American Psychological Association}}}, firstkey = {{American Psychological Association [APA]}}, key = {{APA}}, @@ -13110,6 +16427,18 @@ short form, of the examples. publisher = {{\bibcorporate{American Psychological Association}}}, } +@book{APAManual6, + author = {{\bibcorporate{American Psychological Association}}}, + firstkey = {{American Psychological Association [APA]}}, + key = {{APA}}, + year = {2009}, + title = {Publication Manual of the {American} {Psychological} + {Association}}, + edition = {6}, + address = {Washington, DC}, + publisher = {{\bibcorporate{American Psychological Association}}}, +} + @book{chicago, title = {The {Chicago} Manual of Style}, edition = {15}, @@ -13155,11 +16484,19 @@ short form, of the examples. publisher = {Addison-Wesley}, } +@book{dLMe08a, + editor = {De Leeuw, Jan and Meijer, Erik}, + year = {2008}, + title = {Handbook of Multilevel Analysis}, + address = {New York, NY}, + publisher = {Springer}, +} + @book{meijer1998, author = {Meijer, Erik}, year = {1998}, title = {Structural Equation Models for Nonnormal Data}, - address = {Leiden, The Netherlands}, + address = {Leiden, Netherlands}, publisher = {DSWO Press}, } @@ -13172,14 +16509,13 @@ short form, of the examples. volume = {16--19}, pages = {1--31}, url = {http://www.eutypon.gr/eutypon/e-cont-16-19.html}, - lastchecked = {October~4, 2008}, } @book{WaMe00, author = {Wansbeek, Tom and Meijer, Erik}, year = {2000}, title = {Measurement Error and Latent Variables in Econometrics}, - address = {Amsterdam}, + address = {Amsterdam, Netherlands}, publisher = {North-Holland}, } @@ -13349,12 +16685,17 @@ short form, of the examples. %</bibdb> % \end{macrocode} % -% \section{\BibTeX\ style (\fname{apacite.bst}, \fname{apacitex.bst})} +% \section{\BibTeX\ style (\fname{apacite.bst} and its siblings)} % The program in \BibTeX's language that formats the reference list. -% These two files are almost identical, but \fname{apacitex.bst} -% generates information that can be used to generate an author index -% as well. +% Currently, this supplies four files: \fname{apacite.bst}, \fname{apacitex.bst} +% \fname{apacann.bst}, and \fname{apacannx.bst}. +% These files are almost identical, but \fname{apacitex.bst} and +% \fname{apacannx.bst} generate information that can be used to generate an +% author index, and \fname{apacann.bst} and \fname{apacannx.bst} use annotation +% when available for annotated bibliographies. % +% We start with file headers and a function that prints the version number in +% the \fname{.blg} file. % \begin{macrocode} %<*!annotated> %<bibstyle>%% apacite.bst : reference list according to APA manual @@ -13376,52 +16717,46 @@ FUNCTION {identify.apacite.version} %<*!annotated> %<bibstyle> "apacite.bst" %<xbibstyle> "apacitex.bst" -%<bibstyle> " [2009/03/01 v4.05 APA bibliography style]" -%<xbibstyle> " [2009/03/01 v4.05 APA bibl. style with author index info]" +%<bibstyle> " [2012/02/14 v6.00 APA bibliography style]" +%<xbibstyle> " [2012/02/14 v6.00 APA bibl. style with author index info]" %</!annotated> %<*annotated> %<bibstyle> "apacann.bst" %<xbibstyle> "apacannx.bst" -%<bibstyle> " [2009/03/01 v4.05 APA annotated bibliography style]" +%<bibstyle> " [2012/02/14 v6.00 APA annotated bibliography style]" %<*xbibstyle> -" [2009/03/01 v4.05 APA annotated bibl. style with author index info]" +" [2012/02/14 v6.00 APA annotated bibl. style with author index info]" %</xbibstyle> %</annotated> %<*bibstyle|xbibstyle> * top$ } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% DECLARATION OF FIELDS, INTEGERS, AND STRINGS FOR EACH % -% ENTRY % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - +% \end{macrocode} +% Declaration of fields, integers, and strings for each entry. +% \begin{macrocode} ENTRY { address - annote % only used for annotated version - annotate % only used for annotated version + annote + annotate author - booktitle % for articles in books - chair % for lectures - chapter % for incollection, esp. internet documents + booktitle + chair + chapter day + doi edition editor - englishtitle % english translation of title in other language - firstkey % key for first citation + englishtitle + firstkey howpublished - institution % for technical reports + institution journal - key % key for second and later citations, or all - % citations if firstkey is missing - lastchecked % for URL's + key + lastchecked month note - number % number of journal or report - organization % for unpublished - % - % for reprints, translations, etc. - % + number + organization originaladdress originalbooktitle originaledition @@ -13432,47 +16767,41 @@ ENTRY originalpublisher originalvolume originalyear - % - % back to normal - % pages publisher - school % for theses - series % not used - symposium % for lectures - text % for literals + school + series + symposium + text title - translator % translator of book (or article) - type % type of phdthesis (e.g., Doctoral dissertation) - % or type of article (e.g., Letter to the editor) - % etc. + translator + type url + urldate volume year } - { title.number % for sorting titles - cite.initials % dummy (0-1) indicating whether or not - % initials of the 1st author must - % be used for citing - cite.num.names.full % number of names to be cited for full and - cite.num.names.short % short cite - add.to.year % For a, b, c, etc. after year - % in multiple citations with same author-year + { title.number %% for sorting titles + cite.initials %% dummy (0-1) indicating whether or not + %% initials of the 1st author must + %% be used for citing + cite.num.names.full %% number of names to be cited for full and + cite.num.names.short %% short cite + add.to.year %% For a, b, c, etc. after year + %% in multiple citations with same author-year } - { year.label % For sorting entries by year - author.year.sort.label % For sorting entries and checking whether - % initials should be added, how many authors - % should be cited and whether a, b, etc. - % after year is necessary - title.sort.label % for sorting titles - type.2 % Replacement for type with misc entries and - % entries that revert to misc. + { year.label %% For sorting entries by year + author.year.sort.label %% For sorting entries and checking whether + %% initials should be added, how many authors + %% should be cited and whether a, b, etc. + %% after year is necessary + title.sort.label %% for sorting titles + type.2 %% Replacement for type with misc entries and + %% entries that revert to misc. } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% DECLARATION OF GLOBAL INTEGERS AND STRINGS % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - +% \end{macrocode} +% Declaration of global integers and strings. +% \begin{macrocode} INTEGERS { len pos name.max old.number numnames numnames.old nameptr lastname format.num.names cite.initials.old cite.num.names.old add.to.year.old forward @@ -13488,84 +16817,63 @@ STRINGS { s t u old.label field aut6 aut6.old year.label.old } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \end{macrocode} % A small function for testing purposes. - +% \begin{macrocode} FUNCTION {test} { #0 } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% A small function that indicates whether index entries must be -% generated. This is the only line that is different between -% apacite.bst and apacitex.bst - +% \end{macrocode} +% A small function that indicates whether index entries must be generated. +% This is the only line that is different between \fname{apacite.bst} and +% \fname{apacitex.bst} (and between \fname{apacann.bst} and +% \fname{apacannx.bst}). +% \begin{macrocode} %</bibstyle|xbibstyle> %<bibstyle>FUNCTION {make.index} { #0 } %<xbibstyle>FUNCTION {make.index} { #1 } %<*bibstyle|xbibstyle> - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% MONTH MACROS % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -% Use numbers now, along with a LaTeX function, which translates -% them into words. This allows language-specific deviations. - +% \end{macrocode} +% Month macros. We use numbers, along with a \LaTeX{} function, which +% translates them into words. This allows language-specific deviations. +% \begin{macrocode} MACRO {jan} {"{\APACmonth{01}}"} - MACRO {feb} {"{\APACmonth{02}}"} - MACRO {mar} {"{\APACmonth{03}}"} - MACRO {apr} {"{\APACmonth{04}}"} - MACRO {may} {"{\APACmonth{05}}"} - MACRO {jun} {"{\APACmonth{06}}"} - MACRO {jul} {"{\APACmonth{07}}"} - MACRO {aug} {"{\APACmonth{08}}"} - MACRO {sep} {"{\APACmonth{09}}"} - MACRO {oct} {"{\APACmonth{10}}"} - MACRO {nov} {"{\APACmonth{11}}"} - MACRO {dec} {"{\APACmonth{12}}"} - MACRO {winter} {"{\APACmonth{13}}"} - MACRO {spring} {"{\APACmonth{14}}"} - MACRO {summer} {"{\APACmonth{15}}"} - MACRO {fall} {"{\APACmonth{16}}"} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% LOGICAL `NOT', `AND', AND `OR' % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Logical 'not': -% If the first element on the stack is A then this function +% \end{macrocode} +% Logical ``not'': If the top element on the stack is $A$ then this function % does the following: +% \begin{verbatim} % push { #0 } % push { #1 } -% So now the first 3 elements of the stack are -% { #1 } { #0 } A -% The first 3 are popped and subjected to 'if': -% If A > 0 then { #0 } is executed, else { #1 } is executed: +% \end{verbatim} +% So now the first three elements of the stack are +% \verb+{ #1 }+ \verb+{ #0 }+ $A$. +% These are popped and subjected to ``if'': +% If $A > 0$ then \verb+{ #0 }+ is executed, else \verb+{ #1 }+ is executed: +% \begin{verbatim} % if A > 0 % then 0 % else 1 +% \end{verbatim} % So consider integers as logicals, where 1 = true and 0 = false, % then this does +% \begin{verbatim} % (if A then false else true) -% which is a logical 'not'. - +% \end{verbatim} +% which is a logical ``not''. +% \begin{macrocode} FUNCTION {not} { { #0 } { #1 } @@ -14140,67 +17448,43 @@ FUNCTION {output.dot.new.block} % whatever is more defined in \newblock FUNCTION {start.new.block} -{ newline$ - "\unskip\ " write$ newline$ +{ "\unskip\ " write$ newline$ "\newblock " write$ newline$ } +% \end{macrocode} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \subsection{Functions for sorting by author (or substitute), +% year, title} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% The ``classic'' versions are the ones with the von part +% treated a in ``Beethoven, L. van'', whereas the nonclassic ones +% have the new approach with the von part always before the last +% name. The ``classic'' versions are not used in this version, +% but I keep them defined so it's easy to switch, and perhaps +% define an option in the future. +% \begin{macrocode} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % finish current entry - % by writing what's left on the stack and starting a new line - % -FUNCTION {fin.entry} -{ output.end.block - "\PrintBackRefs{\CurrentBib}" write$ newline$ - test - { "\vspace{\baselineskip}" write$ newline$ } - 'skip$ - if$ -%<*annotated> - % - % According to TLC2, pp. 810-811, both annote and annotate fields are - % known, so support them both, but do not print them both, in case - % someone wants to make a file that is compatible with both the annotate - % and annotation styles and thus duplicates the information. Instead, we - % give annote priority. - % - annote empty$ - {% Try annotate - annotate empty$ - 'skip$ - { % add annotation - "\begin{APACrefannotation}" write$ newline$ - annotate write$ newline$ - "\end{APACrefannotation}" write$ newline$ - } - if$ - } - { % add annotation - "\begin{APACrefannotation}" write$ newline$ - annote write$ newline$ - "\end{APACrefannotation}" write$ newline$ - } - if$ -%</annotated> -} +FUNCTION {sort.name.format.classic} { "{ll{}}{ f{}}{ vv{}}{ jj{}}" } -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% FUNCTIONS FOR SORTING BY AUTHOR (OR SUBSTITUTE), YEAR, % -% TITLE % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +FUNCTION {cite.name.format.classic} { "{ll}" } + +FUNCTION {author.name.format.classic} { "{ll}{, f{\BPBI }.}{ vv}{, jj}" } -FUNCTION {sort.name.format} { "{ll{}}{ f{}}{ vv{}}{ jj{}}" } +FUNCTION {index.name.format.classic} { "{ll}{, f{\BPBI }.}{ vv}{, jj}" } -FUNCTION {cite.name.format} { "{ll}" } +FUNCTION {sort.name.format} { "{vv{}}{ll{}}{ f{}}{ jj{}}" } + +FUNCTION {cite.name.format} { "{vv }{ll}" } FUNCTION {cite.initials.name.format} { "{f{\BPBI }.~~}{vv }{ll}{ jj}" } -FUNCTION {author.name.format} { "{ll}{, f{\BPBI }.}{ vv}{, jj}" } +FUNCTION {author.name.format} { "{vv }{ll}{, f{\BPBI }.}{, jj}" } FUNCTION {editor.name.format} { "{f{\BPBI }.~~}{vv }{ll}{ jj}" } -FUNCTION {index.name.format} { "{ll}{, f{\BPBI }.}{ vv}{, jj}" } +FUNCTION {index.name.format} { "{vv }{ll}{, f{\BPBI }.}{, jj}" } + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Check whether initials must be added (1). @@ -15747,23 +19031,31 @@ FUNCTION {make.title.number} } if$ } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% NAME FORMATTING % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - +% \end{macrocode} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \subsection{Name formatting} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % In order to support removal of spaces between the initials, % we have to split the formatting of the constituent parts, -% because something like "{ll}{, f{\BPBI }.}{ vv}{, jj}" removes -% the hyphens between initials as well. +% because something like |"{ll}{, f{\BPBI }.}{ vv}{, jj}"| removes +% the hyphens between initials as well. The ``classic'' versions +% treat the von part differently. They were used in pervious versions +% of \pkg{apacite}. +% +% \begin{macrocode} + +FUNCTION {last.part.name.format.classic} { "{ll}" } -FUNCTION {last.part.name.format} { "{ll}" } +FUNCTION {von.junior.name.format.classic} { "{ vv}{, jj}" } + +FUNCTION {last.part.name.format} { "{vv }{ll}" } FUNCTION {initials.with.space.name.format} { "{f.}" } FUNCTION {von.last.junior.name.format} { "{vv }{ll}{ jj}" } -FUNCTION {von.junior.name.format} { "{ vv}{, jj}" } +FUNCTION {von.junior.name.format} { "{, jj}" } FUNCTION {one.complete.name.format} { "{vv }{ll}{, jj}{, ff}" } @@ -15997,29 +19289,48 @@ FUNCTION {format.index.name} format.author.name } - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % CITATION LABELS % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Some macro strings about commas, etc. between authors - -FUNCTION {comma.between.two} { "\BCBT{}" } +% \end{macrocode} +% +% \begin{macro}{comma.between.two} +% \begin{macro}{comma.between.names} +% \begin{macro}{comma.before.last} +% \begin{macro}{dots.before.last} +% \begin{macro}{and.before.last} +% \begin{macro}{et.al.string.cite} +% \begin{macro}{et.al.string} +% \begin{macro}{et.al.string.period} +% Some macro strings about commas etc.\ between authors. +% \begin{macrocode} +FUNCTION {comma.between.two} { "\BCBT {}" } FUNCTION {comma.between.names} { ", " } -FUNCTION {comma.before.last} { "\BCBL{}" } +FUNCTION {comma.before.last} { "\BCBL {}" } + +FUNCTION {dots.before.last} { "\BDBL {}" } -FUNCTION {and.before.last} { "\ \BBA{} " } +FUNCTION {and.before.last} { "\ \BBA {} " } -FUNCTION {et.al.string.cite} { "\ \protect\BOthers{.}" } +FUNCTION {et.al.string.cite} { "\ \protect \BOthers {.}" } -FUNCTION {et.al.string} { "\ \BOthers{.}" } +FUNCTION {et.al.string} { "\ \BOthers {.}" } -FUNCTION {et.al.string.period} { "\ \BOthersPeriod{.}" } +FUNCTION {et.al.string.period} { "\ \BOthersPeriod {.}" } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Add author index entry when desired. % "field" must have been defined before and must contain the @@ -16186,8 +19497,8 @@ FUNCTION {make.title.cite.label} % as book title, and insert this formatting. % is.atype - { "\APACciteatitle{" } - { "\APACcitebtitle{" } + { "\APACciteatitle {" } + { "\APACcitebtitle {" } if$ % title empty$ @@ -16281,14 +19592,14 @@ FUNCTION {make.definitive.year.supplement} % add.to.year #0 = { "" } - { "{\protect" + { "{\protect " year empty$ - { "\BCntND" * } + { "\BCntND " * } { year "\bibnodate" = - { "\BCntND" * } + { "\BCntND " * } { year "\BIP" = - { "\BCntIP" * } - { "\BCnt" * } + { "\BCntIP " * } + { "\BCnt " * } if$ } if$ @@ -16304,11 +19615,11 @@ FUNCTION {make.definitive.year.supplement} FUNCTION {protect.year} { year empty$ - { "{\protect\bibnodate{}}" } + { "{\protect \bibnodate {}}" } { year "\bibnodate" = - { "{\protect\bibnodate{}}" } + { "{\protect \bibnodate {}}" } { year "\BIP" = - { "{\protect\BIP{}}" } + { "{\protect \BIP {}}" } { year } if$ } @@ -16321,21 +19632,21 @@ FUNCTION {protect.year} % Make year label that is used for citations in text. FUNCTION {make.definitive.year.label} -{ "{\protect\APACyear{" +{ "{\protect \APACyear {" originalyear empty$ { protect.year } { originalyear "\bibnodate" = % date of original publication unknown { translator empty$ { protect.year } { year empty$ - { "{\protect\BTRANSL{}~\protect\bibnodate{}}" } % trans. n.d. - { "{\protect\BTRANSL{}}~" protect.year * } % trans. 1931 + { "{\protect \BTRANSL {}~\protect \bibnodate {}}" } % trans. n.d. + { "{\protect \BTRANSL {}}~" protect.year * } % trans. 1931 if$ } if$ } { year empty$ - { originalyear "/{\protect\bibnodate{}}" * } % 1923/n.d. + { originalyear "/{\protect \bibnodate {}}" * } % 1923/n.d. { originalyear year = { protect.year } { originalyear "/" * protect.year * } % 1923/1961 @@ -16350,7 +19661,7 @@ FUNCTION {make.definitive.year.label} % % Add "a", "b", etc. when necessary. % - "{\protect\APACexlab{" "}}" + "{\protect \APACexlab {" "}}" make.definitive.year.supplement enclose.check } @@ -16371,13 +19682,13 @@ FUNCTION {make.cite.labels} % Write a few lines for testing purposes. % test - { "\bibitem[]{} \fullciteA{" cite$ * "}" * write$ newline$ - "\bibitem[]{} \citeA{" cite$ * "}" * write$ newline$ + { "\bibitem [] {} \fullciteA {" cite$ * "}" * write$ newline$ + "\bibitem [] {} \citeA {" cite$ * "}" * write$ newline$ } 'skip$ if$ % - "\bibitem[\protect\citeauthoryear{%" write$ newline$ + "\bibitem [\protect \citeauthoryear {%" write$ newline$ % % When key or firstkey is available, this takes precedence. % @@ -16431,14 +19742,14 @@ FUNCTION {make.cite.labels} make.definitive.year.label write$ "}]{%" write$ newline$ cite$ write$ - "}%" write$ newline$ + "} " write$ newline$ % author.year.sort.label write$ newline$ % for testing purposes % year.label write$ newline$ % for testing purposes % % If the item is used in a meta-analysis, indicate this with % a star. % - "\APACinsertmetastar{%" write$ newline$ + "\APACinsertmetastar {%" write$ newline$ cite$ write$ "}%" write$ newline$ } @@ -16483,17 +19794,17 @@ FUNCTION {trans.postfix} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Format authors (or editors acting as authors) for -% reference list. +% Format authors (or editors acting as authors) for the +% reference list, according to APA 5th ed. rules. % % Call with -% dot field format.author.names +% dot field authors.editors.reflist.apa5 % where field is the field (string) that contains the authors % (or editors acting as authors) that must be formatted and % dot is 1 or 0 indicating whether or not a period must end % the formatting. -FUNCTION {format.author.names} +FUNCTION {authors.editors.reflist.apa5} { 'field := 'dot := % @@ -16509,6 +19820,11 @@ FUNCTION {format.author.names} 'skip$ if$ % + % Enclose authors in APACrefauthors environment to allow crude style + % options in \LaTeX. + "\begin{APACrefauthors}%" + write$ newline$ + % % It is kind of explicit in the APA manual that if "et al." would % refer to exactly one author (the 7th), then this author should % still be replaced by "et al.", unlike with citations. @@ -16669,16 +19985,208 @@ FUNCTION {format.author.names} if$ } if$ + % + % End APACrefauthors environment. + "\end{APACrefauthors}%" + write$ newline$ } +% +% \begin{macro}{authors.reflist.apa6} +% Format authors for the reference list according to the rules of the +% 6th edition of the \emph{APA Manual}, i.e., if there are more than 7 +% authors, list the first 6, then dots, and then the last. +% Call with +% \begin{verbatim} +% dot field authors.reflist.apa6 +% \end{verbatim} +% where \texttt{field} is the field (string) that contains the authors +% (or editors acting as authors) that must be formatted and \texttt{dot} +% is 1 or 0 indicating whether or not a period must end the formatting. +% \begin{macrocode} +FUNCTION {authors.reflist.apa6} +{ 'field := + 'dot := +% \end{macrocode} +% \texttt{numnames} is the total number of names in the \texttt{field}. +% \texttt{format.num.names} is the number of names to be formatted, +% which is \texttt{numnames} or 7, whichever is smaller +% \begin{macrocode} + field num.names$ 'numnames := + numnames #7 > + { #7 'format.num.names := } + { numnames 'format.num.names := } + if$ +% \end{macrocode} +% Enclose authors in \envirname{APACrefauthors} environment to allow crude +% style options in \LaTeX. +% \begin{macrocode} + "\begin{APACrefauthors}%" + write$ newline$ +% \end{macrocode} +% Format first author. +% \begin{macrocode} + #1 'nameptr := + field nameptr format.author.name + numnames #1 = +% \end{macrocode} +% Add period if required and if this is the only author, and add index +% entry when desired. +% \begin{macrocode} + { dot + { add.period$ } + 'skip$ + if$ + add.name.index + } + { add.name.index + numnames #2 = +% \end{macrocode} +% Optional comma between two authors; format second author and store in +% \texttt{s}. +% \begin{macrocode} + { comma.between.two write$ + #2 'nameptr := + field nameptr format.author.name 's := + s "others" = +% \end{macrocode} +% Second author is explicit ``|others|''. Therefore, insert +% ``et al.'' string. Note that this does not correspond with the +% 6th edition of the \emph{APA manual}, so give a warning here, +% but after that format the authors as in the 5th edition: +% ``First, et al.''. Add a period if required. +% \begin{macrocode} + { "`others' not consistent with 6th ed. of the APA Manual" + warning$ + dot + { et.al.string.period } + { et.al.string } + if$ + write$ newline$ + } +% \end{macrocode} +% There really are two authors: ``First, \& Second'', with a period +% after the latter if required. +% \begin{macrocode} + { and.before.last write$ + dot + { s add.period$ } + { s } + if$ + add.name.index + } + if$ + } +% \end{macrocode} +% Three or more authors, Format all the ones that need to be formatted, +% except the last one, which needs special treatment. +% \begin{macrocode} + { %% for nameptr := 2 to format.num.names - 1 do + #2 'nameptr := + { nameptr format.num.names < } +% \end{macrocode} +% Put comma between consecutive authors and format and add the next +% author and the optional index entry, and increase the loop variable. +% \begin{macrocode} + { comma.between.names write$ + field nameptr format.author.name + add.name.index + nameptr #1 + 'nameptr := + } + while$ +% \end{macrocode} +% Format the last author. If all authors are formatted, add an +% ampersand; otherwise, add dots (new in 6th ed.). +% \begin{macrocode} + field numnames format.author.name 's := + format.num.names numnames = + { comma.before.last write$ +% \end{macrocode} +% Check if this author is an explicit ``|others|''. If so, insert +% ``et al.'' string. Note that this does not correspond with the +% 6th edition of the \emph{APA manual}, so give a warning here. Add +% a period if required. +% \begin{macrocode} + s "others" = + { "`others' not consistent with 6th ed. of the APA " + "Manual" * + warning$ + dot + { et.al.string.period } + { et.al.string } + if$ + write$ + } + { and.before.last write$ + dot + { s add.period$ } + { s } + if$ + add.name.index + } + if$ + } +% \end{macrocode} +% We skipped some authors. Indicate by dots. +% \begin{macrocode} + { dots.before.last write$ + s + add.name.index + } + if$ + } + if$ + } + if$ +% \end{macrocode} +% End \envirname{APACrefauthors} environment. +% \begin{macrocode} + "\end{APACrefauthors}%" + write$ newline$ +} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{format.author.names} +% Format authors (or editors acting as authors) for the reference list. +% Call with +% \begin{verbatim} +% dot field format.author.names +% \end{verbatim} +% where \texttt{field} is the field (string) that contains the authors +% (or editors acting as authors) that must be formatted and \texttt{dot} +% is 1 or 0 indicating whether or not a period must end the formatting. +% \begin{macrocode} +FUNCTION {format.author.names} +{ 'field := + 'dot := +% \end{macrocode} +% This is a temporary trick, which needs to be cleaned up. We +% now check whether |dot| is 1, which indicates it's an author +% field. If it's not, it's an editor field. In the former case, +% if there are more than 7 authors, the first 6 plus dots plus +% the last author must be given, whereas in the latter case, +% only the first and ``et al.'' needs to be given. The latter +% is the same behavior as in the 5th edition, so we use that +% function, whereas we use an adapted function for authors in +% the 6th edition. +% \begin{macrocode} + dot + { dot field authors.reflist.apa6 } + { dot field authors.editors.reflist.apa5 } + if$ +} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Format authors in reference list, where it is given that % the author field is not empty. FUNCTION {format.authors} -{ #1 author format.author.names - "%" write$ -} +{ #1 author format.author.names } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Format editors in reference list in case editors act as @@ -16692,7 +20200,7 @@ FUNCTION {format.authors} FUNCTION {format.editors.as.authors} { #0 editor format.author.names - "\ " editor.postfix * add.period$ write$ + "\ " editor.postfix * add.period$ write$ newline$ } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -16709,7 +20217,7 @@ FUNCTION {format.editors.as.authors} FUNCTION {format.ed.trans.as.authors} { #0 editor format.author.names - "\ " editor.trans.postfix * add.period$ write$ + "\ " editor.trans.postfix * add.period$ write$ newline$ } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -17065,27 +20573,24 @@ FUNCTION {format.year.month.day.check} "}" * } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% TITLE FORMATTING % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % title of article in journal or book - % no finishing period - % field must be on top of stack - % (so englishtitle can be handled also) - % +% \end{macrocode} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \subsection{Title formatting} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \begin{macro}{format.atitle.no.dot} +% Title of article in journal or book, without finishing period. +% The field must be on top of stack (so \fieldname{englishtitle} can +% be handled as well). +% \begin{macrocode} FUNCTION {format.atitle.no.dot} -{ "\BBOQ{}" swap$ - "\BBCQ{}" swap$ +{ "{\BBOQ}" swap$ + "{\BBCQ}" swap$ duplicate$ empty$ 'skip$ { duplicate$ % Two arguments: Title twice: (1) don't change case; (2) change case - "\APACrefatitle{" swap$ * "}{" * swap$ + "\APACrefatitle {" swap$ * "} {" * swap$ "t" change.case$ * "}" * } @@ -17093,22 +20598,22 @@ FUNCTION {format.atitle.no.dot} enclose.check } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % title of article in journal or book - % with finishing period - % field must be on top of stack - % (so englishtitle can be handled also) - % +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{format.atitle.dot} +% Title of article in journal or book, with finishing period. +% The field must be on top of stack (so \fieldname{englishtitle} can +% be handled as well). +% \begin{macrocode} FUNCTION {format.atitle.dot} -{ "\BBOQ{}" swap$ - "\BBCQ{}" swap$ +{ "{\BBOQ}" swap$ + "{\BBCQ}" swap$ duplicate$ empty$ 'skip$ { duplicate$ % Two arguments: Title twice: (1) don't change case; (2) change case - "\APACrefatitle{" swap$ * "}{" * swap$ + "\APACrefatitle {" swap$ * "} {" * swap$ "t" change.case$ * "}" * add.period$ } @@ -17116,15 +20621,15 @@ FUNCTION {format.atitle.dot} enclose.check } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % title of article in journal or book - % field must be on top of stack - % second element on stack must be connected: - % if that is empty, then atitle.dot - % else atitle.no.dot, connect, and add period - % +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{format.atitle.connect} +% Title of article in journal or book. The field must be on top of stack. +% The second element on stack must be connected: if that is empty, then +% |format.atitle.dot|, else |format.atitle.no.dot|, connect, and add a +% period. +% \begin{macrocode} FUNCTION {format.atitle.connect} { swap$ duplicate$ empty$ @@ -17139,39 +20644,50 @@ FUNCTION {format.atitle.connect} if$ } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % title of book or so, without period - % call with - % field format.btitle.no.dot - % +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{format.btitle.no.dot} +% Title of a book or so, without period. Call with +% \begin{verbatim} +% field format.btitle.no.dot +% \end{verbatim} +% \begin{macrocode} FUNCTION {format.btitle.no.dot} { duplicate$ empty$ - 'skip$ + { pop$ + "" + } { duplicate$ % Two arguments: Title twice: (1) don't change case; (2) change case - "\APACrefbtitle{" swap$ * "}{" * swap$ + "\APACrefbtitle {" swap$ * "} {" * swap$ "t" change.case$ * "}" * } if$ } -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % title of book or so, with period - % call with - % field format.btitle.dot - % +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{format.btitle.dot} +% Title of book or so, with period. Call with +% \begin{verbatim} +% field format.btitle.dot +% \end{verbatim} +% \begin{macrocode} FUNCTION {format.btitle.dot} { duplicate$ empty$ - 'skip$ + { pop$ + "" + } { add.period$ format.btitle.no.dot } if$ } - - +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % title of book and similar @@ -17221,7 +20737,7 @@ FUNCTION {format.aetitle.check} { englishtitle empty$ { "" } { % Two arguments: Title twice: (1) don't change case; (2) change case - "\APACrefaetitle{" englishtitle * "}{" * + "\APACrefaetitle {" englishtitle * "} {" * englishtitle "t" change.case$ * "}" * } if$ @@ -17235,7 +20751,7 @@ FUNCTION {format.betitle.check} { englishtitle empty$ { "" } { % Two arguments: Title twice: (1) don't change case; (2) change case - "\APACrefbetitle{" englishtitle * "}{" * + "\APACrefbetitle {" englishtitle * "} {" * englishtitle "t" change.case$ * "}" * } if$ @@ -17530,27 +21046,23 @@ FUNCTION {format.address.publisher} swap$ "" connect.check "}" * } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % format address and publisher of book etc. - % - % New York: Wiley - % or - % Wiley (if address empty) - % or - % New York (if publisher empty) - % - % warning if no publisher or no address - % +% \end{macrocode} +% +% \begin{macro}{format.address.publisher.check} +% Format \fieldname{address} and \fieldname{publisher} of a book etc.: +% ``New York, NY: Wiley'' or ``Wiley'' (if \fieldname{address} is empty) +% or ``New York, NY'' (if \fieldname{publisher} is empty), or do nothing +% if both are empty. +% \begin{macrocode} FUNCTION {format.address.publisher.check} -{ "publisher" publisher warning.if.empty - "address" address warning.if.empty - publisher empty$ +{ publisher empty$ address empty$ and 'skip$ - { % Clear the stack + { +% \end{macrocode} +% Clear the stack. +% \begin{macrocode} duplicate$ empty$ 'skip$ { output.new.block } @@ -17560,7 +21072,9 @@ FUNCTION {format.address.publisher.check} if$ } - +% \end{macrocode} +% \end{macro} +% \begin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % TYPE AND NUMBER OF A REPORT % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -17621,7 +21135,7 @@ FUNCTION {format.howpublished} 'pop$ { output.dot.new.block } if$ - "\APAChowpublished{" howpublished * "}" * + "\APAChowpublished {" howpublished * "}" * } if$ } @@ -17636,41 +21150,61 @@ FUNCTION {format.howpublished} FUNCTION {output.howpublished} { howpublished empty$ 'skip$ - { "\APAChowpublished{" howpublished * "}" * + { "\APAChowpublished {" howpublished * "}" * output.dot.new.block } if$ } - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% URL FORMATTING FUNCTIONS % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % begin and end of url environment - % +% \end{macrocode} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \subsection{URL formatting functions} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \begin{macro}{begin.end.url.env} +% Begin and end of a URL environment. +% \begin{macrocode} FUNCTION {begin.end.url.env} -{ " \begin{APACrefURL} " - % For "Retrieved <date>, from" +{ "\begin{APACrefURL} " +% \end{macrocode} +% For ``Retrieved $\langle$\textit{date}$\rangle$, from'' +% \begin{macrocode} lastchecked empty$ - 'skip$ + { urldate empty$ + 'skip$ + { "[{" * urldate * "}]" * } + if$ + } { "[{" * lastchecked * "}]" * } if$ " \end{APACrefURL} " } -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % begin and end of message environment - % +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{begin.end.doi.env} +% Begin and end of a DOI environment. +% \begin{macrocode} +FUNCTION {begin.end.doi.env} +{ "\begin{APACrefDOI} " + " \end{APACrefDOI} " +} + +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{begin.end.msg.env} +% Begin and end of a message environment. +% \begin{macrocode} FUNCTION {begin.end.msg.env} -{ " \begin{APACrefURLmsg} " +{ "\begin{APACrefURLmsg} " " \end{APACrefURLmsg} " } +% \end{macrocode} +% \end{macro} +% \begin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % format url given that it is not empty, @@ -17695,6 +21229,22 @@ FUNCTION {format.url} enclose.check } +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % + % format doi given that it is not empty, + % for various entry types + % call with + % format.doi + % +FUNCTION {format.doi} +{ % First format begin and end of the enclosing environment. + begin.end.doi.env + % The doi string. + "\doi{" doi * "}" * + % Enclose in begin and end environment + enclose.check +} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % NOTE FORMATTING FUNCTIONS % @@ -17749,19 +21299,19 @@ FUNCTION {format.orig.book.note} originaleditor empty$ 'skip$ { originaleditor num.names$ #1 > - { "\APACorigEDS{" * originaleditor format.editor.names * "}" * } - { "\APACorigED{" * originaleditor format.editor.names * "}" * } + { "\APACorigEDS {" * originaleditor format.editor.names * "}" * } + { "\APACorigED {" * originaleditor format.editor.names * "}" * } if$ } if$ % "}{" * - originalbooktitle format.btitle.no.dot "" connect.check "}{" * - originaledition format.edition.check "" connect.check "}{" * - originalvolume format.bvolume.check "" connect.check "}{" * - originalpages format.bpages.check "" connect.check "}{" * - originaladdress "" connect.check "}{" * - originalpublisher "" connect.check "}{" * + originalbooktitle format.btitle.no.dot "" connect.check "} {" * + originaledition format.edition.check "" connect.check "} {" * + originalvolume format.bvolume.check "" connect.check "} {" * + originalpages format.bpages.check "" connect.check "} {" * + originaladdress "" connect.check "} {" * + originalpublisher "" connect.check "} {" * note "" connect.check "}" * } @@ -17803,22 +21353,68 @@ FUNCTION {format.orig.note} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% PERIODICALS % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % - % article in periodical: journal, magazine, newspaper, ... + % finish current entry + % by writing what's left on the stack and starting a new line % - % call with - % formatted.pages formatted.date periodical +FUNCTION {fin.entry} +{ doi empty$ + { output.end.block } + { output.new.block + format.doi + output.end.block + } + if$ + "\PrintBackRefs{\CurrentBib}" write$ newline$ + test + { "\vspace{\baselineskip}" write$ newline$ } + 'skip$ + if$ +%<*annotated> % -FUNCTION {periodical} -{ % - % author or editor, year, title, englishtitle, type + % According to TLC2, pp. 810-811, both annote and annotate fields are + % known, so support them both, but do not print them both, in case + % someone wants to make a file that is compatible with both the annotate + % and annotation styles and thus duplicates the information. Instead, we + % give annote priority. % + annote empty$ + {% Try annotate + annotate empty$ + 'skip$ + { % add annotation + "\begin{APACrefannotation}" write$ newline$ + annotate write$ newline$ + "\end{APACrefannotation}" write$ newline$ + } + if$ + } + { % add annotation + "\begin{APACrefannotation}" write$ newline$ + annote write$ newline$ + "\end{APACrefannotation}" write$ newline$ + } + if$ +%</annotated> +} +% \end{macrocode} +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \subsection{Top-level and near-top level functions for formatting complete +% entries} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Article in periodical: \entryname{journal}, \entryname{magazine}, +% \entryname{newspaper}. Call with +% \begin{verbatim} +% formatted.pages formatted.date periodical +% \end{verbatim} +% \begin{macrocode} +FUNCTION {periodical} +{ +% \end{macrocode} +% \fieldname{author} or \fieldname{editor}, \fieldname{year}, +% \fieldname{title}, \fieldname{englishtitle}, \fieldname{type}. +% \begin{macrocode} author empty$ % % no author: possibly special issue with editors as authors @@ -17986,7 +21582,7 @@ FUNCTION {book} } if$ % - % format address and publisher, check if address and publisher present + % format address and publisher % format.address.publisher.check % @@ -18014,36 +21610,33 @@ FUNCTION {book} format.orig.note fin.entry } - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % - % (translated) article or chapter in edited book - % +% +% \end{macrocode} +% Article or chapter in edited book. +% \begin{macrocode} FUNCTION {incollection} { author empty$ - % - % no author: title serves as author. - % title formatted as article title (APA manual not consistent in this, - % compare statement on p. 119: ``treat as book title'' and - % example 8, p. 121: no underlining => article title) - % +% \end{macrocode} +% No \fieldname{author}: \fieldname{title} serves as author. The title is +% formatted as an article title. +% \begin{macrocode} { editor.ne.trans { format.atitle.type.trans.check } { format.atitle.type.check } if$ output.new.block - % - % format month and day as well when available - % esp. for ``collections'' that are not books, - % such as parts of internet documents - % +% \end{macrocode} +% Format \fieldname{month} and \fieldname{day} as well when available, +% esp.\ for ``collections'' that are not books, such as parts of internet +% documents. +% \begin{macrocode} format.year.month.day.check add.period$ } - % - % format author and year, and check if year is present - % format article title and check if title or type present - % +% \end{macrocode} +% Format \fieldname{author} and \fieldname{year}, and check whether +% \fieldname{year} is present. Format article title and check whether +% \fieldname{title} or \fieldname{type} are present. +% \begin{macrocode} { format.authors start.new.block format.year.month.day.check output.dot.new.block editor.ne.trans @@ -18052,29 +21645,43 @@ FUNCTION {incollection} if$ } if$ - % - % format "In " editor " (Ed. \& Trans.), " - % booktitle, volume, edition, pages - % - output.new.block - format.in.editors.trans - format.bvol.edition.pages - booktitle format.btitle.connect * add.period$ - % - % format address and publisher, check if publisher present - % +% \end{macrocode} +% Format ``In '' \fieldname{editor} `` (Ed.\ \& Trans.), '' +% \fieldname{booktitle}, \fieldname{volume}, \fieldname{edition}, +% \fieldname{pages}. Leave empty if all these fields are missing. +% \begin{macrocode} + editor empty$ + translator empty$ and + edition empty$ and + volume empty$ and + pages empty$ and + chapter empty$ and + booktitle empty$ and + 'skip$ + { + output.new.block + format.in.editors.trans + format.bvol.edition.pages + booktitle format.btitle.connect * add.period$ + } + if$ +% \end{macrocode} +% Format \fieldname{address} and \fieldname{publisher}. +% \begin{macrocode} format.address.publisher.check - % - % if not empty, insert howpublished. - % (used if article is retrieved from the internet) - % +% \end{macrocode} +% If not empty, insert \fieldname{howpublished}. +% \begin{macrocode} format.howpublished add.period$ - % - % format url - % +% \end{macrocode} +% Format \fieldname{url}. +% \begin{macrocode} url empty$ 'skip$ - { % Clear the stack + { +% \end{macrocode} +% Clear the stack. +% \begin{macrocode} duplicate$ empty$ 'skip$ { output.new.block } @@ -18082,10 +21689,9 @@ FUNCTION {incollection} format.url } if$ - % - % format original publication (of reprint/translation) - % and optional note - % +% \end{macrocode} +% Format original publication (of reprint/translation) and optional note. +% \begin{macrocode} format.orig.note fin.entry } @@ -18136,7 +21742,7 @@ FUNCTION {format.tr.title.number} { "" } { % Now, we're in the regular situation with at least a % number, a type, a volume, or an edition. - "\APACbVolEdTR{" format.bvol.edition.check * "}{" * + "\APACbVolEdTR {" format.bvol.edition.check * "}{" * format.tr.number * "}" * } if$ @@ -18311,15 +21917,15 @@ FUNCTION {intechreport} % % volume, edition, report type and number, pages % - "\APACbVolEdTRpgs{" format.bvol.edition.check * "}{" * + "\APACbVolEdTRpgs {" format.bvol.edition.check * "} {" * format.tr.number * - "}{" * pages format.bpages.check * + "} {" * pages format.bpages.check * "}" * % booktitle format.btitle.connect * add.period$ % - % format address and publisher, check if publisher present + % format address and publisher % format.address.institution.check % @@ -18370,7 +21976,7 @@ FUNCTION {lecture} { "symposium and howpublished missing in " cite$ * warning$ "" } - { "\APAChowpublished{" howpublished * "}" * } + { "\APAChowpublished {" howpublished * "}" * } if$ address connect.with.comma.check } diff --git a/Master/texmf-dist/source/latex/apacite/apacite.ins b/Master/texmf-dist/source/bibtex/apacite/apacite.ins index a6ddc7416b9..0ecec8fc23a 100644 --- a/Master/texmf-dist/source/latex/apacite/apacite.ins +++ b/Master/texmf-dist/source/bibtex/apacite/apacite.ins @@ -2,7 +2,7 @@ %% This file will generate fast loadable files and documentation %% driver files from apacite.dtx when run through LaTeX. %% -%% Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +%% Copyright (C) 1994-8888 Erik Meijer and any individual authors listed %% elsewhere in this file. %% %% This file is part of the `apacite' package. @@ -20,10 +20,12 @@ %% %% The `apacite' package consists of the files apacite.dtx and %% apacite.ins, and the following generated files: -%% apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -%% apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -%% english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -%% ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +%% apacite.sty, apacdoc.sty, apacite.drv, +%% apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +%% apa5ex.bib, apacxmpl.tex, +%% english.apc, dutch.apc, finnish.apc, french.apc, +%% german.apc, ngerman.apc, greek.apc, norsk.apc, +%% spanish.apc, swedish.apc. %% %% This work has the LPPL maintenance status `maintained' %% @@ -41,7 +43,7 @@ This is a generated file. -Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +Copyright (C) 1994-8888 Erik Meijer and any individual authors listed elsewhere in this file. This file is part of the `apacite' package. @@ -59,10 +61,12 @@ LaTeX version 2005/12/01 or later. The `apacite' package consists of the files apacite.dtx and apacite.ins, and the following generated files: -apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +apacite.sty, apacdoc.sty, apacite.drv, +apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +apa5ex.bib, apacxmpl.tex, +english.apc, dutch.apc, finnish.apc, french.apc, +german.apc, ngerman.apc, greek.apc, norsk.apc, +spanish.apc, swedish.apc. This work has the LPPL maintenance status `maintained' @@ -79,7 +83,7 @@ the generated files. This is a generated file. -Copyright (C) 1994-2009 Erik Meijer and any individual authors listed +Copyright (C) 1994-8888 Erik Meijer and any individual authors listed elsewhere in this file. This file is part of the `apacite' package. @@ -97,10 +101,12 @@ LaTeX version 2005/12/01 or later. The `apacite' package consists of the files apacite.dtx and apacite.ins, and the following generated files: -apacite.sty, apacite.bst, apacitex.bst, apa5ex.bib, -apacite.drv, apacdoc.sty, apacann.bst, apacannx.bst, -english.apc, dutch.apc, finnish.apc, french.apc, german.apc, -ngerman.apc, greek.apc, norsk.apc, spanish.apc, swedish.apc. +apacite.sty, apacdoc.sty, apacite.drv, +apacite.bst, apacitex.bst, apacann.bst, apacannx.bst, +apa5ex.bib, apacxmpl.tex, +english.apc, dutch.apc, finnish.apc, french.apc, +german.apc, ngerman.apc, greek.apc, norsk.apc, +spanish.apc, swedish.apc. This work has the LPPL maintenance status `maintained' @@ -138,6 +144,7 @@ do not change apacite.dtx for this purpose. \file{norsk.apc}{\from{apacite.dtx}{norsk}} \file{spanish.apc}{\from{apacite.dtx}{spanish}} \file{swedish.apc}{\from{apacite.dtx}{swedish}} + \file{apacxmpl.tex}{\from{apacite.dtx}{xmpl}} \usepreamble\drvpreamble \file{apacite.drv}{\from{apacite.dtx}{driver}} \usepreamble\mainpreamble |