File: bibtool.tex

package info (click to toggle)
bibtool 2.68%2Bds-1
links: PTS, VCS
area: main
in suites: bookworm, bullseye
size: 2,608 kB
sloc: ansic: 11,808; perl: 8,145; makefile: 550; sh: 307; tcl: 51
file content (4806 lines) | stat: -rw-r--r-- 196,871 bytes
parent folder | download | duplicates (2)
%%*** bibtool.tex *************************************************************
%%
%% This file is part of BibTool.
%% It is distributed under the Creative Commons Attribution-Share
%% Alike 3.0 License.
%%
%% (c) 1995-2020 Gerd Neugebauer
%%
%% Net: gene@gerd-neugebauer.de
%%
%%-----------------------------------------------------------------------------
%% Usage:  latex     bibtool
%%         bibtex    bibtool
%%         latex     bibtool
%%         makeindex -s bibtool.ist bibtool
%%         latex     bibtool
%%*****************************************************************************

\documentclass[11pt,a4paper]{scrbook}

\usepackage{bibtool-doc}

\input{config.tex}

\hypersetup{pdftitle={BibTool Manual}}
\hypersetup{pdfauthor={Gerd Neugebauer}}
\hypersetup{pdfsubject={Version \Version}}

\makeindex

\DeclareFontShape{OT1}{cmss}{m}{it}{<-> ssub * cmss/m/sl}{}

\definecolor{keyword}{rgb}{0,.5,0}
\definecolor{bibtex-bg}{rgb}{0.9607843137,0.9019607843,0.8235294118}
\usepackage{listings}
\lstdefinelanguage{BibTeX}{sensitive=false,
  basicstyle=\footnotesize\ttfamily,
  keywordstyle=\bfseries\color{keyword},
  keywords={@string,@article,@book,@misc,@proceedings,@manual,@modify,
    @alias,@include,@InBook,@XData},
  backgroundcolor=\color{bibtex-bg},
  frame=single,
  framerule=0pt}
\lstdefinelanguage{BibTool}{sensitive=false,
  basicstyle=\scriptsize\ttfamily,
  keywordstyle=\color{keyword}\bfseries,
  alsoletter=.,%
  keywords={add.field,apply.alias,apply.modify,apply.include,and,
    bibtex.env.name,bibtex.search.path,check.double,
    check.double.delete,check.rule,check.case.sensitive,
    clear.crossref.map,clear.ignored.words,count.all,count.used,
    crossref.limit,crossref.map,default.key,delete.field,
    dir.file.separator,dump.symbols,env.separator,extract.file,
    extract.regex,expand.macros,expand.crossref,expand.xdata,
    fmt.inter.name,fmt.name.pre,fmt.name.name,fmt.name.title,
    fmt.title.title,fmt.et.al,fmt.word.separator,field.type,false,
    input,ignored.word,ilike,key.generation,key.base,key.format,
    key.make.alias,key.number.separator,key.expand.macros,like,
    macro.file,mod,new.entry.type,new.field.type,new.format.type,not,
    nil,output.file,or,pass.comments,preserve.key.case,preserve.keys,
    print,print.align.string,print.align.comment,print.align.preamble,
    print.align.key,print.align,print.all.strings,print.entry.types,
    print.equal.right,print.braces,print.comma.at.end,
    print.deleted.prefix,print.deleted.entries,print.indent,
    print.line.length,print.newline,print.parentheses,
    print.terminal.comma,print.use.tab,print.wide.equal,quiet,
    regexp.syntax,rename.field,resource,resource.search.path,
    rewrite.rule,rewrite.case.sensitive,rewrite.limit,select,
    select.by.string,select.by.non.string,select.by.string.ignored,
    select.case.sensitive,select.fields,select.non,select.crossrefs,
    sort,sort.cased,sort.macros,sort.reverse,sort.order,sort.format,
    suppress.initial.newline,symbol.type,tex.define,true,verbose,
    version},
  backgroundcolor=\color{rsc-bg},
  frame=single,
  framerule=0pt}

\makeatletter%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

