
\section{Main functions of \texttt{References}}

\label{SecMainFunctions}

The command \mopt{main-e} (figure \ref{fig:MainMenu}), selects a group of
functions for editing, transferring and reading data. In detail, you can read
bibliographic records of the database, create empty forms (text files for
entering and editing data), transfer data from text file forms to the database
(and back), browse in lists of journal names and in the keywords thesaurus.

Lists of references or macros for various tasks 
are produced with the functions behind \mopt{main-l}, the
options behind \mopt{main-b} manipulate batch tables (bbt-files, tbt-files),
options behind \mopt{main-s} search for records in the database,
\mopt{main-d}-options process bibliographic format and macro 
definitions.  Functions
behind \mopt{main-t} manipulate text files, export database records into
archive files, import archive files. \mopt{Main-f} functions check and
restructure the database, and provides a simple `file manager'. \mopt{Main-i}
issues information on names of input text file forms\footnote{This is
especially important, if names for these input files have been changed, cf.
section \ref{SecConfigFile}}. 


\subsection{View references of the database}


\begin{figure}[h]
\small
\centering
\begin{boxedverbatim}
[j1] create empty form for j1-type bibliographic record,
     more: [j2], [b1], [b2], [b3], [m1], [m2]
     [ir] import bibliographic record/reference (from form to database),
     [er] export/edit bibliographic record/reference (write to form)
[fj] create empty form for journal data (name, short form ISSN)
     [ij] import journal data (from form to database),
     [ej] export/edit journal data (write to form),
     [lj] list journal data
[fk] create empty form for keywords (to be transferred to the thesaurus),
     [ik] import keywords (from form to thesaurus),
     [lk] list keywords
[ed] edit text files
[ c] browse complete database
[ b] browse database records by BBT-file
[ s] browse records by BBT-file from last search
[ q] back to main menu

[menu]:
\end{boxedverbatim}
\caption{Menu: enter, edit, view}
\label{fig:EnterEditMenu}
\end{figure} 

\begin{figure}[h]
\small
\centering
\begin{boxedverbatim}
[f] first, [l] last, [n] next, [p] previous, [c] current record
[k] go to reference with key number, [#] go to position number
[i] information: show record number, [s] save reference number in BBT-file
[a] show abstract (notes, text) of current record
[q] back to menu `enter, edit, view'

[menu]:
\end{boxedverbatim}
\caption{Menu: browse complete database}
  \label{fig:MenuNavigateInDBase}
\end{figure}


In order to ``browse'' (see the records of) 
the complete database
enter \mopt{main-e c}\footnote{In this manual, selections at menu prompts are
written in \mopt{boxed in monospaced font}, each menu selection (selections
are separated by spaces) has to be entered with the \texttt{Return}-key}.
\index{browse!complete database} Navigate within the database with options of
the menu shown in figure \ref{fig:MenuNavigateInDBase}: With \mopt{l}
(``last'') you go to the reference with the highest key number, with \mopt{p}
you go back one reference toward the beginning of the database. The option
\mopt{\#} allows you to jump to the n$^{th}$ record\footnote{The first record
is numbered $0$, the last $n-1$}, with \mopt{k} you may select a reference by
its reference number.  \index{browse!references referred to in a bbt-file} It
is possible to see a subset of references. Subsets of the reference numbers of
a database are defined in a bbt-file (cf. section \ref{SecBatchFiles}).  The
command \mopt{main-e b} (figure \ref{fig:EnterEditMenu}) prompts for selection
of a bbt-file (cf. section \ref{SecBatchFiles}). Then you will encounter the
menu with the navigation commands (figure \ref{fig:MenuNavigateInDBase}).  
The menu option
\mopt{main-e s} opens the bbt-file generated with the last search command.

%% \clearpage

\subsection{Enter references}

\label{SecEnterReferences}

\index{enter new bibliographic references}
To enter a bibliographic record for an article of a journal 
% write 
you should first generate an empty form for data entry with \mopt{main-e j1}.
The code \texttt{j1} refers to the document type of an entry, 
other document types and their codes
are described in section \ref{secDocumentTypes}. \texttt{References} prompts
you for a reference number and checks if it is really new to the database. 

In brief the next steps in the process to enter records are:

\begin{enumerate}
  \item enter the form with your text editor, e.\,g. with the command 
   \mopt{main-t ed r} or \mopt{edit-main-r},
  \item fill out the fields of the form (see figure \ref{fig:DataEntryj1} as
    an example), 
  \item save the form in the text editor, close the text editor,
  \item press \texttt{[Enter]} at the prompt: ``\texttt{Please press [ENTER] to
    continue}'', 
  \item import the file with \mopt{main-e ir}, this command prompts you to
    view the record with the message: ``\texttt{Check data of citation entered
    [f/l/n/p/+/-/r/ ... /q]}'', to go to the first page of the record, press 
    \mopt{f},
  \item after checking the file quit the viewing function with \mopt{q},
  \item \texttt{References} asks you if you really wish to transfer the record
    with the message: ``\texttt{Write this record into database [y/n]?}''.
  \item If the record with the current reference number is already in the
    database, you will additionally be asked if you wish to overwrite the
    existing record. 
\end{enumerate}

In the rest of this section, details of how to enter the record into the form
will be described.

\begin{figure}[htbp]

\begin{center}
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a001
----DOCUMENT-TYPE-[width:2]
j1
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----JOURNAL-[width:10]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]

----ISSUE-NUMBER-[width:8]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\end{center}
\caption[Data entry form for j1 document type]{Data entry form for j1 
  document type. Text has to be written into the empty lines below the field
  names as this has already been done automatically with ``\texttt{a001}'' and
  ``\texttt{j1}''.  Field specifications are indicated in \texttt{[~]}: the
  maximal number of characters is given as \texttt{[width:nn]}, fields with
  \texttt{w} appended may span over more than one line, \texttt{num} indicates
  that only (integer) numbers may be entered, \texttt{num:1..n} indicates the
  valid range.}
  \label{fig:DataEntryj1}
\end{figure}

Fields with a ``\texttt{w}''\footnote{\texttt{w} for word-wrap}
in the field-width specification: \texttt{[width:255w]}%
  \footnote{like \texttt{TITLE-ARTICLE}, \texttt{TITLE-BOOK},
  \texttt{PLACE-OF-PUBLICATION}, \texttt{PUBLISHER} or
  \texttt{ABSTRACT}, an exception it the
  \texttt{HOWPUBLISHED}-field of m1, m2-document types which is 
  also intended to be used for (sometimes rather long) URLs} 
may span over more than one line:

\begin{listing}{1}
----TITLE-ARTICLE-[width:255w]
A randomized comparison of a sirolimus-eluting stent with a standard stent
for coronary revascularization
----JOURNAL-[width:4]
\end{listing}

Please do not enter an empty line between the last line of a field and and the
label for the next field. However, to leave a field empty, you should leave an
empty line. Therefore,



\begin{listing}{1}
----ISSUE-NUMBER-[width:8]

----FIRST-PAGE-[width:10]
\end{listing}

is correct.
If you do not wish to enter the issue number of the journal for an article in
a journal, it may be omitted. Also the \texttt{STATUS}- and
\texttt{ABSTRACT}-fields are optional. In every case, \texttt{AUTHORS}- and
\texttt{KEYWORDS} (or \texttt{K-NUMBER})-fields \emph{must} 
contain valid entries,
otherwise it will not be possible to save the record. The
\texttt{TITLE-ARTIC\-LE},
\texttt{DATE-YEAR}, \texttt{VOLUME}, \texttt{FIRST-PAGE},
\texttt{LAST-PAGE}-fields should contain pertinent information, otherwise
\texttt{References} will not be able to compile correctly formatted lists of
references. 

\label{IDNR-field}
\label{identifying numbers field}
The \texttt{IDNR}-field%
  \footnote{introduced in \texttt{References} v4.3}  
