path: root/macros/latex/contrib/apa6e/apa6e.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011 by Nathaniel J. Smith <njs@pobox.com>
% --------------------------------------------------------
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%    1. Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%    2. Redistributions in binary form must reproduce the above
%       copyright notice, this list of conditions and the following
%       disclaimer in the documentation and/or other materials provided
%       with the distribution.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
% LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
% A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
% HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
% SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
% LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
% DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
% THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
% (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
% OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{apa6e.dtx}
%</driver>
%<class>\NeedsTeXFormat{LaTeX2e}
%<class>\ProvidesClass{apa6e}
%<*class>
    [2011/03/03 v0.3 APA 6e manuscript formatting]
%</class>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{url}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{apa6e.dtx}
\end{document}
%</driver>
% \fi
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
%   \changes{v0.1}{2011/02/12}{Initial version}
%
%   \changes{v0.2}{2011/03/01}{Added support for appendices}
%
%   \changes{v0.3}{2011/07/02}{Added \texttt{floatmarkers}
%   option. Increased |\headheight| to make \textsc{fancyhdr}
%   happy. Made it possible to refer to appendices by
%   label. Implemented the rule that if there is only a single
%   appendix, it is simply called ``Appendix'', not ``Appendix
%   A''. Fixed a bug where floats were sometimes labeled as being in
%   an appendix (like ``Figure A1'') even when they weren't (thanks to
%   J.~Olson and Alex Sommerfeldt for the report and fix).}
%
% \GetFileInfo{apa6e.dtx}
%
% \DoNotIndex{\newcommand,\renewcommand}
% 
%
% \title{The \textsf{apa6e} class\thanks{This document
%   corresponds to \textsf{apa6e}~\fileversion, dated \filedate.}}
% \author{Nathaniel J.~Smith \\ \texttt{njs@pobox.com}}
%
% \maketitle
%
% \section{Introduction}
%
% This is a minimalist class file for formatting manuscripts in the
% style described the American Psychological Association (APA) 6th
% edition guidelines. Perhaps someday the more capable
% \textsf{apa.cls} will gain support for 6th edition APA formatting,
% in which case you should probably use it instead. But in the mean
% time, this class may be useful.
%
% Note that this class relies heavily on existing \LaTeX\ packages to
% do its work. If you're using a reasonably complete \LaTeX\
% distribution like \TeX\ Live then you probably have them already,
% but if not then they can all be retrieved from CTAN.
%
% \section{Usage}
%
% Here's a sample document to get you started:
% \begin{verbatim}
%   \documentclass{apa6e}
%   \usepackage{apacite} % This is not done automatically!
%   \bibliographystyle{apacite}
%   \title{A simple, correct explanation for every aspect of mental function}
%   \shorttitle{Psychology: the end}
%   \author{Over J.~Optimistic\\Pie in the Sky University}
%   \authornote{\dots}
%   \abstract{\dots}
%   \begin{document}
%   \maketitle
%   I have discovered a truly remarkable theory which
%   this example is too small to contain.
%   \bibliography{my-refs}
%   \end{document}
% \end{verbatim}
% Pretty simple, really. But for a few more details, read on.
%
% \section{Appendices}
%
% In APA style, appendices are not named. So to get appendices, use
% the same mechanism as normal \LaTeX (i.e., type |\appendix| to
% switch to `appendix mode' and then use |\section| to start each
% appendix), but note that the section title will be ignored. You can
% type |\section{Stimuli}| or |\section{La La La}| or just
% |\section{}| and you'll get the same result regardless (something
% like ``Appendix B'').
%
% \subsection{References}
%
% This class does not provide any built-in support for formatting
% references in APA style; I suggest using either the classic
% \textsf{apacite} package, or the \textsf{biblatex-apa} package
% (which more accurately implements current APA guidelines, but
% depends on use of the new \textsf{biblatex} system).
%
% If you do use \textsf{apacite}, then this package will automatically
% make sure that it uses the appropriate style of header. If you use
% \textsf{biblatex-apa}, then you're on your own --- if you try this,
% please let me know whether you had to adjust anything!
%
% \subsection{Class options}
%
% This class supports several options.
%
% \subsubsection{\texttt{leavefloats}}
% When reading drafts, I find the APA manuscript format quite
% usable, except that I find it very annoying to have to flip back and
% forth between the text and tables/figures/their captions. Use this
% option if you want to let \LaTeX do use normal handling of floats,
% e.g.: |\documentclass[leavefloats]{apa6e}|.
%
% To make sure you don't forget to take it out before submitting,
% this also inserts a large note on the front page to remind you that
% you are looking at a draft with illegitimate formatting.
%
% \subsubsection{\texttt{floatmarkers}}
% Some people like to leave little markers in the text that say
% ``Figure 3 about here'' and so on. As far as I can tell, this
% is actually not part of APA 6e style, but if you want to do it
% anyway, then this option is here for you:
% |\documentclass{floatmarkers}{apa6e}|.
%
% \subsubsection{\texttt{endnotes}}
% APA style allows footnotes to either be formatted as footnotes
% directly in the text, or placed at the end in a `Footnotes'
% section. By default we do the former; if you really want the latter
% for some reason, then enable this option:
% |\documentclass[endnotes]{apa6e}|.
%
% Of course, if you want multiple, then you can accomplish that in the
% usual way: |\documentclass[leavefloats,endnotes]{apa6e}|.
%
% \subsection{Known limitations}
%
% We currently make no attempt to alter the standard list
% environments (|itemize|, |enumerate|). As far as I can tell they are
% already APA compliant, but they might introduce enough extra
% vertical spacing as to be visually unpleasant. If this bothers you
% and you find a good solution, let me know. (Also, we don't even
% attempt to reproduce \textsf{apa.cls}'s |seriate| environment. I'm
% not sure why one would use it in the first place.)
%
% We only format manuscripts; in particular, there is no equivalent to
% \textsf{apa.cls}'s |jou| or |doc| modes. I don't really see the
% point, personally, so I'm unlikely to fix this, but if you find
% one of these modes useful and want to write some code for it, then
% contributions are welcome.
%
% \subsection{Known \textit{Non}-limitations}
%
% In \textsf{apa.cls}, you cannot have any blank lines around
% |\maketitle|, or formatting gets screwed up. When using
% \textsf{apa6e.cls}, you can use as many blank lines as you like. Go
% crazy.
%
% In \textsf{apa.cls}, you must be careful about where you place your
% captions inside a floating environment --- they must go at the top
% of |table| environments, and at the bottom of |figure|
% environments. In \textsf{apa6e.cls}, you can put your captions
% where-ever you want, and they'll still come out in the right
% place. One less thing to worry about.
%
% \subsection{New macros}
% 
% \DescribeMacro{\mspart}
% This class defines just one new macro, and you shouldn't need to use
% it. But just in case\dots\ |\mspart| is a new sectioning command,
% designed to format the header at the beginning of each APA
% manuscript `part' --- e.g., the abstract, the main body, the
% references, etc. The syntax is exactly the same as for |\section|
% and friends, e.g.: |\mspart{Abstract}|. However, since all the
% standard manuscript parts are generated automatically by other
% macros, this is unlikely to be useful.
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
%
% Define our options, and then load up the standard \textsf{article} class.
%    \begin{macrocode}
\DeclareOption{endnotes}{\def\apaSIXe@endnotes\relax}
\DeclareOption{leavefloats}{\def\apaSIXe@leavefloats\relax}
\DeclareOption{floatmarkers}{\def\apaSIXe@floatmarkers\relax}
%    \end{macrocode}
% All unrecognized options are passed through to \textsf{article}.
%    \begin{macrocode}
\DeclareOption*{%
\PassOptionsToClass{\CurrentOption}{article}%
}
\ProcessOptions\relax
\LoadClass[12pt]{article}
%    \end{macrocode}
% We want to typeset everything in Times, including math.
%    \begin{macrocode}
\RequirePackage{times}
\RequirePackage{mathptmx}
%    \end{macrocode}
% Set margins and justification. If |\headheight| is less than 15 pt,
% \textsc{fancyhdr} will complain.
%    \begin{macrocode}
\RequirePackage[margin=1in,headheight=15pt]{geometry}
\RequirePackage[document]{ragged2e}
%    \end{macrocode}
% APA 6e says that indents should be ``5--7 spaces, or 1/2
% inch''. We'll use the latter.
%    \begin{macrocode}
\setlength{\RaggedRightParindent}{0.5in}
%    \end{macrocode}
% Doublespacing: The \textsf{setspace} package has the good taste to
% disable doublespacing for things like captions and footnotes; the
% APA doesn't. Which is totally reasonable, but it means that we can't
% use \textsf{setspace}. I stole this magic number from the
% \textsf{setspace} code --- it is only correct for 12 pt font. But 
% we only support 12 pt font anyway.
%    \begin{macrocode}
\newcommand{\@doublespacing}{\linespread{1.655}}
\@doublespacing
%    \end{macrocode}
% Set up the running header.
%    \begin{macrocode}
\RequirePackage{fancyhdr}
\setlength{\headheight}{15.2pt}
\fancyhf{}
\renewcommand{\headrulewidth}{0pt}
\rhead{\thepage}
\fancypagestyle{titlepage}{\lhead{Running head: \MakeUppercase{\@shorttitle}}}
\fancypagestyle{otherpage}{\lhead{\MakeUppercase{\@shorttitle}}}
\pagestyle{otherpage}
%    \end{macrocode}
% \subsection{The title page}
% The commands to capture the various bits of the title page and
% abstract.
%    \begin{macrocode}
\newcommand{\shorttitle}[1]{\def\@shorttitle{#1}}
\renewcommand{\title}[1]{\def\@title{#1}}
\renewcommand{\author}[1]{\def\@author{#1}}
\newcommand{\authornote}[1]{\def\@authornote{#1}}
\renewcommand{\abstract}[1]{\def\@abstract{#1}}
%    \end{macrocode}
% And here's how we actually format the title page.
%    \begin{macrocode}
\renewcommand{\maketitle}{%
\thispagestyle{titlepage}%
\vspace*{1in}%
\Centering\@title\\\@author%
\vfill%
\ifdefined%
  \apaSIXe@leavefloats%
  {\large\textbf{\textit{A helpful reminder, courtesy \texttt{apa6e.cls}:} Figures and tables are currently mixed in with
      your text for easier reading. Don't forget to remove the
      \texttt{leavefloats} option before you submit!}\vfill}%
\fi
Author Note\par\RaggedRight\@authornote%
\mspart{Abstract}%
\@abstract%
\mspart{\@title}}
%    \end{macrocode}
% By default, the \textsf{apacite} package will format the beginning
% of the references as if a section, by calling
% |\section{References}|. But that would be wrong. So we override the
% internal command that it uses to do this.
%    \begin{macrocode}
\AtBeginDocument{\def\st@rtbibsection{\mspart{References}}}
%    \end{macrocode}
% \subsection{Captions}
% Caption formatting is complicated. For tables, captions go above the
% float body, and are formatted like:
% \begin{center}
% \framebox{\begin{tabular}{ll}Table 3 \\ \textit{My fabulous table}\end{tabular}}
% \end{center}
% For figures, captions go below the float body, and are formatted like:
% \begin{center}
% \framebox{\textit{Figure 7:} My smashing graph.}
% \end{center}
%    \begin{macrocode}
\RequirePackage{float}
\floatstyle{plaintop}
\restylefloat{table}
\floatstyle{plain} % This puts captions below the figure
\restylefloat{figure}
\RequirePackage[singlelinecheck=off,justification=RaggedRight]{caption}
\DeclareCaptionLabelFormat{tablelabel}{\hspace{-\RaggedRightParindent}#1 #2}
\DeclareCaptionLabelFormat{figurelabel}{\hspace{-\RaggedRightParindent}\textit{#1 #2}}
\DeclareCaptionTextFormat{tabletext}{\hspace{-\RaggedRightParindent}\textit{#1}}
\captionsetup[table]{position=above,labelformat=tablelabel,labelsep=newline,
                     textformat=tabletext}
\captionsetup[figure]{position=below,labelformat=figurelabel}
%    \end{macrocode}
% \subsection{Sectioning}
% First, disable section numbering.
%    \begin{macrocode}
\setcounter{secnumdepth}{0}
%    \end{macrocode}
% Now, redefine the various sectioning commands to look like APA
% titles --- |\section| is APA level 1, |\subsection| is APA level 2,
% etc. This requires we use the |\@startsection| macro, which is very
% confusing. Apparently it is documented in something called
% \texttt{rep10.doc}; I found the relevant snippet at
% \url{http://help-csli.stanford.edu/tex/latex-sections.shtml} and
% reproduce it here for reference:
%
% \begin{verbatim}
% \@startsection {NAME}{LEVEL}{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE} 
%            optional * [ALTHEADING]{HEADING}
%    Generic command to start a section.  
%    NAME       : e.g., 'subsection'
%    LEVEL      : a number, denoting depth of section -- e.g., chapter=1,
%                 section = 2, etc.  A section number will be printed if
%                 and only if LEVEL < or = the value of the secnumdepth
%                 counter.
%    INDENT     : Indentation of heading from left margin
%    BEFORESKIP : Absolute value = skip to leave above the heading.  
%                 If negative, then paragraph indent of text following 
%                 heading is suppressed.
%    AFTERSKIP  : if positive, then skip to leave below heading,
%                       else - skip to leave to right of run-in heading.
%    STYLE      : commands to set style
%  If '*' missing, then increments the counter.  If it is present, then
%  there should be no [ALTHEADING] argument.  A sectioning command
%  is normally defined to \@startsection + its first six arguments.
% \end{verbatim}
%
% \begin{macro}{\section}
% \begin{macro}{\subsection}
% Now, the code. For level 1 and 2 titles, we give them just a
% \textit{little} bit of extra vertical room --- I find it makes them
% much easier to read.
%    \begin{macrocode}
\renewcommand{\section}{\@startsection {section}{1}{\z@}%
    {0.2\baselineskip \@plus 0.2ex \@minus 0.2ex}%
    {0.2\baselineskip \@plus .2ex}%
    {\Centering\normalfont\normalsize\bfseries}}
\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
    {0.2\baselineskip \@plus 0.2ex \@minus 0.2ex}%
    {0.2\baselineskip \@plus 0.2ex}%
    {\normalfont\normalsize\bfseries}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\subsubsection}
% \begin{macro}{\paragraph}
% \begin{macro}{\subparagraph}
% For levels 3--5, we don't add any extra vertical spacing, but we do
% add just a little bit of extra horizontal space between the section
% name and the text. And of course, we need to handle the obligatory
% period.
%    \begin{macrocode}
\renewcommand{\subsubsection}[1]{\@startsection{subsubsection}{3}{\parindent}%
    {0\baselineskip \@plus 0.2ex \@minus 0.2ex}%
    {-\z@}%
    {\normalfont\normalsize\bfseries}{#1}\textbf{.}\hspace{0.2em}}
\renewcommand{\paragraph}[1]{\@startsection{paragraph}{4}{\parindent}%
    {0\baselineskip \@plus 0.2ex \@minus 0.2ex}%
    {-\z@}%
    {\normalfont\normalsize\bfseries\itshape}{#1}\textbf{\textit{.}}\hspace{0.2em}}
\renewcommand{\subparagraph}[1]{\@startsection{subparagraph}{5}{\parindent}%
    {0\baselineskip \@plus 0.2ex \@minus 0.2ex}%
    {-\z@}%
    {\normalfont\normalsize\itshape}{#1}\textit{.}\hspace{0.2em}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\mspart}
% And we define a new sectioning command, for beginning 'manuscript
% parts' (e.g., abstract, main body, references). Unlike section
% headings, these should \textit{not} be bolded, but we do disable
% following indentation. (Note that we cheat and re-use the section
% counter, which doesn't matter since sections are unnumbered anyway.)
%    \begin{macrocode}
\newcommand{\mspart}{\newpage\@startsection {section}{1}{\z@}%
    {-0.2\baselineskip \@plus -0.2ex \@minus -0.2ex}%
    {0.2\baselineskip \@plus .2ex}%
    {\Centering\normalfont\normalsize}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\appendix}
% Appendix handling is pretty straightforward, except that we have to
% rearrange how floats are numbered (they go A1, A2, ... within
% appendix A), and this is complicated by the need to work properly
% with \textsc{endfloat}. So if the \textsc{leavefloats} option is in
% effect, we'll want to change numbering immediately, but if we're
% putting floats at the end, then we need to arrange for the numbering
% changes to happen when \textsc{endfloat} is part of the way through
% processing the floats. This is done by defining
% |\apaSIXe@appendixfloats@setup| appropriately in the two cases,
% below.
%
% The other slightly messy bit is that if there is only one appendix,
% it is called ``Appendix'', but if there is more than one, then the
% first is called ``Appendix A''. So we need to keep track of how many
% appendices the document contains. We do this using a nasty |\label|
% hack to get the necessary information into the \texttt{.aux} file.
%    \begin{macrocode}
\RequirePackage{ifthen}
\renewcommand{\appendix}{\setcounter{section}{0}
    \renewcommand{\section}[1]{\addtocounter{section}{1}
        \ifthenelse{\equal{\value{section}}{2}}
            {\label{apaSIXe@has@multiple@appendices}}
            {}
        \apaSIXe@appendixfloats@setup{\Alph{section}}
        \def\@currentlabel{\Alph{section}}
        \ifdefined\r@apaSIXe@has@multiple@appendices
          \mspart{Appendix \Alph{section}}
        \else
          \mspart{Appendix}
        \fi}}
\newcommand{\apaSIXe@appendixfloats@figureson}[1]{%
    \setcounter{figure}{0}%
    \renewcommand{\thefigure}{#1\arabic{figure}}}
\newcommand{\apaSIXe@appendixfloats@tableson}[1]{%
    \setcounter{table}{0}%
    \renewcommand{\thetable}{#1\arabic{table}}}
%    \end{macrocode}
% \end{macro}
% \subsection{Endnotes}
% If the user requested endnotes, then set them up here. I'm not sure
% why you'd want this, but I wrote the code before realizing that
% ordinary footnotes were legal, so you get the benefit of my
% mistake.
%    \begin{macrocode}
\ifdefined\apaSIXe@endnotes
    \RequirePackage{endnotes}
    \renewcommand{\enoteheading}{\mspart{Footnotes}}
    \def\enotesize{\normalsize}
    \renewcommand{\footnote}[1]{\def\apaSIXe@hasendnotes\relax{}\endnote{#1}}
    \AtEndDocument{\ifdefined \apaSIXe@hasendnotes \theendnotes \fi}
\fi
%    \end{macrocode}
% \subsection{Floats at the end}
% This must come after the endnotes handling above, since they both
% use |\AtEndDocument| and floats are supposed to come after
% footnotes.
%
% If \textsc{endfloat} is in use, then we have to arrange for
% |\apaSIXe@appendixfloats@figureson| and
% |\apaSIXe@appendixfloats@tableson| to be called partly through the
% floats being processed. We accomplish this by writing out a calls to
% them in the \texttt{fff} and \texttt{ttt} files that
% \textsc{endfloat} uses. (Note that it's important to have two
% different commands --- we used to have just one, but then whichever
% file was loaded first turned on the appendix mode half-way through,
% and then appendix mode was in effect for \textit{all} of the other
% file.) If \texttt{floatmarkers} option is in effect, then we also
% need to make sure that the markers for floats in the appendix use
% the right numbers --- and these use different counters.
%    \begin{macrocode}
\ifdefined\apaSIXe@leavefloats
    \newcommand{\apaSIXe@appendixfloats@setup}[1]{%
      \apaSIXe@appendixfloats@tableson{#1}%
      \apaSIXe@appendixfloats@figureson{#1}%
    }
\else
    \ifdefined\apaSIXe@floatmarkers
        \relax
    \else
        \PassOptionsToPackage{nomarkers}{endfloat}
    \fi
    \RequirePackage[nolists,noheads,tablesfirst]{endfloat}
    \AtBeginDelayedFloats{\@doublespacing}
    \newcommand{\apaSIXe@appendixfloats@setup}[1]{%
        \setcounter{postfig}{0}%
        \renewcommand{\thepostfig}{#1\arabic{postfig}}%
        \setcounter{posttbl}{0}%
        \renewcommand{\theposttbl}{#1\arabic{posttbl}}%
        \efloat@iwrite{fff}{%
            \string\makeatletter\string\apaSIXe@appendixfloats@figureson{#1}\string\makeatother}%
        \efloat@iwrite{ttt}{%
            \string\makeatletter\string\apaSIXe@appendixfloats@tableson{#1}\string\makeatother}}
\fi
%    \end{macrocode}
% 
% \Finale
\endinput