diff options
Diffstat (limited to 'Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc')
| -rw-r--r-- | Master/texmf-dist/doc/otherformats/texsis/base/TXSrefs.doc | 474 |
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 <<< |