summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biblatex-contrib/biblatex-apa/biblatex-apa.tex
blob: d4a6ec517165d05bd6517129d46a2e44f64e65d0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
\documentclass{ltxdockit}
\usepackage[british]{babel}
\usepackage[strict]{csquotes}
\usepackage{shortvrb}
\usepackage{ifthen}
\usepackage{listings}
\usepackage{metalogo}
\MakeAutoQuote{«}{»}
\MakeShortVerb{\|}

% Unicode
\usepackage{fontspec}
\setmainfont[Ligatures=TeX]{TeXGyrePagella}
\setsansfont[Ligatures=TeX]{TexGyreHeros}
\setmonofont[Ligatures=NoCommon]{TeXGyreCursor}

\newcommand\apa[2][]{\ifthenelse{\equal{#1}{}}%
                       {\texttt{(APA #2)}}%
                       {\texttt{(APA #2 Example #1)}}}

\titlepage{%
  title={APA Bib\LaTeX\ style},
  subtitle={Citation and References macros for Bib\LaTeX},
  url={http://mirror.ctan.org/macros/latex/exptl/biblatex-contrib/biblatex-apa/},
  author={Philip Kime},
  email={Philip@kime.org.uk},
  revision={9.7},
  date={\today}}

\hypersetup{%
  pdftitle={APA Bib\LaTeX\ style},
  pdfsubject={APA 7th Edition Conformant Style for Bib\LaTeX},
  pdfauthor={Philip Kime},
  pdfkeywords={latex, biblatex, APA, style}}

\begin{document}

\printtitlepage
\tableofcontents

\section{Important Changes}\label{special}

Please see the revision history below (section \ref{rev}) for  details on changes in each
version. This section is just for important things like incompatible
changes which users should be aware of.

\minisec{9.0}
Completely overhauled for APA 7th edition. APA 7th edition is a lot more
consistent in terms of its formatting blocks and elements, resulting in
much less dependence on ad-hoc entry types and fields. In general, your
\file{.bib} should be updated in accordance with this documentation for APA
7th edition compatibility. 

\noindent |biber| 2.14+ and and |biblatex| 3.14 + are \emph{required}.

One effect of the normalisation of reference entries in the 7th edition is
that standard entrytypes can be used to cover many more cases. Indeed, the
set of standard entrytypes required is also smaller, for example,
|@COLLECTION| and |@INCOLLECTION| are not required at all (and are
internally remapped to |@BOOK| and |@INBOOK| respectively). Differentiation
between different entry subtypes (for example, songs, albums or podcasts
within the |AUDIO| entry type) is handled by localised strings held in the
|ENTRYSUBTYPE| field. As a result, many more localisation strings have been
added to the |.lbx| files. Please let me know if you are able to
translation the new strings in the |.lbx| file for your language, they are
generally marked with ``\texttt{\%FIXME}``.

\section{Introduction}\label{int}

\subsection{About}

This package is a Bib\LaTeX\ style for APA (American Psychological
Association) 7th Edition style compliant documents typeset in \latex. It
implements a citation style (\file{apa.cbx}), a references section style
(\file{apa.bbx}), some data model enhancements (\file{apa.dbx}) and string
localisation files (\path{<language>-apa.lbx}). The style is loaded just
like any other Bib\LaTeX\ styles but don't try to use the citation and
references styles separately as they rely on each other, macro-wise, in
places.

Please see the package |biblatex-apa6| on CTAN for the APA 6th edition
conformant version of this style.

In general, there is no attempt to generalise this style for non-APA
requirements--it is written for APA compliance only. Having said that,
there are a few options which allow users to change the APA defaults.

In this document and in the code, the specific APA requirements are
referred to by the section and (if appropriate) the example number of the
APA Style Guide (7th Edition).

\subsection{Requirements}\label{ref:req}

You will need to be using \sty{csquotes} ($\geq$ 4.3), Bib\LaTeX\ ($\geq$
3.14) and Biber ($\geq$ 2.14). If you want to take advantage of the
Bib\LaTeX\ |\DeclareQuotePunctuation| facility to enforce the APA required
«American» punctuation, you should normally use the \sty{babel} package
with the «american» option (see Bib\LaTeX\ manual section |3.9.1|). You can
of course use other languages but in such cases, to adhere to APA
«American» punctuation rules (following commas moved inside closing quotes
etc.), then you should set up |\DeclareQuotePunctuation| yourself as per
section |4.7.5| of the Bib\LaTeX\ manual.

If you are using an APA document \latex class, the class should be invoked
with the |noapacite| class option as per the documentation. Without this
class option, the APA class will automatically try to use plain Bib\TeX\
with the |apacite| style which is completely incompatible with Bib\LaTeX.

\subsection{License}

Permission is granted to copy, distribute and/or modify this software under
the terms of the \latex Project Public License, version
1.3c\footnote{\url{http://www.latex-project.org/lppl.txt}}. The current
maintainer is Philip Kime.

\subsection{History}

When I started using Bib\LaTeX, I assumed there would be an APA style. I
was wrong. I started to try to make one and realised why there was none.
The APA style manual is enormous; the citation and references
specifications run over many chapters and are very specific in terms of
formatting. They are also not entirely consistent but then again, it is
rare to have such a thorough specification to work from. Inconsistencies in
the manual and workarounds are noted in the examples document.

\subsection{Acknowledgments}

Thanks to Philipp Lehman for Bib\LaTeX\ which really has been a major
advance over pure Bib\TeX. Thanks to Alexander van Loon for the Dutch
localisation. Thanks to Paul Thompson for the suggestion to
parameterise the max authors setting. Thanks to George Gkotsis for the
Greek localisation. Thanks to Erikson Kaszubowski for the Brazilian
localisation. Thanks to Braulio José Solano Rojas for the Spanish
localisation. Thanks to Stefan Mayer for the |subtitlepunct| suggestion.
Thanks to Håkon Malmedal for the Norwegian localisation. Thanks to
Johann Gründl for the Austrian localisation. Thanks to Svante Kvarnström
for the Swedish localisation. Thanks to Hendrik Maryns for further Dutch
localisation. Thanks to Tea Tušar and Bogdan Filipič for the Slovenian
localisation. Thanks to Sebastian Ørsted for the Danish localisation.
Thanks to Jürgen Spitzmüller for the DGPs localisation hints. Thanks to
Sergei Golovan for the Russian localisation. Thanks to Vítor Míguez for the
Galacian localisation.

\section{Use}\label{ref:use}
\label{use}
This package is available via \TeX Live as |biblatex-apa|. You can find it
through the provided \TeX Live update utilities which will install it
automatically for you. If you need to install manually (to use a new
version which has not yet been published to the \TeX Live updaters, for
example), you can download it from CTAN and then, put the \path{.cbx},
\path{.bbx} and \path{.lbx} files in your texmf tree, usually:\\ 

\noindent\path{<texmf>/tex/latex/biblatex/cbx/apa.cbx}\\
\path{<texmf>/tex/latex/biblatex/bbx/apa.bbx}\\
\path{<texmf>/tex/latex/biblatex/lbx/<language>-apa.lbx}\\

\noindent Specify the style in the usual way when loading Bib\LaTeX. If you
are using \sty{babel}:

\begin{ltxcode}
\usepackage[american]{babel}
\usepackage{csquotes}
\usepackage[style=apa]{biblatex}
\end{ltxcode}

or \sty{polyglossia}:

\begin{ltxcode}
\usepackage{polyglossia}
\setdefaultlanguage[variant=american]{english}
\usepackage{csquotes}
\usepackage[style=apa]{biblatex}
\end{ltxcode}

\noindent Note that the APA manual requires the forcing of titles into
«sentence case», that is, initial cap followed by lower case for sentence
units, with the exception of names and material from languages which do not
follow English capitalisation. As of version 0.8a, Bib\LaTeX\ has a
|\MakeSentenceCase| macro which deals with this. So, in the traditional
Bib\TeX\ way, capitalise normally in the |.bib| file, protecting names etc.
with the usual brace pairs and the style will take care of forcing the
APA-style sentence case in the References section. Unlike the References
section, titles in citations in the APA style appear in normal case and the
style will ensure this too.

\subsection{Package options}\label{opts}

\begin{ltxcode}
apamaxprtauth=<num>
\end{ltxcode}

\noindent This option controls the number of author/editor names which are
printed in the References. APA style defaults to 20. You can change this if
you really want to fully print all author list references in certain
contexts (for example in a CV where you are an author in position 21 \ldots).

\subsection{Localisation}

Localisation is provided for APA-specific strings in the accompanying
|.lbx| files which are loaded automatically.

Normal use will invoke \sty{babel} with the «american» language or
\sty{polyglossia} with «american» variant of «english».

The \file{english-apa.lbx} is a copy of the \file{american-apa.lbx} since
the default is «American» English.

The APA manual does not mention nor sanction any non «American» English
strings but it is quite common for non-English journals to ask for APA style
bibliographies and so this must be supported.

If not using the \sty{babel} «american» option, it may be necessary to set up
the |\DeclareQuotePunctuation| option as mentioned in section \ref{ref:req}
above. You would only need to do this if, for some strange reason, a
non-american journal required the (unpleasant) american practice of moving
final punctuation marks inside closing quotes.

\subsubsection{Date formats}

Obviously, an American style uses month/day/year formats. European formats
are usually day/month/year. The APA style dictates long date formats and so
this is not really apparent in the bibliography. There is an APA standard
for long date formats which may not be correct for European journals using
roughly APA formatting standards (German journals tend to have a different
long date format, for example). The «american» babel option will give you
APA compliant US date formats. Default sensible date formats are included
for german, ngerman and french. You should redefine the |\mkbibdatelong|
macro in the relevant language |.lbx| file to change this if needed.

A customisable macro \cmd{urldatecomma} determines what comes between the
date of a URL and the URL itself. This defaults to the standard comma and
space as per APA style but just a space in germanic localisations.

\section{Details}

The detailed information for this style is contained in the example document and
accompanying \path{.bib} files:
\begin{description}
\item[\path{biblatex-apa.tex}] This document.
\item[\path{biblatex-apa-test.tex}]\footnote{\path{biblatex-apa-test.pdf}
    is also provided and is the typeset version of this \latex source
    file.} This document typesets every useful example from
  \apa{8--10}. The examples in it aim to look as much like the APA
  manual examples as possible. All citation examples in the document are
  real examples using a \path{.bib} file.
\item[\path{biblatex-apa-test-citations.bib}] This contains the \path{.bib}
  entries for the citations examples. You won't find anything of interest
  in this file---it's just used to provide real data for the citation
  examples.
\item[\path{biblatex-apa-test-references.bib}] This contains the
  \path{.bib} entries for all of the examples in \apa{9--11}. This
  file is the main documentation for the |biblatex-apa| implementation of
  the APA References section style. To see how the style deals with a
  particular example from \apa{9--11}, look it up in here. Every
  example is marked with the APA example number and has explanatory notes
  where necessary.
\item[\path{apa.cbx}] The |biblatex-apa| citations style. It is
  decently structured with comments but shouldn't need to be read for
  normal use.
\item[\path{apa.bbx}] The |biblatex-apa| references style. It is
  decently structured with comments but shouldn't need to be read for
  normal use.
\item[\path{apa.dbx}] The |biblatex-apa| data model additions. This allows
  users to utilise more natural entry type and field names for certain
  entries. See comments in the \path{biblatex-apa-test-references.bib}.
\item[\path{*.lbx}] The |biblatex-apa| localisation files. These files
  override some language-specific macros for some fixed strings.
\end{description}

\subsection{Citations}

\apa{8.11} requires that there should be no parentheses around the year of
the citation when the citation itself occurs within parenthesis. This is
tricky to completely automate within the remit of a citation style since it
requires knowledge of the current typesetting state. So, the new citation
command

\begin{ltxsyntax}
\cmditem{nptextcite}[prenote][postnote]{key}<punctuation>
\end{ltxsyntax}

\noindent is provided for such situations. It is identical to |\textcite|
but does not put parentheses around the year and separates items with
commas. See examples using this command in \path{biblatex-apa-test.tex}.
There is also a multi-cite version |\nptextcites| that works in the same
way as |\textcites|.

The |\fullcite| command uses ampersands, like the references section
and there is also a |\fullcitebib| command which is the same as
|\fullcite| but which fakes a mini references section with APA style
indentation and so is not intended to be used inline like
|\fullcite|. See examples in the test file.

\subsection{References}\label{refs}

The references style was based on the Bib\LaTeX\ default
|authoryear-comp| style but is heavily modified. If in doubt read the
example references |.bib| as it is commented and you can learn a lot from
the examples by picking something close to what you need from the APA
examples and then looking in this file to see how it was implemented. Some
general notes:

\subsubsection{Publication Status}
In addition to the standard |PUBSTATE| field publication state localisation
string ``in press'', the |HOWPUBLISHED| field offers also the following
localisation strings \apa{10.8}. There is no better way to do this as such
states are language dependent and need localisation strings:

\begin{description}
  \item[manunpub] Unpublished Manuscript
  \item[maninprep] Manuscript in preparation
  \item[mansub] Manuscript submitted for publication
\end{description}

\subsubsection{Authors and Group Authors}
APA 7th edition has a concept of a ``Group'' author \apa{9.11}. The style
provides the |GROUPAUTHOR| entry field in all entry types. It is
recommended to use |GROUPAUTHOR| when the author is an organisation or
group as there are rules for name lists which are different for group
authors (for example \apa{9.8}). |AUTHOR| is used much more extensively as
the main agent of a work and the specific roles for particular agents is
handled using |biber'|'s data annotation feature, see below.

\subsubsection{Roles}
The main role \apa{9.10} is of course specified by the |AUTHOR| entry
field. You can attach specialised roles to any name in the |AUTHOR| field as
required by many examples in \apa{10}, using |biber|'s data annotation
feature. This is heavily used in the style and allows easy automation of
complex examples like those in \apa{10.12}. See the
|biblatex-apa-test-references.bib| example file used to generate the main
test document. Data annotations can be named and the style requires that
you name data annotations for various tasks correctly:

\begin{description}
  \item[role] Data annotation to denote a specialised role for a particular
    name in the |AUTHOR| name list or a specialised role for the entire
    name list. Multiple roles may be specified for a name/name list.
  \item[username] Literal data annotation to denote a username for an
    online service associated with a name in the |AUTHOR| name list.
\end{description}    
%
Examples of these data annotations can be found in example documentation
and |.bib| file. Data annotations are generally used when particular names
in a name list require annotating with a specialized role.

Some roles:

\begin{itemize}
  \item Editor(s)
  \item Translator(s)
  \item Narrator(s)
\end{itemize}
%
are very common and often occur in addition to the |AUTHOR| name list and
so are usually specified by their own entry field. When the specialized
role attaches to a complete name list \apa{10.2:26} rather than
an individual name in a list \apa{10.12:84}, you have the choice
to use data annotations or a dedicated name list. The latter is preferable
if an appropriate name list exists (it does for all examples in \apa{10}).

There are some special cases for secondary name lists with uncommon roles
which are handled with the standard |biblatex| |EDITORX| fields and
associated |EDITORTYPE| fields \apa{10.5:63}.

\subsubsection{Article types}

Since |ARTICLE| entry types are used extensively for academic journals and
also newspaper articles, the |KEYWORD| ``nonacademic'' should be specified
for articles that are not academic articles in an academic journal. This is
because date formatting differs in the style between academic and
non-academic articles. This is a more general solution than introducing new
entry types which are not supported by other software.

\subsubsection{Legal Entry Types}

\apa{11} contains the format guidelines for legal references. This is fully
implemented and the |biblatex-apa-test-references.bib| demonstrates which
entry types and fields are used to produce the \apa{11} examples. There are
some custom entry types and fields used to manage this, as you will see in
the |.bib| file. Considerable use is made of localisation strings in legal
entries due to the requirements that certain strings change their
abbreviation status between citations and references (and even between
parenthetical and narrative citations).

The localisation strings for the U.S. specific elements of this section
(most of it) are not provided in other languages as there is not much
point. Feel free to copy them from |american-apa.lbx| if you really need
to. Localisation strings for all 50 U.S. States are provided to support
state constitution references.

Pay attention to the |JURISDICTION| entries in the example |.bib| which use
|biber|'s data annotation feature in order to match the required style
elements. The names of the data annotations are not optional and must match
the examples.

\section{Revision history}\label{rev}

\begin{changelog}

\begin{release}{9.7}{2020-04-05}
\item Bugfixes
\end{release}

\begin{release}{9.6}{2020-02-22}
\item Bugfixes
\end{release}

\begin{release}{9.5}{2020-02-01}
\item Bugfixes
\end{release}

\begin{release}{9.4}{2019-12-22}
\item Bugfixes
\end{release}

\begin{release}{9.3}{2019-12-21}
\item Rationalised some entrytype usage
\end{release}

\begin{release}{9.2}{2019-11-29}
\item Bug fixes
\end{release}
  
\begin{release}{9.1}{2019-11-27}
\item Bug fixes, internal improvements and implementation of \apa{11}.
\end{release}

\begin{release}{9.0}{2019-11-23}
\item First release (of APA 7th edition style)
\end{release}

\end{changelog}
\end{document}

% Local Variables:
% TeX-engine: luatex
% End: