path: root/macros/latex/contrib/apa/apacls.txt

This is file apacls.txt, which contains instructions for using the
APA LaTeX2e class file apa.cls 

 Athanassios Protopapas  *******  Version 1.3.4 December 2008


Introduction

 apa.cls is a LaTeX2e class file that makes your document conform to
 the APA Publication Manual (Fifth Edition, 2002) specifications for
 manuscripts or to the APA journal look found in journals like the
 Journal of Experimental Psychology etc. In addition, it provides a
 regular LaTeX-like output with a few enhancements and APA-motivated
 changes.  The headings and enumeration/seriation code is taken from
 theapa.sty by Young U. Ryu.

Note

 apa.cls is not in any way connected to, endorsed by, or even 
 probably known at all at the American Psychological Association.  


Description

 a) Manuscript mode (man)

 apa.cls typesets a title page, abstract page, text body, then
 references, author notes, footnotes, tables, figure captions, and
 figures. All text is double spaced. The title page contains
 (centered) the title, author name, affiliation, short title, and the
 running head (automatically capitalized).  A note is inserted in
 place of each table and figure in the text.

 The title is printed as a heading at the beginning of the text (don't
 include an extra \section, because the introduction is not supposed
 to be titled in printed articles). \leftheader is ignored in
 manuscript mode. The contents of \note are printed under the author
 names and affiliations, typically the date of submission. The "Author
 Notes" page contains the contents of \acknowledgements.  A footnote
 page is only produced if there is at least one footnote in the text.

 b) Journal mode (jou)

 apa.cls typesets the text in double-sided, double column format, with
 an appropriately centered title, author names, affiliations, note,
 and abstract.  The contents of acknowledgements are printed as
 footnotes in a box at the lower left corner of the first page.
 Journal-like headers can also be produced on the first page.
 Dimensions and overall "look" are modeled after JEP:HPP.  The purpose
 of this mode is to produce readable and reasonably condensed output
 for double-sided printing and distribution.

 c) Document mode (doc)

 apa.cls typesets the text in single-sided, single-column format, with
 an appropriately centered title, author names, affiliations, note,
 and abstract on the first page. The contents of acknowledgements are
 printed at the bottom of the first page. Section headings and
 enumeration follow the APA guidelines and floats (figures and tables)
 are inserted in the text where they are defined, as in regular LaTeX
 articles.

 The purpose of this format is to provide hardcopies during the
 development of articles that are later going to be submitted (using
 the manuscript format) and distrubuted (using the journal
 format). The advantage over using a regular article class is that all
 the extra definitions related to APA style are supported (or simply
 ignored without producing errors), so no changes need to be made
 to the text other than the format parameter.


Known restrictions:

 - Up to six affiliations (for article author(s)) are supported.
 - No provision for A4 paper.  See examples for a workaround.


Other necessary files:

 To use BibTeX (default), for all apa.cls document modes you need
 apacite.sty and apacite.bst. Download the most recent version
 (June 2005 or later) for full compatibility.
 If you prefer to use BibLaTeX with the biblatex-apa style, you 
 need apa.cbx and apa.bbx.

 For manuscript mode, you need endnotes.sty and endfloat.sty 

 For journal mode, optional packages include txfonts (or pslatex,
  or times.sty and mathptm.sty), ftnright.sty, fancyhdr.sty (for 
  first page headers), and flushend.sty


To use this class, include one of the following

 \documentclass[jou]{apa}  for the two-column output (txfonts default)
 \documentclass[man}{apa}  for the manuscript (double-spaced) output
 \documentclass[doc]{apa}  for regular document (in computer modern)
   
 at the beginning of your file (instead of {article}), then define the
 title, author, etc. (see below), and start with

 \maketitle

 right after \begin{document}, immediately followed by the first
 paragraph of you text (no blank line). Do not use a
 \bibliographystyle command, because apacite is selected automatically
 (for backwards compatibility, any existing \bibliographystyle command
 is ignored and a warning is issued).

 The journal format uses Times Roman by default (it does look like
 published after all); if you don't have txfonts or pslatex or 
 times.sty, or if you just prefer computer modern, add notxfonts 
 after the jou option in the class line: 
 \documentclass[jou,notxfonts]{apa} 
 (this has no effect in modes other than jou and may be left in)

 Manuscript format uses Computer Modern by default but can use
 Helvetica or typewriter look by using the options helv or tt,
 respectively. I find the result with either of these much more
 "manuscript"-like but that's a matter of taste.  These options have
 no effect in modes other than man and may be left in when switching.