\newcommand\opt[1]{\texttt{-{}#1}\index{#1@\texttt{-{}#1}}}

\definecolor{sh-bg}{rgb}{.9,.9,.9}
\definecolor{sh-border}{rgb}{.4,.4,.4}

\newcommand\sh{\smallskip\par\hspace*{2em}\@ifnextchar[{\sh@}{\sh@@}}
\def\sh@[#1]#2{%
  \fcolorbox{sh-border}{sh-bg}{\hspace*{1em}\begin{minipage}{.85\textwidth}
      \texttt{bibtool -{}#1 }\textit{#2}\index{#1@\texttt{-{}#1}}
    \end{minipage}}\smallskip\par\noindent\ignorespaces}
\newcommand\sh@@[1]{%
  \fcolorbox{sh-border}{sh-bg}{\hspace*{1em}\begin{minipage}{.85\textwidth}
      \texttt{bibtool }\textit{#1}
    \end{minipage}}\smallskip\par\noindent\ignorespaces}

\newcommand\bibLaTeX{Bib\-\LaTeX\index{biblatex@Bib\-\LaTeX}}

\makeatother%<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

\newcommand\rsc[1]{\textsf{#1}\index{#1@\textsf{#1}}}
\newcommand\rscEqBraces[2]{\rsc{#1} = \(\{\)#2\(\}\)}
\newcommand\rscBraces[2]{\rsc{#1} \(\{\)#2\(\}\)}
\newcommand\rscIt[1]{\textsf{\textit{#1}}}
\newcommand\env[1]{\texttt{#1}\index{#1@\texttt{#1}}}

\definecolor{rsc-bg}{rgb}{.9,1,.9}
\definecolor{rsc-border}{rgb}{.4,.6,.4}
\newbox\rscbox
\newenvironment{Resources}%
  {\setbox\rscbox=\hbox\bgroup\hspace*{.06\textwidth}\begin{minipage}{.88\textwidth}\sffamily\obeylines\obeyspaces
  }{\end{minipage}\egroup\vspace{1.5ex}%
    \fcolorbox{rsc-border}{rsc-bg}{\usebox\rscbox}%
    \medskip\par
  }

\newcommand\code[1]{\texttt{#1}}
\newcommand\file[1]{\textsf{#1}}

\newcommand\off{\textsf{off}}
\newcommand\on{\textsf{on}}

\newcommand\bs{\texttt{\symbol{"5C}}\ignorespaces}
\newcommand\BS{\(\backslash\)}
\newcommand\Hat{\^{}}

\newfont\cminch{cminch}
\ifx\chaptername\relax\else
\renewcommand\chaptername{\cminch}
\renewcommand\appendixname{\cminch}
\fi

\newcommand\rfill[1]{\leaders\hrule height #1\hfill}

\newenvironment{Summary}{\subsection*{Summary}
  \begin{center}\small
    \begin{tabular}{p{.08\textwidth}p{.35\textwidth}p{.48\textwidth}}
      \toprule
      \textit{\scriptsize Option}&
      \textit{\scriptsize Resource command}&
      \textit{\scriptsize Description}\\
      \midrule
}{\bottomrule\end{tabular}\end{center}}

\newcommand\Desc[3]{\textit{#1}&\textit{#2}&#3\\\hline}

\newenvironment{Example}{\smallskip\par\textit{Example}\par}{\smallskip\par}

\newenvironment{Disclaimer}{\begin{center}\sffamily\tiny --- }{ ---\end{center}}

\newcommand\LINK[2]{\texttt{#2}}
\newcommand\Link[2]{\href{#1}{\texttt{#2}}}
\newcommand\email[1]{\href{mailto:#1}{\texttt{#1}}}

\newcommand\FTP[2]{\texttt{#1}}

\newcommand\ASCII{\textsc{ascii}}

\let\BIBTEX\BibTeX
\renewcommand\BibTeX{\BIBTEX\index{bibtex@\BIBTEX}}

\begin{document} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\title{\BibTool{} Manual}
\author{\(\cal G\)\hspace{-.1em}erd \(\cal N\)\hspace{-.2em}eugebauer}
\maketitle

\begin{Abstract}
  \BibTeX\ provides an easy to use means to integrate citations and
  bibliographies into \LaTeX\ documents. But the user is left alone with the
  management of the \BibTeX\ files. The program \BibTool\ is intended to fill
  this gap. \BibTool\ allows the manipulation of \BibTeX\ files which goes
  beyond the possibilities -- and intentions -- of \BibTeX. The possibilities
  of \BibTool\ include sorting and merging of \BibTeX\ data bases, generation
  of uniform reference keys, and selecting of references used in a
  publication.
\end{Abstract}

%------------------------------------------------------------------------------
\newpage
\begingroup\setlength\parskip{1ex}\setlength\parindent{0pt}
This file is part of \BibTool{} Version \Version
\medskip\par

Copyright \copyright{} \Year{} Gerd Neugebauer
\medskip\par

\BibTool{} is free software; you can redistribute it and/or modify it under
the terms of the \LINK{GPL.html}{GNU General Public License} as published by
the Free Software Foundation; either version 1, or (at your option) any later
version.

\BibTool{} is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE.  See the \LINK{GPL.html}{GNU General Public License} for
more details.

You should have received a copy of the \LINK{GPL.html}{GNU General Public
  License} along with this documentation; see the file
\LINK{GPL.html}{COPYING}.  If not, write to the Free Software Foundation, 675
Mass Ave, Cambridge, MA 02139, USA.
\vfill\par
Gerd Neugebauer\\
Im Lerchelsb\"ohl 5\\
64521 Gro\ss-Gerau (Germany)\par\noindent
Net: \Link{http://www.gerd-neugebauer.de/}{http://www.gerd-neugebauer.de/}
\par\noindent
E-Mail: \email{gene@gerd-neugebauer.de}
\endgroup
%------------------------------------------------------------------------------
\tableofcontents

%------------------------------------------------------------------------------
\chapter{Introduction}

The user's manual is divided into two parts. In this first part the big
picture on \BibTool{} is shown. The next chapter after this one is then
devoted to the nitty gritty details.


\section{Related Programs}

\BibTeX{} \cite{lamport:latex,patashnik:bibtexing,patashnik:designing} is a
system for integrating bibliographic information into \LaTeX{}
\cite{lamport:latex} documents. \BibTeX{} is designed to serve exactly this
purpose. It has shown that various tasks in relation with managing
bibliographic databases are not covered by \BibTeX. Usual activities on
bibliographic databases include
\begin{itemize}
  \item inserting new entries
  \item editing
  \item using citations in documents
  \item sorting and merging of bibliographic data bases
  \item extraction of bibliographic data bases
\end{itemize}
%
Since only the integration in documents is covered by \BibTeX{} several
utilities emerged to fill the gaps. We will sketch some of them shortly.
%
\begin{description}
\item
  [\href{https://www.ctan.org/pkg/bibtex}{\BibTeX}] is
  a program by Oren Patashnik to select publications used in a \LaTeX{}
  document and format them for inclusion into this document. This program
  should be part of each \TeX{} installation.

\item
  [\href{https://www.ctan.org/pkg/biber}{biber}] is a program to replace
  \BibTeX\ when used in combination with
  \href{https://www.ctan.org/pkg/biblatex/}{\bibLaTeX}
  
\item
  [\href{https://www.ctan.org/pkg/bibclean}{bibclean}]
  is a program by Nelson H.F.~Beebe to pretty-print \BibTeX{} files. It also
  can act as syntax checker. The C sources can be compiled on several systems.
  
\item
  [\href{https://www.ctan.org/pkg/biblook}{bibindex/biblook}]
  is a pair of programs by Nelson H.F.~Beebe to generate an index for a
  \BibTeX{} file and use it to perform a fast look-up of certain entries. The
  programs so far run only under UNIX.
    
\item
  [\href{https://www.ctan.org/pkg/bibsort}{bibsort}]
  is a UNIX shell script by Nelson H.F.~Beebe to sort a \BibTeX{} file.
  
\item
  [\href{https://www.ctan.org/pkg/bibextract}{bibextract}]
  is a UNIX shell script by Nelson H.F.~Beebe to extract entries from a
  \BibTeX{} file which are used in a \LaTeX{} document.
    
\item
  [\href{https://www.ctan.org/pkg/lookbibtex}{lookbibtex/bibdestringify}]
    are Perl scripts by John Heidemann to extract entries from a \BibTeX{}
    file which are used in a \LaTeX{} document and to remove strings from a
    \BibTeX{} file.
    
\item
  [\href{https://www.ctan.org/pkg/bibtools}{bibtools}]
  is a collection of UNIX shell scripts by David Kotz to add and extract
  entries to bibliographic databases. Several small programs are provided to
  perform special tasks.
    
\item
  [\href{https://www.ctan.org/pkg/bibview}{bibview}]
  is a Perl script by Dana Jacobsen to extract entries from a \BibTeX{} file
  which are used in a \LaTeX{} document.
    
\item
  [\href{https://www.ctan.org/pkg/jabref}{JabRef}]
  is a graphical front-end to manage \BibTeX\ databases, designed and built to
  be platform independent.
  
\item
  [\href{https://www.ctan.org/pkg/bibcard}{BibCard}]
  is a program by William C.~Ogden running under X11/xview which provides a
  means to edit bibliographic databases.
  
\item
  [\href{https://www.ctan.org/pkg/xbibtex}{xbibtex/bibprocess/bibsearch}]
  are programs by Nicholas J. Kelly and Christian H. Bischof running under X11
  which provides a means to edit bibliographic databases, add fields to a
  \BibTeX{} file and extract certain entries from a \BibTeX{} file.
    
\item
  [\href{https://www.ctan.org/pkg/bibview}{bibview}]
  is an X11 program by Holger Martin, Peter Urban, and Armin Liebl to search
  in and manipulate \BibTeX{} files. It is similar to BibCard and hyperbibtex.
 
\item
  [\href{https://www.ctan.org/pkg/tkbibtex}{tkbibtex}]
  is a \BibTeX{} file browser with support for editing, searching sorting and
  merging. Written by Peter Corke in Tcl/Tk it runs under Unix and Windows.

\item [\href{https://www.ctan.org/pkg/bibdb}{bibdb}] Editor
  for \BibTeX{} files that runs under Dos and Windows.
  
\item
  [\href{https://www.ctan.org/pkg/qbibman}{qbibman}]
  is a graphical user interface by Ralf G\"{o}rtz utilizing \BibTool{} as
  underlying library. It is written in C++ and uses Qt.
      
\item [\href{http://barracuda.linuxbox.com/}{Barracuda}] an X11 Editor for
  \BibTeX{} files, written in C++ and Qt.
 
\item [\BibTeX-Mode] is an extension of the editor GNU-Emacs to provide means
  to edit \BibTeX{} files. Several useful operations are provided.
  There is also a \BibTeX-Mode for the Emacs-like JED-Editor.
  
\item
  [\href{https://www.ctan.org/pkg/btool/}{btOOL}]
  is a Perl library to access \BibTeX{} files. It is implemented in Perl and C
  and has been written by Greg Ward.
  
\end{description}

This is a selection of some programs I have heard of. I have tested some of
them and I have skipped through the documentation of others. Thus the
description may be too short or incomplete. Some additional information can be
found in \cite[Chapter~13]{goosens.mittelbach.ea:companion}.

Most of those utilities are tailored towards a particular operating system and
thus they are not available on other platforms. Most of these program are made
to perform a single task. Often they can not be configured to suit a personal
taste of a user.

Still there are some points not covered by the utilities mentioned above.
\BibTool{} tries to provide the missing features and integrate others into a
single tool.


%------------------------------------------------------------------------------
\section{Using \BibTool{}---Some Instructive Examples}

\BibTool\ has been developed on UN*X and UN*X-like machines. This has
influenced many of the design decisions. Version 1 was controlled using
numerous command line options. This way of controlling has been supplemented
in version 2 by the concept of a resource file. This resource file allows the
modification of the various internal parameters determining the behavior of
\BibTool.

When \BibTool\ has been compiled correctly there should be an executable file
named \texttt{bibtool}\footnote{Maybe with an additional extension.}. We will
assume that you are running \BibTool\ from a command line interpreter. There
you can simply issue the command

\sh{}

Now \BibTool{} will start reading from the standard input lines obeying the
rules of a \BibTeX{} file.\footnote{We assume that no resource file can be
  found. Resource files will be described later.} The entries read are
pretty-printed on the standard output. It is obvious that this behavior is not
very useful in itself. The origin of this kind of interface lies in the
concepts of UN*X where many commands can act as filters.

Usually we do not intend to use \BibTool{} in this way. Thus we need a way to
specify an input file. This is simply done by adding the file name as argument
after the command name like in

\sh{file.bib}

The result of this command can at once be seen on the screen. The contents of
the file \texttt{file.bib} is pretty printed.


Now that we have seen the simplest case of the application of \BibTool{} we
will see the case of a useful application of \BibTool. This application is the
sorting and merging of \BibTeX{} databases.


%------------------------------------------------------------------------------
\subsection{Sorting and Merging}\label{sample.sort}

\BibTeX{} files can be sorted by specifying the command line option \opt{s}.
The given files are sorted according to the reference key. Several files can
be given at once in which case \BibTool{} will sort and merge those files.

\sh[s]{file1.bib file2.bib}

With the command line option \opt{S} the files are sorted in reverse \ASCII{}
order.

\sh[S]{file1.bib file2.bib}

If you want to sort the \BibTeX{} files according to the authors then the
following invocation should do the trick:\index{N@\%N}

\sh[s]{--sort.format="\%N(author)" file1.bib file2.bib}

This means that the sorting order is determined by the (normalized) author
field. Note that single quotes encapsulating the \rsc{sort.format} are
necessary to prevent the command line interpreter to gobble the special
characters.


If you want to sort the \BibTeX{} files according to the date then you have to
know how the year field is filled. Suppose you know that the year contains the
year preceeded by the month like in \texttt{Mar 2018}. Then the following
invocation sorts according to the year:\index{d@\%d}

\sh[s]{--sort.format="\%d(year)" file1.bib file2.bib}


%------------------------------------------------------------------------------
\subsection{Key Generation}

Once you have a reference and you insert it into a \BibTeX{} file you have to
assign a reference key to it. The problem is to find a key which is unique and
meaningful, i.e.\ easy to remember. The easiest way to remember a key is to
use an algorithm to create it and remember the algorithm---which is the same
for all keys.

One algorithm which comes to mind is to use the author and (an initial part)
of the title. Alternatively we can use the author and the year. But the
problem is with industrious authors writing more than one publication per
year. The necessary disambiguation of such references is not very intuitive.
However, \BibTool{} has the capability to describe desired keys. Thus, the
alternatives described above can be realized.


For this section we want to use the following \BibTeX{} entry as our
example:\footnote{Shamelessly stolen from the \BibTeX{} \file{xamples.bib}
  file.} Suppose it is contained in a file named \file{sample.bib}.

\label{sample1}%
\begin{lstlisting}[language=BibTeX]
@ARTICLE{article-full,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   journal = {\mbox{G-Animal's} Journal},
   year = 1986,
   volume = 41,
   number = 7,
   pages = "73+",
   month = jul,
   note = "This is a full ARTICLE entry",
}
\end{lstlisting}

First, we want to see how we can make keys consisting of author and title.
This is one of my favorite algorithms thus it is rather easy to use it. You
simply have to run the following command:

\sh[k]{\texttt{sample.bib \opt{o} sample1.bib}}

After the command has completed it's work the following entry can be found in
the output file \file{sample1.bib}: 

\begin{lstlisting}[language=BibTeX]
@Article{         aamport:gnats,
  author        = {L[eslie] A. Aamport},
  title         = {The Gnats and Gnus Document Preparation System},
  journal       = {\mbox{G-Animal's} Journal},
  year          = 1986,
  volume        = 41,
  number        = 7,
  pages         = "73+",
  month         = jul,
  note          = "This is a full ARTICLE entry"
}
\end{lstlisting}

You see that the reference key has been changed. It now consists of the last
name and the first relevant word of the title, separated by a colon. Sometimes
it might be desirable to incorporate the initial names as well. This can be
achieved by the command

\sh[K]{\texttt{sample.bib \opt{o} sample1.bib}}

The resulting reference key is \texttt{aamport.la:gnats}. The initials are
appended after the first name. Thus the usual lexicographic order on the keys
will (hopefully) bring together the publications of the same first author.

Another alternative is to use the author and the year. This can be achieved
with the following command:\footnote{Note that some command line interpreters
  (like the UN*X shells) require the format string to be quoted (enclosed in
  single quotes).}\index{n@\%n}

\sh[f]{\texttt{\%n(author):\%2d(year) sample.bib \opt{o} sample1.bib}}

The resulting key is \texttt{Aamport:86}. Note that the last example works as
desired for our sample file. But for a real application of this technique a
deep understanding of the key generation mechanism as described in
section~\ref{sec:key.gen} is necessary.


%------------------------------------------------------------------------------
\subsection{Normalization}\label{sample.norm}

\BibTool{} can be used to normalize the appearance of \BibTeX{} databases. As
an example we can consider the different forms of delimiters for fields.
\BibTeX{} allows the use of of braces or double quotes. Now it can be
desirable to use one style only. For this purpose the rewriting facility of
\BibTool{} can be applied.

\sh{-{}- \texttt{ 'rewrite.rule=\symbol{"7B}"\symbol{"5E}\symbol{"5C}"%
    \symbol{"5C}([\symbol{"5E}\#]*\symbol{"5C})\symbol{"5C}"\$"
    "\symbol{"7B}\symbol{"5C}1\symbol{"7D}"\symbol{"7D}'} \opt{o} out.bib}

Since this seems to be rather cryptic we will have a closer look at this
example. First we have to mention that the outer quotes are there because the
UN*X shell (csh, sh, bash,...) treats some characters special and we want to
avoid this to happen to the rewrite rule given. A similar quoting mechanism
might be required for all command line interpreters.

The rewrite rule is applied to any field. The first string---called
pattern---which is enclosed in double quotes is matched against the contents
of the field. If a match is found then the matching sub-string is replaced by
the replacement text in the second string.

The pattern is a regular expression\index{regular expression} like the ones
used in Emacs\index{Emacs}. The first character is the hat (\verb|^|). This
character anchors the match at the beginning of the line. The last character
is the dollar sign which anchors the end at the end of the field value. Thus
only complete matches are considered.

Since we want to find those fields whose values are enclosed in double quotes
they are given after the hat and before the dollar. To avoid a
misinterpretation as the end of the pattern they have to be quoted with the
backslash (\verb|\|).

Next we have the parentheses \verb|\(|\ldots\verb|\)|. They are instructions
to memorize the matching sub-string in a register. Since it is the first
instruction of this kind the register number~1 is used.

Now we come to the point where we have to specify the contents of the string.
For this purpose we use a character class---written as \verb|[|\ldots\verb|]|.
Since the first character in this class specification is a hat this class
consists of all characters but those given after the hat. Thus all characters
but the hash sign (\verb|#|\index{\#}) are allowed.

The star (\verb|*|\index{*}) after the character class indicates that an
arbitrary number of characters of this class are allowed.

We have used the complicated construction with a character class to avoid
wrong results which would have resulted when this rewrite rule is applied to a
concatenated field value like the following one:

\begin{lstlisting}[language=BibTeX]
  author = "A. U. Thor" # " and " # "S. O. Meone"
\end{lstlisting}

Such fields are left unchanged by the rewrite rule given above. We could have
used the point (\verb|.|) instead of the character class since the point
matches any character. But this would have let to the syntactic wrong result:
\begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor" # " and " # "S. O. Meone}
\end{lstlisting}

But we have to complete the explanation of the rewrite rule. The remaining
part is the replacement text. Here we just have to note that the sub-string
\verb|\1| is not copied verbose but replaced with the contents of the first
register. This register contains the contents of the field without the
delimiting double quotes.

Thus we have a solution to our initial problem which is conservative in the
sense that it sometimes fails but never produces a wrong result.


%------------------------------------------------------------------------------
\subsection{Extracting Entries for a Document}\label{sample:extract}

\BibTool{} can be used to extract the references used in a document. For this
purpose \BibTool{} analyzes the \verb|.aux| file and takes the information
given there. This includes the names of the \BibTeX{} files. Thus no \BibTeX{}
files have to be given in the command line. Instead the \verb|.aux| file has
to specified---preceded by the option \opt{x}.

\sh[x]{document.aux \opt{o} document.bib}

The second option \opt{o} followed by a file name specifies the destination of
the output. This means, instead of writing the result to the standard output
stream the result is written into this file.

%------------------------------------------------------------------------------
\subsection{Extracting Entries Matching a Regular Expression}

\BibTool{} can be used to extract the references which fulfill certain
criteria. Those criteria can be specified utilizing regular
expressions.\footnote{Those features are only usable if the regular expression
  library has been enabled during the configuration of \BibTool{}---which is
  the default.} As a special case we can extract all entries containing a
certain sub-string of the key:

\sh[X]{tex all.bib \texttt{-o} some.bib}

This instruction selects all entries containing the sub-string \texttt{tex} in
the key. The second option \opt{o} followed by a file name specifies the
destination of the output. Thus instead of writing the result to the standard
output stream the result is written into this file.

Next we want to look up all entries containing a sub-string in some of its
fields. For this purpose we search for the string in all fields
first:\footnote{Note that some command line interpreters (e.g the UN*X shells)
  might need additional quoting of the select instruction since it contains
  special characters.}

\sh[-]{select\{"tex"\} all.bib \texttt{-o} some.bib}

Note that the comparison is not done case sensitive; however this can be
customized (see page~\pageref{sec:extract}).

Finally we want to select only those entries containing the sub-string in
anyone of certain fields. For this purpose we simply specify the names of
those fields in the \textit{select} instruction:

\sh[-]{select\{title booktitle \$key "tex"\} all.bib \texttt{-o} some.bib}

This example extracts all entries containing the sub-string \texttt{tex} in
the title field, the booktitle field, or the reference key.

After we have come so far we can say that the first example in this section is
in fact a short version of the following command:

\sh[-]{select\{\$key "tex"\} all.bib \texttt{-o} some.bib}

As a simple case of extraction we might want to extract all books from a
bibliography. This can be done with the following command:

\sh[-]{select\{@book\} all.bib \texttt{-o} some.bib}

A similar method can also be applied for other entry types.

\begin{description}
\item[Note] Usually cross-referenced entries are not selected automatically.
  This can result in incomplete---and thus incorrect---\BibTeX\ files. To
  avoid this behavior use the following command:

  \sh[-]{select\{\@{}book\} \texttt{-c} all.bib \texttt{-o} some.bib}

\end{description}

%------------------------------------------------------------------------------
\subsection{Translating ISO 8859-1 Characters}

Sometimes you need to translate some special characters into \BibTeX\
sequences. Suppose you have edited a \BibTeX\ file and by mistake used those
nice characters that are incompatible with standard \ASCII{} as used in
\BibTeX. You can use \BibTool\ to do the trick:

\sh[r]{iso2tex \opt{i} iso.bib \opt{o} ascii.bib}


%------------------------------------------------------------------------------
\subsection{Correctly Sorting Cross-referenced Entries}

\BibTeX\ has a restriction that a cross-referenced entry has to come after the
referencing entry. This can be achieved by putting all entries containing a
field ``crossref'' before those containing none. As second sorting criterion
we want to use the reference key.

This can be achieved with a resource file containing the
following instructions\index{l@\%l}

\begin{Resources}
  \rsc{sort.format} = \{\{\%1.\#s(crossref)a\#z\}\$key\}
  \rsc{sort.reverse} = off
  \rsc{sort} = on
\end{Resources}

The magic is contained in the first instruction. Thus we will examine it in
detail: 
\begin{description}
\item [\texttt{\%1.\#s(crossref)}]\index{l@\%l}\ \\
  This formatting instruction does not produce any output but simply acts as
  condition to determine whether or not to include the following string. The
  condition counts the allowed characters (\texttt{\#s}) of the field
  \texttt{crossref} and compares this number with the given interval
  \([1,\infty]\) (\texttt{1.}).

  Thus it detects those entries containing a non empty crossref field.
\item [\texttt{\%1.\#s(crossref)a}]\index{l@\%l}\ \\
  If the condition holds then the string \texttt{a} is used as part of the
  sort key.
\item [\texttt{\{\%1.\#s(crossref)a\#z\}}]\index{l@\%l}\ \\
  If the first condition fails then the next alternative after the hash mark
  (\texttt{\#}) is considered. This is the string \texttt{z} which will always
  succeed and thus be included into the sort key.

  Thus this construction will produce \texttt{a} if a crossref field is
  present and not empty or \texttt{z} otherwise.
\item [\texttt{\{\%1.\#s(crossref)a\#z\}\$key}]\index{l@\%l}\ \\
  Finally the reference key (\texttt{\$key}) is appended to the characterizing
  initial letter.
\end{description}

The sorting according to ascending ASCII order will bring all the entries with
crossref fields to the beginning.


%------------------------------------------------------------------------------
\subsection{Petering Out Fields}

Sometimes you might be collecting \BibTeX\ files form various sources. Then
there might be additional and for you useless fields. For instance a creator
of the \BibTeX\ files may have included a library number in the field |libno|
and you want to get rid of it. In such a case you can use the resource
\rsc{delete.field} as in the following example.

The following instruction is placed in a resource file which is passed to
\BibTool\ with the command line option \opt{r}.

\begin{Resources}
  \rsc{delete.field} = \{ libno \}
\end{Resources}

If you have several fileds to delete then you can use the resource
\rsc{delete.field} several times. All fields will be deleted.

Another example can be achieved with the following command line:

\sh[r]{keep\_bibtex wild.bib \opt{o} reduced.bib}

This invocation utilizes the library \file{keep\_bibtex.rsc} which declares
that only those fields should not be deleted which are defined for the
standard styles of \BibTeX.

And in a similar way the standard fields of \bibLaTeX\ can be kept with the
following command line:

\sh[r]{keep\_biblatex wild.bib \opt{o} reduced.bib}


%------------------------------------------------------------------------------
\subsection{\BibTool\ for \bibLaTeX}

\BibTool\ contains the definitions to cope with \BibTeX\ files prepared for
\bibLaTeX. These definitions are contained in the library \file{biblatex.rsc}.
It can be easily included on the command line:

\sh[r]{biblatex \opt{i} in.bib \opt{o} out.bib}

Details can be found in section~\ref{lib:biblatex}.

%------------------------------------------------------------------------------
\section{Interfacing \BibTool{} with Other Programming Languages}

\BibTool{} can be used as a means for other programming languages to access
\BibTeX{} data bases. In this course \BibTool{} reads the \BibTeX{} file and
prints it in a normalized form which makes it easy for the host programming
language to parse it and get the information about the entries and fields.

In addition \BibTool{} can already pre-select several entries or do other
useful transformations before the host programming language even sees the
contents.  Thus it is fairly easy to write a CGI script (e.g.\ in Perl) which
utilizes \BibTool{} to extract certain entries from a \BibTeX{} data base and
presents the result on a HTML page.

Currently the distribution of \BibTool{} contains frames of programs in Perl
and Tcl which can be used as a basis for further developments.

I am working towards making \BibTool{} a linkable library of C code. As one
step into this direction the exported functions and header information has
been documented. This documentation is contained in the distribution.

A tight integration of BibTool into another programming language is possible.
As an experiment into this direction I have chosen Tcl as the target language.
The result is BibTcl which is contained in the distribution of \BibTool.


%------------------------------------------------------------------------------
\section{Getting \BibTool, Hot News, and Bug Reports}

Usually \BibTool{} can be found on the CTAN or one of its mirrors. Thus you
can get \BibTool{} via HTTP or FTP or extract it from a DVD containing a dump
of the CTAN. It can be found in the following location:
\begin{list}{}{}
\item \Link{http://mirrors.ctan.org/biblio/bibtex/utils/bibtool}%
  {http://mirrors.ctan.org/biblio/bibtex/utils/bibtool}
\end{list}

A signature for the source bundle is provided as well. My public key can be
found  on \Link{http://pgp.mit.edu/}{http://pgp.mit.edu/}. You should search
for \texttt{gene@gerd-neugebauer.de}.

\BibTool\ is hosted in a public repository at
\Link{https://github.com}{github}\footnote{It used to be on
  Sarovar 'till December 2013.}. The repository contains the released sources
as well as the development versions. The repository can be found at
\begin{quote}
  \Link{https://github.com/ge-ne/bibtool}{https://github.com/ge-ne/bibtool}
\end{quote}

I have set up a WWW page for \BibTool. It contains a short description of the
features and links to the documentation and the current downloadable version
in source form. The URL is:

\begin{quote}
  \Link{http://www.gerd-neugebauer.de/software/TeX/BibTool/}{http://www.gerd-neugebauer.de/software/TeX/BibTool/}
\end{quote}

In addition, this page contains a description of the current version of
\BibTool{} and a list of changes in the last few releases.

If you encounter problems installing or using \BibTool{} you can send me a bug
report to my email address \texttt{gene@gerd-neugebauer.de}. Please include
the following information into a bug report:
\begin{itemize}
\item The version of \BibTool{} you are using.
\item Your hardware specification and operating system version.
\item The C compiler you are using and its version. (Only for compilation and
  installation problems)
\item The resource file you are using. Try to reduce it to the absolute
  minimum necessary for demonstrating the problem.
\item A \emph{small} \BibTeX{} file showing the problem.
\item The command line options of an invocation of \BibTool{} making
  the problem appear.
\item A short justification why you think that the behavior is an error.
\end{itemize}

I have had the experience that compiling this information has helped me find
my own problems in using software. Thus I could fix several problems before
sending a bug report.

On the other side I have unfortunately also had the experience that I have got
complains about problems in my software. After several questions it turned out
that the program had not been used properly.

Oh, sure. There have been bugs and I suppose there are still some bugs in
\BibTool. I am grateful for each hint which helps me eliminating these bugs.



\section{Contributing to \BibTool}

As you might have read \BibTool{} is free software in the sense of the Free
Software Foundation. This means that you can use it as a whole or parts of it
as long as you do not deny anyone to have the sources and use it freely. See
the file \LINK{COPYING}{COPYING} for details.

If you feel morally obliged to provide compensation for the use of this
program I have the following suggestions.

\begin{itemize}
\item Proofread this documentation and report any errors you find as well as
  additional material to put in.
\item Provide additional contributed pieces to \BibTool. For instance useful
  resource files which could be included into the library.
\item Write a useful program and release it to the public without making
  profit, preferably under an Open Source license like the \LINK{GPL.html}{GNU
    General Public License} or the GNU artistic license.
\end{itemize}


%------------------------------------------------------------------------------
\appendix
\chapter{Reference Manual}
%------------------------------------------------------------------------------

This part of the documentation tries to describe all commands and options.
Since the behavior of \BibTool{} can be adjusted at compile time not all
features may be present in your executable. Thus watch out and complain to the
\emph{installer} if something is missing.

%------------------------------------------------------------------------------
\section{Beware of the Command Line}

Be aware that command line interpreters have different ideas about what to do
with a command line before passing the arguments to a program. Thus it might
be necessary to carefully quote the arguments. Especially if the command
contains spaces it is very likely that quoting is needed.

For instance in UN*X shells it is in general a good strategy to enclose
command line arguments in single quotes (\verb|'|) if they contain white-space
or special characters like \texttt{\symbol{"5C}}, \texttt{\$}, \texttt{\&},
\verb|!|, or \verb|#|.

Instead of excessively using command line arguments it is preferable and less
error-prone to put the major configuration into a resource file and just
include this resource file on the command line. Details on this are described
in the next section.

%------------------------------------------------------------------------------
\section{Command Line Usage and Resource Files}

\BibTool{} can be controlled either by arguments given in the command line or
by commands given in a file (or both). Those command files are called resource
files. If \BibTool{} is installed correctly you should have the executable
command \texttt{bibtool} (maybe with an additional extension). Depending on
your computer and operating system you can start \BibTool{} in different ways.
This can be done either by issuing a command in a command line interpreter
(shell), by clicking an icon, or by selecting a menu item. In the following
description we will concentrate on the use in a UN*X like shell. There you can
type simply

\sh{}

Now \BibTool{} is waiting for your input. As you type \BibTool{} reads what
you type. This input is interpreted as data conforming \BibTeX{} file rules.
The result is printed when \BibTool{} is finished. You can terminate the
reading phase with your End-Of-File character (e.g.\ Control-D on UN*X, or
Control-Z on MS-D*S)

This application in itself is rather uninteresting. Thus we come to the
possibility to give arguments to \BibTool. The simplest argument is \opt{h} as
in

\sh[h]{}

This command should print the version number and a short description of the
command line arguments to the screen.

The next application is the specification of resources. Resource files can be
given in the command line after the flag \opt{r}.

\sh[r]{resource\_file}

In this way an arbitrary number of resource files can be given. Those resource
files are read in turn and the commands contained are evaluated. If no
resource file is given in the command line \BibTool{} tries to find one in
standard places. First of all the environment variable \env{BIBTOOLRSC} is
searched. If it is defined then the value is taken as a list of resource file
names separated by colon (UNIX), semicolon (DOS), or comma (Amiga). All of
them are tried in turn and loaded if they exist. If the environment variable
is not set or no file could be loaded successfully then the default resource
file (usually the file \texttt{.bibtoolrsc}) is tried to be read in the home
directory (determined by the environment variable \env{HOME}) or the current
directory.

The resource files are searched similar to the searching mechanism for
\BibTeX{} files (see section \ref{sec:search}). The extension \texttt{.rsc} is
tried and a search path can be used. This search path is initialized from the
environment variable \env{BIBTOOL}. Initially only the current directory is on
the search path. The search path can also be set in a resource file (for
following resource file reading). This can be achieved by setting the resource
\rsc{resource.search.path}.

\begin{Resources}
  \rsc{resource.search.path} = \emph{path}
\end{Resources}

When an explicit resource file is given in the command line the defaults are
not used. To incorporate the default resource searching mechanism the command
line option \opt{R} can be used:

\sh[R]{}

Now let us consider some examples. Suppose that the current directory contains
a default resource file (named \file{.bibtoolrsc}) and an additional resource
file \file{my\_rsc}.

The following invocation of \BibTool{} uses only the resource file
\textit{my\_rsc}: 

\sh{\opt{r} my\_rsc \opt{i} sample}

If you want to initialize the resources from the default resource file before
you can use the \opt{R} \emph{before} the inclusion of the resource file:

\sh{\opt{R} \opt{r} my\_rsc \opt{i} sample}

If you add the \opt{R} argument after the resource specification then the
default resource is evaluated after your resource file. Thus settings are
potentially overwritten:

\sh{\opt{r} my\_rsc \opt{R} \opt{i} sample}

Additionally note that resource files are evaluated at once whereas input
files are read in one chunk at the end. Thus you can not specify one set of
parameters to be used for one file and another set of parameters for the next
file. This is impossible within one invocation of \BibTool\footnote{This might
  be changed in the next major revision (3.0).}.

As a consequence of this behavior the last example is equivalent to the
following invocations:

\sh{\opt{r} my\_rsc  \opt{i} sample \opt{R}}\vspace*{-4ex}
\sh{\opt{i} sample \opt{r} my\_rsc \opt{R}}
\medskip

Now we have to describe the commands allowed in a resource file.  The general
form of a resource command is of the form

\begin{Resources}
  \rscIt{name} = $\{$\textit{value}$\}$
\end{Resources}

\rscIt{name} is the resource name which conforms the rules of \BibTeX{}
reference keys. Thus \rscIt{name} can be composed of all characters but
white-space characters and\index{\#}\index{\%}\index{=}\index{,}\index{\"@\"{}}%
\index{'}\index{(}\index{)}\index{\{@$\{$}\index{\}@$\}$}
\begin{verbatim}
    "  #  %  '  (  )  ,  =  {  }
\end{verbatim}

Resource names are currently composed of letters and the period. The next
component is an optional equality sign (\texttt{=}). The equality sign is
recommended as it helps detecting syntax problems. White-space characters
surrounding the equality sign or separating resource name and resource value
are ignored. The resource value can be of the following kind:
\begin{itemize}
\item A number composed of digits only.
\item A string conforming the rules of resource names, i.e.\ made up of all
  but the forbidden characters described above.
\item A string containing arbitrary characters delimited by double quotes (")
  not containing double quotes. Parentheses and curly brackets have to come in
  matching pairs.
\item A string containing arbitrary characters delimited by curly brackets
  (\{\}). Parentheses and curly brackets have to come in matching pairs.
\end{itemize}

You can think of resource names as variables or functions in a programming
language. Resource commands simply set the variables to the given value, add
the value to the old value, or initiate a action. There are different types of
resources
\begin{itemize}
\item Boolean resources can take only the values \rsc{on} and \rsc{off}. The
  values \rsc{on}, \rsc{t}, \rsc{true}, 1, and \rsc{yes} are interpreted as
  the same. For those values the case of the letters is ignored. Thus
  \rsc{true} and \rsc{TrUe} are the same. Every other value else is
  interpreted as \rsc{off}.
\item Numeric resources can take numeric values only.
\item String resources can take arbitrary strings.
\end{itemize}

Usually white-space characters are ignored. There is one exception. The
characters \texttt{\%} and \texttt{\#} act as comment start characters if
given between resource commands. All characters to the end of the line are
ignored afterwards.


Now we come the description of the first resource available. To read in
additional resource files the resource file may contain the resource

\begin{Resources}
  \rscBraces{resource}{additional/resource/file}
\end{Resources}

Thus the resource given above has the same functionality as the command line
option \opt{r} described above. Path names should be specified in the normal
manner for your operating system.

One resource command useful for debugging is the \rsc{print} resource. The
resource value is immediately written to the error stream. The output is
terminated by a newline character. Certain translations are performed during
the reading of a resource which can be observed when printing. Each sequence
of white-space characters is translated into a single space.

To end this subsection we give an example of the \rsc{print} resource. In this
sample we also see the possibility to omit the equality sign and use quotes as
delimiters.

\begin{Resources}
  \rsc{print} "This is a stupid message."
\end{Resources}

Finally we can note that the commands given in a resource file can also be
specified on the command line. This can be achieved with the command line
option \opt{-} The next command line argument is taken as a resource command.

\sh[-]{resource\_command}

This can be used to issue resource commands which do not have a command line
counterpart. One example we have already seen. The \rsc{print} instruction can
be used from the command line with the following

\sh[-]{print\{hello\_world\}}

%------------------------------------------------------------------------------
\section{Exit Code}

\BibTool{} as invoked on the command line returns an exit code. This exit code
can be used to control the flow of control for any script which uses
\BibTool{} internally.

In general \BibTool{} returns an exit code of \verb|0| if no error occurs.
Errors lead to an exit code different from \verb|0|.

\medskip

\begin{Summary}
  \Desc{\opt{h}}{}{Show a list of command line options.}
  \Desc{\opt{R}}{}{Immediately evaluate the
    instructions from the default file.} 
  \Desc{}{\rsc{print} \{message\}}{Write out the text \textit{message}.} 
  \Desc{\opt{r} file}{\rsc{resource} = file}{Immediately evaluate the
    instructions from the resource file \textit{file}.} 
  \Desc{}{\rsc{resource.search.path}}{List of directories to search
    for resource files.} 
  \Desc{\opt{-} rsc}{rsc}{Evaluate the resource instruction \textit{rsc}.}
\end{Summary}

%------------------------------------------------------------------------------
\section{Input File Specification and Search Path}\label{sec:search}

An arbitrary number of input files can be specified. Input files can be
specified in two ways. The command line option \opt{i} is immediately followed
by a file name. Since no restriction on the file name is applied this can also
be used to specify files starting with a dash.

\sh[i]{input\_file}

The resource name \rsc{input} can be used to specify additional input files.

\begin{Resources}
  \rscBraces{input}{input\_file}
\end{Resources}

Input files are processed in the order they are given. If no input file is
specified the standard input is used to read from.

Depending on the special configuration of \BibTool{} there are two ways of
searching for \BibTeX{} files. The native mode of \BibTool{} uses a list of
directories and a list of extensions to find a file. Alternatively the
kpathsea library can be used which provides additional features like the
recursive searching in sub-directories. First we look at the native \BibTool{}
searching mechanism.

The files are searched in the following way. If the file is can't be opened as
given the extension \texttt{.bib} is appended and another read is tried. In
addition directories can be given which are searched for input files. The
search path can be given in two different ways. First, the resource name
\rsc{bibtex.search.path} can be set to contain a search path specification.

\begin{Resources}
  \rscEqBraces{bibtex.search.path}{directory1:directory2:directory3}
\end{Resources}

The elements of the search path are separated by colons. Thus colons are not
allowed as parts of directories. Another source of the search path is the
environment variable \env{BIBINPUTS}. This environment variable is usually
used by \BibTeX{} to specify the search path. The syntax of the specification
is the same as for the resource \rsc{bibtex.search.path}. To check the
appropriate way to set your environment variable consult the documentation of
your shell, since this is highly dependent on it.

To allow adaption to operating systems other than UN*X the following resources
can be used. The name of the environment \rsc{bibtex.env.name} overwrites the
name of the environment variable which defaults to \env{BIBINPUTS}.

\begin{Resources}
  \rscEqBraces{bibtex.env.name}{ENVIRONMENT\_VARIABLE}
\end{Resources}

The first character of the resource \rsc{env.separator} is used as separator
of directories in the resource \rsc{bibtex.search.path} and the environment
variable given as \rsc{bibtex.env.name}.

\begin{Resources}
  \rscEqBraces{env.separator}{:}
\end{Resources}

The default character separating directories in a file name is the slash
(\verb|/|).  The first character of the resource \rsc{dir.file.separator} can
be used to change this value.

\begin{Resources}
  \rscEqBraces{dir.file.separator}{\BS}
\end{Resources}

\textbf{Note} that the defaults for \rsc{env.separator} and
\rsc{dir.file.separator} are set at compile time to a value suitable for the
operating system. Usually you don't have to change them at all. For instance
for MSD*S machines the \rsc{env.separator} is usually set to \verb|;| and the
\rsc{dir.file.separator} is usually set to \verb|\|.

If the kpathsea library is used for searching \BibTeX{} files then some of the
resources described above have no effect. They are replaced by their kpathsea
counterparts. Most probably you are using the kpathsea library already in
other \TeX{} related programs. Thus I just have to direct you to the
documentation distributed with the kpathsea library for details.

\begin{Summary}
  \Desc{}{\rsc{bibtex.env.name}=\{var\}}{Use the environment variable
    \textit{env} to add more directories to the search path for \BibTeX{} 
    (input) files.}
  \Desc{}{\rsc{bibtex.search.path}=\{path\}}{Use the list of directories
    \textit{path} to find \BibTeX{} (input) files.} 
  \Desc{}{\rsc{dir.file.separator}=\{c\}}{Use the character \textit{c} to
    separate the directory from the file.} 
  \Desc{}{\rsc{env.separator}=\{c\}}{Use the character \textit{c} to separate
    directories in a path.} 
  \Desc{\opt{i} file}{\rsc{input}\{file\}}{Add the \BibTeX{}
    file \textit{file} to the list of input files.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Output File Specification and Status Reporting}

By default, the processed \BibTeX{} entries are written to the standard
output. This output can be redirected to a file using the command line option
\opt{o} as in

\sh[o]{output\_file}

The resource name \rsc{output.file} can also be used for this purpose.

\begin{Resources}
  \rscEqBraces{output.file}{output\_file}
\end{Resources}

The output file may be one of the special values. If the output file is a
single minus sign then the output is redirected to the standard output stream
as shown in the following example:

\begin{Resources}
  \rscEqBraces{output.file}{-}
\end{Resources}

If the output file is the empty string -- i.e. no characters at all -- then
the output is suppressed entirely. This can be useful for instance if the
input file should be validated only. An empty output file can be seen in the
following example:

\begin{Resources}
  \rscEqBraces{output.file}{}
\end{Resources}

No provisions are made to check if the output file is the same as a input
file.

A second output stream is used to display error messages and status reports.
The standard error stream is used for this purpose.

The messages can roughly be divided in three categories: error messages,
warnings, and status reports. Error messages indicate severe problems. They
can not be suppressed. Warnings indicate possible problems which could
(possibly) have been corrected. They are displayed by default but can be
suppressed. Status reports are messages during the processing which indicate
actions currently performed. They are suppressed by default but can be
enabled.

Warning messages can be suppressed using the command line option \opt{q}.
This option toggles the Boolean quiet value.

\sh[q]{}

The same effect can be obtained by assigning the value \textsf{on} or
\textsf{off} to the resource \rsc{quiet}:

\begin{Resources}
  \rsc{quiet} = on
\end{Resources}

Status reports are useful to see the operations performed. They can be enabled
using the command line option \opt{v}. This option toggles the Boolean verbose
value.

\sh[v]{}

The same can also be achieved with the Boolean resource \rsc{verbose}:

\begin{Resources}
  \rsc{verbose} = on
\end{Resources}

Another output stream can be used to select the string definitions. This is
described in section~\ref{sec:macros} on macros.

%\iffalse
%For completeness we can also mention that the internal symbol table can be
%printed using the command line option \opt{\$} or the boolean resource
%\rsc{dump.symbols}.  This is mainly meant for debugging purposes. \emph{Please
%  send me a bug report and the diffs to fix it :-)}
%\fi

\begin{Summary}
  \Desc{\opt{o} file}{\rsc{output.file} \{file\}}{Direct output to the
    file \textit{file}. If file is \texttt{-} then the standard output is
    used. If the file is the empty string then the output is suppressed.}
  \Desc{\opt{q}}{\rsc{quiet}=on}{Suppress warnings. Errors can not be
    suppressed.}
  \Desc{\opt{v}}{\rsc{verbose}=on}{Enable informative messages on the
    activities of \BibTool.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Parsing and Pretty Printing}\label{sec:parse.pretty}

The first and simplest task we have to provide on \BibTeX{} files is the
parsing and pretty printing. This is not superfluous since \BibTeX{} is rather
pedantic about the accepted syntax. Thus I decided to try to be generous and
correct as many errors as I can.

This can be changed with the resource \rsc{parse.exit.on.error}. If this
resouce is turned on then \BibTool\ exits iimediately when an error during the
parsing is encountered. The default is \textsf{off}.
\begin{Resources}
  \rsc{parse.exit.on.error} = on
\end{Resources}

Each input file is parsed and stored in an internal representation. \BibTeX{}
simply ignores any characters between entries. \BibTool{} stores the comments
and attaches them to the entry immediately following them. Normally anything
between entries is simply discarded and a warning printed. The Boolean
resource \rsc{pass.comments} can be used to change this behavior.

\begin{Resources}
  \rsc{pass.comments} = on
\end{Resources}

If this resource is on then the characters between entries are directly passed
to the output file. This transfer starts with the first non-space character
after the end of an entry.

The standard \BibTeX{} styles support a limited number of entry types. Those
are predefined in \BibTool. Additional entry types can be defined using the
resource \rsc{new.entry.type} as in

\begin{Resources}
  \rscBraces{new.entry.type}{Anthology}
\end{Resources}

This option can also be used to redefine the appearance of entry types which
are already defined. Suppose we have defined \emph{Anthology} as above.
Afterwards we can redefine this entry type to be printed in upper case with
the following option:

\begin{Resources}
  \rscBraces{new.entry.type}{ANTHOLOGY}
\end{Resources}

Each undefined entry type leads to an error message.

When a database is printed the different kinds of entries are printed
together. For instance all normal entries are printed en block. The order of
the entry types is determined by the resource \rsc{print.entry.types}. The
value of this resource is a string where each character represents an entry
type to be printed. If a letter is missing then this part of the database is
omitted. The following letters are recognized---uppercase letters are folded
to their lowercase counterparts if they are not mentioned explicitly:
\begin{description}
\item [a] The aliases of the database.
\item [c] The comments of the database which are not attached to an entry.
\item [i] The includes of the database.
\item [m] The modifies of the database.
\item [n] The normal entries of the database.
\item [p] The preambles of the database.
\item [\$] The strings (macros) of the database.
\item [S] The strings (macros) of the database which are used in the other
  entries.
\item [s] The strings (macros) of the database where the resource
  \rsc{print.all.strings} determines whether all strings are printed or the
  used ones only.
\end{description}

The following invocation prints the preambles and the normal entries only.
This can be desirable if the macros are printed into a separate file.

\begin{Resources}
  \rscBraces{print.entry.types}{pn}
\end{Resources}

The internal representation is printed in a format which can be adjusted by
certain options. Those options are available through resource files or
by specifying resources on the command line.

\begin{description}
  \item [\rsc{print.line.length}]
        This numeric resource specifies the desired width of the lines. lines
        which turn out to be longer are tried to split at spaces and continued
        in the next line. The value defaults to 77.
  \item [\rsc{print.indent}]
        This numeric resource specifies indentation of normal items, i.e.\
        items in entries which are not strings or comments. The value defaults
        to 2.
  \item [\rsc{print.align}]
        This numeric resource specifies the column at which the '=' in
        non-comment and non-string entries are aligned. This value defaults
        to 18.
  \item [\rsc{print.align.key}]
        This numeric resource specifies the column at which the keys in
        non-comment and non-string entries are aligned. This value defaults
        to 18.
  \item [\rsc{print.align.string}]
        This numeric resource specifies the column at which the '=' in string
        entries are aligned. This value defaults to 18.
  \item [\rsc{print.align.preamble}]
        This numeric resource specifies the column at which preamble
        entries are aligned. This value defaults to 11.
  \item [\rsc{print.align.comment}]
        This numeric resource specifies the column at which comment
        entries are aligned.\footnote{This is mainly obsolete now
        since comments do not have to follow any syntactic
        restriction.} This value defaults to 10. 
  \item [\rsc{print.comma.at.end}]
    	This Boolean resource determines whether the comma between fields
    	should be printed at the end of the line. If it is \textsf{off} then
    	the comma is printed just before the field name. In this case the
    	alignment given by \rsc{print.align} determines the column of the
    	comma.
  \item [\rsc{print.equal.right}]
        This Boolean resource specifies whether the = sign in normal entries
        is aligned right. If turned off then the = sign is flushed left to the
        field name. This value defaults to \textsf{on}.
  \item [\rsc{print.newline}]
        This numeric resource specifies the number of newlines between
        entries. This value defaults to 1.
  \item [\rsc{print.terminal.comma}]
        This Boolean resource specifies whether a comma should be printed
        after the last record of a normal entry. This contradicts the rules of
        \BibTeX\ but might be useful for other programs. This value defaults
        to \textsf{off}.
  \item [\rsc{print.use.tab}]
        This Boolean resource specifies if the \texttt{TAB} character should be
        used for indenting. This use is said to cause portability problems.
        Thus it can be disabled. If disabled then the appropriate number of
        spaces are inserted instead. This value defaults to \textsf{on}.
  \item [\rsc{print.wide.equal}]
    	This Boolean resource determines whether the equality sign should be
    	forced to be surrounded by spaces. Usually this resource is \off{}
    	which means that no spaces are required around the equality sign and
    	they can be omitted if the alignment forces it.
  \item [\rsc{suppress.initial.newline}]
        This Boolean resource suppresses the initial newline before normal
        records since this might be distracting under certain circumstances.
\end{description}

The resource values described above are illustrated by the following examples.
First we look at a string entry.
\bigskip

\ifHTML
{\small
\begin{verbatim}
                  |                                                        |
                  | print.align.string                   print.line.length |
\end{verbatim}
}
\else
\noindent
\vbox{
\begin{minipage}{\textwidth}
\begingroup%
\settowidth{\unitlength}{\texttt{\small m}}%
\begin{picture}(0,2)(0,-3)
  \put(18,0){\line(0,1){5.5}}
  \put(77,0){\line(0,1){5.5}}
  \put(77,0){\makebox(0,0)[r]{\rsc{print.line.length}}}
  \put(18,0){\makebox(0,0)[l]{\rsc{print.align.string}}}
\end{picture}
\endgroup
\vspace{1ex}\end{minipage}}
\fi

Next we look at an unpublished entry. It has a rather long list of authors and
a long title. It shows how the lines are broken.
\vspace{4.5ex}

\ifHTML
{\small
\begin{verbatim}
                  | print.align.key
                  | 
@Unpublished{     unpublished-key,
  author        = "First A. U. Thor and Seco N. D. Author and Third A. Uthor
                  and others",
  title         = "This is a rather long title of an unpublished entry which
                  exceeds one line",
  note          = "Some useless comment"
}
  |               |                                                        |
  | print.indent  | print.align                          print.line.length |
\end{verbatim}
}
\else
\noindent
\hbox{%
\begin{minipage}{\textwidth}
{\small
\begin{verbatim}
@Unpublished{     unpublished-key,
  author        = "First A. U. Thor and Seco N. D. Author and Third A. Uthor
                  and others",
  title         = "This is a rather long title of an unpublished entry which
                  exceeds one line",
  note          = "Some useless comment"
}
\end{verbatim}%
}%
\settowidth{\unitlength}{\texttt{\small m}}%
\begin{picture}(0,2)(0,-3)
  \put( 2,0){\line(0,1){14.5}}
  \put(18,15.5){\line(0,1){3.5}}
  \put(18,0){\line(0,1){14.5}}
  \put(77,0){\line(0,1){14.5}}
  \put(18,19){\makebox(0,0)[l]{\rsc{print.align.key}}}
  \put(77,0){\makebox(0,0)[r]{\rsc{print.line.length}}}
  \put(18,0){\makebox(0,0)[l]{\rsc{print.align}}}
  \put( 2,0){\makebox(0,0)[l]{\rsc{print.indent}}}
\end{picture}
\end{minipage}}
\vspace{1ex}
\fi

The field names of an entry are usually printed in lower case. This can be
changed with the resource \rsc{new.field.type}. The argument of this resource
is an equation where left of the '=' sign is the name of a field and on the
right side is it's print name. They should only contain allowed characters.

\begin{Resources}
  \rsc{new.field.type} {\(\{\) author = AUTHOR \(\}\)}
\end{Resources}

This feature can be used to rewrite the field types. Thus it is completely
legal to have a different replacement text than the original field:

\begin{Resources}
  \rsc{new.field.type} {\(\{\) OPTauthor = Author \(\}\)}
\end{Resources}

String names are used case insensitive by \BibTeX. \BibTool{} normalizes
string names before printing. By default string names are translated to lower
case.  Currently two other types are supported: translation to upper case and
translation to capitalized case, i.e. the first letter upper case and the
others in lower case.

The translation is controlled by the resource
\rsc{symbol.type}\label{symbol.type}.  The value is one of the strings
\verb|lower|, \verb|upper|, and \verb|cased|. The resource can be set as in

\begin{Resources}
  \rsc{symbol.type} = upper
\end{Resources}

The macro names are passed through the same normalization apparatus as field
types. Thus you can force a rewriting of macro names with the same method as
described above. You should be careful when choosing macro names which are
also used as field types.

The reference key is usually translated to lower case letters unless a new key
is generated (see section~\ref{sec:key.gen}). In this case the chosen format
determines the case of the key. Sometimes it can be desirable to preserve the
case of the key as given (even so \BibTeX{} does not mind). This can be
achieved with the Boolean resource \rsc{preserve.key.case}. Usually it is
turned off (because of backward compatibility and the memory used for this
feature). You can turn it on as in

\begin{Resources}
  \rsc{preserve.key.case} = on
\end{Resources}

If it is turned on then the keys as they are read are recorded and used when
printing the entries. The internal comparisons are performed case insensitive.
This is not influenced by the resource \rsc{preserve.key.case}.  Especially
this holds for sorting which does not recognize differences in case.

\begin{Summary}
  \Desc{}{\rsc{new.entry.type}\{type\}}{Define a new entry type \textit{type}.}
  \Desc{}{\rsc{new.field.type}\{type\}}{Define a new field type \textit{type}.}
  \Desc{}{\rsc{parse.exit.on.error}=on}{Force immediate exit at the first
    parse error encountered.}
  \Desc{}{\rsc{pass.comments}=on}{Do not discard comments but attach
    them to the entry following them.} 
  \Desc{}{\rsc{preserve.key.case}=on}{Do not translate keys to lower
    case when reading.} 
  \Desc{}{\rsc{print.align.comment}=n}{Align comment entries at column
    \textit{n}.} 
  \Desc{}{\rsc{print.align.key}=n}{Align the key of normal entries at
    column \textit{n}.} 
  \Desc{}{\rsc{print.align.string}=n}{Align the \texttt{=} of string
    entries at column \textit{n}.} 
  \Desc{}{\rsc{print.align}=n}{Align the \texttt{=} of normal entries at
    column \textit{n}.} 
  \Desc{}{\rsc{print.comma.at.end}=on}{Put the separating comma at then end of
  the line instead of the beginning.} 
  \Desc{}{\rsc{print.indent}=n}{Indent normal entries to column \textit{n}.}
  \Desc{}{\rsc{print.line.length}=n}{Break lines at column \textit{n}.}
  \Desc{}{\rsc{print.print.newline}=n}{Number of empty lines between entries.}
  \Desc{}{\rsc{print.use.tab}=on}{Use the \texttt{TAB} character to
    compress multiple spaces.} 
  \Desc{}{\rsc{print.wide.equal}=off}{Force spaces around the equal sign.} 
  \Desc{}{\rsc{suppress.initial.newline}=on}{Suppress the initial newline
  before normal records.}  
  \Desc{}{\rsc{symbol.type}=type}{Translate symbols according to
  \textit{type}: upper, lower, or cased.}  
\end{Summary}


%------------------------------------------------------------------------------
\section{Sorting}\label{sorting}

The entries can be sorted according to a certain sort key. The sort key is by
default the reference key. Sorting can enabled with the command line switches
\opt{s} and \opt{S} as in

\sh[s]{}\vspace{-4ex}
\sh[S]{}

The first variant sorts in ascending \ASCII{} order (including differentiation
of upper and lower case). The second form sorts in descending \ASCII{} order.
The same effect can be achieved with the Boolean resource values \rsc{sort}
and \rsc{sort.reverse} respectively.

\begin{Resources}
  \rscEqBraces{sort}{on}
  \rscEqBraces{sort.reverse}{on}
\end{Resources}

The resource \rsc{sort} determines whether or not the entries should be
sorted. The resource \rsc{sort.reverse} determines whether the order is
ascending (off) or descending (on) \ASCII{} order of the sort key. The sort
key is initialized from the reference key if not given otherwise.

Alternatively the sort key can be constructed according to a specification.
This specification can be given in the same way as a specification for key
generation. This is described in section \ref{sec:key.gen} in detail.

The associated resource name is \rsc{sort.format}. Several formats are
combined as alternatives. 

\begin{Resources}
  \rscEqBraces{sort.format}{\%N(author)}\index{N@\%N}
  \rscEqBraces{sort.format}{\%N(editor)}
\end{Resources}

Those two lines are equivalent with the single resource

\begin{Resources}
  \rscEqBraces{sort.format}{\textit{\%N(author) \# \%N(editor)}}\index{N@\%N}
\end{Resources}

This means that the sort key is set to the (normalized) author names if an
author is given. Otherwise it tries to use the normalized editor name. If
everything fails the sort key is empty.

Let us reconsider the unprocessed example on page \pageref{sample1}. Without
any \rsc{sort.format} instructions this entry would sorted in under
``article-full''. With the \rsc{sort.format} given above it would be sorted in
under ``Aamport.LA''.

\textbf{Note} that in \ASCII{} order the case is important. The
uppercase letters all come before the lowercase letters.  \medskip

Usually the keys are folded to lower case during the normalization. Thus the
lower case variants are also used for comparison. The resource
\rsc{preserve.key.case} can be used to print cased keys as they are
encountered in the input file. This feature can be combined with the Boolean
resource \rsc{sort.cased} to achieve sorting according to the unfolded
reference key:

\begin{Resources}
  \rscEqBraces{preserve.key.case}{on}
  \rscEqBraces{sort.cased}{on}
\end{Resources}

Beside the normal entries the macros (string entries) are sorted. This happens
in per default. The resource \rsc{sort.macros} can be used to turn off this
feature as in

\begin{Resources}
  \rscEqBraces{sort.macros}{off}
\end{Resources}

An example of sorting can be seen in section~\ref{sample.sort} on page
\pageref{sample.sort}.

\begin{Summary}
  \Desc{\opt{S}}{}{Enable sorting of entries in reverse sorting order.}
  \Desc{\opt{s}}{\rsc{sort}}{Enable sorting of entries.}
  \Desc{}{\rsc{sort.cased}=on}{Use the cased form of the reference key for sorting.}
  \Desc{}{\rsc{sort.format}\{spec\}}{Add disjunctive branch \textit{spec} to
  the sort key specifier.} 
  \Desc{}{\rsc{sort.macros}=off}{Turn off the sorting of string entries.}
  \Desc{}{\rsc{sort.reverse}=on}{Reverse the sorting order.}
\end{Summary}

%------------------------------------------------------------------------------
\section{Regular Expression Matching}\label{sec:regex}

\BibTool{} makes use of the GNU regular expression library. Thus a short
excursion into regular expressions is contained in this manual. Several
examples of the application of regular expressions can be found also in other
sections of this manual.

A concise description of regular expressions is contained in the document
\file{regex-0.12/regex.texi} contained in the \BibTool{} distribution. In any
cases of doubt this documentation is preferable. The remainder of this section
contains a short description of regular expressions.

Note that the default regular expressions of the Emacs style are used.

\begin{description}
\item[Ordinary characters] match only to themselves or their upper or lower
  case counterpart. Any character not mentioned as special is an ordinary
  character. Among others letters and digits are ordinary characters.

  For instance the regular expression \emph{abc} matches the string
  \emph{abc}.

\item[The period] (\verb|.|) matches any single character.
  
  For instance the regular expression \emph{a.c} matches the string \emph{abc}
  but it does not match the string \emph{abbc}.
  
\item[The star] (\verb|*|) is used to denote any number of repetitions of the
  preceding regular expression. If no regular expression precedes the star then
  it is an ordinary character.
  
  For instance the regular expression \emph{ab*c} matches any string which
  starts with a followed by an arbitrary number of b and ended by a c. Thus it
  matches \emph{ac} and \emph{abbbc}. But it does not match the string
  \emph{abcc}.
  
\item[The plus] (\verb|+|) is used to denote any number of repetitions of the
  preceding regular expression, but at least one. Thus it is the same as the
  star operator except that the empty string does not match. If no regular
  expression precedes the plus then it is an ordinary character.
  
  For instance the regular expression \emph{ab+c} matches any string which
  starts with a followed by one or more b and ended by a c. Thus it matches
  \emph{abbbc}.  But it does not match the string \emph{ac}.
  
\item[The question mark] (\verb|?|) is used to denote an optional regular
  expression. The preceding regular expression matches zero or one times. If
  no regular expression precedes the question mark then it is an ordinary
  character.
  
  For instance the regular expression \emph{ab?c} matches any string which
  starts with a followed by at most one b and ended by a c. Thus it matches
  \emph{abc}. But it does not match the string \emph{abbc}.

\item[The bar] (\verb/\|/) separates two regular expressions. The combined
  regular expression matches a string if one of the alternative separated by
  the bar does.

  Note that the bar has to be preceded by a backslash.
  
  For instance the regular expression \emph{abc\(\backslash\mid\)def} matches
  the string \emph{abc} and the string \emph{def}.

\item[Parentheses] (\verb|\(\)|) can be used to group regular expressions. A
  group is enclosed in parentheses. It matches a string if the enclosed
  regular expression does.

  Note that the parentheses have to be preceded by a backslash.
  
  For instance the regular expression
  \emph{\(a\backslash(b\backslash\mid\backslash d)c\)} matches the strings
  \emph{abc} and \emph{adc}.
  
\item[The dollar] (\verb|$|) %$
  matches the empty string at the end of the string. It can be used to anchor
  a regular expression at the end.  If the dollar is not the end of the
  regular expression then it is an ordinary character.

  For instance the regular expression \emph{abc\$} matches the string
  \emph{aaaabc} but does not match the string \emph{abcdef}.
  
\item[The hat] (\texttt{\Hat}) matches the empty string at the beginning of
  the string. It can be used to anchor a regular expression at the beginning.
  If the hat is not the beginning of the regular expression then it is an
  ordinary character. There is one additional context in which the hat has a
  special meaning. This context is the list operator described below.

  For instance the regular expression \emph{\Hat abc} matches the strings
  \emph{abcccc} but does not match the string \emph{aaaabc}.
  
\item[The brackets] (\verb|[]|) are used to denote a list of characters. If
  the first character of the list is the hat (\texttt{\Hat}) then the list
  matches any character not contained in the list. Otherwise it matches any
  characters contained in the list.

  For instance the regular expression \emph{[abc]} matches the single letter
  strings \emph{a}, \emph{b}, and \emph{c}. It does not match \emph{d}.

  The regular expression \emph{[\Hat abc]} matches any single letter string
  not consisting of an a, b, or c.
  
\item[The backslash] (\texttt{\BS}) is used for several purposes. Primarily it
  can be used to quote any special character. Thus if a special character is
  preceded by the backslash then it is treated as if it were an ordinary
  character.
  
  If the backslash is followed by a digit \(d\)\/ then this construct is the
  same as the \(d^{th}\) matching group.
  
  For instance the regular expression \emph{(an)\BS1as} matches the string
  \emph{ananas} since the first group matches \emph{an}.
  
  If the backslash is followed by the character \texttt{n} then this is
  equivalent to entering a newline.
  
  If the backslash is followed by the character \texttt{t} then this is
  equivalent to entering a single \texttt{TAB} character.

\end{description}


%------------------------------------------------------------------------------
\section{Selecting Items}

\subsection{Extracting by \texttt{aux} Files}

\BibTool{} includes a module to extract \BibTeX{} entries required for a
document. This is accomplished by analyzing the \texttt{aux} file of the
document. The \texttt{aux} file is usually produced by \LaTeX. It contains the
information which \BibTeX{} files and which references are used in the
document. Only those entries mentioned in the \texttt{aux} file are selected
for printing. Since the \BibTeX{} files are already named in the \texttt{aux}
file it is not necessary to specify an input file.

To use an \texttt{aux} file the command line option \opt{x} can be given. This
option is followed by the name of the \texttt{aux} file.

\sh[x]{file.aux}

Multiple files can be given this way. As always the same functionality can be
requested with a resource. The resource \rsc{extract.file} can be used for
this purpose.

\begin{Resources}
  \rscBraces{extract.file}{\textit{file.aux}}
\end{Resources}

A small difference exists between the two variants. the command line option
automatically sets the resource \rsc{print.all.strings} to \verb|off|. This
has to be done in the resource file manually.

Note that the extraction automatically respects the cross-references in the
selected entries. Thus you will get a complete \BibTeX\ file---unless some
references can not be resolved and an error is produced.

One special feature of \BibTeX{} is supported. If the command
\verb|\nocite{*}| is given in the \LaTeX{} file then all entries of the
bibliography files are included in the bibliography. The same behavior is
imitated by the extracting mechanism of \BibTool.

An example of extracting can be seen in section~\ref{sample:extract} on page
\pageref{sample:extract}.

\subsection{Extracting with Sub-string Matching}

The simplest way of specifying an entry---except by giving its key---is to
give a string which has to be present in one of the fields or pseudo fields.
The resource \rsc{select.by.string} can be used to store a selection rule
which is applied at the appropriate time later on. If several rules are
supplied then any entry matching one of the rules is selected. Thus different
rules act as alternatives. This includes rules with regular expressions as
described in section~\ref{sec:extract}.

The simplest form of the resource \rsc{select.by.string} is to specify a
single string to search for. This string has to be enclosed in double quotes.
Since the argument of the resource has to be enclosed in braces we get the
following funny syntax:

\begin{Resources}
  \rscBraces{select.by.string}{"some string"}
\end{Resources}

This operation selects all entries containing \texttt{some string} in one of
the normal fields. The search can be restricted to specific fields or extended
to pseudo fields by specifying those fields before the search string. An
arbitrary number of white-space separated fields can be given there. Thus the
general syntax for this resource is as follows:

\begin{Resources}
  \rscBraces{select.by.string}{\textit{field\(_1\) \(\ldots\) field\(_n\) "string"}}
\end{Resources}

To make this selection operation more flexible it is possible to determine
whether or not the comparison against the value of a field is performed case
sensitive. This can be done with the Boolean resource
\rsc{select.case.sensitive}. Since the selection is performed after all
resources have been read the value of this resource is only considered then.
Thus it is not possible to mix case sensitive and non case sensitive
selections as with regular expressions (see section~\ref{sec:extract}).

During the matching of the search string against the value of a field
\BibTool{} ignores certain characters. Thus it is possible to hide irrelevant
details like braces or spaces. The characters to ignore are stored in the
resource \rsc{select.by.string.ignored}. As a default the following resource
command is performed implicitly:

\begin{Resources}
  \rscBraces{select.by.string.ignored}{"\{\} []"}
\end{Resources}

As for the resource \rsc{select.case.sensitive} the evaluation of the resource
\rsc{select.by.string.ignored} is performed just before the comparisons are
carried out. Thus it is not possible to use several rules with different
ignored sets of characters.

In addition to the functionality described above the resource
\rsc{select.by.non.string} can be used to select all entries for which the
match against the given field fails. The general form is the same as for
\rsc{select.by.string}:

\begin{Resources}
  \rscBraces{select.by.non.string}{\textit{field\(_1\) \(\ldots\) field\(_n\) "string"}}
\end{Resources}

\begin{description}
\item[Note] Cross-references are not considered unless \rsc{select.crossrefs}
  is set.
\end{description}

\subsection{Extracting with Regular Expressions}\label{sec:extract}

Another selecting mechanism uses regular expressions to select items. This
feature can be used in addition to the selection according to \texttt{aux}
files. The regular expression syntax is identical to the one used in GNU
Emacs. For a description see section \ref{sec:regex}.

The resource \rsc{select} allows to specify which fields should be used to
select entries. The general form is as follows:

\begin{Resources}
  \rscBraces{select}{\textit{field\(_1\) \(\ldots\) field\(_n\) "regular\_expression"}}
\end{Resources}

If no field is specified then the regular expression is searched in each
field. If no regular expression is specified then any value is accepted; i.e.
the regular expression \texttt{"."} is used.

Any number of selection rules can be given. An entry is selected if one of
those rules selects it. The select rule selects an entry if this entry has a
field named \emph{field} which has a sub-string matching
\emph{regular\_expression}. The field can be missing in which case the regular
expression is tried to match against any field in turn.

The pseudo fields \verb|$key|, \verb|$type|, and \verb|@|\emph{type} can be
used to access the key and the type of the entry. See page
\pageref{pseudo:key} for details. The routines used there are the same as
those used here.

Analogously to the negation of the string matching the regular expression
matching can be negated. The resource to perform this functionality is
\rsc{select.non}. The general form is

\begin{Resources}
  \rscBraces{select.non}{\textit{field\(_1\) \(\ldots\) field\(_n\) "regular\_expression"}}
\end{Resources}


The Boolean resource \rsc{select.case.sensitive} can be used to determine
whether the selection is performed case sensitive or not:

\begin{Resources}
  \rscEqBraces{select.case.sensitive}{off}
\end{Resources}

Note that the selection does not take place immediately. Instead all selection
rules are collected and the selection is performed at an appropriate time
later on. The different selection rules are treated as alternatives. Thus any
entry which matches at least one of the rules is selected. Nevertheless the
value of the resource \rsc{select.case.sensitive} is used which is in effect
when the selection rule is issued. Thus it is possible to mix case sensitive
rules with non-case sensitive rule.

A regular expression can be specified in the command line using the option
\opt{X} as in

\sh[X]{regular\_expression}

The fields compared against this regular expression are given in the string
valued resource \rsc{select.fields}. Initially this resource has the value
\verb|$key|. In general the value is a list of fields and pseudo fields to be
considered. The elements of the list are separated by spaces. If the list is
empty then all fields and the key are considered for comparison.
%$

Thus the following setting means that the regular only the fields \verb|author|
and \verb|editor| are considered when doing a selection.

\begin{Resources}
  \rscEqBraces{select.fields}{"author editor"}
\end{Resources}

Without changing the resource \rsc{select.fields} the command line given
previously is equi\-va\-lent to the (longer) command

\sh[-]{select\{\$key "regular\_expression"\}}

Note that the resources \rsc{select.case.sensitive} and \rsc{select.fields}
are used for all regular expressions following their definition until they are
redefined. This means that it is possible to specify that some comparisons are
done case sensitive and others are not done case sensitive.


Finally the resource \rsc{extract.regex} can be used as in

\begin{Resources}
  \rscEqBraces{extract.regex}{\textit{regular\_expression}}
\end{Resources}

This is equivalent to specifying a single regular expression to be matched
against the key. This feature is kept for backward compatibility only. It is
not encouraged and will vanish in a future release.

\begin{description}
\item[Note] Cross-references are not considered unless \rsc{select.crossrefs}
  is set.
\end{description}

\subsection{Extracting and Cross-references}\label{sec:xref}

When extracting entries due to contained sub-strings or regular expression
matching cross-references are not considered automatically. This behavior can
result in incomplete and thus incorrect \BibTeX\ files.

The automatic selection of cross-referenced entries can be controlled by the
resource \rsc{select.crossrefs}. This resource is \texttt{off} by default.
This means that cross-references are ignored.

The following instruction can be used to turn on the automatic inclusion of
cross-referenced entries:

\begin{Resources}
  \rsc{select.crossrefs} = on
\end{Resources}

\subsection{Inheritance and Cross-references}\label{sec:inherit}

\BibTeX\ provides one way to include fields from one entry into another. This
is accomplished with the help of the \texttt{crossref} field.

\begin{lstlisting}[language=BibTeX]
@Book{book-entry,
  bookauthor   = "A. U. Thor",
  booktitle    = "This is the book title"
}
@InBook{in-book-entry,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   crossref = {book-entry}
}
\end{lstlisting}

Sometimes it is desirable to include the fields referenced via
\texttt{crossref} and thus avoiding to have referenced entries in the
bibliography. This can be accomplished with the boolean resource
\rsc{expand.crossref}. This resource is \texttt{off} by default. This means
that cross-references left as they are.

The following instruction can be used to turn on the automatic expansion of
cross-referenced entries:

\begin{Resources}
  \rsc{expand.crossref} = on
\end{Resources}

Note that the crossref mechanism implemented in \BibTool\ acts like
inheritance. This means that fields \emph{not present} in the entry containing
a \texttt{crossref} field are taken from the referenced entry. If for instance
the entry and the referenced entry both contain a title filed then the one in
the entry in not overwritten by one in the referenced entry.

A referenced entry can in turn contain another \texttt{crossref} field. The
referenced entry is recursively explored. This can lead to infinite
cross-reference chains when expanding. The depth of cross-reference chains can
be restricted with the resource \rsc{crossref.limit}. This numeric value
limits the depth of the cross-references. If the actual depth is greater than
this value then the cross-referencing is terminated artificially. The default
value is 32.

\begin{Resources}
  \rsc{crossref.limit} = 42
\end{Resources}

\bibLaTeX\ \cite{lehmann:biblatex} has introduced a mechanism to modify the
names of the fields which are included via \texttt{crossref}. This can for
instance be useful because the standard styles expect a title field of a @Book
but the same information goes into the booktitle field in an @InBook.

To support this behaviour \BibTool\ contains a mapping which declares which
name for a field should be substituted when the cross-referencing is expanded.
It defines which field name to used when the field is expanded from a source
entry of a type with a certain name into an entry of another type.

This is accomplished with the resource \rsc{crossref.map}. It takes an
argument with four symbols: source entry type, source field name, target
entry type, and target field name. This invocation adds a replacement rule to
the set of rules already present:

\begin{Resources}
  \rsc{crossref.map} \{source.type source.field target.type target.field\}
\end{Resources}

The source type and target type need to be defined entry types. Otherwise a
warning is issued and the new rule is ignored.

To ease the definition of mapping rules the source type and target type can be
sets of types respectively. Those are enclosed in braces and separated with
white-space. 

\begin{Resources}
  \rsc{crossref.map} \{\{source.type$_1$ source.type$_2$\} source.field
  \{target.type$_1$ target.type$_2$ target.type$_3$\} target.field\}
\end{Resources}

In such a case each combination with an element of one of the four
constituents is added as mapping rule.

If a mapping rule exists for one combination of source type, source filed, and
target type when defining a new rule then the old rule is overwritten. The
replacement uses the newly defined target field instead.

Initially the set of mapping rules is empty. If some mapping rules have been
defined they can be cleared with the resource \rsc{clear.crossref.map}. The
invocation discards all previously defined mapping rules.

\begin{Resources}
  \rsc{clear.crossref.map} \{\}
\end{Resources}

\bibLaTeX\ \cite{lehmann:biblatex} knows of an additional inheritance
mechanism. For this purpose a special entry type \texttt{@XData} can be used.
This entry carries the fields to be inherited by other entries.
The inheriting entry contains a field named \texttt{xdata} which contains a
comma separated list of \texttt{@XData} entries from which it inherits.

\begin{lstlisting}[language=BibTeX]
@XData{x1,
  bookauthor   = "A. U. Thor",
  booktitle    = "This is the book title"
}
@XData{aw,
  publisher    = "Addison-Wesley Publishing",
  address      = "Reading, Mass."
}
@InBook{in-book-entry,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   xdata = {x1,aw}
}
\end{lstlisting}

\BibTool\ supports this inheritance by taking it into consideration when
selecting. Similar to the expansion of \texttt{crossref} fields \BibTool\ can
be asked to expand \texttt{xdata} fields. This can be achieved with the
boolean resource \rsc{expand.xdata}. This resource is \off\ by default. It can
be turned on as in the following example:

\begin{Resources}
  \rsc{expand.xdata} = on
\end{Resources}


\begin{Summary}
  \Desc{}{\rsc{expand.crossref}=on}{Include the fields for entries references
  via a \texttt{crossref} field.}
  \Desc{}{\rsc{expand.xdata}=on}{Include the fields for entries references
  via an \texttt{xdata} field.}
  \Desc{\opt{x}}{\rsc{extract.file}\{file\}}{Extract the entries from an
    \texttt{aux} file.}
  \Desc{}{\rsc{extract.regex}\{expr\}}{Discouraged backward
    compatibility command.}
  \Desc{\opt{X} regex}{\rsc{select}\{spec\}}{Select certain entries according
    to a regular expression.}
  \Desc{}{\rsc{select.by.non.string}\{spec\}}{Select certain entries according
    to a failing sub-string matching.}
  \Desc{}{\rsc{select.by.string}\{spec\}}{Select certain entries according to
    a sub-string matching.}
  \Desc{}{\rsc{select.by.string.ignored}\{chars\}}{Define the class of
    characters to be ignored by the sub-string matching.}
  \Desc{}{\rsc{select.case.sensitive}=off}{Turn off the case
    insensitive comparison.}
  \Desc{\opt{c}}{\rsc{select.crossrefs}=on}{Turn on the additional selection of
    cross-referenced entries.}
  \Desc{}{\rsc{select.fields}\{fields\}}{Determine fields for \opt{X}.}
  \Desc{}{\rsc{select.non}\{spec\}}{Select certain entries according
    to a failing regular expression matching.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Key Generation}\label{sec:key.gen}

The key generation facility provides a mean to uniformly replace the reference
keys by generated values. Some algorithms are hardwired, namely the generation
of short keys or long keys either unconditionally or only when they are
needed. Additionally a free formatting facility is provided. This can be used
to specify your own algorithm to generate keys. The generation of new keys can
be enabled using the command line option \opt{f} in the following way:

\sh[f]{format}

This command adds format disjunctivly to the formatting instructions already
given. The same effect can be achieved with the resource \rsc{key.format}.

\begin{Resources}
  \rscEqBraces{key.format}{\textit{format}}
\end{Resources}

Some values of \textit{format} have a special meaning. Fixed formatting rules
are used when one of them is in effect. The special values are described
below. To illustrate their results we consider the following \BibTeX{}
database entries:
\begin{lstlisting}[language=BibTeX]
@Unpublished{unpublished-key,
  author   = "First A. U. Thor and Seco N. D. Author and Third A. Uthor
              and others",
  title    = "This is a rather long title of an unpublished entry which
              exceeds one line",
  ...
}
@Article{,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   ...
}
@BOOK{whole-collection,
   editor = "David J. Lipcoll and D. H. Lawrie and A. H. Sameh",
   title = "High Speed Computer and Algorithm Organization",
   ...
}
@MISC{misc-minimal,
   key = "Missilany",
   note = "This is a minimal MISC entry"
}
\end{lstlisting}

\begin{description}
\item [\rsc{short}]
  If a field named \verb|key| is present then its value is used. Otherwise if
  an author or editor field are present, then this field is used. The short
  version uses last names only. Afterwards a title or booktitle field is
  appended, after the \rsc{fmt.name.title} separator has been inserted.
  Finally if all else fails then the default key \rsc{default.key} is used.
  The result is disambiguated (cf.\ \rsc{key.base}).
  
  To see the effect we apply \BibTool{} to the example entries given earlier
  with the command line argument \verb|-- key.format=short|.  This results in
  the following keys (remaining lines skipped):
\begin{lstlisting}[language=BibTeX]
@Unpublished{     thor.author.ea:this,
@Article{         aamport:gnats,
@Book{            lipcoll.lawrie.ea:high,
@Misc{            missilany,
\end{lstlisting}

\item [\rsc{long}]
  The long version acts like the short version but incorporates initials when
  formatting names.
  
  If \BibTool{} is applied to the example entries given earlier with the
  command line argument \verb|-- key.format=long| we get the following keys:
\begin{lstlisting}[language=BibTeX]
@Unpublished{     thor.fau.author.snd.ea:this,
@Article{         aamport.la:gnats,
@Book{            lipcoll.dj.lawrie.dh.ea:high,
@Misc{            missilany,
\end{lstlisting}

\item [\rsc{new.short}]
  This version formats like \rsc{short} but only if the given key field is
  empty. This is obsoleted by the resource \rsc{preserve.keys} and will be
  withdrawn in a future release.
  
  If \BibTool{} is applied to the example entries given earlier with the
  command line argument \verb|-- key.format=short.need| we get the following
  keys:
\begin{lstlisting}[language=BibTeX]
@Unpublished{     unpublished-key,
@Article{         aamport:gnats,
@Book{            whole-collection,
@Misc{            misc-minimal,
\end{lstlisting}
\item [\rsc{new.long}]
  This version formats like \rsc{long} but only if the given key field is
  empty. This is obsoleted by the resource \rsc{preserve.keys} and will be
  withdrawn in a future release.
  
  If \BibTool{} is applied to the example entries given earlier with the
  command line argument \verb|-- key.format=short.need| we get the following
  keys:
\begin{lstlisting}[language=BibTeX]
@Unpublished{     unpublished-key,
@Article{         aamport.la:gnats,
@Book{            whole-collection,
@Misc{            misc-minimal,
\end{lstlisting}

\item [\rsc{empty}]
  The empty version clears the key entirely. The result does not conform to
  the \BibTeX{} syntax rules. This feature can be useful if a resource file
  must be used which generates only new keys. In this case a first pass can
  clear the keys and the given resource file can be applied in a second pass
  to generate all keys.

  If \BibTool{} is applied to the example entries given earlier with the
  command line argument \verb|-- key.format=empty| we get the following
  keys:
\begin{lstlisting}[language=BibTeX]
@Unpublished{	  ,
@Article{	  ,
@Book{		  ,
@Misc{		  ,
\end{lstlisting}
\end{description}

In contrast to the command line option, the resource instruction only modifies
the formatting specification. The key generation has to be activated
explicitly. This can be done using the command line option \opt{F} as in

\sh[F]{}

Alternatively the Boolean resource \rsc{key.generation} can be used in a
resource file:

\begin{Resources}
  \rsc{key.generation} = on
\end{Resources}

Usually all keys are regenerated. This can have the unpleasant side-effect to
invalidate citations in old documents. For this situation the resource
\rsc{preserve.keys} is meant. This resource is usually \verb|off|. If it is
turned \verb|on| then only those entries receive new keys if they do not have
a key already. This means that the input contains only a sequence of
white-space characters (which is not accepted by \BibTeX) as in the following
example:

\begin{lstlisting}[language=BibTeX]
@Article{,
   author = {L[eslie] A. Aamport},
   title = {The Gnats and Gnus Document Preparation System},
   journal = {\mbox{G-Animal's} Journal},
   year = 1986,
   volume = 41,
   number = 7,
   pages = "73+",
   month = jul,
   note = "This is a full ARTICLE entry",
}
\end{lstlisting}
    
Even if \rsc{preserve.keys} is \verb|on|, \BibTool{} still changes all keys to
lower case by default.  This can be suppressed by switching
\rsc{preserve.key.case} to \verb|on| (see section~\ref{sec:parse.pretty}).

When the \rsc{key.format} is not \rsc{empty} then the keys are disambiguated
by appending letters or numbers. Thus there can not occur a conflict which
would arise when two entries have the same key. The disambiguation uses the
resource \rsc{key.number.separator}. If a key is found (during the generation)
which is already been used then the valid characters from the value of this
resource is appended. Additionally a number is added. The appearance of the
number can be controlled with the resource \rsc{key.base}. This resource can
take the values \rsc{upper}, \rsc{lower}, and \rsc{digit}. The effect can be
seen in the following table:

\begin{center}%
  \begin{tabular}{cccc}
    \textrm{generated key}&\rsc{digit}&\rsc{lower}&\rsc{upper}\\\hline
    \texttt{key} & \texttt{key}   & \texttt{key}   & \texttt{key}	\\
    \texttt{key} & \texttt{key*1} & \texttt{key*a} & \texttt{key*A}	\\
    \texttt{key} & \texttt{key*2} & \texttt{key*b} & \texttt{key*B}	\\
    \texttt{key} & \texttt{key*3} & \texttt{key*c} & \texttt{key*C}	\\
    \texttt{key} & \texttt{key*4} & \texttt{key*d} & \texttt{key*D}
  \end{tabular}
\end{center}


As we have seen there are options to adapt the behavior of formatting.  Before
we explain the free formatting specification in section \ref{sec:key.format} we
will present the formatting options. Those options can be activated from a
resource file or with the corresponding feature to specify resource
instructions on the command line.

\begin{description}
  \item [\rsc{preserve.keys}]
        This Boolean resource determines whether existing keys should
        be left unchanged when new keys are generated.
        The default value is \verb|off|.
  \item [\rsc{preserve.key.case}]
        This Boolean resource determines whether keys should be recorded and
        used exactly as read as opposed to normalizing them by translating all
        uppercase letters to lower case.  The default value is \verb|off|.
  \item [\rsc{default.key}]
        The value of this resource is used if nothing else fits.
        The default value is \verb|**key*|.
  \item [\rsc{key.base}]
        The value of this resource is used to determine the kind of formatting
        the disambiguating number. Possible values are \rsc{upper},
        \rsc{lower}, and \rsc{digit}. Uppercase letters, lower case letters,
        or digits are used respectively.
  \item [\rsc{key.number.separator}]
        The value of this resource is used to separate the disambiguating
        number from the rest of the key.
        The default value is \verb|*|.
  \item [\rsc{key.expand.macros}]
        The value of this Boolean resource is used to indicate whether
        macros should be expanded while generating a key.
        The default value is \verb|off|.
  \item [\rsc{fmt.name.title}]
        The value of this resource is used by the styles \rsc{short} and
        \rsc{long} to separate names and titles.
        The default value is \verb|:|.
  \item [\rsc{fmt.title.title}]
        The value of this resource is used to separate words inside titles.
        The default value is \verb|:|.
  \item [\rsc{fmt.name.name}]
        The value of this resource is used to separate different names (where
        the \BibTeX{} file has \verb|and|) when formatting names.
        The default value is \verb|.|.
  \item [\rsc{fmt.inter.name}]
        The value of this resource is used to separate parts of multi-word
        names when formatting names.
        The default value is \verb|-|.
  \item [\rsc{fmt.name.pre}]
        The value of this resource is used to separate names and first names
        when formatting names.
        The default value is \verb|.|.
  \item [\rsc{fmt.et.al}]
        The value of this resource is used to format \verb|and others| parts
        of a name list.
        The default value is \verb|.ea|.
  \item [\rsc{fmt.word.separator}]
        The value of this resource is used as additional characters not to be
        considered as word constituents. Word separators are white-space and
        punctuation characters. Those can not be redefined.
        The default value is empty. 
\end{description}

The key style \rsc{short} can be formulated in terms of the format
specification given in section \ref{sec:key.format} as follows:

\begin{lstlisting}[language=BibTool]
{
  { %-2n(author)
  # %-2n(editor)
  }
  { %s($fmt.name.title) %-1T(title)
  # %s($fmt.name.title) %-1T(booktitle)
  #
  }
}
#
{ { %s($fmt.name.title) %-1T(title)
  # %s($fmt.name.title) %-1T(booktitle)
  }
}
# %s($default.key)
\end{lstlisting}

The syntax and meaning of such format specifications is explained in section
\ref{sec:key.format}.

\subsection{Aliases for Renamed Entries}

\BibTool{} provides a means to automatically generate \verb|@Alias|
definitions for those entries whoich have received a new key during the key
generation. This works for a sufficiently current \BibTeX{} only.

The aliases can be requested with the boolean resource \rsc{key.make.alias}.
This can be set in a resource file file thie:

\begin{Resources}
  \rsc{key.make.alias} = on
\end{Resources}

The default is \texttt{off}. This means that no additional entries are
created.


\begin{Summary}
  \Desc{}{\rsc{preserve.keys}=off}{Do not generate new keys if one is already
  present.}
  \Desc{}{\rsc{preserve.key.case}=on}{Do not translate keys to lower
    case when reading.} 
  \Desc{}{\rsc{default.key}=\{key\}}{Key used if nothing else applies.}
  \Desc{}{\rsc{fmt.et.al}=\{ea\}}{String used to abbreviate further names.}
  \Desc{}{\rsc{fmt.inter.name}=\{s\}}{String used between parts of names.}
  \Desc{}{\rsc{fmt.name.name}=\{s\}}{String used between names.}
  \Desc{}{\rsc{fmt.name.pre}=\{s\}}{String separating first and last names.}
  \Desc{}{\rsc{fmt.name.title}=\{s\}}{String used to separate names
  from titles.}
  \Desc{}{\rsc{fmt.title.title}=\{s\}}{String used to separate words
  in titles.}
  \Desc{}{\rsc{key.base}=\{base\}}{Kind of numbers or letters for
  disambiguating keys.}
  \Desc{}{\rsc{key.expand.macros}=off}{Turn off macro expansion for key
  generation.}
  \Desc{\opt{f}}{\rsc{key.format}\{fmt\}}{Set the specification for
  key generation to \textit{fmt}.}
  \Desc{\opt{F}}{\rsc{key.generation}=on}{Turn on key generation.}
  \Desc{}{\rsc{key.make.alias}=on}{Turn on creation of \texttt{@Alias} entries
  for entries which have received a new key.}
  \Desc{}{\rsc{key.number.separator}=\{s\}}{String to be used before the
    disambiguating number.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Format Specification}\label{sec:key.format}

\subsection{Constant Parts}

The simplest component of a format is a constant string. Such strings are
made up of any character except white-space and the following ten characters

\begin{verbatim}
    "  #  %  '  (  )  ,  =  {  }
\end{verbatim}

This choice of special characters is the same as the special characters of
\BibTeX. Since no means is provided to include a special character into a
format string we guarantee that the resulting key string is conform to the
\BibTeX{} rules.

For example the following strings are legal constant
parts of a format:
\begin{verbatim}
  Key
  the_name.of-the-@uthor-is:
\end{verbatim}


Now we come to explain the meaning of the special characters. The first case
consists of the white-space characters. They are simply ignored. Thus the
following format strings are equal:\footnote{Well, this is not the whole
truth. Internally it makes a difference whether there is a space or not. In
the presence of spaces more memory is used. But you shouldn't worry too much
about this.}
\begin{verbatim}
  Author Or Editor
  AuthorOrEditor
  A u t h o r   O r   E d i t o r
\end{verbatim}


\subsection{Formatting Fields}\label{ssec:fields}

The next component of formats are made up formatting instructions which are
starting with a \texttt{\%} character. The general idea has been inspired by
formatting facilities of C. Since there are several different types of
information in a \BibTeX{} entry we provide several primitives for formatting.
The simplest form is for instance\index{N@\%N}
\begin{verbatim}
  %N(author)
\end{verbatim}

The \texttt{\%} character is followed by a single character---here
\verb|N|---which indicates the way of formatting and the name of the field to
be formatted enclosed in parenthesis. The example above requests to format the
field \verb|author| according to formatting rules for names (\verb|N|).

The general form is

\begin{itemize}
  \item [] \texttt{\%}\textit{sign pre.post qualifier letter}\texttt{(}\textit{field}\texttt{)}
\end{itemize}

In this specification \textit{sign} is \texttt{+} or \texttt{-}. \texttt{+}
means that all characters will be translated to upper case. \texttt{-} means
that all characters will be translated to lower case. If no sign is given, the
case of the field is preserved.

\textit{pre} and \textit{post} are positive integers whose meaning depends on
the format letter \textit{letter}. \textit{qualifier letter} is a one letter
specification indicating the desired formatting type optionally preceded by
the qualifier \verb|#|. Possible values are as described in the following
list:

\begin{itemize}
  \item [\texttt{p}] \index{p@\%p|(}Format names according to the format
    specifier number \textit{post}. In a list of names at most \textit{pre}
    names are used. If there are more names they are treated as given as
    \texttt{and others}.

    \textit{pre} defaults to 2 and \textit{post} defaults to 0.

    See section~\ref{sec:names} for a description of how to specify name
    formats.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor and S. O. Meone and others}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%p(author)}	& \texttt{Thor.Meone.ea}	\\
        \texttt{\%1p(author)}	& \texttt{Thor.ea}		\\
        \texttt{\%-2p(author)}	& \texttt{thor.meone.ea}	\\
        \texttt{\%+1p(author)}	& \texttt{THOR.EA}		
      \end{tabular}
    \end{Example}\index{p@\%p|)}

  \item [\texttt{n}] \index{n@\%n|(}Format last names only.\\
    In a list of names at most \textit{pre} last names are used. If there are
    more names they are treated as given as \texttt{and others}. If
    \textit{post} is greater than 0 then at most \textit{post} characters per
    name are used. Otherwise the whole name is considered.

    \textit{pre} defaults to 2 and \textit{post} defaults to 0.

    This is the same as using the \texttt{p} format specifier with the post
    value of 0. The \textit{post} value of the \texttt{n} specifier is used as
    the \textit{len} value of the first item of the name format specifier.
    (See also section~\ref{sec:names})

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor and S. O. Meone and others}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%n(author)}	& \texttt{Thor.Meone.ea}	\\
        \texttt{\%1n(author)}	& \texttt{Thor.ea}		\\
        \texttt{\%-2n(author)}	& \texttt{thor.meone.ea}	\\
        \texttt{\%+1n(author)}	& \texttt{THOR.EA}		\\
        \texttt{\%.3n(author)}	& \texttt{Tho.Meo.ea}		
      \end{tabular}
    \end{Example}\index{n@\%n|)}

  \item [\texttt{N}] \index{N@\%N|(}Format names with last names and 
    initials.\\
    In a list of names at most \textit{pre} last names are used. If there are
    more names they are treated as given as \texttt{and others}. If
    \textit{post} is greater than 0 then at most \textit{post} characters per
    name are used. Otherwise the whole name is considered.

    \textit{pre} defaults to 2 and \textit{post} defaults to 0.

    This is the same as using the \texttt{p} format specifier with the post
    value of 1. The \textit{post} value of the \texttt{n} specifier is used as
    the \textit{len} value of the first item of the name format specifier.
    (See also section~\ref{sec:names})

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor and S. O. Meone and others}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:
      
      \begin{tabular}{ll}
        \texttt{\%N(author)}	& \texttt{Thor.AU.Meone.SO.ea}	\\
        \texttt{\%1N(author)}	& \texttt{Thor.AU.ea}		\\
        \texttt{\%-2N(author)}	& \texttt{thor.au.meone.so.ea}	\\
        \texttt{\%+1N(author)}	& \texttt{THOR.AU.EA}		\\
        \texttt{\%.3N(author)}	& \texttt{Tho.AU.Meo.SO.ea}	
      \end{tabular}
    \end{Example}\index{N@\%N|)}
    
  \item [\texttt{d}] \index{d@\%d|(}Format a number, e.g.\ a year.\\
    
    The \textit{post}$^{th}$ number in the field is searched. At most
    \textit{pre} digits---counted from the right---are used. For instance
    the field \texttt{"june 1958"} formatted with \texttt{\%2d} results in
    \texttt{58}.
    
    \textit{pre} defaults to a large number except in when the negative sign
    is present. Then it defaults to 1.
        
    \textit{post} defaults to 1. Thus if you want to select the second number
    you can simply use \texttt{\%.2d} as format specifier.
        
    If no number is contained in the field then this specifier fails. Thus the
    specifier \texttt{\%0d} can be used to check for a number.
    
    Positive and negative signs make no sense in specifying translations since
    numbers have no uppercase or lowercase counterparts. Thus they have a
    different meaning in this context.
    
    If the positive sign is given then the specifier does not fail at all.
    Instead of failing a single \verb|0| is used.
    
    If the negative sign is given then the result is padded with \verb|0| if
    required. In this case the specifier does not fail at all. Even if no
    number is found then an appropriate number of \verb|0|s is used.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  pages = {89--123}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:
      
      \begin{tabular}{ll}
        \texttt{\%d(pages)}	& \texttt{89}			\\
        \texttt{\%1d(pages)}	& \texttt{9}			\\
        \texttt{\%4d(pages)}	& \texttt{89}			\\
        \texttt{\%-4d(pages)}	& \texttt{0089}			\\
        \texttt{\%-5.2d(pages)}	& \texttt{00123}		\\
        \texttt{\%.3d(pages)}	& \textit{fails}		\\
        \texttt{\%+.3d(pages)}	& \texttt{0}			\\
        \texttt{\%0d(pages)}	& \textit{succeeds with empty result}
      \end{tabular}
    \end{Example}\index{d@\%d|)}

  \item [\texttt{D}] \index{D@\%D|(}Format a number.\\
    This format specifier acts like the \texttt{d} specifier except that the
    number is not truncated. Thus a large number comes out complete and not
    only the last few digits.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  pages = {89--123}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:
      
      \begin{tabular}{ll}
        \texttt{\%D(pages)}		& \texttt{89}		\\
        \texttt{\%1D(pages)}	& \texttt{89}		\\
        \texttt{\%4D(pages)}	& \texttt{89}		\\
        \texttt{\%-4D(pages)}	& \texttt{0089}		\\
        \texttt{\%-5.2D(pages)}	& \texttt{00123}	\\
        \texttt{\%.3D(pages)}	& \textit{fails}	\\
        \texttt{\%+.3D(pages)}	& \texttt{0}		\\
        \texttt{\%0D(pages)}	& \texttt{89}
      \end{tabular}
    \end{Example}\index{D@\%D|)}

  \item [\texttt{s}] \index{s@\%s|(}Take a field as is (after translation of
    special characters).\\ 
    At most \textit{pre} characters are used.

    \textit{pre} defaults to a large number.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor and S. O. Meone and others}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:
      
      \begin{tabular}{ll}
        \texttt{\%s(author)}	& \texttt{A.-U.-Thor-and-S.-O.-Meone-and-others}	\\
        \texttt{\%8s(author)}	& \texttt{A.-U.-Th}	\\
        \texttt{\%-8s(author)}	& \texttt{a.-u.-th}	\\
        \texttt{\%+8s(author)}	& \texttt{A.-U.-TH}	\\
        \texttt{\%0s(author)}	& \textit{succeeds with empty result}
      \end{tabular}
    \end{Example}\index{s@\%s|)}

  \item [\texttt{T}] \index{T@\%T|(}Format sentences. Certain words are 
    ignored.\\
    At most \textit{pre} words are used. The other words are ignored. If
    \textit{pre} is 0 then no artificial limit is forced. If \textit{post} is
    positive then at most \textit{post} letters of each word are considered.
    Otherwise the complete words are used.

    New words to be ignored can be added with the resource \rsc{ignored.word}.

    \textit{pre} defaults to 1 and \textit{post} defaults to 0.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:
      
      \begin{tabular}{ll}
        \texttt{\%T(title)}		& \texttt{Whole}		\\
        \texttt{\%2T(title)}	& \texttt{Whole-Title}		\\
        \texttt{\%2.1T(title)}	& \texttt{W-T}			\\
        \texttt{\%-T(title)}	& \texttt{whole}		\\
        \texttt{\%+T(title)}	& \texttt{WHOLE}		
      \end{tabular}
    \end{Example}

    The string to be formatted according to this specification is separated
    into words. To accomplish this white-space characters and punctuation
    characters are considered to be not part of a word but as separator. To
    add additional word separators use the resource \rsc{fmt.word.separator}.
    In the following example the characters \verb|+|, \verb|-|, \verb|<|,
    \verb|=|, \verb|>|, \verb|*|, and \verb|/| are declared as additional word
    separators.

    \begin{Resources}
      \rsc{fmt.word.separator} = \texttt{"+-<=>*/"}
    \end{Resources}

    Note that the effect of \rsc{fmt.word.separator} is accumulating more
    characters. It is not possible to define a character not to be a word
    separator once it has this property.\index{T@\%T|)}

  \item [\texttt{t}] \index{t@\%t|(}Format sentences. In contrast to the
    format letter \texttt{T} no words are ignored.\\
    At most \textit{pre} words are used. The other words are ignored. If
    \textit{pre} is 0 then no artificial limit is forced. If \textit{post} is
    positive then at most \textit{post} letters of each word are considered.
    Otherwise the complete words are used.

    \textit{pre} defaults to 1 and \textit{post} defaults to 0.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%t(title)}	& \texttt{The}		\\
        \texttt{\%2t(title)}	& \texttt{The-Whole}	\\
        \texttt{\%2.1t(title)}	& \texttt{T-W}		\\
        \texttt{\%-t(title)}	& \texttt{the}		\\
        \texttt{\%+t(title)}	& \texttt{THE}
      \end{tabular}
    \end{Example}\index{t@\%t|)}

  \item [\texttt{W}] \index{W@\%W|(}Format word lists.\\
    This specifier acts like \texttt{T} except that nothing is inserted
    between words.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%W(title)}	& \texttt{Whole}		\\
        \texttt{\%2W(title)}	& \texttt{WholeTitle}		\\
        \texttt{\%2.1W(title)}	& \texttt{WT}			\\
        \texttt{\%-W(title)}	& \texttt{whole}		\\
        \texttt{\%+W(title)}	& \texttt{WHOLE}	
      \end{tabular}
    \end{Example}\index{W@\%W|)}

  \item [\texttt{w}] \index{w@\%w|(}Format word lists.\\
    This specifier acts like \texttt{t} except that nothing is inserted
    between words.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%w(title)}	& \texttt{The}		\\
        \texttt{\%2w(title)}	& \texttt{TheWhole}	\\
        \texttt{\%2.1w(title)}	& \texttt{TW}		\\
        \texttt{\%-w(title)}	& \texttt{the}		\\
        \texttt{\%+w(title)}	& \texttt{THE}
      \end{tabular}
    \end{Example}\index{w@\%w|)}

  \item [\texttt{\#p}] \index{p@\%\#p|(}Count the number of names.

    If no \textit{sign} is given or the \textit{sign} is \verb|+| then the
    following rules apply. If the count is less than \textit{pre} or the count
    is greater than \textit{post} then this specifier fails. Otherwise it
    succeeds without adding something to the key.

    The construction \verb|and others|, which indicates an unspecified number
    of additional authors, counts as one single author.

    If the \textit{sign} is \verb|-| then the specifier succeeds if and only
    if the specifier without this sign fails. Thus the \verb|-| acts like a
    negation of the condition.

    If post has the value 0 than this is treated like \(\infty\).

    If \(a\) is the number of names separated by \texttt{and} then\\
    \texttt{\%\textit{l}.\textit{h}\#p} succeeds if and only if
    \(l\leq a\leq h\).\\
    \texttt{\%-\textit{l}.\textit{h}\#p} succeeds if and only if \(l>a\) or
    \(a>h\).

    \textit{pre} and \textit{post} both defaults to 0.

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  author = {A. U. Thor and S. O. Meone and others}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%2\#p(author)}		& \textit{succeeds with empty result}	\\
        \texttt{\%4\#p(author)}		& \textit{fails}	\\
        \texttt{\%-4\#p(author)}	& \textit{succeeds with empty result}	\\
        \texttt{\%3.4\#p(author)}	& \textit{succeeds with empty result}	\\
        \texttt{\%-3.4\#p(author)}	& \textit{fails}
      \end{tabular}
    \end{Example}\index{p@\%\#p|)}
    
  \item [\texttt{\#n}] Is the same as \texttt{\#p}\index{n@\%\#n}.

  \item [\texttt{\#N}] Is the same as \texttt{\#p}\index{N@\%\#N}.

  \item [\texttt{\#s}] \index{s@\%\#s|(}Count the number of allowed characters.

    If no \textit{sign} is given or the \textit{sign} is \verb|+| then the
    following rules apply. If the count is less than \textit{pre} or the count
    is greater than \textit{post} then this specifier fails. Otherwise it
    succeeds without adding something to the key.

    If the \textit{sign} is \verb|-| then the specifier succeeds if and only
    if the specifier without this sign fails. Thus the \verb|-| acts like a
    negation of the condition.

    If post has the value 0 than this is treated like \(\infty\).

    \textit{pre} and \textit{post} both default to 0.

    If \(a\) is the number of allowed characters then\\
    \texttt{\%\textit{l}.\textit{h}\#s} succeeds if and only if
    \(l\leq a\leq h\).\\
    \texttt{\%-\textit{l}.\textit{h}\#s} succeeds if and only if \(l>a\) or
    \(a>h\).

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%\#s(title)}		& \textit{succeeds with empty result}\\
        \texttt{\%13.13\#s(title)}	& \textit{succeeds with empty result}\\
        \texttt{\%10.16\#s(title)}	& \textit{succeeds with empty result}\\
        \texttt{\%-10.16\#s(title)}	& \textit{fails}
      \end{tabular}
    \end{Example}\index{s@\%\#s|)}
 
  \item [\texttt{\#w}] \index{w@\%\#w|(}Count the number of words. All words
    are considered as valid. The division into words is performed after
    de\TeX{}ing the field.

    If no \textit{sign} is given or the \textit{sign} is \verb|+| then the
    following rules apply. If the count is less than \textit{pre} or the count
    is greater than \textit{post} then this specifier fails. Otherwise it
    succeeds without adding something to the key.

    If the \textit{sign} is \verb|-| then the specifier succeeds if and only
    if the specifier without this sign succeeds. Thus the \verb|-| acts like a
    negation of the condition.

    If post has the value 0 than this is treated like \(\infty\).

    \textit{pre} and \textit{post} both default to 0.

    If \(a\) is the number of words separated by white-space then\\
    \texttt{\%\textit{l}.\textit{h}\#p} succeeds if and only if 
    \(l\leq a\leq h\).\\
    \texttt{\%-\textit{l}.\textit{h}\#p} succeeds if and only if 
    \(l>a\) or \(a>h\).

    \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
      With the above item we get the following results:

      \begin{tabular}{ll}
        \texttt{\%\#w(title)}	& \textit{succeeds with empty result}\\
        \texttt{\%3.3\#w(title)}	& \textit{succeeds with empty result}\\
        \texttt{\%1.6\#w(title)}	& \textit{succeeds with empty result}\\
        \texttt{\%-1.6\#w(title)}	& \textit{fails}
      \end{tabular}
    \end{Example}\index{w@\%\#w|)}

   \item [\texttt{\#t}] \index{t@\%\#t}Is the same as \texttt{\#w}.
     
   \item [\texttt{\#W}] \index{W@\%\#W|(}Count the number of words. Certain
     words are ignored. The ignored words are determined by the resource
     \rsc{ignored.word}. The division into words is performed after
     de\TeX{}ing the field.

     If no \textit{sign} is given or the \textit{sign} is \verb|+| then the
     following rules apply. If the count is less than \textit{pre} or the
     count is greater than \textit{post} then this specifier fails. Otherwise
     it succeeds without adding something to the key.

     If the \textit{sign} is \verb|-| then the specifier succeeds if and only
     if the specifier without this sign fails. Thus the \verb|-| acts like a
     negation of the condition.

     If post has the value 0 than this is treated like \(\infty\).

     \textit{pre} and \textit{post} both default to 0.

     If \(a\) is the number of words separated by white-space which are
     not marked to be ignored then\\
     \texttt{\%\textit{l}.\textit{h}\#p} succeeds if and only if
     \(l\leq a\leq h\).\\
     \texttt{\%-\textit{l}.\textit{h}\#p} succeeds if and only if \(l>a\) or
     \(a>h\).

     \begin{Example}
      \begin{lstlisting}[language=BibTeX]
  title = {The Whole Title}
      \end{lstlisting}\vspace{-2ex}
       With the above item we get the following results:

       \begin{tabular}{ll}
         \texttt{\%\#W(title)}		& \textit{succeeds with empty result}\\
         \texttt{\%2.2\#W(title)}	& \textit{succeeds with empty result}\\
         \texttt{\%1.6\#W(title)}	& \textit{succeeds with empty result}\\
         \texttt{\%-1.6\#W(title)}	& \textit{fails}
       \end{tabular}
     \end{Example}\index{w@\%\#w|)}

   \item [\texttt{\#T}] \index{T@\%\#T}Is the same as \texttt{\#W}.

\end{itemize}

If some words are enclosed in brace, they are considered as one composed word.
For example, with the format \verb|%t(title)|\index{t@\%t}, and
this field:
\begin{lstlisting}[language=BibTeX]
  title = "{The Whole Title}"
\end{lstlisting}
In this case we obtain \verb|The-Whole-Title|.

The field specification \textit{(field)} selects the field of the entry to be
formatted. As usual in \BibTeX{} the case of the letters is ignored. If the
field does not exist then the formatting fails and continues at the next
alternative (see below).

But the field is not only sought in the current entry. According to the
behavior of \BibTeX{} the special field \texttt{crossref} is taken into
account. If a field is missing them the entry named in the \texttt{crossref}
field is also considered. Since this dereferencing contains the potential
danger of an infinite loop the number of dereferencing steps is restricted by
the numeric resource \rsc{crossref.limit}. The number of uses of the
\texttt{crossref} field is limited by the value of this resource. The default
of this resource is 32.

Usually a value of 1 would be sufficient for \BibTeX{} files conforming to the
standard styles. Nevertheless other applications can be imagined where a
higher value is desirable.

To turn off the crossref feature complete you can set the value of
\rsc{crossref.limit} to 0. In this case only the fields found in the entry
itself are considered.


\subsection{Pseudo Fields}\label{sec:pseudo-fields}

In addition to the ordinary fields of an entry there are several
pseudo fields. They are listed below.

\begin{description}
\item [\texttt{\$key}]\label{pseudo:key}%
  This pseudo field contains the old reference key---before generating a new
  one. If none has been given then the access fails.

\item [\texttt{\$sortkey}]%
  This pseudofield contains the string according to which the sorting is
  performed. It defaults to the reference key.

\item [\texttt{\$default.key}]%
  This pseudo field contains the value of the resource \rsc{default.key}
  similarly the resources \rsc{fmt.name.title}, \rsc{fmt.title.title},
  \rsc{fmt.name.name}, \rsc{fmt.inter.name}, \rsc{fmt.name.pre}, and
  \rsc{fmt.et.al} can be accessed.

\item [\texttt{\$source}]%
  This pseudo field contains the name of the file the entry has been read
  from. If this file can not be determined, e.g. because the entry has been
  read from stdin, then this pseudo field is empty.

\item [\texttt{\$type}]%
  This pseudo field contains the type of the entry, i.e.\ the string following
  the initial \texttt{@} of an \BibTeX{} entry, e.g.\ \texttt{article}. It is
  always present.

\item [\texttt{@}\textit{type}]%
  This pseudo field is matched against the type of the entry. If they are
  identical (ignoring cases) then the type is returned. Otherwise the access
  fails.
  
  In an article item the specification \texttt{\%s(@Article)}\index{s@\%s}
  succeeds and returns \texttt{Article} whereas
  \texttt{\%s(@Book)}\index{s@\%s} fails.

\item [\texttt{\$day}]%
  This pseudo field contains the current day as a two digit number or the
  empty string if this value is not available. The date and time values are
  determined at the beginning of the \BibTool{} run and does not reflect the
  execution time used by \BibTool.

  On some systems the timing function might be missing or returning strange
  values. In this case the timing fields simply return the empty string. 

\item [\texttt{\$month}]%
  This pseudo field contains the current month as a two digit number or the
  empty string if this value is not available. 

\item [\texttt{\$mon}]%
  This pseudo field contains the current month name as a string or the
  empty string if this value is not available. 

\item [\texttt{\$year}]%
  This pseudo field contains the current year as a four digit number or the
  empty string if this value is not available. 

\item [\texttt{\$hour}]%
  This pseudo field contains the current hour as a two digit number or the
  empty string if this value is not available. 

\item [\texttt{\$minute}]%
  This pseudo field contains the current minute as a two digit number or the
  empty string if this value is not available. 

\item [\texttt{\$second}]%
  This pseudo field contains the current second as a two digit number or the
  empty string if this value is not available. 
  
\item [\texttt{\$user}] %
  This pseudo field contains the contents of the environment variable
  \texttt{\$USER} or the empty string if this value is not available. On UN*X
  systems this variable usually contains the name of the user. This can be
  used to write logging information into a field.

\item [\texttt{\$hostname}]%
  This pseudo field contains the contents of the environment variable
  \texttt{\$HOSTNAME} or the empty string if this value is not available.
\end{description}


\subsection{Conjunctions}

Conjunctions are formatting instructions evaluated in sequence. The
conjunctions are simply written by successive formatting instructions. A
conjunction succeeds if every part succeeds. The empty conjunction always
succeeds.

Suppose an \BibTeX{} entry contains fields for \texttt{editor} and
\texttt{year}.  Then the following conjunction succeeds:

\begin{itemize}
\item [] \texttt{\%-3n(editor) : \%2d(year)} \index{n@\%n}\index{d@\%d}
\end{itemize}

If the value of the \texttt{editor} field is \verb|"|\verb|E.D. Itor"| and the
\texttt{year} field contains \texttt{"1992"} then the result is
\texttt{itor:92}.

\subsection{If-Then-Else}\label{ssec:if-then-else}

Depending on the presence of a (pseudo-) field formatting instructions can be
issued. This corresponds to an if-then-else statement in a
\textsc{Pascal}-like language. The syntax is as follows:

\begin{itemize}
  \item [] \verb|(|\textit{field}\/\verb|)|
           \verb|{|\textit{then-part}\/\verb|}|
           \verb|{|\textit{else-part}\/\verb|}|
\end{itemize}

If the access to the (pseudo-)field as described in \ref{ssec:fields} succeeds
then the \textit{then-part} is evaluated. Otherwise the \textit{else-part} is
evaluated. Both parts may be empty. Nevertheless the braces are required.

Let us look at an example. The following construction can be used to format a
field \texttt{author} if it is present or print a constant string.

\begin{itemize}
\item [] \verb|(author){|\texttt{\%}\verb|N(author)}{--no-author--}|
  \index{N@\%N}
\end{itemize}


\subsection{Alternatives}

Alternatives (disjunctives) are separated by the hash mark (\verb|#|). The
general form is

\begin{itemize}
\item [] \textit{alternative\(_1\)} \verb|#|
         \textit{alternative\(_2\)} \verb|#| 
         \textit{\dots}             \verb|#|
         \textit{alternative\(_n\)}
\end{itemize}

The alternatives are evaluated from left to right. The first one that succeeds
terminates the processing of all alternatives with success. If no alternative
is successful then the whole construct fails.

An alternative can be empty. The empty alternative succeeds without any other
effect.

The example given in subsection \ref{ssec:if-then-else} can be also written as

\begin{itemize}
  \item [] \texttt{\%}\verb|N(author) # --no-author--|\index{N@\%N}
\end{itemize}

If the author field is accessible the first alternative succeeds and
terminates the construct. Otherwise the constant string is used. This constant
string always succeeds.


\subsection{Grouping}

Any number of constructs can be enclosed in braces (\verb|{}|) for grouping.
Thus the precedence of operators can be bypassed.

Coming back to our example from the previous subsection. To complicate the
example we want to append an optional title, or a constant string. This is
accomplished as follows.


\begin{itemize}
  \item [] \verb|{|\texttt{\%}\verb|N(author) # --no-author-- } |\index{N@\%N}
           \verb|{|\texttt{\%}\verb|T(title) # --no-title-- } |\index{T@\%T}
\end{itemize}

The grouping allows to restrict the range of the alternative operator \verb|#|
in this example.

Another example shows how the alternative together with grouping can be
used to share a format specification for certain types of entries:

\begin{itemize}
  \item [] \verb|{|\texttt{\%}\verb|0s(@book) # |\texttt{\%}\verb|0s(@proceedings)} --book-or-proc--|\index{s@\%s}
\end{itemize}

The \texttt{\%}\verb|0s|\index{s@\%s} specifier is used to check for the
existence of a certain field without actually adding anything to the output.
Other constructs may serve for the same purpose. This construct is applied to
the pseudo fields \texttt{@book} and \texttt{@proceedings}. The access to the
pseudo field fails if requested in another type of entry. Those two checks are
combined to form a disjunction. Thus the following code---the constant in this
example---is reached only if we are in a book or in a proceedings entry. It is
not reached in an article.


\subsection{Ignored Words}

Certain format specifiers act on lists of words. In this situation it can be
desirable to ignore certain words. For instance when a sort key is constructed
with the title of books it is common practice to omit certain words like
articles. This is accomplished by a list of ignored words. This list is
initialized at compile time to contain articles of different languages (If the
installer has not modified it).

The resource \rsc{ignored.word} can be used to put additional words onto the
list of ignored words. For this purpose the new word is given as argument to
the resource. Note that there should be no space between the braces and the
word. For example:

\begin{Resources}
  \rscBraces{ignored.word}{word}
\end{Resources}

To gain complete control over the list of ignored words you can completely
overwrite the compiled in defaults. This can be accomplished by clearing the
list of ignored words. Afterwards no word is recognized as ignored word until
new words are added to this list. This operation can be performed with the
resource \rsc{clear.ignored.words}. In principal this operation does not
require any argument. Since this contradicts the syntactic restrictions for
resources you have to give an empty argument to this resource:

\begin{Resources}
  \rscBraces{clear.ignored.words}{}
\end{Resources}


\subsection{Expanding \TeX/\LaTeX{} Macros}

When fields are formatted certain \LaTeX{} macros may be replaced by pure
text. Each macro not defined is simply ignored. Initially no \LaTeX{} macro is
defined. The resource \rsc{tex.define} can be used to define \LaTeX{} macros.
The syntax is very close to \LaTeX. The simplest form is the following
definition.

\begin{Resources}
  \rscBraces{tex.define}{\textit{macro=replacement text}}
\end{Resources}

This resource defines a simple macro which is replaced by the replacement
text. This replacement text may in turn contain macros.

In addition to this simple macro also macros involving arguments can be
defined. As in \LaTeX's \verb|\newcommand| the number of arguments is appended
after the macro name.

\begin{Resources}
  \rscBraces{tex.define}{\textit{macro}\texttt{[}\textit{arg}\texttt{]=}\textit{replacement text}}
\end{Resources}

The number of arguments may not exceed 9. The actual parameters are addressed
by writing \texttt{\#}\textit{n}, where \textit{n} is the number of the argument.

For instance, this feature can be used to ignore certain arguments of macros.

Note that spaces between the macro head and the equality sign (\verb|=|) are
ignored. Any unwanted spaces after the equality sign may have strange effects.

Usually the macro name starts with a backslash (\verb|\|). If the macro name
starts with another character then this character is made active
(cf.~\cite{knuth:texbook}). This feature is especially useful for translating
characters with an extended ASCII code (\(\geq128\)) to the appropriate \TeX{}
macros.

For instance the following definition forces the expansion of the macro
\verb|\TeX| to the string \verb|TeX|.

\begin{Resources}
  \rscBraces{tex.define}{\BS{}TeX=TeX}
\end{Resources}

Without this definition the title \verb|The \TeX{}book| would result in
\verb|book|. With this definition the same title results in \verb|TeXbook|.

Suppose you have an input file containing 8-bit characters (e.g. ISO 8859-1
encoding). The following definition can be used to map this character into a
pure ASCII string\footnote{To add an e is the German convention for umlaut
  characters.}

\begin{Resources}
  \rscBraces{tex.define}{{\"u}=ue}
\end{Resources}

With the following definition the \verb|\protect| macro and the corresponding 
braces would be ignored when formatting field, otherwise the braces would 
remain.

\begin{Resources}
  \rscBraces{tex.define}{\BS{}protect[1]=\#1}
\end{Resources}

Some useful definitions can be found in the libraries distributed with
\BibTool{} (see also appendix \ref{chap:resource.files}). 


\subsection{Name Formatting}\label{sec:names}

Names are a complicated thing. \BibTool{} tries to analyze names and
``understand'' them correctly. According to the \BibTeX{} definition a
name consists of four types of components:
\begin{itemize}
\item The first names are any names before the last names which start
  with an upper case letter.\\
  For instance for the name ``Ludwig van Beethoven'' the first name is
  ``Ludwig''.
\item The last name is the last word (or group of words) which does
  not belong to the junior part.\\
  For instance for the name ``Ludwig van Beethoven'' the last name is
  ``Beethoven''.
\item The von part are the names before the last name which start with
  lower case letters.\\
  For instance for the name ``Ludwig van Beethoven'' the von part consists of
  the word ``van''.
\item The junior part of a name is an appendix following the last
  name. \BibTool{} knows only a small number of words that can appear
  in the junior part: junior, jr., senior, sen., Esq., PhD., and roman
  numerals up to XXX.
\end{itemize}

Everything except the last name is optional. Each part can also consist of
several words. More on names can be found in \cite{lamport:latex} and
\cite{patashnik:designing}.

\BibTool{} provides a means to specify how the various parts of a name
should be used to construct a string. This string can be used as part
of a key with the \texttt{\%p}\index{p@\%p} format specifier (see above).

\BibTool{} uses a small number of name format specifiers.\footnote{The exact
  number can be changed in the configuration file before compilation. The
  default is 128.} Initially most of them are undefined. The name format
specifier 0 is initially set to the value
\verb|%*l[|\emph{fmt.inter.name}\/\verb|]|. The name format specifier 1 is
initially set to the value 
\verb|%*l[|\emph{fmt.inter.name}\/\verb|]%*1f[|\emph{fmt.inter.name}\/\verb|]|. 

The name format specifiers 0 and 1 are used by the formatting instructions
\verb|%N|\index{N@\%N} and \verb|%n|\index{n@\%n}. Thus you should be careful
when redefining them. To help you keep an eye on these two name format
specifiers \BibTool{} issues a warning when they are modified.

The resource \rsc{new.format.type} can be used to assign values to those name
format specifiers:\index{f@\%f}\index{v@\%v}\index{l@\%l}

\begin{Resources}
  \rscBraces{new.format.type}{17="\%f\%v\%l"}
\end{Resources}

This instruction sets the name format specifier number 17 to the given value.
This value is a string of characters to be used directly. There is only one
construct which is not used literally. This construct is started by a \% sign
optionally followed by a \verb|+| or a \verb|-| and a number. Next comes one
of the letters \texttt{f}\index{f@\%f}, \texttt{v}\index{v@\%v},
\texttt{l}\index{f@\%f}, or \texttt{j}\index{j@\%j}. Finally there are three
optional arguments enclosed in brackets.

Thus the general form looks as follows:

\begin{itemize}
  \item [] \texttt{\%}\textit{sign} \textit{len}\texttt{.}\textit{number}
           \textit{letter} \texttt{[}%
           \textit{pre}\texttt{][}%
           \textit{mid}\texttt{][}%
           \textit{post}\texttt{]} 
\end{itemize}

The letter \texttt{f}\index{f@\%f} denotes all first names.  The letter
\texttt{l}\index{l@\%l} denotes all last names.  The letter
\texttt{v}\index{v@\%v} denotes all words in the von part.  The letter
\texttt{j}\index{j@\%j} denotes all words in the junior part.

If \textit{sign} is \verb|+| then the words are translated to upper case.  If
\textit{sign} is \verb|-| then the words are translated to lower case.  If no
sign is given then no conversion is performed. If the sign is \verb|*| then
the translation is inherited from the calling format.

The number \textit{len} can be used to specify the number of characters to be
used. Each word is truncated to at most \textit{len} characters if
\textit{len} is greater than 0. Otherwise no truncation is performed. Thus a
value of \(0\) acts like \(\infty\). Note that the length of the name format
specifiers 0 and 1 are automatically inherited from the calling format.

The fractional number \textit{number} after the period denotes the number of
name parts to be taken into account. This can be used to just show the one
first name if more are given.

If \texttt{[}\textit{mid}\texttt{]} is given then this string is used between
several words of the given part. If none is given then the empty string is
used.

If \texttt{[}\textit{pre}\texttt{]} is given then this string is used before
the given part, but only if the part is not empty. If none is given then the
empty string is used.

If \texttt{[}\textit{post}\texttt{]} is given then this string is used after
the given part, but only if the part is not empty. If none is given then the
empty string is used.


Now we can come to an example. Suppose the name field contains the value
\texttt{Cervantes Saavedra, Miguel de}\footnote{This is the author of ``Don
  Quixote''}. This name has two last names, one first name and one word in the
von part.

We want to apply the following name format specifier

\begin{itemize}
  \item [] \verb|%1f[.][][.]|\verb|%1v[.][][.]|\verb|%3l[-]|\verb|%1j| \index{f@\%f}\index{v@\%v}\index{l@\%l}
\end{itemize}

This means we want to use abbreviation of first name, von and junior part to
one letter and of three letters of the last name. Thus we will get the result
\verb|M.d.Cer-Saa|.

Note that the name specifier does not take care to include only allowed
letters into a key. Thus watch out and avoid special characters as white-space
and comma.


%------------------------------------------------------------------------------
\subsection{Example}

To end this section we should have a look at a complete example of key
generation specification. For this purpose we define a rule according to which
the keys should be generated:
\begin{enumerate}
\item If a field named \texttt{bibkey} is present then the value of this field
  should be used.
\item If the type of the entry is a book then the authors/editors are used
  followed by the year separated by a colon.
\item If the type of the entry is an article in a journal (\texttt{article}) then
  the author, the journal, the number, and the year should be used. Author and
  journal should be separated by a colon, The journal should be abbreviated
  with the initials and separated from number and year by a period.
\item If the type of the entry is a volume of conference proceedings
  (\texttt{proceedings}) then the editor, the first 5 initials of the title
  and the year should be used. The editor should be followed by a colon and
  the year preceded by a period.
\item If the type of the entry is a contribution in conference proceedings
  then the author, the initials of the book title and the year should be used.
\item Otherwise the first three letters of the type, the author and the
  year should be used. If no author is given then the initials of the
  title should be used instead---but at most 6 characters.
\end{enumerate}
The names should include up to two names abbreviated to four letters and
should be translated to lower case. If an information is missing then the
respective part together with the following separator should be omitted.

The disambiguation should be done by appending upper case letters without a
preceding string. If everything else fails three question marks should be
inserted as key.

To implement this scheme we write the following specification into a resource
file:
\begin{lstlisting}[language=BibTool]
key.expand.macros = on
key.base = upper
key.number.separator = {}
key.format =
{
    %s(bibkey)
  #
    %0w(@book)
    { %-2.4n(author): # %-2.4n(editor): # }
    { %4d(year)       # }
  #
    %0w(@article)
    { %-2.4n(author): # }
    { %-.1W(journal). # }
    { %4d(year)       # }
  #
    %0w(@proceedings)
    { %-2.4n(editor): # }
    { %-.1W(title).   # %-.1W(booktitle). # }
    { %4d(year)       # }
  #
    %0w(@inproceedings)
    { %-2.4n(author):   # }
    { %-.1W(booktitle). # }
    { %4d(year)         # }
  #
    %3s($type)-
    { %-2.4n(author):
    # %-6.1W(title).
    }
    {%4d(year) # }
  #
    %3s($type)-
    %4d(year)
  # ???
}
\end{lstlisting}
  
Since each part has been explained before we just need some overall remarks. I
prefer to use the backtracking-based disjunctions instead of nested
if-then-else constructs because they save some braces. They can be read as a
switch statement, or even better as a \texttt{cond} statement in Lisp. This
means they describe cases. The first successful case terminates the evaluation
of the whole cascade.

The constructions like \verb|%0w(@book)| are use to distinguish the different
types. This construction does not produce any output. It just succeeds or
fails depending on the type of the current entry. The \verb|%0w| could also
be replaced by other specifiers which serve the same purpose.

The constructions like \verb|{%4d(year) # }| always succeed. The hash sign
(\verb|#|) catches the failure and inserts the second alternative---which
happens to be empty---if the requested field does not exist.


\begin{Summary}
  \Desc{}{\rsc{clear.ignored.words}\{\}}{Forget all words from the list of
    ignored words.}
  \Desc{}{\rsc{new.format.type}\{n=spec\}}{Define a new way to format names.}
  \Desc{}{\rsc{ignored.word}\{s\}}{Add a word to the list of ignored words.}
  \Desc{}{\rsc{tex.define}\{macro=text\}}{Expand the \TeX{} macro
    \textit{macro} to \textit{text}.} 
  \Desc{}{\rsc{tex.define}\{macro[n]=text\}}{Expand the \TeX{} macro
    with arguments.}
\end{Summary}

%------------------------------------------------------------------------------
\section{Field Manipulation}

This sections contains some operations to manipulate fields in some kind.

%------------------------------------------------------------------------------
\subsection{Adding Fields}

Certain fields can be added. This feature can be used for instance
to update time stamps. For this purpose it is important to know that deletion
is done before addition. It is also important to know that the newly added
entries are not rewritten (see next section) even though rewrite rules are
applicable. The resource \rsc{add.field} is provided to perform this
operation.

\begin{Resources}
  \rscBraces{add.field}{\textit{field=value}}
\end{Resources}

This instruction replaces the contents of the field \textit{field} by
\textit{value} in each entry. If this field does not exist already then it is
added first. The additions are applied in the sequence they are given.

\textit{value} can contain formatting instructions already introduced in the
section~\ref{ssec:fields} about ``Formatting Fields'' on
page~\pageref{ssec:fields}.

Suppose a time stamp is stored in the field \texttt{time}.  With these
resources the update of a time-stamp can be achieved using the resource
instructions

\begin{Resources}
  \rscBraces{add.field}{time="June 13, 2000"}
\end{Resources}

If you want to update all time fields to contain the current date the
following instruction can be used. It makes use of the pseudo fields (see
page~\pageref{pseudo:key}).\index{s@\%s}

\begin{Resources}
  \rscBraces{add.field}{time="\%s(\$mon) \%s(\$day), \%s(\$year)"}
\end{Resources}

If you want to strip the month to three leading letters and the year to two
trailing digits this can be achieved with the following
instruction:\index{s@\%s}\index{d@\%d}

\begin{Resources}
  \rscBraces{add.field}{time="\%3s(\$mon) \%s(\$day), \%2d(\$year)"}
\end{Resources}

%------------------------------------------------------------------------------
\subsection{Deleting Fields}

Certain fields can be deleted. The resource \rsc{delete.field} is provided to
perform this operation.

The following instruction deletes all fields named \textit{field}:

\begin{Resources}
  \rscBraces{delete.field}{\textit{field}}
\end{Resources}

Several instructions of this type can be used to delete several fields.


%------------------------------------------------------------------------------
\subsection{Keeping Fields}

The reverse to the specification of fields to be deleted is the specification
of fields to be kept. Then all fields which are not declared to be kept are
deleted. The resource \rsc{keep.field} allows such a specification.

In the simplest form you can specify the name of a field to be kept. This is
shown in the following example.

\begin{Resources}
  \rscBraces{keep.field}{\textit{field}}
\end{Resources}

Several instructions with the resource \rsc{keep.field} can be given. Then all
fields which are not specified to be kept are deleted.

Note that in the extreme case all fields are deleted and an empty entry
containing just the key remains.

Next you can add a condition

\begin{Resources}
  \rscBraces{keep.field}{\textit{field} if \textit{field$_c$} = "\textit{pattern}"}
\end{Resources}

The condition follows the key word \texttt{if}. It consists of the comparison
of a field -- or pseudo-field -- with a pattern. The pattern is a regular
expression with which the field is matched. The matching is perfomed
case-insensitiv.

As simplification you can specify several fields to be kept in one rule. For
this purpose you enclose the field names in braces and separate them with
white-space. This is illustrated in the following resources:

\begin{Resources}
  \rscBraces{keep.field}{\{\textit{field$_1$} \ldots \textit{field$_n$}\}}
  \rscBraces{keep.field}{\{\textit{field$_1$} \ldots \textit{field$_n$}\} if \textit{field$_c$} = "\textit{pattern}"}
\end{Resources}

The forms of the arguments given above require to list the fields to be given
explicitly. In addition to these forms you can specify the star (\verb|*|) as
field name. If the special field name \verb|*| is encountered then this is
interpreted as arbitrary field name.

\begin{Resources}
  \rscBraces{keep.field}{*}
  \rscBraces{keep.field}{* if \textit{field$_c$} = "\textit{pattern}"}
\end{Resources}

The first form is rather useless since it means that all fields should be
kept. This nullifies any other rule to keep a field.

The second form can be used to express that all fields should be kept if the
record satisfies the given condition.

The libraries \file{keep\_bibtex.rsc} and  \file{keep\_biblatex.rsc} contain
\rsc{keep.field} resources contain declarations to keep the fields in the
record types defined in the standard styles of \BibTeX\ and \bibLaTeX\
respectively.

%------------------------------------------------------------------------------
\subsection{Renaming Fields}

Fields can be renamed during the field rewriting phase. This takes immediate
effect such that rewriting rules can fire after the renaming has been
performed.

The resource \rsc{rename.field} can be used to perform this operation. This
resource can be used in the following forms:

\begin{Resources}
  \rscBraces{rename.field}{\textit{old=new}}
  \rscBraces{rename.field}{\textit{old=new} if \textit{field=pattern}}
\end{Resources}

The parameters \textit{old} and \textit{new} are the old and the new name of
the field. The values are (unquoted) symbols. They are treated case
in-sensitive. The final appearance in the output is determined in the printing
phase.

In the second form a selector is added. \textit{field} is the name of a field
or pseudo field (see section~\ref{sec:pseudo-fields}). The value of this field
is gathered from the current record and matched against the pattern given as
\textit{pattern}. \textit{pattern} is a string value enclosed in double quotes.
The matching succeeds if the \textit{pattern} matches a substring of the value
of the \textit{field}. If the record does not have such a field then the
renaming is not applied. 

The case-sensitivity of the matching is controlled by the resource
\rsc{rewrite.case.sensitive}. 

The equal signs in the parameter of the resource are optional. They can
omitted or written as \#.

Note that it is up to you to ensure that double appearing field names are
avoided. They would lead to illegal records in the \BibTeX\ output.

Note that the selecting pattern is rather restricted at the moment. This might
change in the future.

The following examples illustrate the function of the resource
\rsc{rename.field}.

The following rule fixes a typo in the field name.

\begin{Resources}
  \rscBraces{rename.field}{autor = author}
\end{Resources}

The following rule renames the field \texttt{title} to \texttt{booktitle} for
books. All other record types are unaffected.

\begin{Resources}
  \rscBraces{rename.field}{title = booktitle if \$type = "book"}
\end{Resources}


%------------------------------------------------------------------------------
\subsection{Field Rewriting}\label{sec:field.rewriting}

Field modifications can be used to optimize or normalize the appearance of a
\BibTeX{} data base. The powerful facility of regular expression matching is
used for this purpose as we have already seen in section~\ref{sample.norm}.

The resource \rsc{rewrite.rule} can be used to specify rewrite rules. The
general form is as follows:

\begin{Resources}
  \rscBraces{rewrite.rule}{field\(_1\) \(\ldots\) field\(_n\) \# pattern \# replacement\_text} 
\end{Resources}

\emph{field\(_1\) \(\ldots\) field\(_n\)} is a list of field names. The
rewrite rule is only applied to those fields which have one of those names. If
no field name is given then the rewrite rule is applied to all fields.

\begin{Resources}
  \rscBraces{rewrite.rule}{\textit{pattern \# replacement\_text}}
\end{Resources}

Next there is the separator '\#'. This separator is optional. It can also be
the equality sign '='.

\emph{pattern} is a regular expression enclosed in double quotes ("). This
pattern is matched against sub-strings of the field value---including the
delimiters. If a match is found then the matching string is replaced by the
replacement text or the field deleted if no replacement text is given.

\emph{replacement\_text} is the string to be inserted for the matching
sistering of the field value. The backslash '\BS' is used as escape character.
'\BS\(n\)' is replaced by the \(n^{th}\)\/ matching group of \emph{pattern}.
\(n\)\/ is a single digit (1--9). Otherwise the character following the
backslash is inserted.\footnote{Future releases may use backslash followed by
  letters for special purposes. It is not safe to rely on escaping letters.}
Thus it is possible to have double quotes inside the replacement text.

Other specials are
\begin{itemize}
\item [\BS\$] which is replaced by the key of the current entry.
\item [\BS @] which is replaced by the type of the current entry.
\end{itemize}

If no replacement text is given then the whole field is deleted. In fact the
instruction \rsc{delete.field} is only an alias for a corresponding rewrite
rule with an empty replacement text.  This behavior is illustrated in the
following abstract examples:

\begin{Resources}
  \rscBraces{rewrite.rule}{\textit{field \# pattern}}
  \rscBraces{rewrite.rule}{\textit{pattern}}
\end{Resources}

More concrete, the rewrite rule

\begin{Resources}
  \rscBraces{rewrite.rule}{ time \# "\Hat\(\{\}\)\$" }
\end{Resources}

deletes the time field if the value of the field is empty and enclosed in
curly braces. This is checked with the anchored regular expression
\texttt{\^{}\(\{\}\)\$}. The hat \verb|^| matches the beginning of the value
and the dollar \texttt{\$} matches its end. Since nothing is in
between---except the field delimiters---the rule is applied only to time
fields with empty contents.

This can be generalized to the following rewrite rule which deletes all empty
fields using the same mechanism and just omitting the specification of a field
name:

\begin{Resources}
  \rscBraces{rewrite.rule}{ "\Hat\(\{\}\)\$" }
\end{Resources}

Note that for a similar kind of rule for double quotes as field delimiters you
need to quote these characters with backslashes:

\begin{Resources}
  \rscBraces{rewrite.rule}{ "\Hat\BS"\BS"\$" }
\end{Resources}


The replacement text may contain field formatting instructions as described in
section~\ref{ssec:fields} on page~\pageref{ssec:fields}. These field
formatting instructions are replaced by their respective values. Thus we could
exploit again the time stamp example from above. The following rewrite rule
will update an existing time stamp without adding one if none is present:

\begin{Resources}
  \rscBraces{rewrite.rule}{ time ".*" = "\%3s(\$mon) \%s(\$day), \%2d(\$year)"	}\index{s@\%s}\index{d@\%d}
\end{Resources}

The pattern \verb|.*| matches any sequence of arbitrary characters. Thus the
old contents of the field is a match. In this example the value is not reused
in the replacement text. Thus the old contents is completely replaced by the
new one.

Usually the matching is done case insensitive. This means that any upper case
letter matches its lower counterpart and vice versa. This behavior is
controlled by the Boolean resource \rsc{rewrite.case.sensitive} which is
\rsc{on} by default. Changing this variable influences only rewrite rules
specified later.

\begin{Resources}
  \rsc{rewrite.case.sensitive} = off
\end{Resources}

A problem occurs e.g. when a string is replaced by a string containing the
original one. To avoid infinite recursion in such cases the numeric resource
\rsc{rewrite.limit} controls the number of applications of each rewrite rule.
If the number given in \rsc{rewrite.limit} is not negative and this limit is
exceeded then a warning is printed and further applications of this rule are
stopped. A negative value of the resource \rsc{rewrite.limit} indicates that
no limitation should be used.


Next we will investigate some concrete examples. Note that in these examples
the character '\texttt{\symbol{32}}' denotes a single space. It is used to
highlight places where spaces have to be used which would be hard to recognize
otherwise.

\begin{itemize}
\item Empty entries are composed of delimiters -- either double quotes or
  curly braces which enclose an arbitrary number of spaces. If we want to
  delete empty entries we can use the following two rules.

  \begin{Resources}
    \rscBraces{rewrite.rule}{\texttt{ "\symbol{"5E}\symbol{"5C}"\symbol{32}*\symbol{"5C}"\$" }}
    \rscBraces{rewrite.rule}{\texttt{ "\symbol{"5E}\symbol{"7B}\symbol{32}*\symbol{"7D}\$" }}
  \end{Resources}

  The caret '\texttt{\symbol{"5E}}' denotes the beginning of the whole string
  and the dollar is its end. The star is an operator which says that an
  arbitrary number of the preceding regular expression -- i.e.\ the space --
  can occur at this point.

\item Ranges of pages should usually be composed of numbers separated by an
  n-dash (\opt{-}). The next example shows how the pages field can be
  normalized. Spaces are deleted and a single minus sign is replaced by a
  double minus.

  \begin{Resources}
      \rscBraces{rewrite.rule}{\texttt{ pages \# "\symbol{"5C}(\symbol{"5B}0-9\symbol{"5D}+\symbol{"5C})\symbol{32}*-\symbol{32}*\symbol{"5C}(\symbol{"5B}0-9\symbol{"5D}+\symbol{"5C})" = "\symbol{"5C}1--\symbol{"5C}2" }}
  \end{Resources}

\item Field rewriting may be used to remove \LaTeX{} commands. This example
  shows how to remove from titles a \texttt{\char"5C protect} macro together with
  the braces, in case the delimiter is a double quote.

  \begin{Resources}
      \rscBraces{rewrite.rule}{\texttt{title \# "\char"5E\char"5C"\char32*\char"5C\char"5C \char32*protect\char32*\char"7B \char"5C(.*\char"5C)\char"7D\char"5C"\$" = "\symbol{"5C}"\symbol{"5C}1\char"5C"" }}
  \end{Resources}
\end{itemize}

%------------------------------------------------------------------------------
\subsection{Field Ordering}

Fields can be reordered within an entry. This feature is controlled by the
presence of a specification for the order to use. The order is specified with
the resource \rsc{sort.order}. The general form is as follows:

\begin{Resources}
  \rscBraces{sort.order}{ \textit{entry = field\(_1\) \# field\(_2\) \# ...} }
\end{Resources}

\emph{entry} is the name of an entry like \texttt{book}. The \emph{field}s are
an arbitrary number of field names like \texttt{author}. This specification
says that \emph{field1} should precede \emph{field2} etc. Fields which are not
in this list are arranged after the specified ones. The are left in the same
order as they appear in the entry.

Another possibility is to specify the entry \texttt{*}. Such a sorting order
is applicable to any kind of entry. If no specific sort order is found then
this general order is used if one has been specified.

Any sorting order is added to a list of sorting orders if it has not been
defined before. If a sorting order is specified again, the old one is simply
overwritten.

Consider the following part of a resource file:

\begin{Resources}
  \rscBraces{sort.order}{* = author \# title}
  \rscBraces{sort.order}{misc = author \# title \# howpublished \# year \# month \# note}
\end{Resources}

This means that the author field goes before the title field in any entry
type. For the misc entries additional specifications are made.

The library \file{sort\_fld.rsc} contains a sample sorting order for the
standard entry types.


\begin{Summary}
  \Desc{}{\rsc{add.field}\{field=value\}}{Add a new field to each entry.}
  \Desc{}{\rsc{delete.field}\{field\}}{Delete the named field from all
    entries.} 
  \Desc{}{\rsc{rename.field}\{old=new\}}{Rename a field.} 
  \Desc{}{\rsc{rename.field}\{old=new if field=pattern\}}{Rename a field if
    the record satisfies a certain condition.} 
  \Desc{}{\rsc{rewrite.case.sensitive}=off}{Turn off the case
    comparison during field rewriting.}
  \Desc{}{\rsc{rewrite.rule}\{fields\#pattern\#text\}}{Replace in all
    given fields the pattern by the replacement text.}
  \Desc{}{\rsc{sort.order}=\{entry=f\#\ldots\#f\}}{Specify a
    preference order for fields in a given entry.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Semantic Checks}

Semantic checks can be enabled in addition to the syntactic checks performed
during parsing.

\subsection{Finding Double Entries}

When merging several bibliographic data bases a common problem is the
occurrence of doubled entries in the resulting data base. When searching for
double entries several problems arise. Which entries should be considered
equal and what should happen to double entries.

The first question is answered as follows. Two entries are considered equal if
their sort key is identical. The condition of identical sort keys allows the
user to specify which criteria should be used when comparing entries. This can
be achieved with the resource \rsc{sort.format} (see section \ref{sorting}).

It remains the question what to do with the doubles. Usually it is not
desirable to keep double entries in one data base, so only one entry found is
kept. The others are printed as comments, i.e.\ the initial ``@'' is replaced
by ``\#\#\#''. Thus all information is still present but inactive in the
\BibTeX{} file. However, further processing with \BibTool{} will remove these
entries if \rsc{pass.comments} is \rsc{off}, which is the default.

Sometimes it is not desirable to include deleted entries in the output -- not
even as comments. In this case the default behavior can be changed with the
help of the Boolean resource \rsc{print.deleted.entries}. If this resource is
\rsc{off} then deleted entries are suppressed completely.

The prefix for deleted entries is stored in the resource
\rsc{print.deleted.prefix} which defaults to ``\#\#\#''. Thus it can be
redefined. However note that you should avoid using a string ending in an at
sign \texttt{@} since this would undo the effect of deleting an entry.

The Boolean resource \rsc{check.double.delete} can be used to delete double
entries completely. For this purpose it has to be turned off as in:

\begin{Resources}
  \rsc{check.double.delete} = on
\end{Resources}

The resource \rsc{check.double} can be used to turn on the checking of
doubles. This feature is turned off initially.

\begin{Resources}
  \rsc{check.double} = on
\end{Resources}

Checking of doubles can also be turned on with the command line option
\opt{d}: 

\sh[d]{}

\subsection{Non-unique Fields}

Double entries are identified by the sort format. Another check which can be
specified is that certain fields are unique. Examples are the reference key
or a DOI number.

The resource \rsc{unique.field} can be used to specify unique constraints for
fields. Each invocation of this resource adds another field and enables the
respective checks.

\begin{Resources}
  \rscBraces{unique.field}{\textit{field}}
\end{Resources}

The argument is the name of a field or pseudo-field. The pseudo-fields |$key|
and |$sortkey| are supported in this context. The pseudo-field |$key| contains
the reference key. The pseudo-field |$sortkey| contains the formatted sort
key. The sort key is constructed according to the contents of the resource
\rsc{sort.format} -- even if no sorting is requested. If no sort format is
specified then the value of |$sortkey| contains the |$key|.

Note that this resource produces messages only. Differing from
\rsc{check.double} the identified records are not marked or deleted.


\subsection{Regular Expression Checks}

The regular expressions (see section \ref{sec:regex}) which are used to
rewrite fields (see section \ref{sec:field.rewriting}) can also be used to
perform semantic checks on fields. For this purpose the resources
\rsc{check.rule}, \rsc{check.warning.rule}, and \rsc{check.error.rule} are
provided. The syntax of these resources is the same as for \rsc{rewrite.rule}.

\begin{Resources}
  \rscBraces{check.rule}{ \textit{field \# pattern \# message} }
  \rscBraces{check.warning.rule}{ \textit{field \# pattern \# message} }
  \rscBraces{check.error.rule}{ \textit{field \# pattern \# message} }
\end{Resources}

Again \emph{field} and \emph{message} is optional. The separator \# can also
be written as equality sign (=) or omitted.

Each field is processed as follows. Each check.rule is tried in turn until one
rule is found where \emph{field} (if given) is identical to the field name and
\emph{pattern} matches a sub-string of the field value. If such a rule is
found then the \emph{message} is written to the error stream. If no message is
given then nothing is printed and processing of the current field is ended.

\emph{message} is treated like the replacement text in \rsc{rewrite.rule},
Thus the special character combinations described in section
\ref{sec:field.rewriting} are expanded.

The variants \rsc{check.warning.rule} and \rsc{check.error.rule} contain an
additional indication as warning or error respectively.

Usually the matching is not done case sensitive. This means that any upper
case letter matches its lower counterpart and vice versa. This behavior is
controlled by the Boolean resource \rsc{check.case.sensitive} which is ON by
default. Changing this variable influences only rewrite rules as described in
section~\ref{sec:field.rewriting}.

\begin{Resources}
  \rsc{check.case.sensitive} = off
\end{Resources}

Consider the following example. We want to check that the year field contains
only years from 1800 to 2029. Additionally we want to allow two digit
abbreviations.

\begin{Resources}
  \rscBraces{check.rule}{\texttt{ year "\Hat[\BS"\symbol{"7B}]1[89][0-9][0-9][\BS"\symbol{"7D}]\$" }}
  \rscBraces{check.rule}{\texttt{ year "\Hat[\BS"\symbol{"7B}]20[0-2][0-9][\BS"\symbol{"7D}]\$" }}
  \rscBraces{check.rule}{\texttt{ year "\Hat[\BS"\symbol{"7B}][0-9][0-9][\BS"\symbol{"7D}]\$" }}
  \rscBraces{check.rule}{\texttt{ year "" "\BS@ \BS\$: Year has to be a suitable number" }}
\end{Resources}

The first rule matches any number starting with 1 followed by 8 or 9 and
finally two digits. The whole number may be enclosed in double quotes or curly
braces.\footnote{In fact the regular expression allows also strings starting
  with a quote and ending in a curly brace. But this syntactical nonsense is
  ruled out by the parser already.} The hat at the beginning and the dollar at
the end force that the pattern matches against the whole field value only.

The second rule applies for the years starting with 200, 201, or 202. The
following character is an arbitrary digit.

The next rule covers years consisting of two digits. The first three rules
produce no error message but end the search for further matches. Thus is
something suitable is found then one of the first rules finds it.

Otherwise we have to produce an error message. This is done with the third
rule. The empty pattern matches against any value of the year field. This rule
is only applied if the preceding rules do not match. In this case we print an
error message. \texttt{\BS@} is replaced by the current type and
\texttt{\BS\$} by the current key.


\begin{Summary}
  \Desc{}{\rsc{check.case.sensitive}=off}{Perform semantic checks case
    sensitive.}
  \Desc{\opt{d}}{\rsc{check.double}=on}{Find and mark or delete entries with
    identical sort keys.}
  \Desc{}{\rsc{check.double.delete}=on}{Delete double entries instead
    of deactivating them.}
  \Desc{}{\rsc{check.rule}\{field\#pattern\#msg\}}{If the value of
    field matches pattern then print the given message.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Strings -- also called Macros}\label{sec:macros}

Strings in \BibTeX{} files play an important role when managing large
bibliographic data bases. Thus the deserve special treatment. If the resource
\rsc{macro.file} is defined then the macros are written to this file. The
argument is a file name as in

\begin{Resources}
  \rscBraces{macro.file}{\textit{macro/file/name}}
\end{Resources}

Note that the reverse operation to string export namely the import of strings
does not deserve special treatment. You can simply give the macro file as one
of the input files---preferably before any input file that makes use of one of
the macros contained therein.

The Boolean resource \rsc{print.all.strings} indicates if all macros defined
in the \BibTeX{} file should be printed or only those macros actually used.

\begin{Resources}
  \rsc{print.all.strings} = on
\end{Resources}

The appearance of string names is controlled by the resource \rsc{symbol.type}
(see \pageref{symbol.type}).

Strings can be expanded when printing entries. This feature of \BibTool{} is
controlled by the resource \rsc{expand.macros} as in

\begin{Resources}
  \rsc{expand.macros} = on
\end{Resources}

The effect is that all known strings in normal entries are replaced by their
values. If the values are not defined at the time of expansion then the macro
name remains untouched. As a side effect strings concatenations are
simplified. Imagine the following \BibTeX{} file.

\begin{lstlisting}[language=BibTeX]
  @string{ WGA = " World Gnus Almanac" }

  @Book{ almanac-66,
          title =  1967 # WGA,
          month = "1~" # jan
  }
\end{lstlisting}

If \BibTool{} is applied with \rsc{expand.macros} turned on this results in
the following output -- if the default settings are used for every other
resource.
\begin{lstlisting}[language=BibTeX]
  @STRING{wga   = " World Gnus Almanac" }

  @Book{          almanac-66,
    title       = {1967 World Gnus Almanac},
    month       = {1~} # jan
  }
\end{lstlisting}
The macro \texttt{WGA} has been expanded and merged with \verb|1967|. Note
that the string \verb|jan| has not been expanded since the value should be
defined in a \BibTeX{} style file (\file{.bst}).

When macros are expanded the delimiters of entries are normalized, i.e.\ only
one style is used. In this example braces have been used. The alternative
would be to use double quotes. This behavior is controlled by the resource
\rsc{print.braces}. If this resource is on then braces are used otherwise
double quotes are taken. It can be changed like in

\begin{Resources}
  \rsc{print.braces} = off
\end{Resources}

The delimiters of the whole entry are recommended to be braces. For
compatibility with Scribe it is also allowed that parentheses are used for
those delimiters. This behavior can be achieved with the Boolean resource
\rsc{print.parentheses}. Initially this resource is off. It can be set like in
the following instruction:

\begin{Resources}
  \rsc{print.parentheses} = on
\end{Resources}


\begin{Summary}
  \Desc{\opt{m} \textit{file}}{\rsc{macro.file}=\{file\}}{Write the macro
    definitions to the file \textit{file}.}
  \Desc{}{\rsc{print.all.strings}=off}{Print only those macro definitions
    which are used instead of all.}
  \Desc{}{\rsc{expand.macros}=on}{Turn on macro (string) expansion in fields.}
  \Desc{}{\rsc{print.braces}=off}{Switch to the use of quotes for expanded
    macros instead of braces.}
  \Desc{}{\rsc{print.parentheses}=on}{Enclose the whole entry in parentheses
    instead of braces.}
\end{Summary}


%------------------------------------------------------------------------------
\section{Statistics}

Some information can be obtained at the end of a \BibTool{} run. The number of
\BibTeX{} items read and written is printed. To enable this feature the
resources \rsc{count.all} and \rsc{count.used} are provided.

\begin{Resources}
  \rsc{count.all} = on
\end{Resources}

\rsc{count.all} indicates that all known types of \BibTeX{} items should be
listed.

\begin{Resources}
  \rsc{count.used} = on
\end{Resources}

\rsc{count.used} forces only those types of \BibTeX{} items to be listed which
have been found in the input files.


\begin{Summary}
  \Desc{\opt{\#}}{\rsc{count.all}=on}{Print statistics about all known entry
    types.}
  \Desc{\opt{@}}{\rsc{count.used}=on}{Print statistics about the used entry
    types only.}
\end{Summary}

%------------------------------------------------------------------------------
\section{\BibTeX1.0 Support}

\BibTool\ supports already some of the feature proposed for \BibTeX1.0.

%------------------------------------------------------------------------------
\subsection{Including Bibliographies}

The bibliography file may contain an instruction of the following form:

\begin{lstlisting}[language=BibTeX]
  @include{abc.bib}
\end{lstlisting}

Such an entry is stored in the database and printed when requested.
Nevertheless the resource  \rsc{apply.include} can be used to control this
behavior. 

%------------------------------------------------------------------------------
\subsection{Aliases}

The bibliography file may contain an instruction of the following form:

\begin{lstlisting}[language=BibTeX]
  @alias{abc=def}
\end{lstlisting}

This means that the key \texttt{abc} is treated as an alias for the key
\texttt{def}. Usually this alias is stored as alias in the database. For old
\BibTeX\ files it may be desirable to eliminate aliases and introduce copies
of records instead. Nevertheless the resource \rsc{apply.alias} can be used to
control this behavior.

%------------------------------------------------------------------------------
\subsection{Modifications}

The bibliography file may contain an instruction of the following form:

\begin{lstlisting}[language=BibTeX]
  @modify{key,
    abc = {def}
  }
\end{lstlisting}

This modification is stored in the database without being applied.
Nevertheless the resource \rsc{apply.modify} can be used to control this
behavior.


\begin{Summary}
  \Desc{}{\rsc{apply.alias}=on}{Expand the aliased entries in the database.}
  \Desc{}{\rsc{apply.include}=on}{Include the entries contained in the
    bibliography file given in \texttt{@include}.}
  \Desc{}{\rsc{apply.modify}=on}{apply the modifies in the database.}
\end{Summary}


%------------------------------------------------------------------------------
%------------------------------------------------------------------------------
\chapter{Limitations}

\section{Limits of \BibTool}

\BibTool{} has been written with dynamic memory management wherever possible.
Thus \BibTool{} should be limited by the memory available only. Especially the
limitation on the field length which is present in \BibTeX\,0.99 is not
present in \BibTool.

\BibTeX{} needs a special order when cross-referenced entries are used. This
limitation has also been released in \BibTool.


\section{Bugs and Problems}

Problems currently known are the following ones. They are not considered to be
bugs.
\begin{itemize}
\item The referencing feature of \BibTeX{} is not supported. \verb|\cite|
  macros can be contained in fields (e.g. notes). Such things can be confused.
\item The memory management uses dynamic memory. This memory is reused but not
  returned to the operating system. Thus \BibTool{} may run out of memory even
  if a more elaborated memory management may find free memory. This is a
  design decision and I don't think that I will change it.
\item The \TeX{} reading apparatus is only imitated to a certain limit. But
  this should be enough for most applications to produce satisfactory results.
\item In several modules ASCII encoding is assumed. I do not know to which
  extend this influences the functionality since I don't have access to
  non-ASCII machines.
\item Macro expansion uses a dynamic array which can turn out to be too
  short. This will be corrected as soon as I have an example where this bug
  shows up. 
\end{itemize}

The distribution of \BibTool{} also contains a file named \file{ToDo}. If you
are interested in more detailed descriptions of possible problems,
limitations, and ideas for improvements in further releases then you can have
a look at the contents of this file.

%------------------------------------------------------------------------------
%------------------------------------------------------------------------------
\chapter{Sample Resource Files}\label{chap:resource.files}

Sample resource files are included in the distribution of \BibTool{} in the
directory \file{lib}. Only some of them are reproduced in this section.

\section{The Default Settings}

The following list shows the defaults for all resource instructions.

\begin{lstlisting}[language=BibTool]
apply.alias              = off
apply.include            = off
apply.modify             = off
bibtex.env.name          = "BIBINPUTS"
check.case.sensitive     = on
check.double             = off
check.double.delete      = off
count.all                = off
count.used               = off
crossref.limit           = 32
default.key              = "**key*"
dir.file.separator       = "/"
env.separator            = ":"
expand.macros            = on
fmt.et.al                = ".ea"
fmt.inter.name           = "-"
fmt.name.name            = "."
fmt.name.pre             = "."
fmt.name.title           = ":"
fmt.title.title          = "-"
ignored.word             = "{a}"
ignored.word             = "{a}n"
ignored.word             = "the"
ignored.word             = "le"
ignored.word             = "les"
ignored.word             = "la"
ignored.word             = "{}un"
ignored.word             = "{}une"
ignored.word             = "{}el"
ignored.word             = "{}il"
ignored.word             = "der"
ignored.word             = "die"
ignored.word             = "das"
ignored.word             = "{}ein"
ignored.word             = "{}eine"
key.base                 = lower
key.expand.macros        = on
key.format               = short
key.generation           = off
key.make.alias           = off
key.number.separator     = "*"
new.entry.type           = "{}Article"    
new.entry.type           = "Book" 
new.entry.type           = "Booklet"
new.entry.type           = "Conference"
new.entry.type           = "{}InBook"     
new.entry.type           = "{}InCollection"
new.entry.type           = "{}InProceedings"
new.entry.type           = "Manual"       
new.entry.type           = "MastersThesis"
new.entry.type           = "Misc" 
new.entry.type           = "PhDThesis"
new.entry.type           = "Proceedings"
new.entry.type           = "TechReport"
new.entry.type           = "{}Unpublished"
preserve.keys            = off
preserve.key.case        = off
print.align              = 18
print.align.string       = 18
print.align.preamble     = 11
print.align.comment      = 10
print.align.key          = 18
print.braces             = on
print.comma.at.end       = on
print.all.strings        = on
print.deleted.prefix     = "\#\#\#"
print.deleted.entries    = on
print.entry.types        = "pisnmac"
print.equal.right        = on
print.indent             = 2
print.line.length        = 77
print.newline            = 1
print.parentheses        = off
print.terminal.comma     = off
print.use.tab            = on
print.wide.equal         = off
rewrite.case.sensitive   = on
rewrite.limit            = 512
quiet                    = off
select.case.sensitive    = off
select.crossrefs	 = off
select.fields            = "\$key"
sort                     = off
sort.cased               = off
sort.format              = "\%s(\$key)"\index{s@\%s}
sort.macros              = on
sort.reverse             = off
suppress.initial.newline = off
symbol.type              = lower
verbose                  = off
\end{lstlisting}

\section{\bibLaTeX\ Support}\label{lib:biblatex}

The resource file \verb|biblatex| contains various definitions for \bibLaTeX.

Entry types for \bibLaTeX{}

\begin{lstlisting}[language=BibTool]
new.entry.type{Article}
new.entry.type{Book}
new.entry.type{MVBook}
new.entry.type{InBook}
new.entry.type{BookInBook}
new.entry.type{SuppBook}
new.entry.type{Booklet}
new.entry.type{Collection}
new.entry.type{MVCollection}
new.entry.type{InCollection}
new.entry.type{SuppCollection}
new.entry.type{Manual}
new.entry.type{Misc}
new.entry.type{Online}
new.entry.type{Patent}
new.entry.type{Periodical}
new.entry.type{SuppPeriodical}
new.entry.type{Proceedings}
new.entry.type{MVProceedings}
new.entry.type{Reference}
new.entry.type{MVReference}
new.entry.type{Inreference}
new.entry.type{Report}
new.entry.type{Set}
new.entry.type{Thesis}
new.entry.type{Unpublished}
new.entry.type{Cdata}
new.entry.type{CustomA}
new.entry.type{CustomB}
new.entry.type{CustomC}
new.entry.type{CustomD}
new.entry.type{CustomE}
new.entry.type{CustomF}
new.entry.type{Conference}
new.entry.type{Electronic}
new.entry.type{MasterThesis}
new.entry.type{PhdThesis}
new.entry.type{TechReport}
new.entry.type{WWW}
new.entry.type{Artwork}
new.entry.type{Audio}
new.entry.type{BibNote}
new.entry.type{Commentary}
new.entry.type{Image}
new.entry.type{Jurisdiction}
new.entry.type{Legislation}
new.entry.type{Legal}
new.entry.type{Letter}
new.entry.type{Movie}
new.entry.type{Music}
new.entry.type{Performance}
new.entry.type{Review}
new.entry.type{Software}
new.entry.type{Standard}
new.entry.type{Video}
new.entry.type{XData}
\end{lstlisting}

Field capitalization for \bibLaTeX{}

\begin{lstlisting}[language=BibTool]
% special fields
new.field.type { entryset        = EntrySet        }
new.field.type { entrysubtype    = EntrySubtype    }
new.field.type { execute         = Execute         }
new.field.type { hyphenation     = Hyphenation     }
new.field.type { keywords        = Keywords        }
new.field.type { label           = Label           }
new.field.type { options         = Options         }
new.field.type { presort         = Presort         }
new.field.type { shorthand       = Shorthand       }
new.field.type { sortkey         = SortKey         }
new.field.type { sortname        = SortName        }
new.field.type { sorttitle       = SortTitle       }
new.field.type { sortyear        = SortYear        }
new.field.type { crossref        = CrossRef        }
new.field.type { xdata           = XData           }
new.field.type { xref            = XRef            }
% data fields
new.field.type { abstract        = Abstract        }
new.field.type { addendum        = Addendum        }
new.field.type { address         = Address         }
new.field.type { afterword       = Afterword       }
new.field.type { annotation      = Annotation      }
new.field.type { annote          = Annote          }
new.field.type { annotator       = Annotator       }
new.field.type { author          = Author          }
new.field.type { authortype      = AuthorType      }
new.field.type { bookauthor      = BookAuthor      }
new.field.type { booksubtitle    = BookSubtitle    }
new.field.type { booktitle       = BookTitle       }
new.field.type { booktitleaddon  = BookTitleAddOn  }
new.field.type { chapter         = Chapter         }
new.field.type { commentator     = Commentator     }
new.field.type { date            = Date            }
new.field.type { doi             = DOI             }
new.field.type { edition         = Edition         }
new.field.type { editor          = Editor          }
new.field.type { editora         = EditorA         }
new.field.type { editorb         = EditorB         }
new.field.type { editorc         = EditorC         }
new.field.type { editortype      = EditorType      }
new.field.type { editoratype     = EditorAType     }
new.field.type { editorbtype     = EditorBType     }
new.field.type { editorctype     = EditorCType     }
new.field.type { eid             = EID             }
new.field.type { eprint          = EPrint          }
new.field.type { eprintclass     = EPrintClass     }
new.field.type { eprinttype      = EPrintType      }
new.field.type { eventdate       = EventDate       }
new.field.type { eventtitle      = EventTitle      }
new.field.type { file            = File            }
new.field.type { foreword        = Foreword        }
new.field.type { gender          = Gender          }
new.field.type { howpublished    = HowPublished    }
new.field.type { indexsorttitle  = IndexSortTitle  }
new.field.type { indextitle      = IndexTitle      }
new.field.type { institution     = Institution     }
new.field.type { introduction    = Introduction    }
new.field.type { isan            = ISAN            }
new.field.type { isbn            = ISBN            }
new.field.type { ismn            = ISMN            }
new.field.type { isrn            = ISRN            }
new.field.type { issn            = ISSN            }
new.field.type { issue           = Issue           }
new.field.type { issuetitle      = IssueTitle      }
new.field.type { issuesubtitle   = IssueSubtitle   }
new.field.type { iswc            = ISWC            }
new.field.type { journal         = Journal         }
new.field.type { journaltitle    = JournalTitle    }
new.field.type { journalsubtitle = JournalSubtitle }
new.field.type { language        = Language        }
new.field.type { library         = Library         }
new.field.type { location        = Location        }
new.field.type { bookpagination  = BookPagination  }
new.field.type { mainsubtitle    = MainSubtitle    }
new.field.type { maintitle       = MainTitle       }
new.field.type { maintitleaddon  = MainTitleAddOn  }
new.field.type { month           = Month           }
new.field.type { nameaddon       = NameAddOn       }
new.field.type { note            = Note            }
new.field.type { number          = Number          }
new.field.type { organization    = Organization    }
new.field.type { origlanguage    = OrigLanguage    }
new.field.type { origlocation    = OrigLocation    }
new.field.type { origpublisher   = OrigPublisher   }
new.field.type { origtitle       = OrigTitle       }
new.field.type { origdate        = OrigDate        }
new.field.type { pages           = Pages           }
new.field.type { pagetotal       = PageTotal       }
new.field.type { pagination      = Pagination      }
new.field.type { part            = Part            }
new.field.type { pdf             = PDF             }
new.field.type { pubstate        = PubState        }
new.field.type { reprinttitle    = ReprintTitle    }
new.field.type { holder          = Holder          }
new.field.type { publisher       = Publisher       }
new.field.type { school          = School          }
new.field.type { series          = Series          }
new.field.type { shortauthor     = ShortAuthor     }
new.field.type { shorteditor     = ShortEditor     }
new.field.type { shorthandintro  = ShorthandIntro  }
new.field.type { shortjournal    = ShortJournal    }
new.field.type { shortseries     = ShortSeries     }
new.field.type { shorttitle      = ShortTitle      }
new.field.type { subtitle        = Subtitle        }
new.field.type { title           = Title           }
new.field.type { titleaddon      = TitleAddOn      }
new.field.type { translator      = Translator      }
new.field.type { type            = Type            }
new.field.type { url             = URL             }
new.field.type { urldate         = URLDate         }
new.field.type { venue           = Venue           }
new.field.type { version         = Version         }
new.field.type { volume          = Volume          }
new.field.type { volumes         = Volumes         }
new.field.type { year            = Year            }
% aliases
new.field.type { archiveprefix	 =  ArchivePrefix  }
new.field.type { primaryclass	 =  PrimaryClass   }
% custom fields
new.field.type { namea		 =  NameA	   }
new.field.type { nameb		 =  NameB	   }
new.field.type { namec		 =  NameC	   }
new.field.type { nameatype	 =  NameAType	   }
new.field.type { namebtype	 =  NameBType	   }
new.field.type { namectype	 =  NameCType	   }
new.field.type { lista		 =  ListA	   }
new.field.type { listb		 =  ListB	   }
new.field.type { listc		 =  ListC	   }
new.field.type { listd		 =  ListD	   }
new.field.type { liste		 =  ListE	   }
new.field.type { listf		 =  ListF	   }
new.field.type { usera		 =  UserA	   }
new.field.type { userb		 =  UserB	   }
new.field.type { userc		 =  UserC	   }
new.field.type { userd		 =  UserD	   }
new.field.type { usere		 =  UserE	   }
new.field.type { userf		 =  UserF	   }
new.field.type { verba		 =  VerbA	   }
new.field.type { verbb		 =  VerbB	   }
new.field.type { verbc		 =  VerbC	   }
\end{lstlisting}

Cross-reference mappings for \bibLaTeX{}

\begin{lstlisting}[language=BibTool]
crossref.map {{inbook bookinbook suppbook}  bookauthor = 
	      {mvbook book} author
}
crossref.map {{book inbook bookinbook suppbook}  maintitle = 
	      mvbook title
}
crossref.map {{book inbook bookinbook suppbook}  mainsubtitle = 
	      mvbook subtitle
}
crossref.map {{book inbook bookinbook suppbook}  maintitleaddon = 
	      mvbook titleaddon
}
crossref.map {{collection reference incollection inreference suppollection}
	      maintitle = 
	      {mvcollection mvreference} title
}
crossref.map {{collection reference incollection inreference suppollection}
	      mainsubtitle = 
	      {mvcollection mvreference} subtitle
}
crossref.map {{collection reference incollection inreference suppollection}
	      maintitleaddon = 
	      {mvcollection mvreference} titleaddon
}
crossref.map {{proceedings inproceedings}
	      maintitle = 
	      mvproceedings title
}
crossref.map {{proceedings inproceedings}
	      mainsubtitle = 
	      mvproceedings subtitle
}
crossref.map {{proceedings inproceedings}
	      maintitleaddon = 
	      mvproceedings titleaddon
}
crossref.map {{inbook bookinbook suppbook}
	      booktitle = 
	      book title
}
crossref.map {{inbook bookinbook suppbook}
	      booksubtitle = 
	      book subtitle
}
crossref.map {{inbook bookinbook suppbook}
	      booktitleaddon = 
	      book titleaddon
}
crossref.map {{incollection inreference suppollection}
	      booktitle = 
	      {collection reference} title
}
crossref.map {{incollection inreference suppollection}
	      booksubtitle = 
	      {collection reference} subtitle
}
crossref.map {{incollection inreference suppollection}
	      booktitleaddon = 
	      {collection reference} titleaddon
}
crossref.map {inproceedings  booktitle = 
	      proceedings title
}
crossref.map {inproceedings  booksubtitle = 
	      proceedings subtitle
}
crossref.map {inproceedings  booktitleaddon = 
	      proceedings titleaddon
}

crossref.map {{article subperiodical}  journaltitle = 
	      periodical} title
}
crossref.map {{article subperiodical}  journalsubtitle = 
	      periodical subtitle
}
\end{lstlisting}

\section{Useful Translations}

The resource file \verb|tex_def| translates international characters into
plain text representations. Especially the German umlaut sequences are
translated. For instance the letter {\"A} which is written as \verb|{\"A}| in
a \BibTeX{} file is translated to \verb|Ae|.\footnote{Note that the short
  notation of \texttt{german.sty} or \texttt{babel} is not understood by
  \BibTeX{} nor by \BibTool. }

Additionally some logos are defined.
\begin{lstlisting}[language=BibTool]
tex.define {\"[1]=#1e}
tex.define {\ss=ss}
tex.define {\AE=AE}
tex.define {\OE=OE}
tex.define {\aa=aa}
tex.define {\AA=AA}
tex.define {\o=o}
tex.define {\O=O}
tex.define {\l=l}
tex.define {\L=L}
tex.define {\i=i}
tex.define {\j=j}
tex.define {\TeX=TeX}
tex.define {\LaTeX=LaTeX}
tex.define {\LaTeXe=LaTeX2e}
tex.define {\BibTeX=BibTeX}
tex.define {\AMSTeX=AMSTeX}
\end{lstlisting}


\section{Other Resource Files}

The distribution contains additional resource files. Some of them are sketched
here. Others may be contained in the distribution as well. Look into the
appropriate directory.

\begin{description}
\item [\file{iso2tex}]\ \\
  define rewrite rules to translate ISO 8859-1 characters into \BibTeX\ 
  compatible sequences.
\item [\file{iso\_def}]\ \\
  define macro equivalents for ISO 8859-1 characters into \TeX{} compatible
  sequences.
\item [\file{sort\_fld}]\ \\
  defines a sort order for the common \BibTeX\ entry types.
\item [\file{check\_y}]\ \\
  contains a sample for semantic checks. The year field is checked to be a
  suitable number.
\item [\file{month}]\ \\
  tries to introduce \BibTeX\ strings for month names.  Provisions are made to
  preserve other information contained in the month field.
\item [\file{opt}]\ \\
  copes with \texttt{OPT} prefixes as introduced e.g. by bibtex-mode.
\item [\file{braces}]\ \\
  tries to replace double quotes as field delimiters by braces.
\item [\file{keep\_bibtex}]\ \\
  defines the entry types and attributes according to the standard \BibTeX\
  styles to be kept. Any undeclared attribute will be deleted.
\item [\file{keep\_biblatex}]\ \\
  defines the entry types and attributes according to the standard \bibLaTeX\
  styles to be kept. Any undeclared attribute will be deleted.
\end{description}


%------------------------------------------------------------------------------
\bibliographystyle{alpha}
\bibliography{bibtool}

\ifHTML\else
\ifx\ptt\undefined\global\let\ptt\ttfamily\fi
\ifx\psf\undefined\global\let\psf\sffamily\fi
\ifx\pdollar\undefined\global\let\pdollar\$\fi
\fi
\printindex

\end{document} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Local Variables:
% mode: latex
% TeX-master: nil
% fill-column: 78
% End: