\section{Configuration file}
\label{SecConfigFile}

\index{configuration file}
Some features of \texttt{References} are determined by variables accessible to
the user in the configuration file. The configuration file 
(\texttt{refs.cfg} ) can be opened with
the command \mopt{main-f c}.
Default values of variables
values may be modified by assigning new values. As an example, the default name
of the text file (``form'') for entering bibliographic references is
\verb+in_form.txt+. If you wish \verb+enter.txt+  as the new name for this
purpose, enter the line

\begin{verbatim}
INPUT_FORM=enter.txt 
\end{verbatim}

into the configuration
file\footnote{\texttt{refs.cfg} (win32) or 
\texttt{\~{}/.refscfg} (Linux)}. A valid file name should be entered
(Chapter \ref{secValidFileNames}). If you enter \verb+#+ the rest of the line
is ignored, i.~e. the line

\begin{verbatim}
# INPUT_FORM=enter.txt 
\end{verbatim}

has no effect. The line

\begin{verbatim}
PROMPT=-->
\end{verbatim}

changes the appearance of the command line prompt within \texttt{References}
from default ``\verb+: +'' to ``\verb+-->+''.
You may wish to use another text editor, e.\,g. \texttt{win32pad.exe}
together with \texttt{References}.
This can be done by entering the line 

\begin{verbatim}
TEXT_EDITOR=win32pad.exe
\end{verbatim}


in the configuration file, if the directory which contains
\texttt{win32pad.exe} has been added to the \texttt{PATH} environment
variable. If not, you may also enter an absolute path as

\begin{verbatim}
TEXT_EDITOR=c:\editors\win32pad.exe
\end{verbatim}

A complete list of configuration file variables can be found in table 
\ref{ConfigFileVar}, (page \pageref{ConfigFileVar}).

\begin{table}
  \begin{center}
\begin{tabular}{lp{12.2cm}} \hline

\textbf{Variable} & \textbf{Description, default values} \\ \hline

\verb+LINES_OF_SCREEN+ & number of lines of screen, possible values range
  from \texttt{24} to \texttt{60}, default 25, for Linux 24\\

\verb+PROMPT+ & Command line prompt (within \texttt{References}), default ``\texttt{:~}'',
  enter a string, the string must not include a ``\texttt{=}'' or a
  ``\texttt{\#}''\\

\verb+OPEN_EDITOR_YN+ &  prompt for loading text file of interest
   in text editor (value: 1, default) or do not prompt (value: 0), the value
   ``1'' makes \texttt{References} more ``interactive'' by calling a menu:
   \texttt{open editor with ``name-of-text-file''? [y/n]}, 
   value ``0'' sets user
   interface to that of previous versions\\

\verb+FORM_LABEL+ & string which introduces field names in the text file for
    entering text file for entering bibliographic records,
    default ``\verb+----+''\\

\verb+INPUT_FORM+ & name of text file for entering bibliographic records
    default \verb+in_form.txt+ \\

\verb+JOURN_FORM+ & name of text file for entering journal names, default
    \verb+jn_form.txt+\\

\verb+KEYW_FORM+ & name of text file for entering keywords, default
    \verb+ky_form.txt+\\

\verb+SEARCH_FORM+ & name of text file for search commands, default 
    \verb+sr_form.txt+\\

\verb+TEMP_TEXT+ & name of temporary text file for viewing bibliographic
    records, before saving, lists of keywords, journal data, 
    default \verb+temp.txt+\\

\verb+TEXT_EDITOR+ & text editor called for editing forms and
    other text files, default \verb+notepad+, for Linux \verb+vim+ \\

\verb+TEXTFILE_ENCODING+ & (Linux only) encoding of text files, possible
   values: \verb+utf-8+, \verb+latin-1+, \verb+latin-9+, 
   \verb+ISO-8859+ (for \verb+latin-1+ or \verb+latin-2+), default:
   \verb+utf-8+\\

\verb+AWK+ & localization of the \texttt{AWK} executable file (used by 
   \texttt{etext}) default: \verb+c:\refs43\bin\awk.exe+, 
   default for Linux: \verb+awk+\\

\verb+PATH_TO_SCRIPTS+ & directory, where \verb+etext+ finds the
  \verb+AWK+-scripts, default: \verb+c:\refs43\bin\+, default for Linux:
  \verb+~/refs43/bin/+\\

% \verb+DBCS+ & database character set (cf. chapter \ref{sec:CharacterSet}) \\
% 
% \verb+EDCS+  & editor character set   (cf. chapter \ref{sec:CharacterSet}) \\
%
\verb+PDF_VIEWER+ & complete path of PDF-file viewer, default: empty string, 
   for Linux: \verb+xpdf+\\

\verb+USES_LESS+ & Linux only: if you add \verb+USES_LESS=1+ to the configuration file, then
\texttt{References} uses \emph{less} instead of the internal text viewing
function for showing text\\

\verb+LESS_OPTIONS+ & Linux only: this variable may be used to enter 
  command line options/parameters for less, if less is uses (i\,.e., if 
  the configuation file contains \verb+USES_LESS+) \\

\verb+HELP_FILE+ &  name (with complete path) of help file default
   \verb+..\doc\refsdok.pdf+, for Linux: \verb+~/refs43/doc/refsdok.pdf+  \\
\hline
\end{tabular}
\end{center}
\caption[Variables in configuration file]{Variables in configuration 
file \texttt{refs.cfg} (win32), \texttt{.refscfg} (Linux).
Paths in a Linux installation: replace ``\texttt{\~{}/}'' by your home
directory: ``\texttt{/home/username/}'' where username is to be replaced by
the appropriate string}
\label{ConfigFileVar}
\end{table}


%%%% -----------

\clearpage

\section{Miscellaneous}

\label{secMiscell}

\subsection{Document types processed by \texttt{References}}

\label{secDocumentTypes}

\index{document types}
Document types supported in the current \texttt{References} version are listed
in table \ref{tab:DocumentTypes}. The \emph{basic} document types in
scientific writing are those coded \texttt{j1}, \texttt{b1} and \texttt{b2},
these documents are usually written by \emph{personal authors}. Sometimes,
however, publications are issued by organizations, groups of institutions, or
groups of investigators \cite[p. 657]{i06177}. For such cases, the name of the
organization may be entered (tables \ref{tab:DocumentTypes},
\ref{tab:DocumentTypesAuEd}). Such organizations will be referred to in this
manual as \emph{institutional authors} or \emph{institutional editors}. %
  \index{authors!personal}%
  \index{authors!individual}%
  \index{personal authors}%
  \index{individual authors}%
  \index{editors!personal}%
  \index{editors!individual}%
  \index{personal editors}%
  \index{individual editors}%
  \index{authors!institutional}%
  \index{institutional authors}%
  \index{editors!institutional}%
  \index{institutional editors}%
Document types with institutional authors may also be used if no authors are
present\footnote{In this case fields for institutional authors or editors are
left empty}.



\begin{table}[htbp]
  \centering
  \begin{tabular}{cp{11cm}} \hline
  \textbf{Code} & \textbf{Document type} \\ \hline
  \texttt{j1} & article in a journal with personal author(s) \\
  \texttt{b1} & complete book with personal editor(s) \\
  \texttt{b2} & article in a book with personal editor(s) and personal author(s) \\[1ex]
  \texttt{j2} & article in a journal with institutional author(s) 
                                           or without authors \\
  \texttt{b3} & complete book with (or without) institutional editor(s) \\
% \texttt{b4} & article in a book with (or without) institutional editor(s) and personal author(s) of the article \\
% \texttt{b5} & article in a book with personal editor(s) and with (or without) institutional author(s) of the article \\
% \texttt{b6} & article in a book with  (or without) institutional editor(s) and with (or without) institutional author(s) of the article \\
  \texttt{m1} & miscellanea with personal author(s) \\
  \texttt{m2} & miscellanea with institutional author(s) or without author(s) \\
  \hline
  \end{tabular}
  \caption[\texttt{References} document types]{Document 
     types, \texttt{j1}, \texttt{b1}, \texttt{b2} are basic document types for
     publications issued by personal authors or editors, \texttt{m1},
     \texttt{m2 }may be used, if no other document types fit}
  \label{tab:DocumentTypes}
\end{table}


\begin{table}[h]
\begin{center}
\begin{tabular}{ccc} \hline
Document type & Author(s) & Editor(s) \\ \hline
j1    &   p   & -- \\
j2    &   i   & -- \\
b1    & --    & p \\
b2    &   p   & p \\
b3    & --    & i \\
% b4 & p & i \\
% b5 & i & p \\
% b6 & i & i \\
m1    &   p   & -- \\
m2    &   i   & -- \\
 \hline
\end{tabular}
\end{center}
  \caption[Document types with personal, institutional authors or 
  editors]{Document types with personal (p), institutional (i) authors or 
  editors}
  \label{tab:DocumentTypesAuEd}
\end{table}



\subsection{Valid file names}

\label{secValidFileNames}

\index{file names!valid}
\texttt{References} makes restrictions to file names, which are more
`severe' than the operating system allows. 
If you use \texttt{References} under Windows or Linux, the program
will accept the letters 


\begin{verbatim}
AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz1234567890_-.
\end{verbatim}

in their filenames. \texttt{References} allows a filename length of 72
characters.
The names `.', `..', `...', etc. are not accepted as valid file names,
but a file name under Windows/Linux may contain more than one full-stop. 
\texttt{References} will
\emph{not} accept file names with spaces. Accented letters and
`Umlaut'-characters will not be accepted. On Linux systems, small and capital
letters are distinguished.


\subsection{Log files}
\label{sec:LogFiles}

\index{log-files} \index{refs.log@\texttt{refs.log}}
\index{srchrepl.log@\texttt{srchrepl.log}}
\index{verify.log@\texttt{verify.log}} Many actions of \texttt{References} are
written into log-files. The main log file is \texttt{refs.log}. As
\texttt{References} appends new text to the file, the size of this log file
will grow, you should therefore delete (parts of it) it from time to time!  
The functions
\mopt{main-t sr}\footnote{performs search and replace operations} \mopt{main-f
  v}\footnote{verifies database integrity} create their own log files
(\texttt{srchrepl.log} and \texttt{verify.log}). As these functions overwrite
the previous version of the log file, it is not necessary to delete them
manually.

\subsection{\texttt{References} and character sets (encoding)}

\label{sec:CharacterSet}

\subsubsection{\texttt{References} on win32 systems}


On computers with Win32 systems, accented characters (\`A, \'A, \^A) or
characters like German ``\emph{Umlaut}'' characters 
(e.g. \"A) are assingned different
numerical codes in the environment of a graphical Windows interface and in a
text based console application. Win32 graphical user interfaces (GUIs) 
use latin-1 (identical with 
ISO/IEC 8859-1 character encoding)\footnote{To be precise, win32 uses
codepage 1252, similar to ISO/IEC 8859-1 character encoding} 
and the normal console may use 
codepage 850.
On a win32 system, \texttt{References} assumes that a graphical text editor
(like \texttt{notepad}) saves text file in latin-1 encoding and that the
console shows and reads text in cp850 encoding\footnote{This is a major change
from v4.2 and earlier, therefore you have to translate your archive file
before you have to import it into a \texttt{References} v4.3 installation}.
Internally, text is represented and saved into database files in latin-1
encoding. This means that \texttt{References} has to translate text from
latin-1 to cp850 when it prints text to the screen and that 
\texttt{References} converts text from cp850 to
latin-1 when it reads text you type at the \texttt{References} prompt. No
conversion is required beween text files and the database files.
A thorough discussion of this issue may be found elsewhere
\cite{WikipediaCharEncod}.
% \cite[page 24--30]{Petzoldt2000}

Before you import \texttt{.arr}- and \texttt{.fd}-files 
from earlier versions to a v4.3
installation you have to translate encoding from cp850 to latin-1, use the
program
\texttt{cp850-to-latin1.exe} in the \texttt{bin} subdirectory for this task.


\index{encoding}
\index{character encoding}
\index{cp850}
\index{codepage 850}
\index{latin-1 character encoding}
\index{ISO/IEC 8859-1 character encoding}

\subsubsection{\texttt{References} on Linux systems}

After installation on a Linux system \texttt{References} internally 
stores text in
latin-1 (ISO/IEC 8859-1) encoding. It assumes that the console and the text
editor uses utf-8 encoding. Thus the program converts between latin-1 and
utf-8 encoding when you when it prints text to the screen and converts back
from utf-8 to latin-1 encoding when it gets input from the
console.\footnote{These conversions are not done on Linux systems with latin-1
or latin-9 encoding, see below}

On \textbf{Linux systems with utf-8 encoding of text files},
\texttt{References} writes text files in latin-1 encoding to disk, and
converts these files to utf-8 encoding when you call the text editor with a
text file from \texttt{etext} or \texttt{refs43} (what you should always do
when you use \texttt{References} in Linux).

On \textbf{Linux systems with latin-1 encoding of text files} the
\texttt{radmin}-tool will write the line 

\begin{verbatim}
   TEXTFILE_ENCODING=ISO-8859
\end{verbatim}

into the configuration file (cf. table \ref{ConfigFileVar}, page
\pageref{ConfigFileVar}). You may enter this line also by hand into the
configuration file instead of \texttt{ISO-8859} you may also enter
\texttt{latin-1}. The same line in the configuration file can be used for
systems configured for latin-9 (ISO-4459-15) encoding: there are only small
differences between latin-1 and latin-9 so in these Linux installations 
will be stored
in latin-9 encoding in the \texttt{References} database files.


Before you import \texttt{.arr}- and \texttt{.fd}- files
from earlier versions to a v4.3
installation you have to translate encoding from cp850 to latin-1, use the
program
\texttt{bin/cp850-to-latin1} for this task. If the \texttt{.arr} file comes
from a win32 installation of \texttt{References}, you will have to change
newline (line break) character sequence from the win32/DOS operating system
specific \texttt{cr-lf} (carriage return-linefeed) type to the
Linux/UNIX-specific \texttt{lf} (linefeed). Therefore you may use the
\texttt{dos2unix} tool of your Linux system. For more information on the
newline problem see \cite{WikipediaNewline}. Linux comes with an extremely
powerful tool to translate encoding of text files, \texttt{recode}.



\index{newline}
\index{dos2unix@\texttt{dos2unix}}
\index{recode@\texttt{recode}}
\clearpage

\section{Error messages and warnings}
\label{sec:ProblemsErrorMessages}
\index{Error messages}
\index{Warnings}

\subsection{Data entry}

Data entry with the input form (default name \verb+in_form.txt+) should not be
difficult. Sometimes, you may obtain an error message like

\begin{verbatim}
   [menu]: ir

   (Reading record)

   Problem: abstract not closed with `----END-OF-RECORD' in C:\refs43\in_form.txt

   (Record not stored)
\end{verbatim}

\index{Problem: abstract not closed with `----END-OF-RECORD' in ...@\texttt{Problem: abstract not closed with `----END-OF-RECORD' in ...} (error message)} 

if you try to import a record. One possible reason for this error message is
that your abstract text contains \verb+----...+ beginning in the first column
(e.\,g. used to underline the head of a table). \textbf{Solutions} (1) indent
the line\footnote{in the abstract text field} containing \verb+----+, (2) if
this problem happens often with your data, change the \verb+FORM_LABEL+
(default \verb+----+)
variable in the configuration file\footnote{refs.cfg, for details see table
\ref{ConfigFileVar}, page \pageref{ConfigFileVar}}. 

\subsection{Problems with \texttt{refsrun.\$}}

After starting \texttt{References}, you may encounter the message
\begin{verbatim}
   (Warning: one copy of `References' still running
     or previous session terminated irregularly)
\end{verbatim}
\index{Warning: one copy of `References' still running@\texttt{Warning: one copy of `References' still running}}

due to one of these reasons:

\begin{enumerate}
  \item You started a second instance of \texttt{References} while the first
    was still running.
  \item Your system crashed while an instance of \texttt{References} was
  running.
  \item Linux: You closed the console window without stopping \texttt{References}
    regularly
\end{enumerate}

\textbf{Technical background:} Each time \texttt{References} is launched, it
writes a small text file named `\verb+refsrun.$+' into the
\emph{database text files directory}. If
it already exists, \texttt{References} shows you the warning above. If 
`\verb+refsrun.$+' does not yet exist, it is written and removed
as soon as the program is finished regularly.%
\footnote{This feature was introduced to avoid that two instances of
\texttt{References} simultaneously manipulate files of the same database}

\textbf{Solution:} If the file \texttt{refsrun.\$} remained due to an earlier
crash, you may select \mopt{start} in the following menu. 
If you tried to open another instance of the
software, select \mopt{q}. 

\subsection{Problems with Emacs on Linux systems}

Users of \texttt{References} on Linux may encounter the following problem:
while editing a text file in the text file directory with Emacs,
\texttt{References} will stop irregularly if 
the user attempts to select a file
(cf. section \ref{RefsInterfaceFileSelect}, page 
\pageref{RefsInterfaceFileSelect}, file selection screen figure
\ref{fig:FileSelection} on page \pageref{fig:FileSelection}). 
Apparently Emacs generates irregular directory entries 
which cannot be handled properly by \texttt{References}' routine for 
reading directories. At present, this problem, which seems to be related
to the implementation of the \texttt{readdir()}-function of the C-library, 
cannot be fixed.



\subsection{Damaged database files}

If, upon starting \texttt{References}, the program stops and the message

\begin{verbatim}
   At least one database file damaged
\end{verbatim}

\index{At least one database file damaged@\texttt{At least one database file damaged} (error message)}

appears, this indicates, that at least one ``binary'' file with one of the
extensions \texttt{dat}, \texttt{ix} or \texttt{bbt} has been damaged.
\textbf{Solution:} the safest method is to delete the database and rebuild a
new one from an arr-files, if one has been made as ``backup''\footnote{Which
is highly recommended}.

\subsection{\texttt{References} fails to write to database, index or bbt-files}

\label{secFwriteFails}

If \texttt{References} issues the message


\begin{verbatim}
   Failure to write to binary file, for information see documentation

   Please press [ENTER] to stop References
\end{verbatim}

\index{Failure to write to binary file, for information see documentation@\texttt{Please press [ENTER] to stop References} (error message)}%
\texttt{References}  fails to write binary data into
database files (\texttt{.dat}), index files (\texttt{.ix}) or bbt-files. One
reason may be that not enough disk space is available. If this message
appears, \texttt{References} will stop. After this critical situation,
database and index files will be inconsistent, you will therefore have to
rebuild a database from an \texttt{.arr}-file. It is strongly recommended to
make regular backups (as \texttt{.arr}-files) (see section
\ref{sec:ExportImportDbtoArr}, page \pageref{sec:ExportImportDbtoArr}).

\subsection{Problems with batch files (win32)}

If you did not assign sufficient memory to the OS ``environment'' a call to
\texttt{tutorial} or \texttt{sortrefs} or any other batch-file%
\footnote{filename extension \texttt{bat}}
will generate%
\footnote{at least on my computer localized in Germany, a possible translation
is: `Insufficient environment memory' (this is probably not the official
message of an English Windows version, which is not available to me)} 
the message:

\begin{verbatim}
   Kein Speicherplatz mehr im Umgebungsbereich
\end{verbatim}

You may solve this by assigning more environment memory to a command prompt
window.

\clearpage

\section{Installation on Win32}
\label{sec:Installation}

\index{installation}

%% \label{sec:NewInstall}

\texttt{References} requires a text editor. For those users who do not wish to
use \texttt{notepad}
on win32-systems, alternatives are described in section
\ref{sec:InterfaceEditingText}. The text editor has to be installed
separately.


\subsection{Installation from exe-files}
\label{sec:InstallEXEFiles}


The program archive can be installed from the \texttt{r43c.exe} executable 
file\footnote{\texttt{r43c.exe} will be called ``installer'' in this section,
although it is only a self-extracting archive}.
The default configuration requires that References is installed in
 the \verb+c:\refs43+-directory (folder). The following steps are required:

 \begin{enumerate}
 \item Create the directory ``\verb+c:\refs43+'' (e.g. using the Windows Explorer)
 \item According to the Windows version, add the item ``\verb+c:\refs43;+'' to 
    the PATH environment variable of the 
    \texttt{AUTOEXEC.BAT} file (see description in section \ref{sec:InstallZIPFiles})
    or to the path entry of ``environment''  in the system dialog,
  \item Call the \verb+r43c.exe+-installer (e.\,g. from the Windows explorer).
   Within the installer, 
    \begin{enumerate}
    \item change the target directory to \verb+c:\refs43+ using the 
      \textbf{Browse}-button (if necessary), 
    \item   extract the contents of the installer with the 
      \textbf{Extract}-button and 
    \item  close the installer with \textbf{Done}
\end{enumerate}
\item You may then add links to the desktop or the start menu
  from the batch files \texttt{tutorial.bat},
  \texttt{e-tutorial.dat}, \texttt{data.bat} and \texttt{e-data.bat}
\item Restart the computer to make the changed PATH environment variable active.
 \end{enumerate}

Installation of \texttt{References} in another directory is described in
section \ref{sec:InstallOtherDir}.

\subsection{Installation from zip-files}
\label{sec:InstallZIPFiles}

Experienced users will be able install the program from the \verb+r43c.zip+
file.  To begin installation of \texttt{References}, open a command prompt,
make \texttt{c} the actual drive, create the directory \verb+c:\refs43+ and
change into this directory: 

\begin{verbatim}
   md c:\refs43
   cd c:\refs43
\end{verbatim}

Copy the file \texttt{r43c.zip} into this directory and unzip it\footnote{At
this place, it is assumed that the unzip tool recreates the subdirectories as
described in \ref{sec:InstallDirectTree} as is the case with Info-Zip's
\texttt{unzip}}. The file \texttt{refs-4.3c-src.tar.gz} contains the source-code for the
program and the documentation (\LaTeX-files) and is not required for use of
this software.

\begin{verbatim}
   unzip r43c.zip
\end{verbatim}

Make the batch files in ``\verb+c:\refs43+'' accessible from other directories
e.\,g. by adding this directory name to the \texttt{PATH} variable according
to the Window version either in the
\texttt{AUTOEXEC.BAT} configuration file or to 
the \texttt{PATH} entry of ``environment''  in the system dialog.

\begin{verbatim}
   ...;c:\refs43
\end{verbatim}

After restarting the computer, opening a command line, a call to
\texttt{tutorial} should start references as shown in figure
\ref{fig:RefsStartingScreen}, to leave \texttt{References}, enter \texttt{q
[Enter] yes [Enter]}.
\index{quit \texttt{References}}

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
(Checking size of database files)
(Checking size of bbt-files)

MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3 -- [e/l/b/s/d/t/f/i/q]

[menu]:
\end{boxedverbatim}
\end{center}
  \caption{Screen after calling \texttt{References}}
  \label{fig:RefsStartingScreen}

\end{figure}

Transfer of data from \texttt{References} v3.6, v4.0, v4.0a, v4.0b, v4.0c
v4.0d, v4.1 or v4.2
can be done through \texttt{.arr}-files and \texttt{.fd}-files. 
As the encoding of the internal
representation changed from ``cp850'' to ``latin-1'' and as \texttt{.arr}-
and \texttt{.fd}-files have the same 
encoding as the \texttt{References'} internal encoding
you have to convert the encoding of these files
with the \texttt{cp850-to-latin1} command
line program in the \texttt{bin} subdirectory.

\begin{verbatim}
   c:\refs43\bin\cp850-to-latin1 olddata.arr
\end{verbatim}


\textbf{You must not apply this command more than once on an \texttt{.arr}-
or a \texttt{.fd}-file!}
For details on different encoding schemes in \texttt{References} see section
\ref{sec:CharacterSet}.





\subsection{Removal of \texttt{References}}
\label{sec:UninstallReferences}

If you wish to remove the \texttt{References}-installation, you will only have
to delete the \verb+c:\refs43+-directory tree (and to remove links made
manually to the \texttt{.bat}-files).

\subsection{Directory tree}
\label{sec:InstallDirectory}
\label{sec:InstallDirectTree}
The default directory structure of \texttt{References} is depicted in fig
\ref{fig:DirectTree}. An installation into another directory requires that all
path entries in the batch (command) files are adjusted.

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
   c:\refs43
      |
      +--doc
      |
      +--bin
      |
      +--data
      |  |
      |  +--rdb
      |
      +--tutorial
         |
         +--rdb
\end{boxedverbatim}
\end{center}
\caption{Directory tree}
\label{fig:DirectTree}
\end{figure} 

The directory \verb+c:\refs43\doc+ contains the documentation of the software
including in PDF. The \texttt{refs43.exe} executable file and AWK-scripts are
located in the \texttt{bin}-directory.  Databases have the general path
\verb+\refs43\data+ and \verb+\refs43\data\rdb+. The \texttt{rdb} subdirectory
will contain the `binary' (database and index) files.
%
The path \verb+\refs43\data+ will be referred to as \emph{database text files
  directory} \index{database text files directory} in this manual and
\verb+\refs43\data\rdb+ as 
\index{database binary files directory}
\emph{database binary files directory} or \emph{database rdb subdirectory}.
\index{database rdb subdirectory}


\subsection{Create a new database}

\label{Sec:ConfigCreateNewDatabase}
\index{Radmin@\texttt{Radmin}}
To create a new database, start the \texttt{Radmin}-tool. You will see the
following screen with the main menu (figure \ref{figRadminStart}):

\begin{figure}[h]
\centering
\begin{boxedverbatim}
Radmin.exe -- tool for administration of References Bibliographic Software

Current directory (folder) is:
   `C:/refs43'
Executable files directory (folder) is:
   `C:/refs43/bin'

Radmin menu -- [p/n/q] -- [Enter] shows menu options

[menu]:

[p] check/correct path entries
[n] create a new References database
[a] about Radmin
[q] quit

[menu]:
\end{boxedverbatim}

  \caption{\texttt{Radmin} main menu}
  \label{figRadminStart}
\end{figure}

Select \mopt{n}, enter the name of the new database, e.\,g. \texttt{mdata} and
press \texttt{[Enter]}. You will see the following message:

\begin{verbatim}
   Database name: mdata
   
   Please press [ENTER] to continue:
   
     `C:/refs43/mdata' created
     `C:/refs43/mdata/rdb' created
     `mdata.bat' written
     `e-mdata.bat' written
   
   To complete installation of the new database
     1. Create database and index files
     2. Import minimal database
   as described in the documentation
   
   Radmin menu -- [p/n/q] -- [Enter] shows menu options
   
   [menu]:
\end{verbatim}

You may then quit \texttt{Radmin} with \mopt{q}. \mopt{Radmin} has created the
subdirectories \texttt{mdata} and \texttt{mdata/rdb} and the starting
batch/script files \texttt{mdata.bat} and \texttt{e-mdata.bat}. The following
must be done to complete the installation:

\begin{enumerate}
\item Start \texttt{References} with the command \texttt{mdata}. 

\item Create a set of empty database and index files with \mopt{main-f r c}.
Go back to the main menu with \mopt{q q}. 

\item Import the \texttt{dbase1.arr}-file (copy this file from the
\texttt{data} subdirectory to the \texttt{mdata} directory) 
with \mopt{main-t im}.

\index{fd-file}
\index{fde-file}
\item Import a set of bibliographic format definitions from a fd-file or from
fde-files
\end{enumerate}

\subsection{Installation of \texttt{References} in another than the default 
  directory/drive}

\label{sec:InstallOtherDir}

After unzipping the \texttt{r43c.zip} archive or the \texttt{r43c.exe}
installer to a directory different from the default
(\verb+c:\refs43+)\footnote{The path to
a \texttt{References} installation must not contain any spaces!} start the
\texttt{Radmin} tool.%
\index{Radmin@\texttt{Radmin}}
Therefore, make the directory which contains 
\texttt{Radmin.bat} the \textbf{current working directory}\footnote{You may
also start Radmin.bat from the Windows explorer}. 
Select \mopt{p} from the
\texttt{Radmin}-menu\footnote{this adjusts the path entries in the
configuration file}, at the next prompt:

\begin{verbatim}
   Database names:
\end{verbatim}

enter the existing databases, for the default installation this should be:

\begin{verbatim}
   Database names: data tutorial
\end{verbatim}

Database names should be separated by spaces. The following message: 

\begin{verbatim}
   Database names: data tutorial
     `data.bat' written
     `e-data.bat' written
     `tutorial.bat' written
     `e-tutorial.bat' written
\end{verbatim}

confirms that the starting batch/script files have been updated.

\subsection{Building \texttt{References} executable files}
\label{sec:BuildingRefs}

The executable file of the \texttt{References} version for Windows has been
compiled with the ``MinGW''-Implementation of the
gcc-compiler\footnote{\url{www.mingw.org}, 
\url{http://www.sf.net/projects/mingw}. For the compilation process it is
also recommended to have the \texttt{msys} package installed which is 
available from the same website. \texttt{Msys} also makes \texttt{gzip} 
and \texttt{tar} available}. 
You will file the source code in the \texttt{refs-4.3c-src.tar.gz} archive,
to uncompress it see section~\ref{sec:InstallationLinux}.
For building the Windows-version with the gcc%
\footnote{For the normal user, it is not necessary to compile
  the binary executable files again, as the \texttt{r43c.zip} or 
  \texttt{r43c.exe}
  archive contain the executable files} 
you may use the enclosed
\texttt{Makefile}. First open the \texttt{Makefile}  with your text editor
and find the following two lines:

\begin{verbatim}
   ### -- Please select your compiling environment: uncomment the items below
   ###    according to the appropriate computing environment
\end{verbatim}

In the following lines the definitions for compilation of win32 have to be
uncommented and the definitions for Linux have to be commented out%
\footnote{In \texttt{Makefiles} the character ``$\#$'' makes the rest of a line
invisible}:

\begin{verbatim}
   ### -- BEGIN: select between Linux and win32
   
   ## Linux with GCC, utf-8 encoded text
   # CFLAGS=-c -Wall -DREFS_USES_LINUXGCC
   # REFSEXE := refs43
   # ETEXTEXE := etext
   # RADMINEXE := radmin
   # CP850_TO_LATIN1EXE := cp850-to-latin1
   
   ## Win32 with MinGW compiler
   CFLAGS=-c -Wall -DREFS_USES_MINGW
   REFSEXE := refs43.exe
   ETEXTEXE := etext.exe
   RADMINEXE := radmin.exe
   CP850_TO_LATIN1EXE := cp850-to-latin1.exe
   
   ### -- END: select between Linux and win32
\end{verbatim}

Save the \texttt{Makefile}\footnote{If you changed something}, close the text
editor and type:

\begin{verbatim}
   make all 
\end{verbatim}


which ensures that \verb+refs43.exe+, \verb+etext.exe+,
\verb+cp850-to-latin1.exe+ and \verb+radmin.exe+ are built.


\section{Installation on Linux systems}

\label{sec:InstallationLinux}

\texttt{References} requires a text editor. On Linux systems, the default text
editor is vim, this may be changed in the configuration file.

The Linux distribution provides the source code of \texttt{References} in the 

\begin{verbatim}
  refs-4.3c-src.tar.gz
\end{verbatim}

archive and all other ``runtime'' files in  

\begin{verbatim}
   refs-4.3c-rt.tar.gz
\end{verbatim}

A set of binary 32 bit files for Linux systems (i386 processor architecture)
is made available\footnote{Beginning with July, 2006. However, users are 
urgently
recommended to compile the binary files on their target system} in 

\begin{verbatim}
   refs-4.3c-i386.tar.gz
\end{verbatim}

The steps to install \texttt{References} on a Linux system:

\begin{enumerate}

\item Please change to your home directory 
and install the \texttt{refs-4.3c-rt.tar.gz} tarball:

\begin{verbatim}
   gzip -d refs-4.3c-rt.tar.gz
   tar -xvf refs-4.3c-rt.tar
\end{verbatim}

This creates the \verb+~/refs43+- subdirectory tree (figure
\ref{fig:DirectTreeLinux}).

\begin{figure}[h]
\begin{center}
\begin{boxedverbatim}
    ~/refs43
      |
      +--doc
      |
      +--bin
      |
      +--data
      |  |
      |  +--rdb
      |
      +--tutorial
         |
         +--rdb
\end{boxedverbatim}
\end{center}
\caption{Directory tree on Linux systems}
\label{fig:DirectTreeLinux}
\end{figure} 


\item Installation of \texttt{References} requires that you compile the binary
files from the sourcecode in the \texttt{refs-4.3c-src.tar.gz} file.  As an
alternative, you may copy the binary files from the archive
\texttt{refs-4.3c-i386.tar.gz} into the \verb+~/refs43/bin+-directory.
\textbf{If you use the precompiled binaries proceed with item
\ref{itemRunRadmin} on page \pageref{itemRunRadmin}}.


\item If you compile the \texttt{References} yourself
tools \texttt{gcc}, \texttt{make} must be available on your
system.  


In a console window, uncompress the file in a temporary directory as
usual, e.\,g.:

\begin{verbatim}
   gzip -d refs-4.3c-src.tar.gz
   tar -xvf refs-4.3c-src.tar
\end{verbatim}



Change into the \texttt{src} subdirectory and open the file \texttt{Makefile}
with your text editor and find the following two lines:

\begin{verbatim}
   ### -- Please select your compiling environment: uncomment the items below
   ###    according to the appropriate computing environment
\end{verbatim}

In the next lines the definitions for compilation of Linux have to be
uncommented and the definitions for win32 have to be commented out (normally
this is the default):

\begin{verbatim}
   ### -- BEGIN: select between Linux and win32
   
   ## Linux with GCC, utf-8 encoded text
   CFLAGS=-c -Wall -DREFS_USES_LINUXGCC
   REFSEXE := refs43
   ETEXTEXE := etext
   RADMINEXE := radmin
   CP850_TO_LATIN1EXE := cp850-to-latin1
   
   ## Win32 with MinGW compiler
   # CFLAGS=-c -Wall -DREFS_USES_MINGW
   # REFSEXE := refs43.exe
   # ETEXTEXE := etext.exe
   # RADMINEXE := radmin.exe
   # CP850_TO_LATIN1EXE := cp850-to-latin1.exe
   
   ### -- END: select between Linux and win32
\end{verbatim}

Save the \texttt{Makefile}\footnote{If you changed something}, close the text
editor and type:

\begin{verbatim}
   make all 
\end{verbatim}

The
binary files can then be found in the \texttt{refs43/bin/} subdirectory. 
Please copy
them (\texttt{refs43}, \texttt{etext}, \texttt{radmin}, 
\texttt{cp850-to-latin1}) into the directory
\verb+~/refs43/bin/+.


\item Change to the \texttt{refs43} directory, and run the \texttt{radmin}
program:
\label{itemRunRadmin}

\begin{verbatim}
   bin/radmin
\end{verbatim}

You will first be asked for information on the text file encoding of your
Linux installation (figure \ref{RadminAsksForEncoding}).
If you are uncertain about this issue, stop \texttt{radmin} and type
\texttt{locale} from the shell. You will obtain output like

\begin{verbatim}
LANG=de_DE.UTF-8
LC_CTYPE="de_DE.UTF-8"
LC_NUMERIC="de_DE.UTF-8"
LC_TIME="de_DE.UTF-8"
LC_COLLATE="de_DE.UTF-8"
LC_MONETARY="de_DE.UTF-8"
...
\end{verbatim}

In this case, a Linux installalation uses utf-8 encoding for text 
files.\footnote{If you cannot obtain sufficient information with this command,
refer to the documentation of your Linux distribution or 
check the ``Language''-specific settings in the
configuration tools}
You can then restart \texttt{radmin} and select option \mopt{1} in the menu of
figure \ref{RadminAsksForEncoding}.


\begin{figure}[h]
\centering
\begin{boxedverbatim}
Please enter text file encoding on your Linux system [1/2/q]

[menu]:

[1] utf-8
[2] latin-1 (ISO-8859-1) or latin-9 (ISO-8859-15)
[q] quit

[menu]:
\end{boxedverbatim}
  \caption{Select text file encoding after installation of References on Linux
  systems}
  \label{RadminAsksForEncoding}
\end{figure}



Then,
type \texttt{Enter} to see the main menu of this tool. 
Select \mopt{p}, this updates or 
creates the configuration file \verb+~/.refscfg+ and inserts information on
the correct text file encoding into the configuration file, 
then enter the names of the
database directories \texttt{data tutorial}\footnote{Details are described in
the chapter on \texttt{radmin}}, this writes new versions of the starting
script files \texttt{data.sh}, \texttt{e-data.sh}, \texttt{tutorial.sh},
\texttt{e-tutorial.sh}. You may then quit \texttt{radmin}  with \mopt{q}.
For ease of use make these script files executable

\begin{verbatim}
  chmod a+x data.sh e-data.sh tutorial.sh e-tutorial.sh
\end{verbatim}

and copy them into a directory included in the list assigned to the 
\texttt{PATH}
variable. This may require on some systems that you login as
``\texttt{root}''\footnote{e.\,g. with the \texttt{su} command}.
You may then start \texttt{References} by typing \texttt{data.sh} from your
shell.
\end{enumerate}

\subsection{Building the \texttt{data} and \texttt{tutorial} databases}

Please read first the description of the References user interface
(section \ref{RefsInterface}, page \pageref{RefsInterface}).
Start the \texttt{data} database with \texttt{data.sh} at the Linux console
prompt, select \mopt{main-f r c}. This creates an empty set  of index and
database files, then return to the main menu with \mopt{q q}. Import the
data with \mopt{main-t im}, press \texttt{[Enter]} and enter the number before
\texttt{data.arr} (this will most probably be ``1''). You will then be asked,
if you wish to delete the archive file, it is recommended to select
\mopt{n}. Selection of \mopt{q} brings you back to the main menu. 

To import the bibliographic format definitions, select \mopt{main-d im y},
type \texttt{[Enter]} and select the number before \texttt{data.fd} (most
probably ``1''). Selection of \mopt{q} brings you back to the main menu.


\subsection{Transfer of databases from earlier (win32) versions of 
  \texttt{References}}

Before importing text files from win32-versions
into \texttt{References} for Linux, the line
terminators have to be changed from the DOS/Win32 format (CRLF) to LF
(Unix/Linux)
This can be done with the
\texttt{dos2unix}-program available on Linux systems. A win32 version is
available as part of the
gnuwin32-project\footnote{\url{http://gnuwin32.sourceforge.net/}} in the
\texttt{cygutils}
package\footnote{\url{http://gnuwin32.sourceforge.net/packages/cygutils.htm}}. 



Transfer of text files from databases created with versions earlier than 4.3 
of \texttt{References} requires that their
enoding is changed to latin-1. Please convert the 
\texttt{.arr}- and \texttt{.fd}-files with the command
\texttt{cp850-to-latin1} in the bin-subdirectory. Please avoid the Unix/Linux
\texttt{recode}-command for arr-files\footnote{with \texttt{cp850-to-latin1}
you will avoid that the code for new lines in abstract is destroyed}.  If you have doubt on the encoding (and if the text contains accented characters
and/or Umlaut characters) you may analyse the file with the Unix/Linux
command:

\begin{verbatim}
   file filename
\end{verbatim}

The \texttt{file} tool also indicates if the ``line terminators'' are of the 
\texttt{CRLF} type (DOS, win32) or \texttt{LF} (Linux, UNIX). You definitely
should convert text files to \texttt{LF}-format before the Linux version of
\texttt{References} uses them.
\index{LF line terminator@\texttt{LF} line terminator}
\index{CRLF line terminator@\texttt{CRLF} line terminator}
\index{line terminator}
\index{newline!win32 and Linux systems}
\index{end of line!win32 and Linux systems}


\subsection{Creating new databases, installation in another than the default
directory}

To create a new database you may use the \texttt{radmin} tool as described in section 
\ref{Sec:ConfigCreateNewDatabase}, page \pageref{Sec:ConfigCreateNewDatabase}. 
To call \texttt{radmin}, change into the
\texttt{References} directory and type

\begin{verbatim}
   bin/radmin
\end{verbatim}

To create a References installation in another than the default 
directory\footnote{i.\,e. \texttt{\~{}/refs43/}}
follow the instructions in section \ref{sec:InstallOtherDir}, page
\pageref{sec:InstallOtherDir}. First change into the \texttt{References}
directory and type \verb+bin/radmin+.


% cygutils package
% 
% http://gnuwin32.sourceforge.net/
% http://gnuwin32.sourceforge.net/packages/cygutils.htm


\clearpage

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