summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex
blob: 902d40a66dd4f78f918f506ac210dea474d5fa16 (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
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
\documentclass{ltxdockit}
\usepackage[british]{babel}
\usepackage[strict]{csquotes}
\usepackage{shortvrb}
\usepackage{ifthen}
\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 \sty{biblatex} style},
  subtitle={Citation and References macros for \sty{biblatex}},
  url={http://www.ctan.org/tex-archive/macros/latex/exptl/biblatex-contrib/biblatex-apa/},
  author={Philip Kime},
  email={Philip@kime.org.uk},
  revision={3.5},
  date={\today}}

\hypersetup{%
  pdftitle={APA \sty{biblatex} style},
  pdfsubject={APA Citation and References macros for \sty{biblatex}},
  pdfauthor={Philip Kime},
  pdfkeywords={latex, biblatex, APA, style}}

\begin{document}

\printtitlepage
\tableofcontents

\section{Introduction}
\label{int}

\subsection{About}

This package is a \sty{biblatex} style for APA (American Psychological
Association) style compliant documents typeset in \latex. It implements a
citation style (\path{apa.cbx}), a references section style
(\path{apa.bbx}) and string localisation files (\path{<language>-apa.lbx}).
Currently there are only string localisations for a few languages---if you can help with any other languages, please mail me; the
localisation |.lbx| files are very small and simple and it would be a small
translation task for the few APA-specific strings needed.
The styles are loaded just like any other \sty{biblatex} styles but I
wouldn't try to use the citation and references styles separately as they
rely on each other, macro-wise, in places.

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

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

You will need to be using \sty{csquotes} ($\geq$ 4.3) and \sty{biblatex}
($\geq$ 1.4). Some features will not work\footnote{Automatic name and name
  list uniqueness disambiguation---see examples doc} without the
\sty{biber} backend for \sty{biblatex} ($\geq$ 0.9.2) which is strongly
recommended. If you want to take advantage of the \sty{biblatex}
|\DeclareQuotePunctuation| facility to enforce the APA required «American»
punctuation, you should normally use the \sty{babel} package with the
«american» option (see \sty{biblatex} 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 \sty{biblatex} manual.

If you are using the |apa.cls| \latex class, you need be using version
$\geq$ 1.3.4. The class should be invoked with the |noapacite| class option
as per the |apa.cls| documentation. Without this class option, the
|apa.cls| class will automatically try to use plain \bibtex with the
|apacite| style which is completely incompatible with \sty{biblatex}.

\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 (\textcopyright\ 2011).

\subsection{History}

When I started using \sty{biblatex}, I assumed there would be an APA style
when I went looking. 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 to about 60 pages and are very specific in
terms of formatting. They are also not entirely consistent but then again,
it is rare to have such a thorough specification to work from.
Inconsistencies in the manual and workarounds are noted in the examples
document.

\subsection{Acknowledgments}

Thanks to Philipp Lehman for \sty{biblatex} which really has been a major
advance over pure \bibtex. 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.

\section{Use}\label{ref:use}
\label{use}
This package is available via |TeXLive| as |biblatex-apa|. You can find it
through the provided |TeXLive| 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 |TeXLive| 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 \sty{biblatex}. 

\begin{ltxcode}
\usepackage[american]{babel}
\usepackage{csquotes}
\usepackage[style=apa]{biblatex}
\DeclareLanguageMapping{american}{american-apa}
\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, \sty{biblatex} has a
|\MakeSentenceCase| macro which deals with this. So, in the traditional
\bibtex way, capitalise correctly 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{Localisation}

Localisation is provided for APA-specific strings in the accompanying
|.lbx| files. To use these files, put an appropriate mapping in your
document preamble, after loading \sty{biblatex}.

Normal use will invoke babel with the «american» babel language. After
loading babel and biblatex, put this in the preamble (see full preamble
example in section \ref{ref:use} above):

\begin{ltxcode}
\DeclareLanguageMapping{american}{american-apa}
\end{ltxcode}

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.

Here is an example to load the German localisation strings. This assumes
that you are using the \sty{babel} package with the appropriate language
option:

\begin{ltxcode}
\DeclareLanguageMapping{german}{german-apa}
\end{ltxcode}

This loads the |german-apa.lbx| file which in turn, loads the |german.lbx|
file and augments it with APA-specific strings. If you are not using the
babel «american» option, they you may need 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 (rather horrible) 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 |*-apa.lbx| file to change this if needed.

\subsection{Limitations}
\label{use:limit}
There are certain limitations you need to bear in mind when using these
styles. The APA manual is written without much regard for automation of
citation and references processing---it just tells you how it wants things to
look and the implicit assumption is that you would type out everything by
hand if necessary. Having said that, the majority of the APA citation
and references style is implemented, there are just a few exceptions which
are hardly worth the coding pain since they ambiguous and easily worked
around.

\subsubsection{Reference Section Limitations}

\begin{description}
\item\apa{6.27} Can't deal yet with authors listed as «with».
\end{description}

\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 just about every useful example from
  \apa{6.11}--\apa{6.21} and \apa{7.01}--\apa{7.11}. 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{7.x}. 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{7.x}, look it up in here. Every example is marked with
  the APA example number and has explanatory notes.
\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{*.lbx}] The |biblatex-apa| localisation files. These files
  override some language-specific macros for some fixed strings.