The following commands are defined and should/may be used:

 1. Required for document compilation

 \title{Title}                          
 \author{Author Name(s)}                
   or \twoauthors{First Author(s)}{Second Author(s)}
   or \threeauthors{John and Jim}{Mary and Sue}{Nick}
   or \fourauthors{Helen}{Dick}{Tracy and Larry}{James Bond}
   or \fiveauthors{...}{...}{...}{...}{...}
   or \sixauthors{...}{...}{...}{...}{...}{...}
 \affiliation{Department\\ University}  
   or \twoaffiliations{Affiliation of 1st Author(s)}{Affil. of 2nd Author(s)}
   or \threeaffiliations{U of A}{U of B}{U of C}
   or \fouraffiliations{My Company}{Your Department}{Heaven}{Earth}
   or \fiveaffiliations{...}{...}{...}{...}{...}
   or \sixaffiliations{...}{...}{...}{...}{...}{...}

 \maketitle                                    % right after \begin{document}

 2. Strongly recommended (required by APA)

 \abstract{Abstract}                    
 \acknowledgements{Author notes etc.}   
 \rightheader{Running head}                    % defaults to title
 \shorttitle{Short title}                      % defaults to title
 \leftheader{Authors}                          % defaults to author 

 3. Optional, possibly helpful 

 \note{Draft/submission date, etc.}	           % To add notes on first page
 \thickline                                    % Use in tables for the top line
 \centeredcaption{width}{caption-text}         % Used with double-column figures 
                                               %  to create centered captions
                                               %  narrower than \textwidth

 \fitfigure[optional-height]{eps-filename}     % Automatically fit a postscript 
                                               %  figure; load graphicx and use
                                               %  instead of \includegraphics
 \fitbitmap[optional-height]{eps-filename}     % Same as \fitfigure but won't scale
                                               %  figure in man mode for best 
                                               %  reproduction of bitmap figures

 \ifapamode{man-code}{jou-code}{doc-code}      % Do different things depending on
 \ifapamodeman{man-mode-code}{doc-or-jou-code} %  mode---you shouldn't have to use
 \ifapamodejou{jou-mode-code}{doc-or-man-code} %  any of these but they're here if
 \ifapamodedoc{doc-mode-code}{man-or-jou-code} %  you want them.  Arguments can
                                               %  be left empty to do nothing

 \journal{Journal name or other note}          % Top left header on page one in
                                               %  jou/doc mode, ignored in man mode
 \volume{Volume, number, pages}                % Top left, under content of \journal
 \ccoppy{Copyright notice etc.}                % Top right header in jou/doc p. 1
 \copnum{Your hovercraft is full of eels}      % Top right, under content of \ccoppy

 \tabfnm{a}				             % Put a note mark inside a table cell
 \tabfnt{a}{Note text}			       % Put the mark and text for a table note
 \apavector{A}				       % Format a symbol as vector by APA rules
 \appendix				             % Standard LaTeX usage, starts off
					             %  appendix section(s)


The following options are available:

 These options must be combined with one of jou, man, doc.

 notxfonts: Effective in jou mode, prevents txfonts from loading, in case
             pslatex (or times) is preferable for some reason
 notimes  : Effective in jou mode, cancels loading txfonts or pslatex or 
             times and uses computer modern fonts.
 nosf     : Effective in man mode, neutralizes the \helvetica command.
 fignum   : Effective in man mode, adds figure numbering to the figure pages.
             Makes it easier to refer to figures and I recommend it for the
             reviewers' copies, but for the original figures you may have
             to print them without this and write the number on the back.
 notab    : Effective in jou mode, cancels the automatic stretching of tabular
             environments to the width of their enclosing float.
 nobf     : Effective in man mode, turns off boldface in section headers
 helv	    : Effective in man mode, uses Helvetica as the base typeface
 tt	    : Effective in man mode, uses a typewriter base typeface
 babel    : Effective in every mode, loads babel to support languages other
             than English. List the desired languages as additional options
             to apa.cls after babel. The last language listed is the main one. 
 longtable: Only usable in man mode, loads longtable.sty if you *really* must
             use long tables in your manuscript.  See special note below
 floatmark: Effective in man mode, inserts placeholders for floats in text
             ("Insert Figure X about here" -- no longer required by APA)
 noapacite: Effective in every mode, prevents loading of apacite to allow
           use of biblatex with the biblatex-apa style.


