
\section{User interface}


\index{user interface}

\subsection{\texttt{References} interface}

\label{RefsInterface}

Version 4.3 comes as Linux console program or 
a console/terminal program compiled for win32 systems.
The functions of this software are controlled
interactively at the \texttt{References} command prompt.  Data are entered
into text files (referred to as \emph{text file forms} 
\index{text file forms} in this manual). This software therefore requires
% intended to be used with
a text editor.  The \texttt{rdb}
subdirectory\footnote{\emph{database binary files directory}} (the directory 
tree is described in section~\ref{sec:InstallDirectory})  
contains the `binary'
(database and index) files.  Text files produced by \texttt{References} and
text file forms are presented in the directory which contains the
\texttt{rdb}-subdirectory\footnote{\emph{database text files directory}}.

\index{main menu}
\index{menus!usage}
In the beginning, you will start \texttt{References} at the command line.
After calling the program you will see the main menu prompt (figure
\ref{figMainMenuPrompt}).

\begin{figure}[t]
\centering
\begin{boxedverbatim}
MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3 -- [e/l/b/s/d/t/f/i/q]

[menu]:
\end{boxedverbatim}
  \caption[Main menu prompt]{Main menu prompt}
  \label{figMainMenuPrompt}
\end{figure}

\index{menus!prompt}
If you press \texttt{[ENTER]} at a menu prompt ``\texttt{[menu]:}'' 
you will see
the options of the main menu (figure \ref{fig:MainMenu}). In this situation
you did not enter any menu option, but you confirmed the (implicit) default
option (``\texttt{[menu]:}'' -- show menu options)
by entering an empty string. If you would wish to select the option 

\begin{verbatim}
[e] enter, edit, view
\end{verbatim}

you should enter \texttt{[e]} and \texttt{[ENTER]}  at the menu prompt. 
In this manual this selection will be indicated as \mopt{main-e}.
To see the text of a menu you may (in any menu of \texttt{References}) select
\mopt{menu}.
In a menu
text, everything in square brackets is an option, it is not necessary that
options appear at the beginning of the line. As a example, the options in the
batch table functions menu (figure \ref{fig:BatchMenu}, page
\pageref{fig:BatchMenu}) are 
\texttt{bt}, \texttt{tb}, \texttt{s1}, \texttt{s2}, \texttt{in}, \texttt{ay},
\texttt{rd}, \texttt{rs}, \texttt{ba}, \texttt{br}, \texttt{ui}, \texttt{ed},
\texttt{q}. If you wish to see browse the current database you will have to
select \mopt{main-e c}, this means that you should type \texttt{[e]}, 
\texttt{[Enter]}, \texttt{[c]}, \texttt{[Enter]}.


\begin{figure}
  \begin{center}
\begin{boxedverbatim}
[e] enter, edit, view
[l] compile lists of references etc.
[b] process batch files
[s] search references by keywords, authors, title etc.
[d] bibliographic/macro format definitions
[t] text files, export/import from/into database
[f] file, database and system functions
[i] information about References v4.3
[q] quit, return to the OS

[menu]:
\end{boxedverbatim} 
  \end{center}
\caption{Main menu}
\label{fig:MainMenu}
\end{figure} 



\begin{figure}[htbp]
  \centering
\begin{boxedverbatim}
   1: all.bbt
  ..: ...
  22: range.bbt

Select file number: 1..22, [q] to abort:
\end{boxedverbatim}
  
  \caption{File selection screen}
  \label{fig:FileSelection}
  
\end{figure}

\label{RefsInterfaceFileSelect}
\index{file selection}
In many situations, the user is required to 
\textbf{select a file}. As an example, if you
wish to see a subset of all bibliographic records referred to in a ``bbt-file''
(cf. section \ref{SecBatchFiles}), select (beginning from the main menu)
\texttt{main-e b}. At the file prompt in figure \ref{fig:FileSelection} you may
select a file by entering the number assigned to a file name.



\subsection{Select/install a text editor, edit text (win32)}

\label{sec:InterfaceEditingText}

\index{text editors}
% All text is entered 
All data required by \texttt{References} have to be entered or edited
with a text editor.  
\index{notepad.exe}
% Under Windows, 
For the first steps with \texttt{References}, \texttt{Notepad} may be used.
However due to some deficiencies\footnote{for example, under Windows versions
  9x and ME, size of files that can be loaded by \texttt{Notepad} is limited,
  and column and line numbers for the current cursor position are not
  indicated in the status line} 
a more powerful and flexible editor may be preferred\footnote{The following
  recommendations list text editors, which proved to be quite stable and
  reliable with their Win32-implementations in the hands of the program author.
  The selection in this chapter will therefore change with new versions of
  this documentation. Every user may select the text editor ``her/his'' is
  already accustomed to.}.
The ideal choice of a simple text editor for use with \texttt{References} is
\texttt{Win32pad}\footnote{This editor is freely made available by its author,
  Gennady Feldman: \url{http://www.gena01.com/win32pad/}, however it is not an
  open source project}. An editor with intermediate complexity is 
  \texttt{SciTE}\footnote{See \url{http://www.scintilla.org}}. 
If you use \texttt{References} in the interactive mode which is switched on by
assigning ``1'' to the configuration variable \verb+OPEN_EDITOR_YN+ (cf. below
in this section), it is
useful to install a ``lightweight'' text editor like 
\texttt{notepad}, \texttt{win32pad} or \texttt{SciTE}, which can be called
quickly.


{\footnotesize
\index{Emacs} \index{Vim} \index{GVim}
If you prefer a more complete, but also also more complex text editor
% A good choice for experienced users
both \texttt{Vim}\footnote{Compiled versions of Vim for 
Windows (\texttt{gvim}) may be found at
\url{ftp://ftp.vim.org/pub/editors/vim/pc/}} and
\texttt{Emacs}\footnote{A compiled version of GNU Emacs may be found at
\url{ftp://ftp.gnu.org/gnu/emacs/windows/}}
are a good choice.  The graphical version of
\texttt{Vim} is \texttt{gvim}. For the beginner with \texttt{gvim}, it is
recommended to use the Easy Vim (\texttt{evim}) mode. Both Emacs and Vim are
well documented in books \cite{m00475,m00466} and in documents available via
the internet \cite{VimDocWebsite,GNUEmacsOnlineManual}.
With these editors, which may have considerably longer loading times on some
computers, it will be more practical, to have the text editor open all the
time you work with References and change between text editor window and the
window with \texttt{References}. In this case you will have to reload text
files within the text editor when they are modified by \texttt{References}.
This can be made automatically by some text editors%
  \footnote{In \texttt{GVim} you may type \texttt{:set autoread}}. 
\par }

\textbf{Usually you will execute commands in the \texttt{References} window,
open the text editor, edit a text file, save it to disk, close the text
editor  and change back to the \texttt{References} window.}


References provides a small additional program (in the following text referred
to as the \emph{text editor shell}) to call the editor with a%
  \index{text editor shell}
  \index{etext.exe@\texttt{etext.exe}}
text file\footnote{The binary (program) file is \texttt{..bin/etext.exe}}. It
is called at the command line with:

\begin{verbatim}
   e-[database-name].bat
\end{verbatim}

if you use the win32 version of References or 

\begin{verbatim}
   e-[database-name].sh
\end{verbatim}

if you use the Linux version.
In the case of the \texttt{tutorial} database, call 
\texttt{e-tutorial}\footnote{Linux: \texttt{e-tutorial.sh}}, in
case of \texttt{data}: \texttt{e-data}\footnote{Linux: \texttt{e-data.sh}}. 
The main menu of the text editor shell
allows to call the text editor\footnote{for the windows version, this is by
  default \texttt{notepad}, another text editor (as an example
  \texttt{win32pad}),
  can be made available by adding \texttt{TEXT\_EDITOR=win32pad.exe} to the
  configuration file \texttt{refs.cfg} (see section \ref{SecConfigFile})}
To enter new bibliographic data into a form or to edit an existing record (see
section \ref{SecEnterReferences}), select \mopt{edit-main-r}, 
to add new keywords to the thesaurus, open the form with \mopt{edit-main-k} 
(details in
section \ref{sec:EditKeywordsThesaurusItems}), open the
form for journal data with \mopt{edit-main-j} (details in section 
\ref{sec:EnterEdJornalData}). Search commands are entered into the text file
called with \mopt{edit-main-s}. The option 
\mopt{edit-main-m} opens the file section screen,
\mopt{edit-main-3} 
opens three files (the references form, search commands form and the
keywords thesaurus form) into the text editor. With 
\mopt{edit-main-p}, a menu (figure \ref{fig:TextEditorShellProcessTextFiles})
accessing 
\texttt{AWK}-scripts for manipulation of text files is selected. 
The command \mopt{edit-main-f} opens a tiny file manager\footnote{it may 
also be accessed by \mopt{main-f f}}. 
With \mopt{edit-main-c}, single commands (of the OS shell 
or command processor may be executed.
If you call another instance of
the Windows command line shell%
  \footnote{Either \texttt{command.com} (Windows 9x, ME) or 
  \texttt{cmd.exe} (Windows NT, XP)},
please do not forget to return to the text editor shell with \texttt{exit}.


\begin{figure}
  \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
[p] process text files
[f] file and system functions
[h] help, References documentation
[a] about References
[q] quit

[menu] -->           
\end{boxedverbatim} 
  \end{center}
\caption[Text editor shell, main menu]{Main menu of the text editor shell}
\label{fig:MainMenuTextEditorShell}
\end{figure} 

\begin{figure}
\centering
\begin{boxedverbatim}
[htm] convert list of references text file to HTML-file
[ltx] convert list of references text file to LaTeX-file
[exc] excite: extract \cite{} arguments from LaTeX text files
[xex] extended excite: extract arguments of \cite{}-equivalents
[srt] process sorting macro with the sortrefs command
[wdm] citations search-and-replace macro for MS Word
[osw] citations search-and-replace macro for OOOrg/StarOffice writer
[ vi] citations search-and-replace script for vi/vim/gvim
[msr] manual search-and-replace citations list for textprocessors
[rsr] References search-and-replace script for citations
[exa] extract reference numbers from arr-file
[snc] sort groups of numeric citations
[  q] quit

[menu]:
\end{boxedverbatim}
  \caption[Text editor shell, process text files]{Text editor shell, process text files}
  \label{fig:TextEditorShellProcessTextFiles}
\end{figure}

Beginning with v4.2, \texttt{References} offers an alternative mode of
interaction with the text editor: if in the configuration file the line

\begin{verbatim}
   OPEN_EDITOR_YN=1
\end{verbatim}

the, value ``1'' is assigned to the variable \verb+OPEN_EDITOR_YN+,
\texttt{References} opens the text exitor with the text file of
interest automatically after showing the prompt:


\begin{verbatim}
   Menu: open editor with file ``C:\refs42\tutorial\sr_form.txt''? [y/n]
\end{verbatim}

In this example, \texttt{References} opens the text editor with the search
command file after selecting the \mopt{main-s} command. The installation of
\texttt{References} sets \verb+OPEN_EDITOR_YN=0+, resulting in the behaviour
of \texttt{References} as in previous versions.


\subsection{Select/install a text editor, edit text (Linux)}

\index{encoding}
On a Linux installation, \texttt{References} writes text files to disk in
\texttt{latin-1} encoding. As modern Linux-versions use \texttt{utf-8}
encoding,
\index{latin-1 encoding}%
\index{utf-8 encoding}%
References converts text files to this format if it opens the text editor
(with a command like \mopt{main-t ed m} or \mopt{edit-main-r}).
You
can see this from the name of the text file to which ``\texttt{\_u8}'' is
appended, e.\,g. \texttt{in\_form.txt} will be converted to  a file named 
\texttt{in\_form.txt\_u8}. After closing and saving the text editor, the file
is converted back to \texttt{latin-1} encoding and and the filename is
\texttt{in\_form.txt}. As long as
you edit the utf-8 encoded version of the text file,
the latin-1 encoded version is not available (i.\,e. it is temporarily
deleted).
If you use a Linux implementation of \texttt{References} with utf-8 encoding, 
you should always
open text files with the text editor through the \emph{text editor shell} 
or from \texttt{References} itself to
make sure that conversions between the different encodings are handled
correctly. If you wish to use the  \mopt{edit-main-3} command you will have to
use a text editor which is able to open more than one file at the same time.

On Linux systems, good choices for a text editor to be used together with
\texttt{References} are \texttt{nano} (simple, see the short description of
commands in table \ref{tab:nanoCommands}, page \pageref{tab:nanoCommands}),
\texttt{vim}/\texttt{gvim}, or \texttt{emacs}.  On the GNOME-desktop,
\texttt{gedit} will be an excellent choice for a text editor with graphical
user interface, its equivalent on the KDE is \texttt{kwrite}.

As already mentioned, a list of references generated with the \mopt{main-l s}
command will be written by \texttt{References} in \texttt{latin-1} encoding.
If you wish to import this text file into the Linux version of
OpenOffice.org/StarOffice writer, you will have to convert encoding from
\texttt{latin-1} to \texttt{utf-8}.
This is most easily done with Linux's \texttt{recode} command:

\begin{verbatim}
   recode latin-1..utf-8 reflist.txt
\end{verbatim}


To check the current encoding of a text file, type 

\begin{verbatim}
   file reflist.txt
\end{verbatim}

\begin{sloppypar}
The message ''\texttt{reflist.txt: ISO-8859 text, with very long lines}''
indicates that the file is encoded with \texttt{ISO-8859} encoding%
  \footnote{More precisely, character encoding is 
  \texttt{ISO-8859-1}, a synonym for 
  \texttt{latin-1} encoding}
After conversion with the \texttt{recode} command, the message will be
``\texttt{reflist.txt: UTF-8 Unicode text, with very long lines}''.
The problem of encoding and character sets is discussed in section
\ref{sec:CharacterSet}.
\end{sloppypar}


\subsection{View text files}
\label{sec:ViewTextFiles}


In many situations, you will have to browse through a text file in the 
References text file reader (the \emph{view text file function}).
% If you have to select an item from a list (cf. section
% \ref{sec:SelectFromLists}) and in many other situations, you will have to read
% a text file.  
To see the navigation commands of the \emph{view text file
function}
 \index{view text file function} 
call the \mopt{menu}
 \index{text files, reading from \texttt{References}}
(figure~\ref{fig:ViewTextFilesMenu}).
This function is used to show an abstract text of a
bibliographic reference with \mopt{main-e c} [go to a reference with an
abstract] \mopt{a}, or you can call it if you explicitly wish 
to see a text file with
\mopt{main-t vi}\footnote{Often it will be more comfortable to view a text
file with the text editor: \mopt{main-e ed m}}. 



\begin{figure}[h]
\centering
\begin{boxedverbatim}
[f] first page     [l] last page      [n] next page      [p] previous page
[+] line forward   [-] line back      [r] refresh page   [.] first column
[>] one page right [<] one page left  [}] one col. right [{] one col. left
[s] show line no   [g] go to line     [/] find           [q] quit

[menu]:
\end{boxedverbatim} 
\caption{Menu of the \emph{view a text file} function}
\label{fig:ViewTextFilesMenu}
\end{figure} 

\MakeShortVerb{\|}
Within the \emph{view a text file} function you will normally open the text
at the beginning
with the \mopt{f} command (for the first screen) or with \mopt{l} for the last
screen. \mopt{n} brings you to the next page, \mopt{+} scrolls one line
forward. Lines which are longer than the screen are indicated as truncated
with the dollar character.  \mopt{|>|} brings you one screen to the right (so
that you can read more of the truncated line),
\mopt{|\}|} shifts the screen one column to the right, \mopt{.} shifts the
screen back to the first column. After printing the menu options with
\mopt{menu} the command \mopt{r} ``refreshes'' output of the current 
page (without the
menu text output). 
You may search a text with \mopt{/}, \mopt{g} prompts you for a line number.
The \emph{view text file} function is closed with \mopt{q}.
\DeleteShortVerb{\|}

For users of the Linux version, \texttt{References} offers the option to use
the text-viewing program (``pager'') \emph{less} instead of the view text file
function described above. You simply have to add the line

\begin{verbatim}
   USES_LESS=1
\end{verbatim}

to the configuration file (\verb+~/.refscfg+, for details, see section
\ref{SecConfigFile}, page \pageref{SecConfigFile}). \emph{Less} is much more
comfortable than \texttt{References'} built-in text viewing function. Use of
\emph{less} with a Linux installation using utf-8 encoding further requires
that the \texttt{recode}-tool is available.


\subsection{Selection of items from a list}
\label{sec:SelectFromLists}

In many situations, \texttt{References} requires that the user selects an item
in a list.  Therefore, the program writes these items into a temporary text
file, 
and reads this file into the \emph{view text file function}
as described in chapter \ref{sec:ViewTextFiles}. If
you have found the item, close the  \emph{view text file function} 
with \mopt{q} and enter the option to be selected at the prompt.

Examples:

\begin{itemize}
\item If you wish to
  write a journal name-record into a text file (for editing and rewriting
  it into the database), select \mopt{main-e ej}. You are then 
  asked to enter a
  `substring'\footnote{a text fragment with which you can restrict the
  resulting journal names to those which contain this text fragment} 
  (this function is described in section 
%%  \ref{sec:EditJournalData}): 
  \ref{sec:EnterEdJornalData}): 