\end{description}

\subsection{Citations}

\apa{6.13} 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. Please note that APA style
does not have multiple citation lists sorted---they appear in the
order cited. Since |\fullcitebib| is a citation command, the citations
will not be sorted which might appear odd since this «citation» style
looks like a references section excerpt. There is no way around this
since the |sortcites| biblatex option is a package-level option. If
you want to customise such a fake references section «citation», you
should probably be using |\printbibliography| with a filter.

\subsection{References}

The references style was based on the \sty{biblatex} 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:

\begin{itemize}
\setlength{\itemsep}{0pt}
\item The |\maxprtauth| commands returns the number of author/editor
  names which are printed. APA style defaults to 7. You can reset this
  after loading biblatex with, for example,
  |\renewcommand{\maxprtauth}{25}| 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 8 \ldots)
\item There are occasions where there is no sensible \path{.bib} key to
  use. This applies to things like |AUDIO| and |VIDEO| entries mainly. The
  format of these requires that different roles (Director, Producer etc.)
  are separately specified for different names. This is not really possible
  for the usual |AUTHOR| or |EDITOR| fields. In such cases, I have resorted
  to the \sty{biblatex} custom |NAME| and |NAMETYPE| fields which are not
  very portable but until the \bibtex backend support is dropped in |biblatex|
  there is no way round this without making things very messy. This will
  happen around |biblatex| version 2.0.
\item APA style sometimes refers to the «series» of a multi-volume work.
  This corresponds to the |MAINTITLE| field in the \path{.bib} and
  \emph{not} the |SERIES| field.
\item |VOLUME|, |NUMBER| and |CHAPTER| are forced into arabic numerals if
  they are given as roman numerals, as required by \apa{6.22}.
\item |USERB| is sometimes used to specify that a URL is for an abstract
  rather than the paper itself. Not very portable but that's because of |bibtex| data
  model limtations.
\item |USERD| is sometimes used to specify information that indicates
  special formatting. Not very portable but that's because of |bibtex| data
  model limtations.
\item |USERE| is sometimes used to specify questionable dates/authors for
  special formatting. Not very portable but that's because of |bibtex| data
  model limtations.
\end{itemize}

\section{Revision history}

\begin{changelog}

\begin{release}{3.5}{2011-09-05}
\item Fixed issue Editor name part order when in Author position (thanks to
  Johann Bauer)
\end{release}

\begin{release}{3.4}{2011-09-01}
\item Fixed issue with |\fullcite| not resetting |bbx| globals
\end{release}

\begin{release}{3.3}{2011-08-23}
\item Spanish localisation
\end{release}

\begin{release}{3.2}{2011-08-12}
\item Minor fix in |inbook| format
\item Doc clean up
\end{release}

\begin{release}{3.1}{2011-07-31}
\item Made compatible with |biblatex| 1.6
\end{release}

\begin{release}{3.0}{2011-05-06}
\item |maxnames| and |minnames| are now set to sensible things and actually
  used. |biber| $\geq$ 0.9.3 is now required as this implements a fix for
  |uniquelist| in |biblatex| which needs |maxnames| and |minnames| set to
  real values.
\item Fixed bug with commas before «et al» not appearing in some cases.
\end{release}

\begin{release}{2.9}{2011-05-03}
\item APA wants no space between volume and number for articles, even though it's
  horribly ugly\ldots
\item Made urls not optional with |biblatex| url toggle in |ONLINE| entrytype (thanks to Mattias Erll)
\end{release}

\begin{release}{2.8}{2011-04-23}
\item Added a Greek localisation strings file.
\end{release}

\begin{release}{2.7}{2011-04-1}
\item Biber is now a strongly recommended requirement due to APA name and
  name list disambiguation requirements.
\item Updated for biblatex 1.4/biber 0.9 with automatic list
  disambiguation. Package now deals with all APA 6th Edition citation examples.
\end{release}

\begin{release}{2.6}{2011-03-15}
\item Made fullcite use ampersand
\item Added fullcitebib macro to allow fake bib citations
\end{release}

\begin{release}{2.5}{2010-11-24}
\item Refactored hyperref to only link from years to make it
  consistent across cite commands
\item Added hyperref target references section for citation examples
\item Fixed textcite multicite issue
\end{release}

\begin{release}{2.4}{2010-11-14}
\item Fixed postnotes/hyperref for textcite
\end{release}

\begin{release}{2.3}{2010-11-04}
\item Overhauled hyperref functionality and made more robust
\end{release}