may contain different \textbf{identifying numbers} (hence its abbreviated name)
or identifying strings. Here you may enter the string now known as 
\textbf{doi}%
  \footnote{\emph{digital object identifier}, for more information, see
  \url{http://www.doi.org}}
Each type of identifying string must be labelled with a tag, indicating the
type of the identifying number, which precedes the string, separated by a colon
(``:''). As an example 

\begin{verbatim}
   url:http://www.tmed.med.uni-rostock.de/hla.pdf
\end{verbatim}

indicates the URL of an electronic document.

Spaces and percent (\%) characters are forbidden in identifying numbers. If
such a number contains a space, please insert \texttt{\%20} instead, if an
identifying number contains a \texttt{\%}-character, insert \texttt{\%25}%
  \footnote{i.\,e. apply hexadecimal encoding, which will be fully supported
  for this field in later versions of \texttt{References}. This practice
  follows conventions for encoding forbidden characters in URLs}
  %% Literatur


Different identifying
numbers can be entered separated by spaces.


A complete example of a bibliographic record:

\begin{listing}[5]{1}
----REFERENCE-NUMBER-[width:12]
i06225
----DOCUMENT-TYPE-[width:2]
j1
----AUTHORS-[width:26,6]
Ceci,A
Baiardi,P
Felisi,M
Cappellini,MD
Carnelli,V
De Sanctis,V
Galanello,R
Maggio,A
Masera,G
Piga,A
Schettini,F
Stefano,I
Tricta,F
----TITLE-ARTICLE-[width:255w]
The safety and effectiveness of deferiprone in a large-scale, 3-year study in
Italian patients
----JOURNAL-[width:10]
bjh
----IDNR-[width:255]

----DATE-YEAR-[width:4;num]
2002
----DATE-MONTH-[width:2;num:1..12]
7
----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]
118
----ISSUE-NUMBER-[width:8]
1
----FIRST-PAGE-[width:10]
330
----LAST-PAGE-[width:10]
336
----STATUS-[width:12]
#001
----KEYWORDS-[width:75]
thalassemia major
chelation therapy
deferiprone
----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]
Ceci et al., 2002

In 1997, the Italian Ministry of Health created a special programme for
the controlled distribution of deferiprone to collect data and to evaluate
its safety and effectiveness in long-term use. Five hundred and thirty-two
thalassaemia patients from 86 treatment centres were enrolled in this
programme. One hundred and eighty-seven patients (32%) experienced a total
of 269 events that led to a temporary interruption or, in some cases, to a
discontinuation of treatment. The incidence of agranulocytosis and milder
neutropenias were 0.4/100 and 2.1/100 patient-years respectively.
Neutropenia occurred predominantly in younger and non-splenectomized
patients. Transient alanine transaminase increase, gastrointestinal
discomfort and arthralgia were the other most commonly reported events.
Ferritin levels showed a significant decrease in time after 3 years of
therapy. This is the largest number of deferiprone-treated patients to
have been reported to date. These data show that the drug was effective in
reducing serum ferritin levels and the incidence of adverse events was not
greater than the frequency reported in clinical trials.
----END-OF-RECORD
\end{listing}


\begin{figure}[p]
\begin{minipage}[b]{7cm}
  \centering \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a002
----DOCUMENT-TYPE-[width:2]
j2
----INSTITUTIONAL-AUTHOR-[width:140w]

----TITLE-ARTICLE-[width:255w]

----JOURNAL-[width:10]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]

----ISSUE-NUMBER-[width:8]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for j2 document type}
  \label{fig:DataEntryj2}  
\end{minipage} \hspace{4em}
\begin{minipage}[b]{7cm}
  \centering  \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a003
----DOCUMENT-TYPE-[width:2]
b1
----EDITORS-[width:26,6]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for b1 document type}
  \label{fig:DataEntryb1}  
\end{minipage}
\end{figure}


\begin{figure}
\begin{minipage}[b]{7cm}
  \centering  \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a004
----DOCUMENT-TYPE-[width:2]
b2
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----EDITORS-[width:26,6]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for b2 document type}
  \label{fig:DataEntryb2}
\end{minipage} \hspace{4em}
\begin{minipage}[b]{7cm}
  \centering  \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a005
----DOCUMENT-TYPE-[width:2]
b3
----INSTITUTIONAL-EDITOR-[width:140w]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for b3 document type}
  \label{fig:DataEntryb3}  
\end{minipage}
\end{figure}


\begin{figure}
\begin{minipage}[b]{7cm}
  \centering \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a006
----DOCUMENT-TYPE-[width:2]
m1
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----HOWPUBLISHED-[width:160]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for m1 document type}
  \label{fig:DataEntrym1}  

\end{minipage}
\hspace{4em}
\begin{minipage}[b]{7cm}
  \centering \scriptsize
\begin{boxedverbatim}
----REFERENCE-NUMBER-[width:12]
a007
----DOCUMENT-TYPE-[width:2]
m2
----INSTITUTIONAL-AUTHOR-[width:140w]

----TITLE-ARTICLE-[width:255w]

----HOWPUBLISHED-[width:160]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
\end{boxedverbatim}
\caption{Data entry form for m2 document type}
  \label{fig:DataEntrym2}  
\end{minipage}
\end{figure}


To obtain empty forms for j2-, b1-, b2-, b3-, m1-, m2-documents, 
enter \mopt{main-e b1} \dots \mopt{main-e m2}, 
resulting in forms are listed in figures 
\ref{fig:DataEntryj2},
\ref{fig:DataEntryb1},
\ref{fig:DataEntryb2},
\ref{fig:DataEntryb3},
\ref{fig:DataEntrym1},
\ref{fig:DataEntrym2}.



\subsection{Edit existing references}

\label{secEditExistingReferences}
To edit a reference already existing in the database:


\begin{enumerate}
  \item look up the record to be changed with \mopt{main-e c}\footnote{or
  \mopt{main-e b} or \mopt{main-e s}}, quit the \emph{browse \dots} function 
  with \mopt{q}. The record shown as you selected \mopt{q} is the
  \textbf{current record}.

  \item write the \textbf{current record} into the form text file 
  (default \verb+in_form.txt+) with
  \mopt{main-e er}.  
  
  \index{current record}
  \index{current record number}
  \index{record!current}
  \index{record number!current}
  Explanantion for \textbf{current record or current record number}:
  If you leave the function \emph{browse complete database}
  or the other two \emph{browse \dots} functions, this writes the record
  number of the current record into a small text file (\verb+R_KEY.T+ in the
  \texttt{rdb}-subdirectory\footnote{but this normally remains hidden to the
  user. \texttt{References} performs certain operations on \textbf{current
  records}, e.\,g. it jumps again to the current record if you select a
  function like \emph{browse complete database}: \mopt{main-e c}}). The
  current record is written into the form text file if \mopt{main-e er}.

  \item Then open form text file with the editor, make the necessary changes
  and write the form back into the editor with \mopt{main-e ir}. 
\end{enumerate}

In this process, you must not change the
document type of e record. In such cases, 
the command \mopt{main-e ir} will 
not accept the form and issue an error message like:

