% vim:foldmethod=marker foldmarker=--->,<---

\section{\texttt{References} and \LaTeX} % --->
\label{LaTeXRefsGeneralDescription}

\index{LaTeX@\LaTeX}

\texttt{References} supports writing \LaTeX\ documents 
with bibliographic references in different ways. This software
may be used as database which helps to generate \texttt{.bib} files 
which can be used
together with BibTeX \cite{Lamport1995} (section \ref{sec:ReferencesBibTeX}) 
and it generates freely formatted
lists of references in a \texttt{thebibliography}-environment
\cite{Lamport1995}, which may be used with the \verb+\cite{}+-command in
\LaTeX-documents (section \ref{sec:thebibliographyLists}).  
Moreover, \texttt{References} provides tools to
``extract'' reference numbers from \verb+\cite{}+-commands 
\index{cite, LaTeX@\textbackslash cite, \LaTeX}
in \LaTeX-documents (section \ref{sec:ExtractLatexCitations}).

% <---

\subsection{\texttt{References} and BibTeX} % --->

\label{sec:ReferencesBibTeX}
Use of BibTeX is described in \cite{Lamport1995,m00015}.  Create a
Bib\TeX-database%
  \index{Bib\TeX\ database!compiling}
with \mopt{main-l b}. 
You are then asked

\begin{enumerate}
  \item to enter the name for the output file (the extension \texttt{.bib}
  will be automatically added),
  \item to select the bbt-file with the reference numbers
\end{enumerate}

then you will have to select the reference number format: with \mopt{o} the
original reference numbers are written into the \texttt{key}-position of the
record as in

\begin{verbatim}
@article{key-from-references-database,
  author={...},
  ...
}
\end{verbatim}

\sloppypar
the option \mopt{n} in this menu will generate new keys. 
%  In current
%  version, \texttt{References} will generate \verb+@article+-records from
%  j1-documents, \verb+@book+-records from b1-documents and
%  \verb+@incollection+-records from b2-documents of the \texttt{References}
%  database. 
Equivalents of \texttt{References} and Bib\TeX{} document types are
listed in table \ref{tab:ReferencesBibTeXDTCorr}.
An example of the output produced by this function is shown in
section \ref{sec:BibTeXDBFormat}.

\begin{table}[h]
\begin{center}
  \begin{tabular}{cl} \hline
  \texttt{References} & Bib\TeX{} \\ \hline
  j1, j2 & \texttt{@article} \\
  b1, b3 & \texttt{@book} \\
  b2     & \texttt{@incollection} \\
  m1, m2 & \texttt{@misc} \\ \hline
  \end{tabular}
\end{center}
  \caption{Corresponding \texttt{References} and Bib\TeX{} document types}
  \label{tab:ReferencesBibTeXDTCorr}
\end{table}

Writing a document in this standard mode implies inclusion of reference
numbers with \verb+\cite{}+, including the \texttt{.bib}-file at the end of
the manuscript and selection of a bibliographic style at the beginning of the
document \cite{Lamport1995}.

% <---

