path: root/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa-test.tex

\documentclass[paper=a4]{article}
\usepackage[american]{babel}
\usepackage{csquotes}
\usepackage{shortvrb}
\usepackage{ifthen}
\usepackage{color}
\usepackage[retainmissing]{MnSymbol}
\usepackage[top=2.5cm]{geometry}

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

% Biblatex
\usepackage[style=apa,backend=biber]{biblatex}

% Custom settings for misc entries in order to format the table for 6.13*
% This table implies that the examples on each line are in a seperate
% document but since we are generating the citations from a real data
% source, we have to prevent the usual uniquelist processing by making
% all of the examples MISC entrytypes and changing uniquelist
% per-type. There is no point in just typsetting static data as this
% wouldn't be a test of anything.
\ExecuteBibliographyOptions[misc]{uniquelist=false}
\DeclareNameFormat[misc]{labelname}{%
  \ifthenelse{\value{listcount}=1\OR\value{listtotal}=2}
    {\usebibmacro{labelname:doname}{#1}{#2}{#3}{#4}{#5}{#6}{#7}{#8}}
    {\ifthenelse{\value{listtotal}>5}
      {\ifnum\value{listcount}=2 \andothersdelim\bibstring{andothers}\fi
       \ifnum\value{listcount}>2 \relax\fi}
      {\ifciteseen
       {\ifnum\value{listcount}=2 \andothersdelim\bibstring{andothers}\fi
        \ifnum\value{listcount}=3 \relax\fi
        \ifnum\value{listcount}=4 \relax\fi
        \ifnum\value{listcount}=5 \relax\fi}
       {\usebibmacro{labelname:doname}{#1}{#2}{#3}{#4}{#5}{#6}{#7}{#8}}}}}

\MakeShortVerb{\|}

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

\setlength{\parskip}{3ex}

\makeatletter
% This solution to detokenize leaving a space after the command and
% arguments is due to Bruno Le Floch on T.SE
\long\def\apaexi#1%
  {%
     \catcode64=11
     \begingroup
        % Ensure that every character is preserved by \lowercase.
        \count@\z@
        \loop\ifnum\count@<256
          \lccode\count@\z@
          \advance\count@\@ne
        \repeat
        % Except spaces, changed to ^^A
        \lccode32=\@ne
        \lowercase
          {%
            \endgroup
            \expandafter\test@\detokenize{#1}\relax%
            \catcode64=12
          }%
  }
% Then map {^^A => space, space =>} onto the string.
\def\test@#1%
  {%
    \ifx#1\relax\test@end\fi
    \ifnum`#1=\@ne\space\else#1\fi
    \test@
   }
\def\test@end\fi#1\test@{\fi}

\def\apaex#1{\hbox{\hspace{-4em}\texttt{\small\apaexi{#1}}}\\$\rcurvearrowse$ \textbf{#1}}
\def\apaexs#1{\hbox{\texttt{\footnotesize\apaexi{#1}}} \textbf{\small #1}}
\makeatother

% This just makes it easier to find a specific (APA 7.x) example in the
% typeset references section
\reversemarginpar
\renewbibmacro*{begentry}{\marginpar{\footnotesize \textcolor{blue}{\thefield{entrykey}}}}

\usepackage[colorlinks=true]{hyperref}

%%%%%%%%%%%%%%%%%%%%%%%%%%%% END PREAMBLE %%%%%%%%%%%%%%%%%%%%%%%%%
\DeclareLanguageMapping{american}{american-apa}

\begin{document}
\section*{|biblatex-apa| style examples}
This file typesets just about all useful examples from
\apa{6.11}--\apa{6.21} and \apa{7.01}--\apa{7.11}. Please refer to the
|biblatex-apa-test-references.bib| file for details on the references
entries. The |.bib| key for each entry in the References section is listed
for convenience in the left margin. The keys are not arbitrary and consist
of the APA section they are taken from (7.01--7.11), followed by a colon,
followed by the example number. This makes it easier to cross-reference
the typeset examples with the commented |.bib| file. I chose not to put the
examples in the References section in example number order so that the APA
requirements for References list alphabetisation and order could also be
demonstrated.

\section*{Citations}
\begin{refsection}[biblatex-apa-test-citations]
\noindent Please see accompanying file |biblatex-apa-test-citations.bib|
for the bibliographic entries which these examples use.

\noindent\apa{6.11}\\
Simple cite. «Jr.» suffix is not shown (bib entry for this example has a suffix):\\
\apaex{\textcite{6.11}}

\noindent Within a paragraph, not in the «narrative sense»:\\
\apaex{\parencite{6.11}}

\noindent To cite the parts separately:\\
\apaex{\citeyear{6.11}, \citeauthor{6.11}}

\noindent The per-paragraph rules for elision of years are more flexible in
APA 6th edition. There is more discretion to do this as the narrative
consistency suggests and so this style no longer automatically elides years
after the first mention within a paragraph. Cases can be handled as
per the examples above.

\noindent\apa{6.12} \apa{6.13}\\
Citations like\\
\apaex{\textcite{6.12a}}\\
which have two authors are never name-truncated after the first cite:\\
\apaex{\textcite{6.12a}}

\noindent First citation of 3--5 author entry:\\
\apaex{\textcite{6.12b}}

\noindent Subsequent first citations in a paragraph:\\
\apaex{\textcite{6.12b}}\\
Subsequent citations within a paragraph:\\
\apaex{\citeauthor{6.12b}}

\noindent Note that the dropping of the year for subsequent paragraph
citations is not automatic as there may be cases where you don't want to do
this (see APA 6.11).

\noindent Automatic list disambiguation for ambiguous truncations after
first cite\footnote{This feature is fairly deep magic and only works when using
  biblatex 1.4+ together with biber 0.9+}. Note that «et al» is plural so
it will only truncate two or more names. If it would truncate just one
name, we just give the name:\\
\apaex{\textcite{6.12c}}\\
\apaex{\textcite{6.12d}}\\
\apaex{\textcite{6.12c}}\footnote{This example is incorrect in the
  APA manual because «et al» is replacing only one name. This has been
  verified with the APA and will be corrected in future editions.}\\
\apaex{\textcite{6.12d}}

\noindent Multiple-authors in running text are separated by «and».
However, in parenthetical cites, multiple authors are separated by «\&»:\\
\apaex{\textcite{6.12e}}\\
\apaex{\parencite{6.12f}}

\noindent Automatic list disambiguation for ambiguous truncations again,
this time the truncation is on first cite as there are more than 5 authors:\\
\apaex{\textcite{6.12g}}\\
\apaex{\textcite{6.12h}}

\noindent The following table replicates with real data the examples
in Table 6.1, p.~177 of the APA 6th Edition manual. Note that this
table in the APA manual essentially assumes that the citations on each
line are in a separate document since there is no list disambiguation
or repeated cite truncations between lines. To simulate this with real
data, the source for this document uses |\citereset| between lines and
makes all of the data entries of MISC type, unsetting «uniquelist» for
this type and using a custom labelname style.

\begin{center}
\begin{tabular}{lllll}
\textbf{\parbox{2cm}{\center Type of citation}} & \textbf{\parbox{2.4cm}{\center First
    citation in text}} & \textbf{\parbox{2.4cm}{\center Subsequent citations in
    text}} & \textbf{\parbox{2.4cm}{\center Parenthetical format, first citation
    in text}} & \textbf{\parbox{2.4cm}{\center Parenthetical format, subsequent
    citations in text}}\\\\
\hline
\\
\parbox{2cm}{\raggedright One work by one author}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13a}}} &
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13a}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13a}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13a}}}\\\\
\parbox{2cm}{\raggedright One work by two authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13b}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13b}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13b}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13b}}}\\\\
\parbox{2cm}{\raggedright One work by three authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13c}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13c}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13c}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13c}}}\\\\
\parbox{2cm}{\raggedright One work by four authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13d}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13d}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13d}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13d}}}\\\\
\parbox{2cm}{\raggedright One work by five authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13e}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13e}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13e}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13e}}}\\\\
\parbox{2cm}{\raggedright One work by six authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13f}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13f}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13f}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13f}}}\\\\
\parbox{2cm}{\raggedright Groups (readily identified through abbreviation) as authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13g}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13g}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13g}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13g}}}\\\\
\parbox{2cm}{\raggedright Groups (no abbreviation) as authors}
& \parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13h}}} & 
\parbox{2.4cm}{\raggedright\apaexs{\textcite{6.13h}}}\citereset
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13h}}}
& \parbox{2.4cm}{\raggedright\apaexs{\parencite{6.13h}}}\\\\
\hline
\end{tabular}
\end{center}

\noindent\apa{6.14}\\
Citations of an entry with an author who shares a
surname with another entry always appears with initials\footnote{This is,
  as with automatic name list disambiguation, fairly deep magic only
  possible with biblatex 1.4+ and biber 0.9+}. Note that the APA example
for this is not really correct for any automated system as the ambiguous
surname should be disambiguated with initials in both cases---we still
don't really know in the APA example whether the Light in the 2008 paper is
the same as the Light in the 2006. The disambiguation performed by biblatex
makes this clear (or as clear as it can be):\\
\apaex{\textcite{6.14}}\\
\apaex{\textcite{7.01:3b}}

\noindent\apa{6.15}\\
Use |SHORTTITLE| field of the entry if it exists:\\
\apaex{\parencite{6.15a}}\\\\
Books, reports etc. use italics instead of quotes:\\
\apaex{\textcite{6.15b}}\\\\
Citing anonymous author:\\
\apaex{\textcite{6.15c}}

\noindent\apa{6.16}\\
Two or more works withing the same parentheses:\\
\apaex{\parencite{6.16a,6.16b}}\\
\apaex{\parencite{6.16c,6.16d,6.16e}}

\noindent Citations of works by same authors in the same year:\\
\apaex{\parencite{6.16f,6.16g,6.16h,6.16i,6.16j}}\\\\
\textcolor{red}{Note: This example, (p.~178 APA Manual 6th edition, 2nd
  printing) is slightly odd as the «in press-a» is not indicated and
  should be «in press» since no other in press items are listed for the
  same authors in the example.}

\noindent Compact citations in alphabetic order:\\
\apaex{\parencites{6.16k,6.16l}}

\noindent Compact citations with special order:\\
\apaex{\parencites{6.16m}[see also][]{6.16n,6.16o}}

\noindent «in press» should have hyphen before disambiguating part of label
(also in references):\\
\apaex{\parencite{6.16p,6.16q,6.16r}}

\noindent\apa{6.17}\\
Secondary sources:\\
\apaex{\parencite[as cited in][]{6.17}}

\noindent\apa{6.18}\\
Classical works:\\
\apaex{(\citeauthor{6.18a}, trans. \citeyear{6.18a})}\\
\textcolor{red}{Note: The example is managed using lower-level cite
  commands. This is another example of the APA not really thinking about
  automated processing and specifying an anomalous infix format. It would
  be better and probably acceptable for it to be:}\\
\apaex{\parencite[][trans.]{6.18a}}\\\\
Entries with an |ORIGYEAR| field will automatically use it:\\
\apaex{\textcite{6.18b}}\\\\
The other examples of standard classical texts in this section should just
be typed by hand--there is little benefit to automating these examples and
they wouldn't usually be in the References section anyway.

\noindent\apa{6.19}\\
These examples are easily dealt with using standard |biblatex| functionality.\\
\apaex{\parencite[][10]{6.19a}}\\
\apaex{\parencite[][Chapter 3]{6.19b}}

\noindent\apa{6.20}\\
Such cases are just typed out--they have no Reference section entry and
don't therefore have a bibliography database entry.

\noindent\apa{6.21}\\
Within parentheses, use the |\nptextcite| command which is equivalent to
the |\textcite| command but omits the parenthesis and uses commas instead.
See the |biblatex-apa| docs.\\
\apaex{(\nptextcite[see Table 3 of][]{6.21} for complete data)}

\noindent\apa{6.28}\\
Entries with no date use «n.d.».\\
\apaex{\textcite{6.28a}}\\
\apaex{\parencite{6.28a}}\\
\apaex{(\nptextcite{6.28a})}

\noindent\apa{7.01:12c}\\
Issue with no editors\\
\apaex{\parencite{7.01:12c}}

\noindent\apa{A7.07}\\
A patent citation uses the title but with no quotes\\
\apaex{\textcite{A7.07}}\\
\apaex{\parencite{A7.07}}

\noindent Some tests of uniqueness and uniquelist

\noindent Two works by same authors in same year are disambiguated by extrayear «a»
and «b» and are truncated after first cite because it is the same author
list and therefore not ambiguous:\\
\apaex{\textcite{UL1}}\\
\apaex{\textcite{UL1}}\\
\apaex{\textcite{UL2}}\\
\apaex{\textcite{UL2}}\\

\noindent One author list is an ordered subset of the other and so both need fully
expanding to be properly disambiguated. Truncating either would be ambiguous.\\
\apaex{\textcite{UL3}}\\
\apaex{\textcite{UL3}}\\
\apaex{\textcite{UL4}}\\
\apaex{\textcite{UL4}}

\noindent Some misc citation cases\\
\apaex{\textcite{6.16c,6.16d,6.16e}}\\
\apaex{\textcite{6.16f,6.16g,6.16h}}\\
\apaex{\textcite{6.16f,6.16g,6.16h,6.16i,6.16j}}\\
Note here that the multicite delimiter is a comma as in running text, a
semi-colon would be strange:
\apaex{\textcites{6.16f}{6.16g}{6.16h}{6.16i}{6.16j}}\\
\apaex{\cite{6.16f,6.16g,6.16h,6.16i,6.16j}}\\
\apaex{\cite{6.16k,6.16l}}\\
\apaex{\fullcite{FC1}}\\
\apaex{\fullcitebib{FC1}}

\noindent Testing «with»\\
\apaex{\cite{with1}}\\
\apaex{\textcite{with1}}

\noindent Testing author name citing\\
\apaex{\citeauthor{ca1}}\\
\apaex{\citeauthor{ca1}}

\end{refsection}
\begin{refsection}[biblatex-apa-test-references]
\nocite{*}
\end{refsection}
\newpage
% Just (APA 7.x) real references and related entry examples here
\printbibliography[section=2]
\newpage
% Include a references section for citation examples just so hyperref
% targets can be checked
\printbibliography[section=1,title=Misc citation references for checking hyperref targets]
\end{document}