{ \small
\begin{verbatim}
  (Reading record)

  Problem: Label `----EDITORS-' not found where expected in C:\refs42\tutorial\in_form.txt

  (Record not stored)
\end{verbatim}

}

This results from a different order of field labels in forms for different
document types.


\subsection{Enter, edit journal (name, ISSN) data}
\label{sec:EnterEdJornalData}

\index{journal names data!enter, edit}
To enter  a record with journal name, ISSN, generate an empty form 
(figure \ref{fig:JournalDatEntry}) with
% You will enter journal data with the text form shown in figure 
% \ref{fig:JournalDatEntry}: select 
\mopt{main-e fj} [Enter a journal code
new to the actual database]. After 
writing details into the form with a text editor,
% entering the data in the text file, 
saving
the text file, the record is transferred to the database with 
the command \mopt{main-e ij}.
Deleting items from the journal names database table is described in
\ref{sec:DeleteKeywJNames}. To change data of a journal record, generate the
form with \mopt{main-e ej}.

%% \enlargethispage{20mm}

\begin{figure}[t]
\centering \small
\begin{boxedverbatim}
----JOURNAL-CODE-[width:10]
4lc
----COMPLETE-JOURNAL-NAME-[width:80]

----JOURNAL-SHORT-NAME-[width:60]

----ISSN-[width:14]

----END-OF-FILE
\end{boxedverbatim}
  \caption[Journal data text file form]{Journal 
  data text file form, default name is \texttt{jn\_form.txt}}
  \label{fig:JournalDatEntry}
\end{figure}

\subsection{Enter keywords thesaurus items}

\label{sec:EditKeywordsThesaurusItems}


\begin{figure}[h]
\centering
\begin{boxedverbatim}
----KEYWORDS-[width:45]

----END-OF-FILE
\end{boxedverbatim}

  \caption[Text file form for keywords thesaurus items]{Text 
    file form for keywords thesaurus items, default name:
  \texttt{ky\_name.txt}}
  \label{fig:iKeywordsItemsEntry}
\end{figure}


\index{kewords thesaurus!enter edit data}
If you wish to add new items to the keywords thesaurus, make an empty for with
\mopt{main-e fk} (figure \ref{fig:iKeywordsItemsEntry}), more than one new
keywords can be entered, each in a new line. Import these new keywords with 
\mopt{main-e ik}. Deleting items from the keywords thesaurus is described in
\ref{sec:DeleteKeywJNames}. If one or more items are already in the thesaurus,
they are ignored.

%% \clearpage


\subsection{Compile lists of references}
\label{SecListReferences}


\begin{figure}[h]
  \centering
\begin{boxedverbatim}
[s] write list of references in standard format
[u] write list with user defined format,
    [tu] test list with user defined format (read fde file)
[b] create list in BibTeX database format
[m] create macro for text processors, sorting
    [tm] test macro with user defined format (read fde-file)
[t] write text files with journal names, keywords
[a] export abstracts
[q] quit

[menu]:
\end{boxedverbatim}
  \caption{List of references menu}
  \label{fig:ListOfRefsMenu}
\end{figure}


The main menu option ``Compile lists of references'' comprises the central
functions of this software: lists of bibliographic references are written into
text files either in predefined formats%
  \footnote{``standard format'' \mopt{main-l s} 
  and ``Bib\TeX\ \mopt{main-l b} database format (cf. figure
  \ref{fig:ListOfRefsMenu})''} 
or in free formats. Some free bibliographic format
definitions are provided with the actual
\texttt{References} distribution, others may be written by the user (cf.
\ref{sec:WriteBiblFormatDef}) or obtained from the \url{References} 
website\footnote{\url{http://references.sourceforge.net/supplement.html}}.
Moreover, options \mopt{main-l m} and \mopt{main-l tm} allow to create macros
for various purposes.

The most simple way to generate a list of bibliographic items (in a
\textbf{``standard format''}):

\begin{itemize}
\item Select \mopt{main-l s} 
\item enter name for list of text file to be created\footnote{If
    you enter a file name which already exists, you will be asked to confirm
    overwriting with \mopt{y}} 
\item select name of bbt-file 
\item select a reference
  number format, in most cases: \mopt{1} 
  \footnote{more options in figure \ref{fig:ReferenceNoformatOptions}}
\item  enter number assigned to the first
  reference\footnote{Normally, you will confirm \mopt{1}}.
\end{itemize}



\begin{figure}[htbp]
  \centering
\begin{boxedverbatim}
[1] number only: (n) ...
[2] number and reference key: (n) <REFKEY> ...
[3] reference key: <REFKEY> ...
[4] no leading numbers
[5] REFKEY*00000N: tbt-format, wrapped (65 char)
[6] REFKEY*BBT-TEXT: tbt-format, wrapped (65 char)
[q] quit

[menu]:
\end{boxedverbatim}
  \caption{Reference number format options}
  \label{fig:ReferenceNoformatOptions}
\end{figure}

If you want to generate a list of references in a 
\textbf{free, user-defined format}, select \mopt{main-l u}.
After entering the name of the output file, selecting the
bbt-file the menu, the message

\begin{verbatim}
View list with bibliographic format definitions
\end{verbatim}

prompts you to open the list of bibliographic format definitions. With
\mopt{f} you will see  the first page, \mopt{menu} opens the menu with the
commands for navigation within the list. To proceed, close the list
with \mopt{q}. At the prompt

\begin{verbatim}
Format definition number, [quit] exit without selection:
\end{verbatim}

please enter the number of the selected format definition. As the next step,
select the reference number format (figure
\ref{fig:ReferenceNoformatOptions}), the number assigned to the first
reference. The command \mopt{main-l tu} (\textbf{``test user defined format
definition''}) works in a similar manner, except that it prompts you for
format definitions in text file format (text files with the extension
\texttt{.fde}). \mopt{Main-l b} creates a list of references in the format of
a \textbf{Bib\TeX\ database} (for documents written for the \LaTeX\ document
preparation system \cite{Lamport1995}, cf. chapter
\ref{sec:ReferencesBibTeX}).  \mopt{Main-l m} and \mopt{main-l tm} generate
lists of references in `macro' format, i.\,e. references are not separated by
empty lines, and the references have no leading reference numbers (as those
listed in figure \ref{fig:ReferenceNoformatOptions}). These two options
(\mopt{tu} and \mopt{tm}) may be used to make `search and replace' macros for
text processors, to generate a list of references for generation of a sorted
tbt-file (section \ref{sec:SortedReferences}). 
If the bbt-file contains reference numbers not found in the database,
\texttt{References} writes ``\verb+--ReferenceNo--+'' into the output 
file\footnote{with \texttt{ReferenceNo} for the current reference number},
``\verb+==ReferenceNo==+'' is inserted into macro format files. This feature
can be used deliberately to process manuscripts with reference numbers missing
in the database (section \ref{secProcRefNosMissingInDB}).


The menu option \mopt{main-l t} generates two text files, \verb+__jour__.txt+
and \verb+__keyw__.txt+.
\index{keywords!text file}
\index{journal names!text file}
\mopt{Main-l a} writes all abstracts (if they
exist) of the references referred to in a bbt-file into a text file.
\index{abstracts!write into text file}

\clearpage

\subsection{Batch files}
\label{SecBatchFiles}

\begin{figure}
\begin{center}
\begin{boxedverbatim}
[bt] convert bbt-file into tbt-file: bbt -> tbt, [tb] convert: tbt -> bbt
[s1] sort bbt-file by reference number field, [s2] sort by text field
[in] invert sequence of records in a bbt-file
[ay] write `author' and `year' into text field of a bbt-file
[rd] remove duplicate records (order of records remains unchanged)
[rs] remove duplicate records and sort by reference number
[ba] write bbt-file with all records from the current database
[br] create bbt-file with range of reference numbers (1st to 2nd record)
[ui] write `unique record identifiers' (URID) into text field of a bbt-file
[ed] extract duplicate records (text field) to a new bbt-file
[ u] union of bbt-files A and B: each record of resulting bbt-file C can be
     found in A or B or both
[ i] intersection of A and B: each record of C can be found in A and B
[ d] difference (complement) of A and B: C contains all records of A which
     are not found in B
[ q] back to main menu

[menu]:
\end{boxedverbatim}
\end{center}
\caption{Batch table functions menu}
\label{fig:BatchMenu}
\end{figure}

\index{batch tables}
\index{batch files}
Batch tables (batch files) are files with records containing reference
numbers (of records in a \texttt{References} database) 
in the first and a short text in the second field. They
play a central role in the \texttt{References} software as they 
list (sub)sets of records in a \texttt{References}
database\footnote{\texttt{References} batch files (filename extensions
\texttt{bbt}, \texttt{tbt}) have no relation to the batch files under MS-DOS
or Windows
(these should be better named script files for the 
COMMAND.COM shell of MS-DOS and have the
filename extension \texttt{bat})}. Batch files provide reference numbers for
the following operations (among others):

\begin{itemize}
\item compilation of lists of references or of macro text files 
  (section \ref{SecListReferences})
\item export of database records into an archive file 
  (section \ref{sec:ExportImportDbtoArr})
\item deletion of bibliographic references in the database
  (section \ref{SecDeleteBiblReferences})
\item storage of search operations for bibliographic references
  (section \ref{SecSearch})
\end{itemize}

\index{bbt-file}
\index{tbt-file}
\index{binary batch file (bbt)}
\index{text batch file (tbt)}
Batch files (as used by \texttt{References}) occur in two variants, \textbf{`binary'
batch files} (or \textbf{`binary batch tables'}, hence the filename extension
\texttt{bbt}) and \textbf{`text batch files'} (\textbf{`text batch tables'}, 
filename extension
\texttt{tbt}). \texttt{Tbt} files are plain text files which you may
manipulate with a text editor. Both types of files are referred to in this
manual as \texttt{bbt}-files or \texttt{tbt}-files. Batch files are read or
written by \texttt{References}
in bbt-format, they can be edited with a text editor after
conversion into the tbt-format and---after modification---are processed
further by \texttt{References} after conversion back into the bbt-format.