Notes on usage:

 If there is more than one author but all in the same department, use
 the \author command with all names and the \affiliation command. If
 there are people from two different departments, use the \twoauthors
 and \twoaffiliations commands to group them appropriately.  For three
 affiliations use \threeauthors and \threeaffiliations, and so on for
 four, five, or six affiliations (and corresponding author groups).

 Default sectioning maps \section, \subsection, and \subsubsection to
 the three-level heading definitions of the APA manual.  If you need
 more/fewer heading levels, you can use the command
 \headinglevels{four} (or any number between one and five---spelled
 out---instead of four) and then use \paragraph and \subparagraph for
 the lower-level sectioning. Don't bother to \label your sections
 because they can't be \ref'd since they are not numbered in APA style.

 When a figure is too wide for a single column, use a double-column
 figure (\begin and \end {figure*} instead of {figure}). When using
 double column figures, it looks better if you use \centeredcaption
 instead of caption, with the first parameter about equal to the width
 of the float (table or figure). This makes no difference in
 manuscript mode.

 It is still *your* responsibility to format the tables in accordance
 with the APA guidelines (e.g., no vertical lines, and so on) and
 precede the actual table body with its caption (i.e., use \caption
 *before* \begin{tabular} in tables, or the results won't be
 conforming to the APA requirements for tables). Because a paragraph
 break is inserted in manuscript mode (along with the "insert
 table/figure" note), don't define tables in the middle of a
 paragraph.

 Remember to use \label for floats *after* the caption (and not inside it!)

 For instructions on using the various citation forms get apacite.tex,
 testAPA.tex, and readme.apa from the CTAN mirror near you.  For
 instructions on using APA enumeration and seriation read apaenum.txt
 in this distribution.

 (BibLaTeX users: pass the "noapacite" option to apa.cls and then use
 biblatex as usual, with the biblatex-apa style.)

 If you need to use additional options for article.cls, use them with
 the apa.cls options and they will be automatically passed along to
 article.cls

 Notes in tables: There is a semi-automatic way to include notes in
 tables such as, for example, to indicate levels of significance.  The
 command \tabfnm{X} inside a table cell (tabular environment) produces
 the note mark.  Use \tabfnt{X}{Note text} immediately before or after
 \end{tabular} inside the table environment to produce the note text.
 See example file.

 Appendices: Use the command \appendix only once, at the point where
 your (first) appendix starts.  Then use \section{Appendix Title} to
 start each appendix section (even if there is only one).  You may use
 cross-references to appendixes, because they are numbered, if there
 are more than one.  The command \label{app:xxx} after the appendix
 \section sets the label.  Refer to it with "Appendix~\ref{app:xxx}"
 anywhere in the article.

 If you use vectors, the command \apavector{X} will make your life easier.

 Long tables: By popular demand, longtable now (sort of) works with
 apa.cls.  You must *not* load the longtable package yourself;
 instead, pass the longtable option to apa.cls (due to precedence
 requirements for proper endfloat function and cross-definitions).
 Since longtable only works in single-column documents it can only be
 used with man mode.  Unfortunately the ifapamode commands won't work
 to keep a single table body and apply a mode-specific (table or
 longtable) environment because of illegal cross-nesting with
 environment begin/end.  In fact the table environment won't even work
 inside in ifapamode argument, which makes it impossible to have a
 single file that can be processed for both man and jou.  This defeats
 the purpose of apa.cls, so only resort to longtable if you absolutely
 have to.  You will need the special APAendfloat.cfg file supplied with 
 apa.cls in order to use longtable, so that endfloat will recognize
 (and postpone) long tables as tables.  Copy this file to the working
 folder with your APA style document, not any central LaTeX location,
 to avoid influencing endfloat's behavior with other classes. Rename
 it locally to endfloat.cfg so that it will be processed by endfloat.

 Sideways tables: Use the rotating package and \sidewaystable. You will
 need the supplied APAendfloat.cfg (renamed endfloat.cfg) in your
 document directory for it to work.


Feedback:

 Send me comments or bug reports (preferably with fixes) at:
 protopap@ilsp.gr


Example of usage:

 See examples.txt and apaexample.tex
 PLEASE, read file examples.txt, it will probably solve your problems.

 Online information: http://www.ilsp.gr/homepages/protopapas/apacls.html


Athanassios Protopapas
August 17, 2008