\begin{verbatim}
Substring (empty for all journal names):
\end{verbatim}
  e.\,g. if you type \texttt{medicine} \texttt{[Enter]}, 
  only those journal names are
  written into the list, which contain this substring. If you type
  \texttt{[Enter]} alone\footnote{i.\,e., if you enter an empty string},
  a \emph{complete} list of journal names is written. You will
  browse in the file with \mopt{f} (first page) \mopt{n} (for next page,
  cf. chapter \ref{sec:ViewTextFiles}), \mopt{+} (next line) or \mopt{-}
  (previous line). If have found the item in the list you
  searched for, you will close the list with \mopt{q}.
  At the prompt 
\begin{verbatim}
Please enter journal code:
\end{verbatim}
  you will enter the journal code to be written into a text file (default
  \verb+jn_form.txt+).
  
\item  A similar list is made from bibliographic (or macro) format 
  definitions in the \texttt{References} database, if you
  wish that something shall be done with one format definition.
  If, as an example, one bibliographic format definition has to be 
  written into a text file
  for editing, select \mopt{main-d ef}, open the list with \mopt{f}, navigate
  in the list with \mopt{n} or \mopt{+} or \mopt{-}, close the list with
  \mopt{q} and enter the number of the format definition\footnote{In this
  situation, you may abort this function with \texttt{quit}}.


\item As you write a bibliographic reference into a text files form 
  you may wish to look up keywords in the thesaurus: select \mopt{main-e lk}.
  In this case, you will only 
  have to search the numbers assigned to the keywords and to enter these 
  numbers into the form (field \texttt{K-NUMBER}, details in section 
  \ref{SecEnterReferences}).


\end{itemize}



\clearpage

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