The commands for manipulation of batch tables may be found behind the
\emph{process batch files} \mopt{main-b} main menu option. 
\mopt{Main-b tb} converts the text version of a batch table
(\texttt{.tbt}) in the text-directory  into its binary (database-like)
equivalent (\texttt{.bbt}) and writes it into the
\verb+./rdb+-subdirectory. The \mopt{main-b bt} command performs a
conversion from bbt-file to tbt-file format and localization. 
A tbt file may be edited with a text editor. The left field between the
`\verb+*+'s is for the reference numbers (obligatory), the right field is a
text field, it can be used for sorting. In this example, the text field is
empty: 

\begin{listing}{1}
* i05863       *                                      *
* i05862       *                                      *
* i05861       *                                      *
* i05860       *                                      *
\end{listing}

If you convert a tbt-file with \mopt{Main-b tb}, leading and trailing spaces
in both fields are ``trimmed'':

\begin{verbatim*}
* i05863       *
\end{verbatim*}

is written as 

\begin{verbatim*}
i05863
\end{verbatim*}

into the bbt-file.  The command \mopt{main-b ay} writes authors names and year
of publication into the text field of a bbt-file. In the previous example it
produces a bbt-file which after conversion into a tbt file looks like:

\begin{listing}{1}
* i05863       * SONNENBERG                FA    2001 *
* i05862       * GOMBOTZ                   H     2000 *
* i05861       * DINKELMANN                S     2002 *
* i05860       * DIETRICH                  G     1999 *
\end{listing}

The command \mopt{main-b s1} sorts records of a bbt-file in ascending order of
reference numbers, \mopt{s2} sorts in ascending order of the text
field. \mopt{main-b in} inverts the order of records in a bbt-file. The
command \mopt{main-b rd} removes duplicate (or multiplicate) records (with
regard to the reference number). This command preserves the order of records,

\begin{listing}{1}
* i05863       * SONNENBERG                FA    2001 *
* i05862       * GOMBOTZ                   H     2000 *
* i05861       * DINKELMANN                S     2002 *
* i05860       * DIETRICH                  G     1999 *
* i05861       * DINKELMANN                S     2002 *
* i05862       * GOMBOTZ                   H     2000 *
* i05861       * DINKELMANN                S     2002 *
\end{listing}

will be converted to 

\begin{listing}{1}
* i05863       * SONNENBERG                FA    2001 *
* i05862       * GOMBOTZ                   H     2000 *
* i05861       * DINKELMANN                S     2002 *
* i05860       * DIETRICH                  G     1999 *
\end{listing}

i.\,e. only the first occurrence of each record is preserved. With the command 
\mopt{main-b rs} records are sorted into ascending order of reference numbers
and the duplicate records are removed. For large bbt-files, processing times
are shorter with the \mopt{main-b rs} command. \mopt{main-b ba} writes all
references numbers of the current database into a bbt-file (this is required to
produce an archive file (filename extension \texttt{.arr}) 
of the complete database). 
\mopt{Main-b br} makes a bbt-file with a \emph{range of reference numbers}.
To make a bbt-file with a complete sequence of reference numbers in the
database write the reference numbers of the first and last record of the range
into the reference number-field of a bbt-file:

\begin{listing}{1}
* i05860       *                                      *
* i05865       *                                      *
\end{listing}

After calling the \mopt{main-b br} command, select this bbt-file and the
function will expand this file to:

\begin{listing}{1}
* i05860       *                                      *
* i05861       *                                      *
* i05862       *                                      *
* i05863       *                                      *
* i05864       *                                      *
* i05865       *                                      *
\end{listing}

\mopt{main-b ui} looks up each reference number in the database and writes a
`unique record identifier' from each reference into the text field. You may
then select \mopt{i} for `case insensitive' (if lower and upper cases of
otherwise identical titles, author's numbers shall yield identical unique
identifier strings) or \mopt{s} for `case sensitive'.

\begin{listing}{1}
* i05778       * J1-0C4-00001400-000012B9             *
* i05779       * J1-0C4-00003037-00000949             *
* i05780       * J1-0C4-00001403-00000DE1             *
\end{listing}

\mopt{main-b ed} sorts the records of a bbt-file modified with 
\mopt{main-b ui} by test fields and makes a copy only with the duplicate 
or multiplicate records (text field). The last two functions are required for
identifying duplicate records in the database (and help to eliminate them).
Details are described in chapter \ref{sec:ElimDuplicateRecs}.


\index{sets of reference numbers/records!bbt-files}
\index{sets of reference numbers/records!operations on}
\index{bbt-file!set of reference numbers/records}
Three options \mopt{main-b u} (union), \mopt{main-b i} (intersection)
\mopt{main-b d} (difference/complement) offer operations on two \textbf{sets of
reference numbers/records} (represented by bbt-files, named in the 
description of the menu `A'
and `B') and writes a third one (named `C') (figure \ref{fig:BatchMenu}). 


\begin{description}
  \item[\mopt{main-b u}]  each record of the resulting bbt-file `C' can be found in 
  `A' \textbf{or} `B' or both
  \item[\mopt{main-b i}] intersection of `A' and `B': each record of `C' can be
  found in `A' \textbf{and} `B'
  \item[\mopt{main-b d}] difference (complement) of `A' and `B': `C' contains
  all records of `A' which are not found in~`B' 
\end{description}

These functions are useful to ``post-process'' bbt-files which are results of
search commands (cf. section \ref{SecSearch}).

\clearpage

\subsection{Search references}
\label{SecSearch}

\index{search!commands to process a search command}
Bibliographic references may be searched e.\,g. by authors'/editors' names, by
keywords, date of publications and many other options. After selecting
\texttt{s} from the main menu, \texttt{References} opens the text file with
search command\footnote{in the first line} and name of the
bbt-file\footnote{second line} (cf. section \ref{SecBatchFiles}).  By default,
its name is \verb+sr_form.txt+ (you may change its name as described in
chapter \ref{SecConfigFile}). Searching is best explained by an example. Open
\verb+sr_form.txt+ and write a search command (search command syntax will be
explained later) into the first line of this text file and the output bbt-file
name into the second line. The example in figure~\ref{fig:SearchCmdEx1} will
produce a the bbt-file \texttt{answ.bbt}\footnote{the suffix \texttt{.bbt}
will be added by the program, so enter only \texttt{answ}!}  with references
containing the string \texttt{blood} in the keywords-field.

\begin{figure}[htbp]
  \centering
\begin{boxedverbatim}
keyw=blood
answ

keyw=platelet & keyw=function

keyw=blood transfusion & keyw=infectious disease
bltr-inf

auth=Aster
aster
\end{boxedverbatim}
  \caption[Example of a search command file]{Example of a search command file. 
    The contents of the third and later lines will be ignored by
    \texttt{References}. In search command files you may store 
    previously used search commands for later use.}
  \label{fig:SearchCmdEx1}
\end{figure}

To process a search command,
select \mopt{main-s}. In the next menu you may enter \mopt{c}
if you wish to search the complete database. The alternative:
\mopt{b} may be selected if search shall be restricted to records listed in
a bbt-file. In the next menu search may be initiated case sensitive
\mopt{s} or case insensitive \mopt{i}. If records fulfilling
the search command are found, you can browse in the records with a menu 
similar
to that in
figure~\ref{fig:MenuNavigateInDBase} (page \pageref{fig:MenuNavigateInDBase}). 


In brief the sequence of things to to for searching is:

\begin{enumerate}
\item edit the search command file (default \verb+sr_form.txt+) 
\item enter \mopt{main-s c s}\footnote{case-sensitive} or 
  \mopt{main-s c i}\footnote{case-insensitive} 
\item (if records were found) browse through the 
  bbt-file with \mopt{l p p ...} (beginning with the last record) or
  \mopt{f n n ...} (beginning with the first record found).
\end{enumerate}

If you wish to view the records of the resulting bbt-file later, select
\mopt{main-e s}, this opens the bbt-file referred to in the second line of the
search command file, if it exists. Section \ref{SecSearchCommand} gives a
complete description of the search command syntax. 

If the search command file  does not exist or if its first line is empty,
\texttt{References} prompts you first for the search command and then for the
output (bbt) file name.


\clearpage 

\subsection{Bibliographic format definitions}

\label{secBibFD}

\subsubsection{Importing, exporting, deleting, sorting bibliographic format
  definitions}

Functions for management are selected from the \emph{bibliographic format
definitions} menu (figure \ref{fig:MenuBiblFD}) \mopt{main-d}.
Format definitions are stored in a database file and
\texttt{References} produces and reads two text file formats of single format
definitions or the complete set of format definitions. 

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
[ef] export format definition into form (.fde)
[if] import format definition (.fde) into database
[mf] make empty form (.fde) for format definition
[ex] export single format definition from database into text file (.fd)
[ea] export all format definitions from database into text file (.fd)
[im] import format definition from file (.fd) into database
[ d] delete format definition in database file
[ s] sort format definitions
[ q] quit

[menu]:
\end{boxedverbatim}
\end{center}  
  \caption{Menu: bibliographic format definitions}
  \label{fig:MenuBiblFD}
\end{figure}



``Plain'' format definitions with the extension
\texttt{.fd}\footnote{\texttt{.fd} for``format
definition''} 
\index{fd-file}
are intended for transfer of format defintions from one installation or
database to another\footnote{\texttt{.fd}-files may contain one or more
  format definitions whereas  \texttt{.fde}-files only contain a single 
  format definition}. 
Format definitions with the file name extension
\texttt{.fde}\footnote{\texttt{.fde} for ``format definition for editing''} 
\index{fde-file} are
intended for development of a format definition and for
modification by the user. \texttt{Fde}-files contain
interspersed short explanations 
(cf. section \ref{sec:BibliographicFormatDefForm}, 
page \pageref{sec:BibliographicFormatDefForm}) intended to help writing a
format definition:

\begin{verbatim}
BIBLIOGRAPHIC STYLE FORMAT DEFINITION -- REFERENCES 4.3

--
-- short name (key) of format definition
--
-- width: 20
--
format definition ''

--
-- description of bibliographic format definition
--
-- width 255
--
description ''

