summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc')
-rw-r--r--Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc474
1 files changed, 474 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc b/Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc
new file mode 100644
index 00000000000..5d3f5c46449
--- /dev/null
+++ b/Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc
@@ -0,0 +1,474 @@
+%% 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 <<<