%^^A* legal notices % \iffalse % % This program is part of the Frankenstein bundle for LaTeX. % % Copyright 1995-2001 Matt Swift . % % This file contains both the code and documentation for the % achicago LaTeX package. It will work ONLY if it is placed in a % proper directory. Files called README, INSTALL, achicago.tex % and achicago.ins should have also been distributed to you % with this file. See them for more information on how to typeset % the documentation with LaTeX and how to generate a version of this % file that will work faster than this one. % % This program is free software; you may redistribute it and/or % modify it under the conditions of the LaTeX Project Public % License, either version 1.2 or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt, and version 1.2 or later is % part of all distributions of LaTeX version 1999/12/01 or later. % % This program is distributed in the hope that it will be useful, % but without any warranty; without even the implied warranty of % merchantability or fitness for a particular purpose. See the % LaTeX Project Public License for more details. % % \fi % %^^A* checks % %^^A NOTE: The character table, with two %'s, will get written to all files. %% \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 \~} % % \CheckSum{284} % %^^A** abstract % \begin{abstract} % \package{Achicago} provides a documentation style for \LaTeX{} that aims % for compliance with the \manual. It uses author-date citations (per % ch.~16), but bibliography entries contain unabbreviated information (per % ch.~15). Requires accompanying \BibTeX{} bibliography style, % \bst{achicago}. % \end{abstract} % \tableofcontents % % \part{Discussion} % \AddToCheckSum{10}^^A FIX no idea why I have to do this. % % \section{General} % % This package is a companion to the \bst{achicago} \BibTeX{} bibliography % style. The set of citation commands offered by \package{achicago} is % unfortunately shared only with an early implementation of a \manual-compliant % documentation style, \package{achicago} and \bst{achicago}. FIX: any others? % In the future, I hope to make \package{achicago} compatible with the most % common % % have to commit to using this bibstyle-package combination when you write your % sources. This needn't be true, and one day I am going to create a series of % mappings from other common bibstyles that are conceptually similar, such as % the \bst{harvard} styles. The user commands are slightly different, but it % should be the case that either set of user commands can be the front end for % either bibstyle. % % Here in this documentation you will read about the commands you will use in % your \LaTeX{} source file to make citations, and what the citations look % like. Documentation of the \bst{achicago} bibstyle itself is in the file % \file{achicago-bst.dvi}. There you can read about what the References % section, the actual book list, looks like. There are also some new fields % recognized and other information you might want to know that relates to your % \BibTeX{} bibliography database file (\ext{bib} file). You may also wish to % look at the \package{titles} package (also in the \Frankenstein bundle), % which can be very helpful in typesetting various styles of titles properly, % even when nested. The \package{achicago} package already requires the % \package{titles} package, so those commands are always there if you want to % use them. % % \caveat{This documentation is sparse but should be accurrate. I will improve % it in the future.} % % \section{Notes on the future of this package and bibstyle} % % \manualref{16.25} permits this combination. % % In the future I hope to document more closely \manual's principles wrt each % entry type, the many choices given by \manual. % % Untested and indeed hardly testable nature of the subject, with all its many % permutations and difficult special bibliographic cases. Feedback is very % welcome, especially with citations from \manual. % % FUTURE One thing I realize now is that I've kept the same user interface I % inherited, which I don't think corresponds with any other popular style. % Besides refinement, this is the next major step in the future of this % bibstyle-package. % % \section{Pros and cons of this style} % % FIX: terminology: reference style, citation style, bibstyle, bibliography style % % When you are required to use a certain reference style, your judgment is not % called for. In the cases where it is, here are some considerations. % % \begin{description} % \item[citations are verbose] % Sometimes this information is useful to the reader, sometimes not. If in % most citations it is not useful, consider a style with briefer citations. % \item[citation style and quality of writing] %% % FIX cite btxdoc Oren Patashnik argues that ``encourages the passive % voice and vague writing.'' I'm not sure. Even if it's true, an author can % surely resist this ``encouragement.'' To encourage is not to require. Do % consider how well \emph{you} write using different citation styles. If the % document is already written, realize that if you change the citation style % to one different than the author had in mind while writing, you may make % reading it more awkward. Then again, maybe you will improve it. % \item[ease of locating references] % % The entry for (Benson et~al. 1980) will appear any number of entries % \emph{after} the entry for (Benson et~al. 1999) when the former was written % by Benson, Zymursky, Wheeler, and Flynn and the latter by Benson (i.e., the % same Benson), Floyd, Wheeler, and Flynn, since Zymursky compares greater % than Floyd. % % This is an issue to consider if you have a large number of entries with the % same initial author (or editor) and often with different sets of 3 or more % subsequent authors. This is, in general, very unlikely. % % The entry for (Gr\"uber 1990b) may not follow the entry for (Gr\"uber % 1990a) immediately. When (the same) Gr\"uber has authored % Any number of entries may intervene, but their % principals will all be exactly Gr\"uber. Entries will intervene only in % the case when Gr\"uber both authored and edited a work in the same year, % and authored one a work with a later date. % \end{description} % % \section{Usage} % % Here are the various citing commands, and examples of the citations they produce. % % \todo{What about the situation when you end a sentence with something ending % with ``et~al.''---in this case you don't want to reproduce the period.} % % Distinct examples are \typeset{distinguished this way}. % % \begin{tabular}{*{3}{p{.33\textwidth}}} % \cs\cite\marg{key} % & parenthesized list of up to 3 principals or one ``et~al.'' plus a year label % & \typeset{(Brown 1978)} \typeset{(Jarke, Turner, and Stohl 1985)} \\ % \cs\cite\oarg{spec}\marg{key1} % & % & \typeset{(Brown 1978, 17)} \typeset{Jarke, Turner, and Stohl 1985, \S 3.3)} \\ % \cs\cite\marg{key1,key2} % & % & \typeset{(Brown 1978; Jarke, Turner, and Stohl 1985)} \\ % \cs\cite\oarg{spec}\marg{key1,key2} FIX: how does this work? % & % & \typeset{(Brown 1978; Jarke, Turner, and Stohl 1985)} \\ % \cs\citeNP\meta{key} % & as \cs\cite but without enclosing parentheses % & \typeset{Brown 1978} \typeset{Jarke, Turner, and Stohl 1985} \\ % \cs\citeA\marg{key} % & as \cs\cite but without year label(s) % & \typeset{(Brown)} \typeset{(Jarke, Turner, and Stohl)} \\ % \cs\citeANP\marg{key} % & as \cs\citeA but without enclosing parentheses % & \typeset{Brown} \typeset{Jarke, Turner, and Stohl} \\ % \cs\citeyear\marg{key} % & as \cs\cite but without principal list % & \typeset{(1978} \typeset{1985} \\ % \cs\citeyearNP\marg{key} % & as \cs\citeyear but without enclosing parentheses % & \typeset{1978} \typeset{1985} \\ % \cs\citeN\marg{key}\footnotemark % & principal list and parenthesized year label (i.e., a noun phrase) % & FIX: referring to author instead of paper? need good example \\ % \end{tabular} % \footnotetext{This command should only be used for one key.} % \todo{Should I use a warning in case more than one key is given to a command % that shouldn't have them?} % % \subsection{Short citation labels} % % Previous versions of \package{achicago} offered a parallel set of citation % commands with the prefix |short| that created citations with abbreviated % labels (\cs\shortcite, \cs\shortciteNP, \cs\shortciteA, \cs\shortciteANP, % \cs\shortciteN). \package{Achicago} now offers only one kind of label, which % is abbreviated according to principles in the \manual as much as possible. % For backwards compatibility, the |short| citation commands still function, % but they are identical to their non-|short|, and will produce a warning that % this syntax is deprecated. Do not use the |short| commands in new documents. % % \section{Some technical notes} % % \todo{See \manualref{16.14} for issues to do with multiple citations.} % % \section{History} % % I wrote this package incorporating \file{chicago\{,a\}.bst} and % file{chicago.sty} (v4, 92/8). By now I've almost totally rewritten it. It % was a great mess because it had been based on \file{newapa.bst} which had % been based on several other bibstyles, and each author had really just hacked % up what was there in the previous bibstyle apparently without fully % understanding it. Now, of course, it is a shining example of clarity and % efficiency. % % \StopEventually{} % % \part{Implementation} % % \section{Version control} % % \begin{macro}{\fileinfo} % \begin{macro}{\DoXUsepackagE} % \begin{macro}{\HaveECitationS} % \begin{macro}{\fileversion} % \begin{macro}{\filedate} % \begin{macro}{\docdate} % \begin{macro}{\PPOptArg} % These definitions must be the first ones in the file. % \begin{macrocode} \def\fileinfo{Chicago Manual author-date citations} \def\DoXPackageS {achicago} \def\initelyHavECitationS {} \def\fileversion{v1.2} \def\filedate{2001/08/31} \def\docdate{2001/08/31} \edef\PPOptArg {% \filedate\space \fileversion\space \fileinfo } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % If we're loading this file from a \cs\ProcessDTXFile command (see the % \package{compsci} package), then \cs\JusTLoaDInformatioN will be defined; % othewise we assume it is not (that's why the FunkY NamE). % % If we're loading from \cs\ProcessDTXFile, we want to load the packages listed % in \cs\DoXPackageS (needed to typeset the documentation for this file) and % then bail out. Otherwise, we're using this file in a normal way as a % package, so do nothing. \cs\DoXPackageS, if there are any, are declared in % the \ext{dtx} file, and, if you're reading the typeset documentation of this % package, would appear just above. (It's OK to call \cs\usepackage with an % empty argument or \cs\relax, by the way.) % \begin{macrocode} \makeatletter% A special comment to help create bst files. Don't change! \@ifundefined{JusTLoaDInformatioN} {% }{% ELSE (we know the compsci package is already loaded, too) \UndefineCS\JusTLoaDInformatioN \SaveDoXVarS \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it's undefined \usepackage{#1}% }% \RestoreDoXVarS \makeatother \endinput }% A special comment to help create bst files. Don't change! % \end{macrocode} % % Now we check for \LaTeX2e and declare the LaTeX package. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{achicago}[\PPOptArg] % \end{macrocode}^^A special comment to help create bst files. Don't change! % % ^^A NOTE: We have to compensate for the above backslashes, which are not % ^^A actually in the .dtx file the author works on, by adding to the % ^^A CheckSum. %% % \AddToCheckSum{17}^^A `dtx-update-checksum' automatically handles this. % \AddToCheckSum{7}^^A The half a macrocode env. at the top is missed, however... % \AddToCheckSum{10}^^A ... and so are the 5 \defs from the .dtx file % ^^A that precede it. % \IfCitations {% % \AddToCheckSum{2}^^A When \initelyHavECitationS is defined in % } ^^A the .dtx file, we need 2 more in the CheckSum. % % % \begin{macrocode} \RequirePackage{blkcntrl,moredefs,slemph,titles,verbatim} % \end{macrocode} % % \begin{macrocode} \newboolean{Annotate} \newcommand\annotate {% \Annotatetrue } \newcommand\noannotate {% \Annotatefalse } % \end{macrocode} % % \cs\citework is supposed to be a general command for citing things declared % with \cs\newwork in the \package{abbrevs} package. It has one optional and % one required argument so that it is parallel with the other citing commands, % but I cannot see any use for it without the optional argument. Environments % can exert complete control over how this macro looks by resetting the three % parameters. The default will look good outside all environments, in running % text. % % The second argument is expected to be something defined with \cs\newwork. % % Needs modification to handle the empty optional arg. Watch interfering with % things surrounding macros might have set. \cs\relax's are intentionally left % out to let constructions like \cs\csname\lips\cs\endcsname [eh? FIX] work on % the arguments. % % \begin{macro}{\PreCiteWork} % \begin{macro}{\PostCiteWork} % \begin{macrocode} \providesavebox\sc@box@a \newcommand\PreCiteWork {% (\csname% } \newcommand\PostCiteWork {% \end{lrbox}\usebox{\sc@box@a})% } % \end{macrocode} % \end{macro} % \end{macro} % % We don't want to be unbreakable here, but we want a high penalty. We % absolutely do not want to break the number range, so we put it in an lrbox. % % I think comma is better, even though it might seem fussy, because it is % better parallel with the way \cs\cite works with an optional page argument: the % convention is that page numbers come after commas. % % \begin{macrocode} \newcommand\MidCiteWork {% \endcsname,\penalty9000\ \begin{lrbox}{\sc@box@a}% } \newcommand\citework [2] {% \PreCiteWork #2\MidCiteWork #1\PostCiteWork } % \end{macrocode} % % \begin{verbatim} % The {} fools abbrevs.dtx into not adding an extra space % \newcommand\MidCiteWork {% % \endcsname{}\penalty9000\ \begin{lrbox}{\sc@box@a}% % } % \end{verbatim} % % \todo{Make citework* with no parentheses, or other alternative.} % % FIX: When the ? is placed there, there are two left parens, one right. % % We want the remaining macros in this section to be available in their own % piece. % % \todo{is \cs\PreChunk the only dependence on blkcntrl? Should make this not % necessary if so.} % % \begin{macrocode} \newcommand\PreAnnotation {% \PreChunk } % \end{macrocode} % % This will make the definition of the \env{thebibliography} environment in % \file{classes.dtx} do the right thing. FIX: not defined in letter class? % \begin{macrocode} \defcommand\@openbib@code {% \advance\leftmargin\bibindent \itemindent -\bibindent \listparindent \itemindent \parsep \z@ } \let\newblock\relax % \end{macrocode} % This doesn't work at the beginning, for some reason. The auxfiles are not % set up right? URK: don't do this. Confuses users and also prevents anyone % from using achicago.sty with another bibstyle, such as a modified achicago.bst. % Is there a way I can provide a useful warning message for those who might % have been using this before, without a \cs\bibliographystyle % \begin{macrocode} %\AtEndDocument {% % \bibliographystyle{achicago}% %} % \end{macrocode} % % The \bst{achicago} bibliography style will insert some macros that are not % defined by \LaTeX, and some that must have new meanings. They are: % \cs\citeN, \cs\SCcite, \cs\SCduplicate, \code{\begin{SCannotation}}, % \code{\end{SCannotation}}. % % Some of these commands should properly have |@| in their names, but % |@|-commands cannot appear in the \ext{bbl} file. As a compromise, the names % have the prefix |SC|. % % \begin{macro}{\SCduplicate} % \begin{macro}{\ac@mmmdash} % The argument will contain the `label' that is a duplicate, in case it might % ever be of use. But for now, we just want to replace duplicates with 3-em % dashes. % % \todo{provide option to spell out the duplicate when it is the first entry on % a page (oneside) or verso page (twosided)} % % A 3em-dash. % \begin{macrocode} \newcommand\ac@mmmdash {% \rule[.6ex]{3em}{.03ex}% } \newcommand*\SCduplicate [1] {% \ac@mmmdash } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\PreAnnotation} % \begin{macro}{\ac@begingobble} % \begin{macro}{\ac@endgobble} % \begin{environment}{SCannotation} % This sets up the \env{SCannotation} environment. When the boolean % \cs\IfAnnotate is false, we gobble everything between \code{\begin{SCannotation}} % and \code{\end{SCannotation}}. % % We require the \package{verbatim} package to do this. I used to put the text % into an |lrbox| and just never use the box. This required balanced text % inside (not a bad thing), but it also would process any \cs\cite-like % commands that appeared in the gobbled text, which could lead to perpetual % warnings about unresolved references. There were in fact no unresolved % references, but the warnings were annoying. % \begin{macrocode} \newlet\ac@begingobble\comment \newlet\ac@endgobble\endcomment % \end{macrocode} % \todo{I shouldn't define annote in terms of quotation, we should copy a % standard one here; What is the point of the \cs\relax? I ended up removing % them before the \cname{ac@begingobble} cases because I had to use the % \cs\expandafter.} % % \begin{macrocode} \newenvironment{SCannotation} {% \ifAnnotate \let\PreQuotation\PreAnnotation \relax\quotation \else \expandafter\ac@begingobble \fi }{% \ifAnnotate \relax\endquotation \else \expandafter\ac@endgobble \fi } % \end{macrocode} % \end{environment} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\SCcite} % \begin{macro}{\ac@firstoftwo} % \cs\SCcite is what \bst{achicago} produces. Its args are `label', % and `year.label'. FIX: aak, plus tag. % \begin{macrocode} \ReserveCS\SCcite \newlet\UnexpandableProtect\@unexpandable@protect \newcommand*\ac@firstoftwo [2] {#1} \newcommand*\ac@secondoftwo [2] {#2} \newcommand*\ac@onespacetwo [2] {#1\ #2} \newcommand*\ac@onespacepretwo [2] {#1\ \PreCite #2} \newcommand*\ac@cite@preonecommatwopost [2] {% \PreCite #1\if@tempswa , #2\fi\PostCite } \newcommand*\ac@cite@onecommatwo [2] {% #1\if@tempswa , #2\fi } \newcommand*\ac@cite@onecommatwopost [2] {% #1\if@tempswa , #2\fi \PostCite } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\PreCite} % \begin{macro}{\PostCite} % \mbox{} % \begin{macrocode} \newlet\PreCite ( \newlet\PostCite ) % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\cite} % \begin{macro}{\citeNP} % \begin{macro}{\citeA} % \begin{macro}{\citeN} % \begin{macro}{\citeANP} % The way this works is: \cname{\@cite} is called once for each citing command, % and \cs\SCcite is called once for each key. The results are spaced by either % semicolons (\cname{\ac@cite@sc}) or commas (\cname{\ac@cite@comma}), and % these become argument |#1| for \cname{\@cite}. % \begin{macrocode} \def\cite {% \let\@cite\ac@cite@preonecommatwopost \let\SCcite\ac@onespacetwo \ac@cite@sc } \newcommand*\citeNP {% \let\@cite\ac@cite@onecommatwo \let\SCcite\ac@onespacetwo \ac@cite@sc } \newcommand*\citeN {% \let\@cite\ac@cite@onecommatwopost \let\SCcite\ac@onespacepretwo \ac@cite@comma } \newcommand*\citeA {% \let\@cite\ac@cite@preonecommatwopost \let\SCcite\ac@firstoftwo \ac@cite@sc } \newcommand*\citeANP {% \let\@cite\ac@cite@onecommatwo \let\SCcite\ac@firstoftwo \ac@cite@sc } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\shortcite} % \begin{macro}{\shortciteNP} % \begin{macro}{\shortciteN} % \begin{macro}{\shortciteA} % \begin{macro}{\shortciteANP} % \begin{macrocode} \newlet\shortcite\cite \newlet\shortciteNP\citeNP \newlet\shortciteN\citeN \newlet\shortciteA\citeA \newlet\shortciteANP\citeANP % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\citeyear} % \begin{macro}{\citeyearNP} % \mbox{} % \begin{macrocode} \newcommand*\citeyear {% \let\@cite\ac@cite@preonecommatwopost \let\SCcite\ac@secondoftwo \ac@cite@comma } \newcommand*\citeyearNP {% \let\@cite\ac@cite@onecommatwo \let\SCcite\ac@secondoftwo \ac@cite@comma } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\ac@citesep} % \begin{macro}{\ac@cite@sc} % \begin{macro}{\ac@cite@comma} % \mbox{} % \begin{macrocode} \ReserveCS\ac@citesep \newcommand\ac@cite@sc {% \let\ac@citesep ;% \ac@cite } \newcommand*\ac@cite@comma {% \let\ac@citesep ,% \ac@cite } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\ac@cite} % This command executes \cname{\b@foo} for every \cs\foo in the list of cited % labels, and separates them by arg |#1|. % % There has got to be a more elegant solution to this whole thing. FIX % \begin{macrocode} \newcommand*\ac@cite {% \@ifnextchar [ {% \@tempswatrue \ac@@cite }{% ELSE \@tempswafalse \ac@@cite[]% }% } % \end{macrocode} % \todo{handle reserving names} % \begin{macrocode} \providecommand\@writeaux {% \immediate\write\@auxout } \NewName*{ac@@cite} {[#1]#2} {% args: [optarg] label % optarg MANDATORY \if@filesw \@writeaux{\string\citation{#2}}% \fi \@cite{% \InitCS\sc@t@a \@for\ac@label:=#2\do {% \sc@t@a % \let\sc@t@a\ac@citesep \def\sc@t@a {\ac@citesep\ }% add space \@ifundefined{b@\ac@label} {% {\bfseries ?}% \@warning{Citation `\ac@label' on page \thepage\space undefined}% }{% ELSE \@nameuse{b@\ac@label}% }% }% }{#1}% } % \end{macrocode} % \end{macro} % % \begin{macro}{\bibindent} % Indent second and subsequent lines of bibliographic entries. % \begin{macrocode} \setlength\bibindent{1.5em} % \end{macrocode} % \end{macro} % % \begin{environment}{thebibliography} % There is no \option{openbib} option. The definitions of \cs\newblock and % \cname{@biblabel} are kept local in case something else weird is going on. % \begin{macrocode} \newcommand\ac@defbib [2] {% \renewenvironment*{thebibliography} [1] {% #1*{#2\@mkboth{#2}{#2}}% \list{}{% \leftmargin\z@ \advance\leftmargin\labelsep \advance\leftmargin\bibindent \itemindent -\bibindent \listparindent \itemindent \parsep \z@}% % \end{macrocode} % \manual does not acknowledge different spacings after different marks of % punctuation, distinguish interword from intersentence space, or give rules % about where to break a line near an ellipsis. So we are on our own in the % bibliography. I have chosen to leave things as they are done in the standard % bibliography styles, because I haven't yet given it my close consideration. % That is, we leave all the punctuation the same except for the period, which % we set to~1000, I forget now whether that's a lower or upper case letter. % Extending the space after a period when appropriate seems to be the purpose % of using \cs\newblock, in this bibstyle. % \begin{macrocode} \sfcode`\.=\@m \def\newblock {% \hskip .11em \@plus.33em \@minus.07em% }% \let\@biblabel\Gobble \sloppy \clubpenalty4000\widowpenalty4000% }{% \def\@noitemerr {% \@latex@warning{Empty `thebibliography' environment}% }% \relax\endlist }% } \@ifclassloaded{article} {% \ac@defbib{\section}{\refname}% }{% ELSE \ac@defbib{\chapter}{\bibname}% } \InitCS\ac@defbib % FIX -- where else can I do this? % \end{macrocode} % \end{environment} % % \Finale