--
-- major elements (lines) for document type `journal article' (j1):
-- sequence of list of authors (%au), title (%ti), localization (%lo)
--
-- width: 3
--
j1 string 1 ''
j1 string 2 ''
j1 string 3 ''

--
-- major elements (lines) for document type `journal article' with
-- institutional author (j2): sequence of author (%au), title (%ti),
-- localization (%lo)
--
-- width: 3
--
j2 string 1 ''
j2 string 2 ''
j2 string 3 ''
\end{verbatim}


In the line:

\begin{verbatim}
  format definition '' 
\end{verbatim}

\texttt{format definition} is recognized as a``keyword'' by the \emph{import
  format definition} command (\mopt{main-d mf}). The ``value'' or the contents
for this field shall be inserted between the \texttt{''}s for (as
\texttt{'nature-bfd'}).

\begin{sloppypar}
  \mopt{Main-d ef} exports a single bibliographic format definition into a
  \texttt{fde}-file (text format).  Therefore, \texttt{References} shows you a
  list of all format definitions in the database, after closing this list with
  \mopt{q}, please enter the numerical code for this format definition. After
  making changes in this \texttt{fde}-file with the text editor, you may
  reimport this bibliographic format definition with \mopt{main-d if}. You are
  then asked if you wish to append it as a new format definition to the
  database, or if you wish to replace an already existing bibliographic format
  definition by the definition in the \texttt{fde}-file. In the latter case
  you will have to select the format definition to be replaced. The command
  \mopt{mf} writes a new \texttt{fde} text file. All the other commands in the
  \emph{bibliographic format definitions} menu (figure \ref{fig:MenuBiblFD})
  explain themselves.
\end{sloppypar}
\subsubsection{Writing bibliographic and macro format definitions}
\label{sec:WriteBiblFormatDef}



Different citation styles are discussed in \cite{i06135,i06177}.  The
following explanation on writing bibliographic format definitions relates to a
complete empty form printed in the appendix (section
\ref{sec:BibliographicFormatDefForm}, page
\pageref{sec:BibliographicFormatDefForm})
The format definitions feature provided by \texttt{References} may be used to
generate lists of references appended to a publication, such format
definitions may be referred as \emph{bibliographic format definitions}.
Moreover, this feature may be used to create \emph{macros}, e.\,g. those to
automatically replace ``raw'' reference numbers (\texttt{refscite(a3467)})
into numerical citation in the text (\texttt{[45]} or \texttt{/45/}) or
author-date text citations \cite{i06177}.%
  \index{bibliographic format definitions}
  \index{macro format definitions}
For smaller publications, it may also be practical to generate a table
for manual replacement of ``raw'' citations by numerical text citations. 
Such format definitions may be referred to as \emph{macro format definitions}.
An introduction to writing format definitions is given in the tutorial
(section \ref{secTutorialBFD}, page \pageref{secTutorialBFD}).

\subsubsection{\texttt{Fde}-files}

As already mentioned, format definition files for editing as produced with the
command \mopt{main-d mf} (filename extension \texttt{.fde}) have comments
introduced by ``\verb+--+''. The rest of this section describes the fields if
a \texttt{fde}-file (line numbers and field names refer to the format
definition form in section \ref{sec:BibliographicFormatDefForm}, page \pageref{sec:BibliographicFormatDefForm}).


\textbf{Line 8} 
(\texttt{format definition ''}):
A short abbreviated name
for the actual bibliographic
format definition, for example:

\begin{verbatim}
   format definition 'vanc-1'
\end{verbatim}


This short string (maximal length: 20 characters) is the key for sorting the
bibliographic format definition database file (with \mopt{main-d s}).

\textbf{Line 15}
(\texttt{description ''}):
A short description of the format definition in 255 characters (line 15).

