diff options
author | Karl Berry <karl@freefriends.org> | 2010-03-08 01:16:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-03-08 01:16:47 +0000 |
commit | f8781b660c74ce51709b40d75de1d58597a54eaa (patch) | |
tree | bc5c72c372ceaa786bd6bb29c543306aa9e87dfe /Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex | |
parent | 4e7ace252f5bb59a3813d0d829a5343667755499 (diff) |
biblatex-apa .09 (7mar10)
git-svn-id: svn://tug.org/texlive/trunk@17375 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex new file mode 100644 index 00000000000..5951fd29281 --- /dev/null +++ b/Master/texmf-dist/doc/latex/biblatex-apa/biblatex-apa.tex @@ -0,0 +1,377 @@ +% $Id$ +\documentclass{ltxdockit} +\usepackage[utf8]{inputenc} +\usepackage[british]{babel} +\usepackage[strict,babel=once]{csquotes} +\usepackage{shortvrb} +\usepackage{ifthen} +\MakeAutoQuote{«}{»} +\MakeShortVerb{\|} + +\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={0.9}, + 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 (5th Edition). + +\subsection{Requirements}\label{ref:req} + +You will need to be using \sty{csquotes} ($\geq$ 4.3) and \sty{biblatex} +($\geq$ 0.9). 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.6.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\ 2010). + +\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. There are +some parts of the requirements which are impossible to automatically +satisfy given the current reliance of \sty{biblatex} (as of version +\texttt{0.8}) on \bibtex . These limitations are described below. + +\subsection{Acknowledgments} + +I wished I could acknowledge someone as then this wouldn't have been such a +huge piece of work \ldots\ thanks to Philipp Lehman for \sty{biblatex} which +really has been a major advance over pure \bibtex. + +\section{Use}\label{ref:use} +\label{use} +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. + +\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 vast majority of the APA citation +and references style is implemented, there are just a few exceptions which +are either hardly worth the coding pain for such rare cases or which are +impossible due to \sty{biblatex} limitations. It is likely that with future +\sty{biblatex} versions some or indeed all of these limitations may be +lifted but that's not likely until after \sty{biblatex} version +\texttt{1.0}, according to the |biblatex| author Philipp Lehman. + +\subsubsection{maxnames/minnames} + +You can't reset these |biblatex| options in your document--you'll get a +message about conflicting options. These are set to ``999'' in |apa.bbx| +because of the tricky requirements for APA name list truncation. The +truncation is then done in the author list code rather than by using these +options. Sorry. This will be changed when |biblatex| moves to using |biber| +as a backend with a more sophisticated data model. + +\subsubsection{Citation Limitations} + +\begin{itemize} +\item \apa{6.14} Disambiguation of truncated author name lists. This is + currently impossible to automate via a \sty{biblatex} style. The + \sty{maxnames} and \sty{minnames} options of \sty{biblatex} only serve to + specify the truncation limits but do not disambiguate name lists which + truncate to the same string. This cannot be reliably done in the style + since it would need to build a backwards and forward list of identical + truncations and map these onto the internal \sty{fullhash} field of + \sty{biblatex} in order to determine which truncations need + disambiguating. Since there is no way of knowing, when you truncate + something, whether something later in the document would have the same + truncation (without \path{.aux} file support anyway), this is not really + possible. It's also further complicated by the fact that \bibtex doesn't + really support name lists in a way which would make this possible and + since the main name list processing is done in \sty{biblatex} by \bibtex + still, there isn't much that can be done about this at the moment until + \sty{biblatex} moves to using something other than \bibtex for its data. + See the following Usenet thread:\\ + + \url{http://groups.google.com/group/comp.text.tex/browse_thread/thread/f3c50d7065159ad4#}\\ + + A related issue is that the \sty{uniquename} option doesn't work in lists + of authors, again because all the name processing is done by \bibtex. + Currently, \sty{biblatex} disambiguates non-unique names in lists by + using the \sty{labelyear} mechanisms which is against APA style (and most + styles since this is supposed to disambiguate same author(s)/different + year situations) but there's nothing really that can be done about it at + the moment. Thankfully, these two problems are not that common and only + occur when you have long lists of authors which share many members with + variations in initials etc. +\end{itemize} + +\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{biblatex-apa.cbx}] The |biblatex-apa| citations style. It is + decently structured with comments but shouldn't need to be read for + normal use. +\item[\path{biblatex-apa.bbx}] The |biblatex-apa| references style. It is + decently structured with comments but shouldn't need to be read for + normal use. +\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 would +be really too much to completely automate as it is 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}. + +\subsection{References} + +The references style was based on the \sty{biblatex} default +|authoryear-comp| style but is so heavily modified, it's almost +unrecognisable. Some general notes: +\begin{itemize} +\setlength{\itemsep}{0pt} +\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 (again, another limitation of + \bibtex, see \ref{use:limit} above). In such cases, I have resorted to + the \sty{biblatex} custom |NAME| and |NAMETYPE| fields which are not very + portable but until \bibtex is replaced by something more flexible, there + is no way round this without making things very messy. +\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 |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}{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 withing 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} |