\subsection{Lists of references in the `thebibliography'-environment.} % --->

\label{sec:thebibliographyLists}
Lists of references in \texttt{thebibliography}-environment are made in two
steps:

\begin{enumerate}
  \item write a list of references with \mopt{main-l s} or \mopt{main-l u},
  in ``\texttt{Menu:~Reference number format}'' select \mopt{3}. This generates
  references beginning with \verb+<REFERENCE-NUMBER> ...+
\item This list of references (filename extension \texttt{txt}) can be
 converted with \mopt{main-t lt} into a list in
 \texttt{thebibliography}-environment (filename extension \texttt{tex}).
\end{enumerate}

The resulting output file looks like:

\begin{listing}[5]{1}
\begin{thebibliography}{99}

\bibitem{m00009} Lamport L. Das LaTeX-Handbuch. Bonn: Addison-Wesley
Publishing Company, 1995.

\bibitem{m00011} Kopka H. LaTeX: Eine Einf\"uhrung Band 1. 2. ed. Bonn:
Addison-Wesley Publishing Company, 1996.

\bibitem{m00015} Goossens M, Mittelbach F, Samarin A. Der LaTeX-Begleiter.
1. ed. Bonn, Paris, Reading, Menlo park, New York, Don Mills, Wokingham,
Amsterdam, Milan, Sydney, Tokyo, Singapore, Madrid, San Juan, Seoul,
Mexico City, Taipei: Addison-Wesley Publishing Company, 1995.

\end{thebibliography}
\end{listing}

In line 1, the argument of the environment should be adjusted, e.\,g. to `999'
if the list of references comprises more than 100 entries, or to `9' if the
list is shorter than 10 references.

% <---

\subsection{Write \LaTeX-documents using \texttt{refscite()} for citations} % --->

\label{sec:LaTeXWithRefscite}

This third option to produce \LaTeX-documents with lists of references and
appropriate citations in the text is perhaps the most flexible and the least
comfortable. It may be appropriate to write single book chapters for a
multi-author-book or a manuscript for a scientific journal with special formal
requirements for the list of references and citations (for details
cf. section \ref{sec:GeneralReferencesMS},
page \pageref{sec:GeneralReferencesMS}).  The following steps are 
required\footnote{This procedure is similar to that for normal text
  processors, cf. section \ref{sec:FormattedCitationsMS}, page
 \pageref{sec:FormattedCitationsMS}}: 

\begin{enumerate}
\item Insert citations in the \LaTeX-document with \texttt{refscite()} or in
  an equivalent format (cf. explanation on \emph{search patterns} in section 
  \ref{sec:ExtractRefNo}, page \pageref{sec:ExtractRefNo}),
\item extract reference numbers with \mopt{main-t xr}, this generates a
  bbt-file (cf. section \ref{sec:ExtractRefNo}, page
  \pageref{sec:ExtractRefNo}),
\item remove duplicate citations from this bbt-file (cf. section
  \ref{SecBatchFiles}),

\item sort the bbt-file,

\item make the list of references with the \mopt{main-l u} function
\item generate a macro for replacing \texttt{refscite(...)}s in the text by
  numerical citations\footnote{like ``\texttt{...[12]...}''} or citations in
  \emph{author year format}\footnote{like ``\texttt{...(Mueller et al,
      1987)...}''} with \mopt{main-l m}
\item process the \LaTeX-document:
  \begin{itemize}
  \item make a copy of the file with the text\footnote{this method is
      appropriate for documents with the text in a single file. You
      \textbf{should} make a copy either as reserve if you wish to repeat the
      steps described in this section}
  \item perform the search and replace operations on the copy of the document

  \item insert the list of references (converted to \TeX{} from text file
      format with \mopt{edit-main-p ltx}) into the document
  
  \end{itemize}
\item run \LaTeX{} on the file with the replacements done

\end{enumerate}

% <---

\subsection{Extract reference numbers from \LaTeX\ documents} % --->

\label{sec:ExtractLatexCitations}

\index{excite command}
\index{LaTeX cite@\LaTeX\ \textbackslash cite\{\}}
The most important command for \LaTeX-users who want to extract the reference
numbers entered with \verb+\cite{...}+ in their documents is 
\mopt{edit-main-p exc}. The script called by this command
issues the message

\begin{verbatim}
   filename.tex -> rcite.tbt

   EXCITE appended 200 reference numbers to rcite.tbt
\end{verbatim}

indicating that all reference numbers have been written into
\texttt{rcite.tbt} text file. 


In order to produce a list of references you
will have to convert this tbt-file into a bbt-file, remove duplicate reference
numbers and sort the bbt file (cf. section \ref{SecBatchFiles}). An
alternative to \texttt{excite} script would be the \emph{extract reference
numbers from a text file} function of \texttt{References} described in section
\ref{sec:ExtractRefNo}. The disadvantage of that function is that it can only
extract \emph{one} item from each \verb+\cite{...}+, whereas \texttt{excite}
can extract all reference numbers from a comma-delimited list as in 
\verb+\cite{label.1,label.2,...label.n}+ and in addition, excite can extract
reference numbers form \texttt{cite}s with optional parameter as in 
\verb+\cite[page n]{...}+.

\index{Harvard, \LaTeX\ package}
The command \mopt{edit-main-p xex} works similarly as \texttt{excite}, but it extends
the literature-referencing commands to many of those required by the
Harvard-package \cite{HarvardPackage}:
\verb+\cite{}+, 
\verb+\cite[]{}+, 
\verb+\citeasnoun{}+, 
\verb+\citeasnoun[]{}+,
\verb+\possessivecite{}+, 
\verb+\possessivecite[]{}+,
\verb+\citeaffixed{}{}+, 
\verb+\citeaffixed[]{}{}+,
\verb+\citeyear{}+, 
\verb+\citeyear[]{}+, 
\verb+\citename{}+, 
\verb+\citename[]{}+.


\index{LaTeX cite@\LaTeX\ \textbackslash cite\{\}}
\index{LaTeX citeasnoun@\LaTeX\ \textbackslash citeasnoun\{\}}
\index{LaTeX possessivecite@\LaTeX\ \textbackslash possessivecite\{\}}
\index{LaTeX citeaffixed@\LaTeX\ \textbackslash citeaffixed\{\}}
\index{LaTeX citeyear@\LaTeX\ \textbackslash citeyear\{\}}
\index{LaTeX citename@\LaTeX\ \textbackslash citename\{\}}


Both \mopt{edit-main p exc} and \mopt{edit-main p xex} only require that
\verb+\cite{...}+ and the constructs for the Harvard-package are written
within one line in the \LaTeX-files%
  \footnote{i.\,e. they must not contain a line-break!}.%
  \index{Natbib, \LaTeX-package}
The Natbib package \cite{NatbibPackage} has even more referencing commands: 
\verb+\citet{...}+, \verb+\citealt{...}+, \verb+\citeauthor{...}+ etc.,
therefore, an \texttt{AWK} or \texttt{perl}-script similar to
\texttt{exharv.awk}\footnote{the script that comes with \texttt{References}} 
may be written by the user.

% <---

\subsection{Tools for \LaTeX{} and \texttt{References}} % --->

\label{secToolsForRefLatex}

\index{fromcite.awk@\texttt{fromcite.awk} filter program}
\index{tocite.awk@\texttt{tocite.awk} filter program}
\index{cite, convert to refscite@\texttt{\textbackslash cite\{\}}, convert to \texttt{refscite()}}

If you have written a \LaTeX-document with reference numbers with
\verb+\cite{}+ (sections \ref{sec:ReferencesBibTeX}, 
\ref{sec:thebibliographyLists}) and wish to process the document 
further with reference numbers
in \verb+refscite()+ (cf. section \ref{sec:LaTeXWithRefscite}), 
you may convert the document with the
\verb+fromcite.awk+ script. You will find the script in the \texttt{bin}
subdirectory of your installation. \verb+fromcite.awk+ works like a  filter
program. You may use it at the (shell) command line:

\begin{verbatim}
   awk -f fromcite.awk < old.tex > new.tex
\end{verbatim}

It is even more practical to use the filter program from within an advanced
text editor like Vim or Emacs: both editors allow to process a region through
an external (``filter'') program. Details can be found in the documentation of
the text editors. The reverse is done by the script \verb+tocite.awk+, which
is used similarly.


% <---

\clearpage


%%% Local Variables: ***
%%% mode:latex ***
%%% TeX-master: "refsdok.tex"  ***
%%% End: ***