\textbf{Line 23--25} 
(\texttt{j1 string 1 '' ... j1 string 3 ''}):
Sequence of major elements for j1-documents (articles in
a journal/periodical). You may enter \texttt{\%au} (list of authors' names),
\texttt{\%ti} (title), \texttt{\%lo} (items related with the
``localization'' of the reference: journal name, volume, date of publication,
range of pages). These three elements: 
\index{list of authors line (bibliographic format definitions)}
\emph{list of authors line},
\index{title line (bibliographic format definitions)}
\emph{title line} 
and 
\index{localization line (bibliographic format definitions)}
\emph{localization line} will be specified in more detail later. If you enter

\begin{verbatim}
   j1 string 1 '%au'
   j1 string 2 '%ti'
   j1 string 3 '%lo'
\end{verbatim}

authors' names will appear first in lists of references generated with this
format definition, followed by the title, and the localization of the
article. This will be the most common case.

 
\textbf{Line 34--36}
(\texttt{j2 string 1 '' ... j2 string 3 ''}):
Sequence of major elements for j2 documents (articles in a journal/periodical
with institutional author). You may enter \texttt{\%au} (author's
name), \texttt{\%ti} (title), \texttt{\%lo} (items related with the
``localization'' of the reference: journal name, volume, date of publication,
range of pages).

\textbf{Line 44--46} 
(\texttt{b1 string 1 '' ... b1 string 3 ''}):
Sequence of major elements for b1-documents (complete
books). You may enter \texttt{\%ed} (list of editors'/book authors' names),
\texttt{\%bo} (title of book), \texttt{\%so} (items related to the
``localization'' of the reference: year of publication, publisher, place of
publisher, range of pages, edition number).

\textbf{Line 44--47} 
(\texttt{b2 string 1 '' ... b2 string 5 ''}):
Sequence of major elements for b2-documents
(chapter/article in a book). You may enter \texttt{\%au} (list of authors'
names), \texttt{\%bo} (title of book), 
\texttt{\%ti} (title of chapter/article),
\texttt{\%ed} (list of editors'/book authors' names),
\texttt{\%so} (anything related to the
``localization'' of the reference: year of publication, publisher, place of
publisher, range of pages, edition number).

\textbf{Line 68--70}
(\texttt{b3 string 1 '' ... b3 string 3 ''}):
Sequence of major elements for b1-documents (complete
books with institutional/no editor). 
You may enter \texttt{\%ed} (editor's name),
\texttt{\%bo} (title of book), \texttt{\%so} (items related to the
``localization'' of the reference: year of publication, publisher, place of
publisher, range of pages, edition number).

\textbf{Line 78--80}
(\texttt{m1 string 1 '' ... m1 string 3 ''}):
Sequence of major elements for m1-documents (miscellanea). 
You may enter \texttt{\%au} (list of authors' names),
\texttt{\%ti} (title), \texttt{\%so} (items related to the
``localization'' of the reference: year of publication, ``howpublished'').

\textbf{Line 89--91}
(\texttt{m2 string 1 '' ... m2 string 3 ''}):
Sequence of major elements for m1-documents (miscellanea with institutional/no
author). 
You may enter \texttt{\%au} (authors name),
\texttt{\%ti} (title), \texttt{\%so} (items related to the
``localization'' of the reference: year of publication, ``howpublished'').


\textbf{Line 98--105} 
(\texttt{j1 authors 0 '' ... j1 authors 7 ''}):
specification of the \emph{list of authors line} (j1-document):
keywords listed in chapter \ref{rfdky:j1title} may be used, their functions
are described in section \ref{DescriptionOfKeywords}.

Lists of editors, title, book-title and localization lines for all document
types are entered analogously as line 98--105.

\sloppypar
\textbf{Line 702--706} 
(\texttt{j1 authors string type '' ... m1 editors string type ''}):
determine the sequence of names and first names in the
authors' and editors' lists as described in table
\ref{tab:SequenceAuthNames}. In this field only 0, 1, 2 or 3 may be entered.

\begin{table}[h]
\begin{center}
\begin{tabular}{cp{6.2cm}p{6.2cm}} \hline
\textbf{Code} & \textbf{Type} & \textbf{Example} \\ \hline
0 & 
  Enters only last names & 
   Miller, Smith and Lastwriter \\
1 & 
  Last names before first names & 
    Miller  A. A., Smith B. B. and Lastwriter Z. Z. \\
2 & 
  First names before names & 
    A. A. Miller, B. B. Smith and Z. Z. Lastwriter \\
3 & 
   Type 1 for first author and type 2 for following authors &
    Miller, A. A., B. B. Smith and Z. Z. Lastwriter \\ \hline
\end{tabular}
\end{center}
\caption[Bibliographic format definitions: sequence of
        authors' names]{Sequence of authors' names}
\label{tab:SequenceAuthNames}
\end{table}


\sloppypar
\textbf{Line 715--719, 728-732, 741--745, 754--758, 767--771, 780--784}
(\texttt{j1 delimiter \^{}1 in authors string '' ... m1 delimiter \^{}6 in
authors string ''}) 
Delimiters between authors' names and forenames are
specified with six delimiters (firgure \ref{fig:AuthorsListsDelimiters}). The
special keyword \texttt{\%()} (see table in chapter
\ref{DescriptionOfKeywords}) allows to insert the argument in brackets, this
may be better readable, but both 
\verb*+'%(. )'+ and \verb*+'. '+ 
yield the same result.

\begin{figure}[htbp]
  \centering 

\begin{boxedverbatim}
FirstAuth, A. A., B. B. SecondAuth, C. C. ThirdAuth & Z. Z. LastAuth.   
                ^^1               ^^1              ^^^2             ^6  
FirstAuth, A. A., B. B. SecondAuth, C. C. ThirdAuth & Z. Z. LastAuth.   
         ^^5^^3^3      ^4            ^3  ^4                         ^6  
\end{boxedverbatim}

  \caption[Bibliographic format 
    definitions: delimiters for authors' and editors' lists]{Delimiters 
    for authors' and editors' lists. 
    1: delimiter between authors' names,
    2: delimiter between the last two authors' names,
    3: delimiter after first names (forenames),
    4: delimiter between first names (forenames) and names,
    5: delimiter between names and first names (forenames),
    6: delimiter after last name}
  \label{fig:AuthorsListsDelimiters}
\end{figure}




\textbf{Line 793--797} 
(\texttt{j1 delimiter more names in authors string '' ... m1 delimiter more
names in editors string ''}): If a list of authors contains more names than
the number of authors printed this can be indicated with a clause like 
\textit{``et al.''} 


\textbf{Line 806--810, 820--824}
(\texttt{j1 n in authors string '' ... m1 m in editors string ''}): 
Two numbers ($m$, $n$) control the numbers of authors
printed into the list. They refer to a rule like \textbf{print all authors 
if not more than $n$ else print $m$}. The Vancouver convention of citing
references \cite{i03285} may serve as an example: $n=6$, $m=3$. 

\clearpage


\subsection{Manipulation of text files}
\label{sec:manip-text-files}

\subsubsection{Export/import of records from/into database (arr-files) --
backups of \texttt{References} databases}
\label{sec:ExportImportDbtoArr}

\index{backup!database}
\index{database!make a backup}

\mopt{Main-t ex} exports records from a \texttt{References}
database into a defined text format (an archive file). Archive files (filename
extension \texttt{.arr})%
 \index{arr-file}
 \index{archive-files}
are described in section \ref{sec:ArchiveFilesDescript}. 
You may either write a complete archive
file with \mopt{c}, in this case the archive file will contain the keywords
thesaurus and the complete journal names database. 
\mopt{Main-t ex e} writes an archive without journal names and without
keywords thesaurus.
The next steps: 

\begin{itemize}
\item enter the name of the archive file\footnote{the extension \texttt{arr} will
    be appended automatically} 
\item select the bbt-file with the records to be
  exported and 
\item determine with \mopt{o} that the original references numbers
  are preserved in the archive file\footnote{if new numbers shall be assigned
    to the records: \mopt{n}}.
\end{itemize}

\textbf{It is strongly recommended to make regular backups (as
\texttt{.arr}-files)}

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
[im] import data from archive file
[ex] export data into archive file
[lt] write list of references to LaTeX ``thebibliography'' environment
[xr] extract reference numbers from a text file
[sr] search and replace operations
[me] convert medline input to form
[ed] edit text file
[vi] view text file
[ q] back to main menu

[menu]:
\end{boxedverbatim}
\end{center}
\caption{Menu: Text files, export/import from/into database}
  \label{fig:MenuTextFilesExIm}
\end{figure}

Contents of an archive file are imported with the command \mopt{main-t im}. 

The command \mopt{main-t lt} converts a text list of references (generated
with \mopt{main-l s} or \mopt{main-l u} in the reference number format
\verb+<reference-number> ...+) into a \texttt{thebibliography} 
environment for the
\LaTeX\ text processing software \cite{Lamport1995}. This issue is described
in detail in section \ref{sec:thebibliographyLists}, page 
\pageref{sec:thebibliographyLists}.

The command \mopt{main-t xr} extracts reference numbers from a document in the
format of a text file (cf. section \ref{sec:ExtractRefNo}), \mopt{main-t sr}
automatically performs ``search-and-replace'' operations. With \mopt{main-t
  me} you can convert a bibliographic reference from ``medline'' format into a
\texttt{References} input form, this procedure is described in detail in
section \ref{sec:ImportFromMedline} 
(page \pageref{sec:ImportFromMedline}). 

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
[r] references form
[s] search command form
[k] keywords thesaurus form
[j] journal data form
[3] three forms: r+k+j
[m] more text files
[t] type text file name
[q] quit

[menu] -->        
\end{boxedverbatim}
\end{center}
\caption{Menu: Edit text files}
  \label{fig:MenuTextFilesEdit}
\end{figure}


\mopt{main-t vi} opens a text file for reading text files, \mopt{main-t ed}
opens the menu of figure \ref{fig:MenuTextFilesEdit}.


\subsubsection{Extract reference numbers from a text file}

\label{sec:ExtractRefNo}

If you write a manuscript you may enter reference numbers directly into the
text in a format that allows to extract them. If a commercial text processor
is used, it will be necessary to make a copy of the document in the format of
a ``text only'' file%
  \footnote{This is most easily done by copying (the most relevant part of) the
  text into the clipboard. Then you will have to open the text editor,
  ``paste'' the data from the clipboard into an empty text document and save
  it as text file}. 
If you use \LaTeX\ or \TeX, \texttt{.tex} files may be
used directly. 

After selecting \mopt{main-t xr} you will be asked to enter a 
``search pattern''.
The default search pattern is \texttt{refscite()}, a second type is
\verb+refscite{}+. Please note that in the second type, curled braces are used
and that \verb+refscite(}+ or \verb+refscite{)+ are not valid search
patterns\footnote{i.\,e. you must use the same type of braces.}.  If you use
\LaTeX\ with Bib\TeX, you may use the search pattern 
\index{search pattern!extract reference numbers from text files}
\verb+\cite{}+\footnote{\texttt{References} provides a better solution for
  \LaTeX\ users with the \mopt{edit-main-p exc} and 
  \mopt{edit-main-p xex} commands, see
  chapter \ref{sec:ExtractLatexCitations} (figure
  \ref{fig:TextEditorShellProcessTextFiles},
  page \pageref{fig:TextEditorShellProcessTextFiles})}.

To get an idea how this function works, enter a small fragment of text into a
file (e.\,g. \texttt{testxr.txt})

\begin{verbatim}
...
Red cell antibodies were detected with a modification of the direct
antiglobulin test refscite(200112Co), eluates were prepared with the acid
elution technique refscite(199401Pa) refscite(199907In).
...
\end{verbatim}



Then process it with \texttt{References}

\begin{itemize}
\item \mopt{main-t xr txt} 
\item type number assigned to \texttt{testxr.txt} 
\item Enter
  name for bbt-file, e.\,g.  \texttt{testxr}\footnote{You may enter any valid
    filename here!}
\item   Accept \texttt{refscite()} search pattern with
  [Enter].
\end{itemize}

You may read output by
converting it into a tbt-file (\mopt{main-b bt}, cf. section
\ref{SecBatchFiles}, page \pageref{SecBatchFiles}):

\begin{verbatim}
* 200112Co     *                                      *
* 199401Pa     *                                      *
* 199907In     *                                      *
\end{verbatim}

If you wish to use another search pattern, e.\,g. ``\texttt{//cite()}'',
reference numbers should be formatted in the text as:


\begin{verbatim}
...
Red cell antibodies were detected with a modification of the direct
antiglobulin test //cite(200112Co), eluates were prepared with the acid
elution technique //cite(199401Pa) //cite(199907In).
...
\end{verbatim}

this file can be processed: 
\begin{itemize}
\item \mopt{main-t xr txt} 
\item  type the number assigned to \texttt{testxr.txt} 
\item  type name for bbt-file, e.\,g.  \texttt{testxr}
\item  enter search pattern \texttt{//cite()}
\end{itemize}

Batch files generated from manuscripts with this command are
used to produce formatted lists of references for a manuscript 
(section \ref{SecListReferences}, page \pageref{SecListReferences})
and to generate macros for text processors which can 
convert ``raw'' citations as
\texttt{refscite(cite(200112Co))} into properly formatted numeric citations as
\texttt{[12]} or citations in author-year format, like: (Mueller et al, 2001)
(section \ref{sec:FormattedCitationsMS}), page
  \pageref{sec:FormattedCitationsMS}). 

\subsubsection{Perform automated ``Search and replace'' operations}

\label{sec:SearchAndReplace}

With the command \mopt{main-t sr} you have access to a function which can
perform automated `search-and-replace' operations. It is used by writing the
\emph{strings to be replaced} and the \emph{new text} into a
search-and-replace script with the filename extension \texttt{sr}.  The
function is best explained by an example. In the text fragment \cite[page
5-6]{m00466} in text file named \texttt{book.txt}, both ``\texttt{emac}'' and
``\texttt{Emac}'' shall be corrected:

\begin{verbatim}
To start emac, simply start emac followed by the name of the file to edit. If
you use a filename that doesn't exist, Emac creates a new file. Of course, if
the file you request already exists, Emac reads the file and displays it on
the screen.
\end{verbatim}

\index{sr-file}
\index{sr-script}
\index{search-and-replace script}
If you wish to replace `emac' by `emacs' and `Emac' by `Emacs' you may write
this into a `search-and-replace' script (\texttt{emacs.sr})\footnote{Files with
the extension \texttt{sr} will be called sr-files or sr-script}:

\begin{verbatim}
/emac/emacs/
/Emac/Emacs/
\end{verbatim}



To process the text file \texttt{book.txt} with the script in
\texttt{emacs.sr}: 

\begin{itemize}
\item select \mopt{main-t sr txt} 
\item enter the number assigned to  \texttt{book.txt} (the file to be processed),
\item enter the number assigned to \texttt{emacs.sr} (the sr-file)
\end{itemize}

If you open \texttt{book.txt} with a text editor you can see the `corrected'
text:

\begin{verbatim}
To start emacs, simply start emacs followed by the name of the file to edit. If
you use a filename that doesn't exist, Emacs creates a new file. Of course, if
the file you request already exists, Emacs reads the file and displays it on
the screen.
\end{verbatim}

Each valid line in a sr-script performs a \emph{search and replace}-operation.
The `syntax' for a sr-script:

\begin{verbatim}
<Delimiter>text to be searched<Delimiter>text to be inserted<Delimiter>
\end{verbatim}

The following rules apply to sr-scripts:

\begin{enumerate}
\item \texttt{References} understands the first character in each line as the
  delimiter which indicates beginning and end of the \emph{text to searched}
  and the \emph{to be inserted in place of the (removed) text to be
  searched}.
\item The delimiter therefore should not be a characater which appears in the
  \emph{text to searched} or in the \emph{new text with the replacements
  done}\footnote{In the example above the delimiter was a slash (`/')}.
\item each line is a search-and-replace command, however, characters following
  the third occurrence of a delimiter will be ignored (or regarded as
  `comment'). In our example,

\begin{verbatim}
/emac/emacs/ ...lower case
/Emac/Emacs/ ...upcase
\end{verbatim}

  will perform as  

\begin{verbatim}
/emac/emacs/
/Emac/Emacs/
\end{verbatim}
  
\item lines with identical text for \emph{text to searched} and \emph{new text
    with the replacements to be done} are ignored, therefore strings like

\begin{verbatim}
/././
'-'-'
ababa
\end{verbatim}

may be used to introduce a comment. The sr-lines

\begin{verbatim}
* **
* *
. ..
. .
\end{verbatim}

may be used to remove spaces.

\item The string \verb+\n+ has a special meaning. If it occurs alone in the
  \emph{new text with the replacements to be done}-field, in introduces
  end-of-line characters into the text file. % Beispiel

\item The \emph{search and replace} function first processes the the first
  line of a text file, i.\,e. it executes all lines in the sr-file, then reads
  the second line of the text file and so on. Each operation is written into a
  special log file (\texttt{srchrepl.log}).

\end{enumerate}

%% stored in the text file \texttt{srexpl.txt}

Powerful alternatives for complex ``search and replace''-operations can be
realized with script tools like \texttt{sed}, \texttt{awk},
\texttt{perl}%
  \index{regular expressions}%
\footnote{They are much more more flexible as they make use of
\textbf{regular expressions}}.



\subsubsection{Import bibliographic records from the PubMed MEDLINE display format}

%  PubMed MEDLINE display format
%  Bezeichnung ist der Hilfeseite:
%  http://www.ncbi.nlm.nih.gov/entrez/query/static/help/pmhelp.html#MEDLINEDisplayFormat
%  entmommen

\label{sec:ImportFromMedline}
\index{PubMed MEDLINE display format}
\index{MEDLINE format}
Workers in the field of biomedical sciences often use PubMed, a service at the
NLM\footnote{National Library of Medicine}, which gives access to the contents
of the MEDLINE bibliographic database. As of the time of writing, PubMed is
accessible under the URL \url{http://www.ncbi.nlm.nih.gov/entrez/query.fcgi}.

Users of \texttt{References} may download bibliographic references in the
``MEDLINE'' display format and enter it directly into a \texttt{References}
database. An example of such a bibliographic record:

\begin{listing}[5]{1}
UI  - 89274408
PMID- 2471562
DA  - 19890714
DCOM- 19890714
LR  - 20001218
IS  - 0006-4971
VI  - 73
IP  - 8
DP  - 1989 Jun
TI  - The Bra/Brb alloantigen system on human platelets.
PG  - 2219-23
AB  - Anti-Bra was first identified in four cases of neonatal alloimmune
      thrombocytopenia (NAIT). The antigen Bra is localized on the glycoprotein
      Ia/IIa complex of platelets. Anti-Bra can best be detected by a
      glycoprotein-specific immunoassay using monoclonal antibodies for antigen
      immobilization (MAIPA assay) and radioimmunoprecipitation (RIP). Recently,
      we have identified sera from two polytransfused patients that contain an
      antibody that recognizes Brb, the allele of Bra. Family studies show that
      both antigens are inherited as autosomal codominant characters. The gene
      frequency of the new allele Brb is 0.888. Approximately 2,000 anti-Bra
      binding sites are present on homozygous platelets and 1,000 on
      heterozygous platelets. Our findings provide evidence for the first
      polymorphism observed on the glycoprotein Ia/IIa complex. Immunization
      against these alloantigens is implicated in NAIT and poly-transfused
      patients.
AD  - Institute for Clinical Immunology, Justus-Liebig-University, Giessen,
      Federal Republic of Germany.
FAU - Kiefel, V
AU  - Kiefel V
FAU - Santoso, S
AU  - Santoso S
FAU - Katzmann, B
AU  - Katzmann B
FAU - Mueller-Eckhardt, C
AU  - Mueller-Eckhardt C
LA  - eng
PT  - Journal Article
CY  - UNITED STATES
TA  - Blood
JID - 7603509
RN  - 0 (Antibodies, Monoclonal)
RN  - 0 (Binding Sites, Antibody)
RN  - 0 (Epitopes)
RN  - 0 (Isoantibodies)
RN  - 0 (Isoantigens)
RN  - 0 (platelet-specific alloantigen Br(a))
SB  - AIM
SB  - IM
MH  - Antibodies, Monoclonal/analysis
MH  - Antibody Specificity
MH  - Binding Sites, Antibody
MH  - Blood Platelets/*immunology
MH  - Epitopes/analysis/immunology
MH  - Human
MH  - Isoantibodies/analysis
MH  - Isoantigens/*analysis/genetics/immunology
MH  - Pedigree
MH  - Phenotype
MH  - Precipitin Tests
MH  - Support, Non-U.S. Gov't
EDAT- 1989/06/01
MHDA- 1989/06/01 00:01
PST - ppublish
SO  - Blood 1989 Jun;73(8):2219-23.
\end{listing}

This record format is able to give information of articles in journals
(periodicals). ``Fields'' are labelled with a ``tag'' at the beginning of the
line. For example \texttt{UI} denotes a unique identifier. The tags
indicating fields transferred into a \texttt{References} record are shown
alphabetically in table \ref{tab:MedlineTags}. 

\begin{table}[htbp]
  \centering
  \begin{tabular}{lp{12cm}}
Tag & description \\ \hline
\texttt{AU} & authors \\
\texttt{AB} & abstract \\
\texttt{DP} & date of publication (year) \\
\texttt{IP} & The number of the issue, part, or supplement of the journal in
              which the article was published \\
\texttt{MH} & MeSH (Medical Subject Headings) terms 
               (in the controlled NLM vocabulary) \\
\texttt{PG} & range of pages (first page -- last page) of the article \\
\texttt{TA} & journal title abbreviation \\
\texttt{TI} & title of the article \\
\texttt{VI} & volume of the journal \\ \hline
  \end{tabular}
  \caption{Tags of the PubMed Medline format translated by
    \texttt{References}}

  \label{tab:MedlineTags}
\end{table}

To convert the above Medline record (example for a file name:
\texttt{me1.txt}\footnote{The filename extension for medline records must be
  \texttt{.txt}}) into an input form\footnote{\texttt{j1}-Format} do the
following:

\begin{itemize}
\item \mopt{main-t me} 
\item select number assigned to \texttt{me1.txt} 
\item enter the reference number for the new record\footnote{this number shall
  be new to the database} like \texttt{i06333},
\item enter  \mopt{n} if contents of the MeSH-fields shall be ignored, 
  \mopt{y} if
  MeSH-entries shall be included.
\end{itemize}

The input form can then be opened with the text editor:

\begin{listing}[5]{1}
----REFERENCE-NUMBER-[width:12]
ChangeMe
----DOCUMENT-TYPE-[width:2]
j1
----AUTHORS-[width:26,6]
Kiefel,V
Santoso,S
Katzmann,B
Mueller-Eckhardt,C
----TITLE-ARTICLE-[width:255]
The Bra/Brb alloantigen system on human platelets
----JOURNAL-[width:4]
blo
----DATE-YEAR-[width:4;num]
1989
----DATE-MONTH-[width:2;num:1..12]
6
----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]
73
----ISSUE-NUMBER-[width:8]
8
----FIRST-PAGE-[width:10]
2219
----LAST-PAGE-[width:10]
2223
----STATUS-[width:12]

----KEYWORDS-[width:45]
no MeSH in MEDLINE format
----K-NUMBER-[width:12]

----ABSTRACT-[width:30600]
AB  - Anti-Bra was first identified in four cases of neonatal alloimmune
      thrombocytopenia (NAIT). The antigen Bra is localized on the glycoprotein
      Ia/IIa complex of platelets. Anti-Bra can best be detected by a
      glycoprotein-specific immunoassay using monoclonal antibodies for antigen
      immobilization (MAIPA assay) and radioimmunoprecipitation (RIP). Recently,
      we have identified sera from two polytransfused patients that contain an
      antibody that recognizes Brb, the allele of Bra. Family studies show that
      both antigens are inherited as autosomal codominant characters. The gene
      frequency of the new allele Brb is 0.888. Approximately 2,000 anti-Bra
      binding sites are present on homozygous platelets and 1,000 on
      heterozygous platelets. Our findings provide evidence for the first
      polymorphism observed on the glycoprotein Ia/IIa complex. Immunization
      against these alloantigens is implicated in NAIT and poly-transfused
      patients.

----END-OF-RECORD
\end{listing}

Before importing this record into the database, some items must be checked and
edited, if necessary:

\begin{description}

\item[line 11:] With some references it may be necessary to change
  capitalization of the title,
\item[line 13:] check if \texttt{References} was successful in identifying the
  correct journal name code, correct the code and enter data for a new journal
  (cf. section \ref{sec:EnterEdJornalData}) if necessary,
\item[lines 31, 33:] enter/edit keywords\footnote{\texttt{References} requires
    at least one entry in the \texttt{KEYWORDS} or \texttt{K-NUMBER}-field to
    store the record}.
\end{description}

The record may then be entered with \mopt{main-e ir}, then you should have
again a look into the converted record in the text view function with \mopt{f
  n ... q} with \mopt{y} you confirm that the record is written into the
database. 



\subsubsection{View text files}

The \emph{view text file} function may be used directly through the command
\mopt{main-t vi}, after selecting the text file and \mopt{menu}, the menu with
the commands for navigating in the text file become visible (figure
\ref{fig:ViewTextFilesMenu}). Details have been described in section
\ref{sec:ViewTextFiles}, page \pageref{sec:ViewTextFiles}.  


\clearpage


\subsection{File, database and system functions}
\label{sec:FileDBSystemFunct}

The menu for file, database and system functions is shown in figure
\ref{fig:FileDatabaseSystemFunct}. To execute a command of a/the shell of the
operation system select \mopt{main-f s}. \mopt{Main-f v} verifies integrity of
all database, index and bbt-files, \mopt{main-f k} deletes entries from the
keywords thesaurus, \mopt{j} from the journal names database. 
The option \mopt{s} can be
called to execute a shell command, \mopt{c} opens the configuration file in
the text editor.


\begin{figure}[h]
  \begin{center}
\begin{boxedverbatim}
[f] file manager: delete, rename, duplicate files
[r] rebuild current database
[v] verify database integrity
[d] delete references in database
[k] delete keywords in thesaurus
[j] delete journal entry
[s] shell command
[c] edit configuration file
[q] quit

[menu]:
\end{boxedverbatim} 
  \end{center}
\caption{Menu: file, database and system functions}
\label{fig:FileDatabaseSystemFunct}
\end{figure} 


\subsubsection{File manager}
\label{SecMainFunctionsFileManager}

This fuction provides a primitive ``file manager''
(figure~\ref{fig:FileManager}) for the files in the database text files and
binary files directories:%
  \index{database text files directory}%
  \index{database binary files directory}%
\mopt{main-f f}. To delete a file, select \mopt{d}, the next menu prompts you
for possible extensions of text files (figure \ref{fig:FileManagerFileSel}).
The \mopt{r} (rename) command allows to rename a file%
  \footnote{The rename and duplicate commands preserve the filename
  extensions}, 
\mopt{2} (duplicate
file) makes a copy of a file in the same directory.

\begin{figure}[h]
  \begin{center}
\begin{boxedverbatim}
[d] delete file
[r] rename file
[2] duplicate file
[q] quit

[menu]:
\end{boxedverbatim} 
  \end{center}
\caption{File manager}
\label{fig:FileManager}
\end{figure} 


\begin{figure}[h]
  \begin{center}
\begin{boxedverbatim}
[bbt] binary batch table (*.bbt)
[tbt] text batch table/file (*.tbt)
[txt] (*.txt), [doc] (*.doc), [bib] (*.bib), [asc] (*.asc), [tex] (*.tex)
[arr] References archive file (*.arr), [fd] format definition (*.fd)
[fde] format definition for editing, [log] (References) log file
[ sr] search and replace script, [html] HTML web document
[  q] quit

[menu]:
\end{boxedverbatim} 
  \end{center}
\caption[File manager: selection for file name extension]{Selection 
  for file name extensions of file manager. Files with the extension
  \texttt{bbt} are expected in the database binary files directory, all other
  files in the database text files directory}
\label{fig:FileManagerFileSel}
\end{figure} 


\subsubsection{Rebuilding the database}

\index{rebuild the database}
\index{restructure the database}
\index{database!rebuild}
\index{database!restructure}
\mopt{Main-f r} brings you to the \emph{rebuild database} menu (figure
\ref{fig:RebuildDBase}). Adding and deleting records in a database enlarges
database files\footnote{e.\,g. all files with the extension \texttt{.dat} in
  the database binary files directory}, leaving unused space in these files.
The \emph{restructure database and index files} command \mopt{r} writes data
into new database files and recreates index files (except the files for the
abstract data and the bibliographic format definition table). \mopt{d}
rebuilds the abstract data and index files. The \mopt{i} and \mopt{a} commands
only refresh the index files. 
\index{create a set of new database files}
\index{database files!create a new set}
If you wish to create a new database, a set of
empty \texttt{.dat} and index (\texttt{ix}) files is created with
\mopt{c}. 
\index{delete all database files}
\index{database!delete all index and data files}
\mopt{2} deletes all \texttt{.dat} and \texttt{.ix}-files, \mopt{1}
deletes the same files except the format definition database
\texttt{formdef.dat}. 

\begin{figure}[h]
  \begin{center}
\begin{boxedverbatim}
[i] rebuild index files only
[r] restructure database and index files
[a] rebuild abstract index file
[d] restructure abstract database and index files
[c] create missing database and index files
[1] destroy database files but not format definition database
[2] destroy database files and format definition database
[q] quit

[menu]:
\end{boxedverbatim} 
  \end{center}
\caption{Commands to rebuild index files, database files and to delete database
files}
\label{fig:RebuildDBase}
\end{figure} 

\subsubsection{Delete bibliographic references in the database}

\label{SecDeleteBiblReferences}

If you wish to delete bibliographic references in the database you will have
to get their reference numbers into a bbt-file (see details in chapter
\ref{SecBatchFiles}). Before deleting something, it is prudent to export the
references referred to in this bbt-file into an archive file (section
\ref{sec:manip-text-files}), so you can ``undo''  a deleting-operation.
To delete, select \mopt{main-f d}, select the number assigned to the bbt-file
with the reference numbers to be deleted, confirm with \mopt{y}. The software
confirms that data have been deleted with a message like:

\begin{verbatim}
   (Deleting records)

   (Modifying main index file)
   (1 records successfully deleted)
   (Modifying abstract index file)
   (1 abstracts successfully deleted)
\end{verbatim}



\subsubsection{Delete items in the keywords thesaurus and in the journal names
  database}

\label{sec:DeleteKeywJNames}
\index{keywords thesaurus!deletion of items}
Keywords in the thesaurus are easily deleted with \mopt{main-f k}, to make a
list of items of the thesaurus fro selection, \texttt{References} prompts you
with

\begin{verbatim}
   Substring (empty for all keywords):
\end{verbatim}

if you enter a blank line with [Enter], \texttt{References} writes all
keywords into the list. A substring selects a subset of keywords 
containing this string. \mopt{f}
brings you to the first page of the list of keywords\footnote{either complete
or selected by substring}. \mopt{n} selects the next page of this list. If you
have found the item to be deleted, quit this list with \mopt{q} and enter the
number assigned to the selected keyword entry in the list.
\index{journal names!deletion}
You can delete journal names following a similar procedure with 
\mopt{main-f k}.


\clearpage


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