path: root/Master/texmf-dist/doc/texsis/base/TXSrefs.doc

%% file: TXSrefs.doc - References and Citations - TeXsis version 2.18
%% @(#) $Id: TXSrefs.doc,v 18.5 2000/05/17 00:19:46 myers Exp $
%======================================================================*
% (C) Copyright 1989, 1992, 1999 by Eric Myers and Frank E. Paige.
% This file is a part of TeXsis.  Distribution and/or modifications
% are allowed under the terms of the LaTeX Project Public License (LPPL).
% See the file COPYING or ftp://ftp.texsis.org/texsis/LPPL
%======================================================================*
\ifx\undefined\meta\texsis\input TXSdocM.doc\input Manual.aux\draft\fi


\section{References and Citations               \label{sect.refs}}

   \TeXsis\ includes instructions for making citations to the
literature in the text of a document.
References are processed in the standard format used by many American
physics journals: they are automatically assigned consecutive numbers
as they appear in the text and are listed in numerical order at the
end of the document.
In the text a citation appears as a superscript number corresponding
to the reference cited, though other methods of citation are possible
(see Section~\use{sect.cite}).
When each reference is defined it is given a \idx{label}, which is
associated with the number assigned to the reference.
Subsequent citations to the same reference are made using this label,
so there is no need to know the particular number assigned to the
reference. Indeed, the number may change as the document goes through
editing and revision, \index{references}\index{citations|see{references}} 
but the references will still automatically be in the correct order.


\subsection{Entering References}

   \TeXsis\ is flexible enough that the text of the references may be
entered in two different ways, either all references at once at the
beginning of the document or each one individually at the point in the
text where the work is first cited.
In either case, \TeXsis\ stores the text of all of the references in
numerical order until it is asked to print the list at the end of the
document, by saying \cs{ListReferences}.

   To make a citation to a new reference and to enter the text of the
reference, use the command \CS{reference}\arg{label}, where
\meta{label} is the label to be used to refer to this reference.
This is followed by the text of the reference, which is terminated by
\cs{endreference}.  An example is:
\TeXexample
To this end we will follow Feynman\reference{Feynman, 1949}
R.P.~Feynman, Phys.\ Rev.\ \vol{76}, 749 (1949)
\endreference                                  
in developing the propagator approach.         
|endTeXexample                                 
\noindent
This would appear in the text of the document as,
\example                                       
To this end we will follow Feynman\reference{Feynman, 1949}
R.P.~Feynman, Phys.\ Rev.\ \vol{76}, 749 (1949)      
\endreference                                        
in developing the propagator approach.               
\endexample                                          
and the text of the reference would be saved until the list of
references is printed at the end of the document.
If you look at the end of this manual you will see it.
     
   There are several things to take note of in the example above.  Most
importantly, there is no space between the word in the text where the
citation is made ("Feynman")\index{Feynman, Richard P.}
and the \CS{reference}.  This is so the
superscript reference number will appear in the text right after the
word to which the citation is attached, with no intervening space.  Note
also in the reference text the tie (|~|) between the initials and the
name, the control spaces (\hbox{\tt\bs\ }) after the abbreviations, and
the use of the \CS{vol} macro for the volume number;
\CS{vol}\arg{number} prints the volume \meta{number} with an underscore
below it.
(This is easier to read than boldfaced volume numbers on small laser
printers, but if you prefer something else you can simply redefine the
\CS{vol} macro).
Similarly, \CS{booktitle}\arg{title} will print the title of a book,
in slanted type.
Finally, note that there is no punctuation at the end of the reference
text.
This is because \TeXsis\ automatically supplies the appropriate
punctuation when it prints the list of references.
Normally this will simply be a period (.), but it is possible to have
multiple references assigned to the same reference number, in which
case the references are separated by semi-colons, with the last
reference terminated by a period.
How to do this is described below.

  Since typing the text of a journal citation is somewhat complicated,
the \CS{journal} macro was created to make things a little easier.
The format is
\example
|\journal| \meta{journal name}|;|\meta{volume}|,|\meta{page number}%
|(|\meta{year}|)|
\endexample
This constructs the journal citation for you, with periods automatically
replaced by ``\hbox{\tt .\bs\char`\ }'' in abbreviations and the volume
number underlined for you by |\vol|.  It is important that the field
separators (the semi-colon, the comma and the parentheses), all be
present and in the right order or \TeX\ will look as far forward as it
takes to find the next one it wants.  There should be no extra spaces
between the arguments.

Besides making it a little easier to type a citation to a journal
article, using \CS{journal} lets you switch from the American form of
citation to the European form very easily.  In the American form the
page number follows the volume, followed by the year in parentheses.  In
the European form the year follows the volume number and the the page
number comes after that.  Normally \TeXsis\ uses the American form, but
you can change to the European form simply by saying
\example
\CS{Eurostyletrue}
\endexample
The arguments to \CS{journal}  are always in the American order,
no matter how they are eventually printed.

A number of abreviations which are commonly used in references
and which are usually set in italics are defined as simple control
words.
Thus saying \CS{cf} produces ``\cf'', saying \CS{etal} 
produces ``\etal'', saying \CS{ie} produces ``\ie'', and
saying \CS{ibid} produces ``\ibid''


Sometimes you want to print the title of a journal article, and
sometimes you don't.  An easy way to control this is to enter the
title using \CS{ArticleTitle}, as in\index{Schwinger, Julian}
\TeXexample
\reference{Schwinger, 1951}
J.~Schwinger, 
\ArticleTitle{On Gauge Invariance and Vacuum Polarization}
\journal Phys. Rev.;82,664(1951)
\endreference
|endTeXexample Then if you say \CS{ShowArticleTitletrue}, the title
will be printed (in slanted type, with a trailing comma), but with
\CS{ShowArticleTitlefalse} (the default) 
it will not.


\bigskip

   To enter several references with the same reference number simply
begin the next \CS{reference} immediately after the previous
\cs{endreference}, and begin the labels of all but the first reference with
an asterisk "|*|", as in the following example:
\TeXexample
The vacuum polarization term can be regularized
by introducing a cut-off at high
frequencies.\reference{Pauli and Villars, 1949}
W.~Pauli and F.~Villars, \journal Rev. Mod. Phys.;21,434(1949)
\endreference
\reference{*Schwinger, 1948}
J.~Schwinger, \journal Phys. Rev.;74,1439(1948)
\endreference
|endTeXexample
This produces the single citation  
\index{Schwinger, Julian}\index{Villars, F.}\index{Pauli, W.}%
\example
The vacuum polarization term can be regularized
by introducing a cut-off at high
frequencies.\reference{Pauli and Villars, 1949}
W.~Pauli and F.~Villars, \journal Rev. Mod. Phys.;21,434(1949)
\endreference
\reference{*Schwinger, 1948}
J.~Schwinger, \journal Phys. Rev.;74,1439(1948)
\endreference
\endexample
The "|*|"\index{*@{\tt *}'d citations}   
at the beginning of the second label tells \TeXsis\ not
to assign a new reference number to this reference, but instead
just to add it to the text of the previous one.  
Of course you
could type the text of both references between one \cs{reference}
and \cs{endreference}. An advantage to following the example
above is that the second reference can be given a reference
number of its own simply by deleting the "|*|" at the beginning of
the label.  Similarly, two references with different reference
numbers can be lumped together into one citation by inserting a
"|*|" in front of the label of the second reference.  Another
advantage to keeping the references separate is that it is easy
to move references around, either within a document that is being
revised or between documents.  It is therefore recommended that
each reference be entered separately, although this is obviously
not required.

   Instead of putting the \cs{reference} \dots \cs{endreference} in
the text it may be more convenient to type them all together,
especially if they already
appear that way in the manuscript. This can be
done without producing any unwanted printed numbers by using
\index{references!entering a list}
\example\obeylines
\CS{referencelist}
|\reference{1}| {\it text 1...} |\endreference |
|\reference{2}| {\it text 2...}  |\endreference |
|...|
|\reference{last}| {\it last text...} |\endreference|
\cs{endreferencelist}
\endexample
The \CS{referencelist} must appear at the beginning of the
document, so that the reference labels are defined before they
are used. This is best put into a separate file which is \cs{input}
by the master file. Of course the list of references is not
printed until the end of the document, when \cs{ListReferences} is
called.
           
\subsection{Citations to Defined References}

   All subsequent citations to a previously defined reference are made
using its label.
If a \CS{referencelist} is used, then \undertext{all} citations
appearing in the text will be made in this way, since then the initial
reference definitions print nothing.
The construction \CS{cite}\arg{label} prints the reference number
corresponding to the label as a superscript.
For example,
\TeXexample                                                             
A good discussion of this is given by Doob\cite{Doob} in section~7.
|endTeXexample produces
\example
A good discussion of this is given by Doob\cite{Doob}  
in section 7.
\endexample
since Michael Doob's\index{Doob, Michael} book \booktitle{A Gentle
Introduction to \TeX} is in fact \Ref{Doob} of this document and has
the label "|Doob|."
If several \CS{cite}'s are given in succession then the corresponding
numbers are printed separated by commas.
Unlike \cs{reference}, which defines the reference numbers, \CS{cite}
does not know if references are sequential, so it cannot replace a
sequence of numbers by a range.
To avoid a long sequence of reference numbers use instead
\CS{citerange}\arg{first label}\arg{last label} to print the numbers
corresponding to the first and last labels as a range.
     
   The construction \CS{Ref}\arg{label} produces ``Ref.~$nn$'' in the
text, with $nn$ the number of the reference corresponding to the
label.  For example, the ``\Ref{Doob}'' in the previous paragraph was
typed into the manuscript file as |\Ref{Doob}|.  \CS{Ref} is simply
shorthand 
for |Ref.~\use{Ref.|\<label>|}|, and you can change what is printed
simply by changing the definition of \CS{Ref}. For example, if you said
\TeXexample
\def\Ref#1{reference~\use{Ref.#1}}
|endTeXexample
\noindent
then |\Ref{Doob}| would produce ``reference~\use{Ref.Doob}'' instead.
See Section~\use{sect.labels} for more on how to use \cs{use}.

%==================================================*

\subsection{Listing the References}

   After the text of the document is complete a printed list of the
references can be obtained by saying 
\TeXexample
\ListReferences
|endTeXexample 
This prints the numbers at the left hand edge of the page with the
text indented by \CS{refindent}, which is chosen so that the equation
numbers line up, and it puts a \CS{refskip} (initially equal to a
\cs{smallskip}) between references.  
The reference format can be changed by redefining the command
\CS{refFormat}, which is executed just before the references are
printed and which initially is simply \cs{relax}.
For example, to have the reference list printed with a ragged right
margin, with no vertical skip in between references, one could say
\index{references!printing the list}
\index{lists!of references}
\TeXexample
\def\refFormat{% formatting for the list of references
   \raggedright                    % ragged right margin
   \refindent=2cm                  % instead of ``natural'' value
   \let\refskip=\bigskip           % more space between entries
   }
\ListReferences         % now do it
|endTeXexample


No heading is printed for the reference list --- you have to do this
yourself in whatever format is appropriate.
Often you will want to use \cs{nosechead} (or perhaps
\cs{beginsection} from Plain \TeX), but sometime you may want
to use \cs{chapter} or \cs{section} instead.
The choice is up to you.

When you have several references under the same number, the |*|'d
references described earlier, they will each normally be printed
begining on a new line.
You can supress the extra line ends and run the reference text
together by saying \CS{refbreaksfalse}.
To go back to breaking lines between multiple citations you should say
\CS{refbreakstrue}.

Once the list of references has been printed, everything is reset so
that you can start over collecting new references.
This is useful if you want to print the references at the end of each
chapter of a book, or at the end of each paper in a conference
proceedings.



%==================================================*
\subsection{Citation Styles     \label{sect.cite}}

Superscript reference numbers are the simplest form of citation, and
the default in \TeXsis, but there are also several other popular
conventions for making citations.
One common one is to display the reference number enclosed in squaqre
brackets rather than as a subscript.
Another is to display a ``citation key,'' such as the first author's
last name and the year, either in brackets or parentheses.
\TeXsis\ is flexible and allows you to use any of these citation
styles.

To cause the reference numbers to appear within brackets simply say
\CS{CiteByNumber}.  
(To go back to superscript reference numbers say
\CS{CiteBySuperscript}.)
It would be nice if that is all you had to do to switch from one
citation style to another, but there is one complication.
When a citation appears at the end of a sentence it looks best if the
punctuation comes before a superscript, but after a reference number
in brackets.
Getting this right is more than a mere macro can easily do, so if you
switch from one style to the other you will have to make appropriate
corrections to your document for citations that appear at the end of
sentences. 

\Ignore  % Duh?
Both \CS{CiteBySuperscript} and \CS{CiteByNumber} list the references
by number when you say \cs{ListReferences}.
\endIgnore


Another citation style which was more popular in journals many years
ago is to cite the work in the text using a superscript number, but to
put the text of the reference at the bottom of the page as a footnote
rather than at the end of the paper or chapter as an ``endnote.''
This is achieved by saying \CS{CiteByFootnote}.
This can be useful for a draft of a paper even if you will eventually
use a different citation style, because it makes it easier to check
the reference text as you proofread the paper.
By the same reasoning it's actually a nice citation style for
scientific books and papers in general, because the reference text is
right there.
If the author thinks it is important enough to his/her argument to
cite another work then it is probably imporant for the reader to see
the reference text at that point.
We hope that this citation style gets used more than it has of late,
though with the increased use hypertext it probably won't.  (Why
bother to put the reference text on the same page as the citation when
you can click on the reference number and jump right to the
appropriate point in the list of references?\ifhtml\phantom{.}
  See Section~\use{sect.hypertext} for details.\fi)

As you might expect, if you use \CS{CiteByFootnote} then no list of
references is produced should you also say \cs{ListReferences}.
After all, the text of the references has already appeared so there
are actually no references to list.  

It is probably not a good idea to mix \CS{CiteByFootnote} and numbered
footnotes using \cs{Nfootnote}, since they are completely separate 
and keep track of their footnote numbers independently.
%% BUT THIS COULD BE FIXED, EH?






\bigskip

Earlier versions of \TeXsis\ had only two citation styles, and for
backward compatibility they are still supported.
Saying \CS{superrefsfalse} is the same as saying \CS{CiteByNumber},
while \CS{superrefstrue} is the same as \CS{CiteBySuperscript}.
The older forms are supported so that you can print old documents that
use them, but you should avoid including them in new documents since
they might disappear some day.


%==================================================*
\subsection{Using \BibTeX}

\BibTeX\ is a system for managing and using bibliographic databases.
If you find you are always citing the same sources again and again in
your papers, or if you have access to a bibliographic database someone
else has already compiled (or which you yourself have compiled), then
\BibTeX\ can make it much easier for you to make your list of references.
All you need to do is specify the name of the database files to be
searched (there can be several), and use the \cs{cite} command to
refer to a paper listed in the database.
Papers in the databases are indexed by a ``citation key,'' and all you
have to do is use that key as the label in the \cs{cite} command.
The first time you run your document through \TeXsis\ these references
will be undefined, but if you then run the \BibTeX\ program it will
extract the proper references from the databases, so that they
will be properly defined (and formatted) the next time you
process your document.

Some extra work is needed to get started using \BibTeX.
First, since \BibTeX\ is a separate program, you need to get that
program---it isn't included with \TeXsis.
You can get the standard distribution of \BibTeX\ from CTAN, in the
directory {\tt bibliography/bibtex}.
If you are not familiar with how to build and install \TeX\ and
related programs then you will need to get your system adminstrator or
\TeX\ guru to install it for you. 
You also need to have the ``reference style'' file for \TeXsis.
This file, called {\tt texsis.bst}, tells \BibTeX\ how to write out
references in the proper \TeXsis\ format.
This file now comes with the standard \TeXsis\ distribution, but if
you don't have it you can easily get it from the \TeXsis\ ftp site, or
from CTAN, in the directory {\tt texsis/bibtex}.


Once \BibTeX\ and {\tt texsis.bst} are installed it is fairly easy to
use them.
First you have to add to your manuscript files a couple of
instructions that tell \BibTeX\ which bibliography database files to
use and how to format the references.
To specify the database files, use \CS{ReferenceFiles}, as in
\TeXexample
\ReferenceFiles{unix,internet,mylist}
|endTeXexample
In this case, \BibTeX\ will search for the references in the
files {\tt unix.bib}, {\tt internet.bib}, and {\tt mylist.bib}.
(Examples of these files are also included in the {\tt texsis/bibtex}
directory on the ftp servers.)
Next, you tell \BibTeX\ to use a ``style'' for creating references in a
form that \TeXsis\ can understand, with 
\TeXexample
\ReferenceStyle{texsis}
|endTeXexample
This tells \BibTeX\ to use the {\tt texsis.bst} style file,
but you must leave off the {\tt .bst} extension.
 
Once you have invoked \CS{ReferenceFiles} and \CS{ReferenceStyle} you
can cite your references using \cs{cite}, as usual.
The ``label'' you use for \cs{cite} should be the ``citation key''
used in the bibliography database.
You can also use \CS{nocite} to create a citation entry without
putting a citation mark (superscript number or number in brackets) in
the output.
Finally, to print the list of references, simply say
\cs{ListReferences}, as usual.  
This just lists the references---it's up to you to provide any heading
or extra space before the list.

Once you have set up your document this way, the only additional thing
you have to do is run the \BibTeX\ program.
Before you do, run your manuscript file through \TeXsis\ once.
It will complain about undefined references, but it will also produce
a list of the papers you cited, in order, in the {\tt .aux} file.
Then run \BibTeX, like so:
\TeXexample
bibtex myjob
|endTeXexample
This uses the information in the {\tt .aux} file and 
extracts the references, in the proper order and with the proper 
\TeXsis\ \cs{reference} commands, into the file {\tt myjob.bbl}  (the
extension means ``bibliography list'').
Finally, run \TeXsis\ again.
This time, since the {\tt .bbl} file exists, it is read in as a
\cs{referencelist} when the \CS{ReferenceFiles} command is executed.
Now all of your citations will be properly defined, with no
complaints.
Just remember to run the \BibTeX\ program again if you add or delete
citations or change their order.  

%>>> EOF TXSrefs.tex <<<