\begin{release}{2.2}{2010-10-15}
\item Parameterised max author/editor list (thanks to Paul Thompson)
\item Better rudimentary regression script
\item Completely reconfigured EPRINT/EPRINTTYPE
\end{release}

\begin{release}{2.1}{2010-10-17}
\item New Dutch localisation (thanks to Alexander van Loon)
\end{release}

\begin{release}{2.0}{2010-09-30}
\item Moved to new date format code internally
\end{release}

\begin{release}{1.9}{2010-09-27}
\item Moved docs to LuaLaTeX compat
\item Fixed german/ngerman date formats
\item Cleaned up date format code
\end{release}

\begin{release}{1.8}{2010-08-06}
\item Fixed seven author ellipsis bug
\end{release}

\begin{release}{1.7}{2010-08-05}
\item Corrected dateless entry format, added examples to test doc
\item Corrected multi delim for |\citeyear|
\item Updated test doc for |biblatex| 0.9b compat
\end{release}

\begin{release}{1.6}{2010-07-19}
\item Added correct |\citeyear| definition
\end{release}

\begin{release}{1.5}{2010-07-12}
\item Corrected |NOTE/ADDENDUM| examples
\item Made |\nptextcite| behave more consistently like |\textcite| for multi-cites.
\end{release}

\begin{release}{1.4}{2010-07-07}
\item Removed extra space after DOI
\end{release}

\begin{release}{1.3}{2010-07-05}
\item Fixed Oxford comma bug
\end{release}

\begin{release}{1.2}{2010-06-18}
\item Made style arguments more explicit in |.bbx|
\item Fixed bad documentation due to beta |biblatex| version.
\item Updated docs - minimum |biblatex| version
\end{release}

\begin{release}{1.1}{2010-05-28}
\item Fixed |INBOOK| |citetitle| format to match |BOOK|.
\item Fixed |extrayear| in entries with full date specifications.
\end{release}

\begin{release}{1.0}{2010-05-12}
\item Fixed |TYPE| and |NUMBER| fields in |REPORT| entries. Now more
  flexible.
\item |PUBSTATE| is now valid for articles.
\item |DOI|, if present, suppresses any |URL| field.
\item Abstract retrieval string is now conditional on |USERB| field, not on
  the existence of an abstract.
\item Default strings for |PHDTHESIS| and |MASTERSTHESIS| entries corrected.
\item |LOCATION| is now valid for thesis entries and comes after |INSTITUTION|.
\end{release}

\begin{release}{0.9}{2010-03-08}
\item Update for APA manual 6th edition and |biblatex| 0.9
\end{release}

\begin{release}{0.8}{2010-02-15}
\item Fixed bug with spaces after nptextcite
\item Updated for |biblatex| 0.9
\end{release}

\begin{release}{0.7}{2010-01-20}
\item Made hyperref links more consistent, using the whole citation and not
  just the year.
\end{release}

\begin{release}{0.6}{2009-11-20}
\item Corrected two bugs in |cite| macro which left a trailing space after
  multiple cites and actually cited the year twice for multiple cite
  commands in some circumstances.
\item Corrected bug where |\textcite| would leave a stray open bracket on
  the stack when year was suppressed within a paragraph.
\end{release}

\begin{release}{0.5}{2009-09-19}
\item Replaced literal string with localised form in url macro.
\item Moved localisation strings into \sty{.lbx} files.
\item |\DeclareLanguageMapping| is now needed in preamble.
\item Moved |\DeclareBibliographyExtras| into \sty{.lbx} files.
\item Some support for alternative localised date formats.
\item Fixed slant/italic font problem since the |\mkbibemph| macro had
  changed in \sty{biblatex} 0.8e.
\item Fixed |liststop| error which was preventing name lists with two
  entries from having the comma before the ampersand.
\end{release}

\begin{release}{0.4}{2009-07-24}
\item Fixed bug where multiple year ranges were not displayed properly.
\item Updated to remove pre-\sty{biblatex} 0.8e macros error.
\end{release}

\begin{release}{0.3}{2008-12-21}
\item Updated to use new fields (|EVENTTITLE|) and new options
  (|usetranslator|) from \sty{biblatex} 0.8b.
\end{release}

\begin{release}{0.2}{2008-12-06}
\item Added |noremoteinfo| option).
\item Fixed bbx bug with more than 7 authors still printing names after «et al». Was
  due to resetting maxnames to 999.
\item Removed the customised (hacked) |apa-biblatex.cls| class from the package as
  |apa.cls| version 1.3.4 is compatible with \sty{biblatex}.
\item Altered documentation about requiring the «american» babel option.
  This is not required if you set up |\DeclareQuotePunctuation| yourself.
\item Added minimum required version of \sty{csquotes}.
\item Minor doc tweaks.
\end{release}

\begin{release}{0.1}{2008-12-01}
\item Initial release
\end{release}



\end{changelog}
\end{document}