
\Header{bibtool/bibtool.h}{bibtoolbibtool.h}

This header file contains includes for all other header files
belonging to the \BibTool{} C library. It is here for the
convenience of the C programmer who doen not have to include
two dozen header files but can use this single file. Thus any
C program which utilizes the \BibTool{} C library can start as
follows:

\verb|#include <bibtool/bibtool.h>|

Note that this include file also contains includes to system
specific header files.


\Header{bibtool/database.h}{bibtooldatabase.h}

This header file contains functions which deal with databases. 

This header file provides also access to the functions and
variables defined in |database.c|. Consult the documentation
of this file for details.

This header file automatically includes |<stdio.h>| and
|record.h| aswell.

\begin{Typedef}{\Type{DB}}{DB}
  This is a pointer type referencing a \BibTeX{}
  database.  It contains all information which
  characterizes a database.
  
  The members of this record should not be used
  explicitly.  Instead the macros should be used which
  are provided to accss this data type.
  
  \STRUCT{}
    Record \ 	&\Member{db\_normal};	& List of normal records.\\
    Record \ 	&\Member{db\_string};	& List of local macros.  \\
    Record \ 	&\Member{db\_preamble};	& List of additional     
			\TeX{} code.          \\
    Record \ 	&\Member{db\_comment};	& List of trailing       
			comments which are    
			not attached to	     
			records.              \\
    Record \ 	&\Member{db\_modify};	& List of modification   
			rules.                \\
    Record \ 	&\Member{db\_include};	& List of included files.\\
    Record \ 	&\Member{db\_alias};	& List of aliases.       
  \EndSTRUCT{\Type{sDB}, \Type{*DB}}
\end{Typedef}
\begin{Constant}{DB \Mac{NoDB}}{NoDB}
  This is an invalid database. In fact it is |NULL| of
  the type |DB|.
\end{Constant}
\begin{Macro}{Record \Mac{DBnormal}}{DBnormal}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the normal
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBstring}}{DBstring}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the string
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBpreamble}}{DBpreamble}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the preamble
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBcomment}}{DBcomment}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the comment
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBalias}}{DBalias}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the alias
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBmodify}}{DBmodify}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the modify
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Record \Mac{DBinclude}}{DBinclude}
  \begin{Arguments}
    & \Var{DB} & The database to consider.\\
  \end{Arguments}%
  This is the functional representation of the include
  component of a database. It can be used to extract
  this information. It can also be used as a lvalue.
\end{Macro}

\Module{database.c}{database.c}

This module contains functions which deal with databases.
Databases are stored in an abstract datatype |DB| which is defined
in |database.h|. Methods are provided to query and modify a database.

\begin{Function}{void \Fct{db\_add\_record}}{add\_db\_record}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to insert the record into.\\
    Record \ 	&\Var{rec};	&Record to add to the database.
  \end{Arguments}%
  Add a record to a database.
  The record can be any kind of record. It is added to the
  appropriate category.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int *\Fct{db\_count}}{db\_count}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to count.\\
    int *\ 	&\Var{lp};	&pointer to an integer for the length.
  \end{Arguments}%
  Count all entries in a database. This includes normal
  aswell as special records. The result is stored in a
  static array which is reused by |db_count()|. A
  pointer to this array is returned. The indices
  correspond to the entry types defined with
  |add_entry_type()| or declared as symbolic constants
  in |entry.h|. 
  
  The end of the array is marked by an element
  containing a negative number. In addition the argument
  |lp| can point to an integer where the number of valid
  elements is stored. If |lp| is |NULL| this step is
  omitted. 
  \begin{Result}
    Static array containing the statistics.
  \end{Result}
\end{Function}
\begin{Function}{Record \Fct{db\_find}}{db\_find}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to search in.\\
    char *\ 	&\Var{key};	&
  \end{Arguments}%
  Search the database for a record with a given key.
  If |RecordOldKey| is set for the record then use this value.
  Otherwise use |*Heap|. |*Heap| contains the reference
  key of normal records.
  
  Deleted records are ignored. An arbitrary matching
  record is returned. Thus if more than one record have
  the same key then the behaviour is nondeterministic. 
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{db\_forall}}{db\_forall}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing |rec|.\\
    int (*\ 	&\Var{fct})(DB,Record); 	&Boolean valued function determining the end of the
processing. It takes two arguments a |DB| and a |Record|.
  \end{Arguments}%
  Visit all normal records in the data base and apply the given
  function |fct| to each.
  if this function returns |TRUE| then no more records need to
  be visited.
  No special order can be assumed in which the records are seen.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{db\_mac\_sort}}{db\_mac\_sort}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to sort.
  \end{Arguments}%
  Sort the macros of a database. The sorting uses
  increasing lexicographic order according to the
  character codes of the macro names. Note that this
  might lead to different results on machines with
  different character encodings, e.g.\ ASCII vs.\ EBCDIC.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{db\_new\_key}}{db\_new\_key}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to search in.\\
    char *\ 	&\Var{key};	&Key to find.
  \end{Arguments}%
  Search the database for a record with a given old key and
  return the new one.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{db\_rewind}}{db\_rewind}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to rewind.
  \end{Arguments}%
  Rewind the normal records of a database to point to the first
  record if at least one records exists. Otherwise nothing is
  done.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{db\_sort}}{db\_sort}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to sort.\\
    int (*\ 	&\Var{less})(Record,Record); 	&Comparison function to use. This boolean function
takes two records and returns |TRUE| iff the first one
is less than the second one.
  \end{Arguments}%
  Sort the normal records of a database. As a side effect the
  records are kept in sorted order in the database.
  The sorting order can be determined by the argument |less|
  which is called to compare two records.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{db\_string}}{db\_string}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database\\
    char *\ 	&\Var{s};	&Name of the \BibTeX{} macro to expand.\\
    int \ 	&\Var{localp};	&Boolean determining whether the search is only local to the db.
  \end{Arguments}%
  Try to find the definition of a macro.
  First, the local values in the database |db| are considered.
  If this fails and |localp| is |FALSE| then the global list
  is searched aswell. If all fails |NULL| is returned.
  \begin{Result}
    The macro expansion or |NULL| upon failure.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{delete\_record}}{delete\_record}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing |rec|.\\
    Record \ 	&\Var{rec};	&Record to delete.
  \end{Arguments}%
  Delete a record from a database.
  It is not checked, that the record really is part of the
  database. The record is just unlinked from its
  list. Just in case the record should be the first one
  the database record is modified.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_db}}{free\_db}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to release.
  \end{Arguments}%
  Deallocate the memory occupied by a database.
  Note that any references to this database becomes invalid.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{DB \Fct{new\_db}}{new\_db}  Create a new database and initialize it to contain no
  information.
  If no memory is left then an error is raised and the program
  is terminated.
  \begin{Result}
    The new database.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{print\_db}}{print\_db}
  \begin{Arguments}
    FILE *\ 	&\Var{file};	&The file handle for printing.\\
    DB \ 	&\Var{db};	&The database to print\\
    char *\ 	&\Var{spec};	&String containing the specification of the parts to print.
  \end{Arguments}%
  Print a database to a file in a way which is readable by
  \BibTeX. The spec determines which parts should be
  printed and the order of this parts. The spec is
  processed from left to right. Each unknown character
  is silently ignored. The following characters
  correspond to parts of the database:
  \begin{description}
  \item [p] The preamble.
  \item [\$] All strings (macros) contained in the database.
  \item [S] The strings (macros) which are used in the
  database.
  \item [s] The strings (macros) contained in the database
  where the resource print.all.strings determines
  whether all strings should be printed or the used
  strings only. 
  \item [n] The normal records.
  \item [c] The comments.
  \item [i] The includes.
  \item [a] The aliases.
  \item [m] The modifies.
  \end{description}
  Uppercase letters which are not mentioned are silently folded
  to their lowercase counterparts. 
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{read\_db}}{read\_db}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to augment.\\
    char *\ 	&\Var{file};	&File name to read from.\\
    int (*\ 	&\Var{fct})(DB,Record); 	&Function to determine whether to store a given record.\\
    int \ 	&\Var{verbose};	&Boolean to determine whether progress should be reported.
  \end{Arguments}%
  Read records from a file and add them to a database.
  A function has to be given as one argument. This function is
  called for each record. If this function returns |TRUE| then
  the record is added to the database. Otherwise the record is
  discarted. 
  
  The progress of reading is reported to |stderr| if the
  boolean argument |verbose| is |TRUE|.
  \begin{Result}
    1 if the file can not be opened. 0 otherwise.
  \end{Result}
\end{Function}

\Header{bibtool/entry.h}{bibtoolentry.h}



This module provides also access to the functions and
variables defined in |entry.c|. Consult also the documentation
of this file for details.

This header file automatically includes |symbols.h|.

\begin{Variable}{char ** \Mac{entry\_type}}{entrytype}
  This is an array of strings which represent entry
  types. They are either built-in or user defined. Use
  the function |def_entry_type()| to allocate a new
  entry type and the function |get_entry_type()| to find
  a certain entry type.
\end{Variable}
\begin{Macro}{char * \Mac{EntryName}}{EntryName}
  \begin{Arguments}
    & \Var{Entry} & Index of the entry.\\
  \end{Arguments}%
  This is the functional representation of the name
  component for an entry type. The argument is the index
  of an entry type. This macro can also be used as
  lvalue. No range checks are performed. 
\end{Macro}
\begin{Constant}{int \Mac{BIB\_EOF}}{BIBEOF}
  This symbolic constant is returned when a record has
  to be read and the end of file has been
  encountered. It is some negative value for which no
  entry type is defined.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_NOOP}}{BIBNOOP}
  This symbolic constant is returned when a record has
  to be read and something has been encountered which
  should be ignored. It is some negative value for which no
  entry type is defined.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_STRING}}{BIBSTRING}
  This symbolic constant representing a record type of a
  \BibTeX{} macro (|@String|). This is a special record
  type which is provided automatically.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_PREAMBLE}}{BIBPREAMBLE}
  This symbolic constant representing a record type of a
  \BibTeX{} preamble (|@Preamble|). This is a special record
  type which is provided automatically.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_COMMENT}}{BIBCOMMENT}
  This symbolic constant representing a record type of a
  \BibTeX{} comment (|@Comment|). This is a special record
  type which is provided automatically.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_ALIAS}}{BIBALIAS}
  This symbolic constant representing a record type of a
  \BibTeX{} alias (|@Alias|) which is proposed for
  \BibTeX\,1.0. This is a special record type which is
  provided automatically.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_MODIFY}}{BIBMODIFY}
  This symbolic constant representing a record type of a
  \BibTeX{} modification rule (|@Modify|) which is proposed for
  \BibTeX\,1.0. This is a special record type which is
  provided automatically.
\end{Constant}
\begin{Constant}{int \Mac{BIB\_INCLUDE}}{BIBINCLUDE}
  This symbolic constant representing a record type of a
  \BibTeX{} inclusion instruction (|@Include|) which is
  proposed for \BibTeX\,1.0. This is a special record
  type which is provided automatically
\end{Constant}
\begin{Macro}{\Mac{IsSpecialRecord}}{IsSpecialRecord}
  \begin{Arguments}
    & \Var{Type} & Record type which should be checked.\\
  \end{Arguments}%
  Test whether a given record type denotes a special record.
  Special records are those defined above. They are
  provided automatically since \BibTeX{} is supposed to
  do so as well.
  \begin{Result}
    |TRUE| iff the rcord type denoted a special record.
  \end{Result}
\end{Macro}
\begin{Macro}{\Mac{IsNormalRecord}}{IsNormalRecord}
  \begin{Arguments}
    & \Var{Type} & Record type which should be checked.\\
  \end{Arguments}%
  Test whether a given record is a normal record. A
  normal record is one defined by a user. Normal records
  have indices larger than those of special records.
  \begin{Result}
    |TRUE| iff the rcord type denoted a normal record.
  \end{Result}
\end{Macro}

\Module{entry.c}{entry.c}

This module contains functions which deal with entry types. 
Right from the beginning only the special record types are
known. Those special record types are |@Comment|, |@Preamble|,
|@String|, |@Include|, |@Modify|, and |@Alias|.

In addition to those special records the user can define
additional record types which are denoted as ``normal''. E.g.\
usually |@Article| and |@Book| are defined which are
``normal'' record types.

The record types are are managed in this module. In the other
modules only numerical representations are used. This module
provides means to map those numerical ids to the string
representation and back. It is also possible to define
additional record types.

Part of this module is likely to be integrated into databases.
\begin{Function}{void \Fct{def\_entry\_type}}{def\_entry\_type}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String containing the name of the entry.
  \end{Arguments}%
  Dynamically define an entry type. If the entry type
  already exists then a new printing representation is
  stored. 
  
  If no memory is left then an error is raised and the
  program is termined
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{find\_entry\_type}}{find\_entry\_type}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String of the potential entry name.
  \end{Arguments}%
  Look up an entry type in the array of defined entries.
  \begin{Result}
    The index in the array or |NOOP|.
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{get\_entry\_type}}{get\_entry\_type}
  \begin{Arguments}
    int \ 	&\Var{idx};	&Index of entry type.
  \end{Arguments}%
  Get the printable string representation corresponding
  to the numerical entry type given as argument. If no
  entry type is defined for the given index then |NULL|
  is returned.
  \begin{Result}
    Print representation of the entry type or |NULL|.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{init\_entries}}{init\_entries}  Predefine some entry types which are stored at startup time
  in an array. The following entry types are predefined
  because they are considered special by \BibTeX:
  \begin{description}
  \item [BIB\_STRING] denotes a \BibTeX{} macro definition.
  \item [BIB\_PREAMBLE] denotes a preamble item which goes
  before the bibligraphy environment.  
  \item [BIB\_COMMENT] denotes a comment entry which is
  passed to the output file.
  \item [BIB\_ALIAS] denotes an alias entry which renames an
  existing entry.
  \item [BIB\_MODIFY] denotes a modification request which
  alters an existing entry.
  \item [BIB\_INCLUDE] denotes an include request which reads
  in another \BibTeX{} file.
  \end{description}
  Note that this function is for internal purposes
  only. The normal user should call |init_bibtool()|
  instead.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/error.h}{bibtoolerror.h}

This header file provides means for issuing error
messages. Most of the macros provided in this header file are
based on the function |error()| described in |error.c|.
Nevertheless this function covers the general cases the macros
in this header file are more convenient since they hide the
unneccesary arguments of the |error()| function providing
appropriate values.

This header file makes availlable the function |error()| as
defined in |error.c|.

\begin{Constant}{int \Mac{ERR\_ERROR}}{ERRERROR}
  Error type: Indicate that the error can not be
  suppressed and the messaged is marked as error.
\end{Constant}
\begin{Constant}{int \Mac{ERR\_WARNING}}{ERRWARNING}
  Error type: Indicate that the error is in fact a
  warning which can be suppressed. The messaged is
  marked as warning. This flag is only in effect if the
  |ERR_ERROR| flag is not set.
\end{Constant}
\begin{Constant}{int \Mac{ERR\_POINT}}{ERRPOINT}
  Error type: Indicate that the line and the error
  pointer should be displayed (if not suppressed via
  other flags).
\end{Constant}
\begin{Constant}{int \Mac{ERR\_FILE}}{ERRFILE}
  Error type: Indicate that the file name and line
  number should be displayed (if not suppressed via
  other flags).
\end{Constant}
\begin{Constant}{int \Mac{ERR\_EXIT}}{ERREXIT}
  Error type: Indicate that the |error()| function
  should be terminated by |exit()| instead of
  returning.
\end{Constant}
\begin{Macro}{void \Mac{ERROR\_EXIT}}{ERROREXIT}
  \begin{Arguments}
    & \Var{X} & Error message.\\
  \end{Arguments}%
  Raise an error, print the single string argument as
  error message and terminate the program with |exit()|.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{OUT\_OF\_MEMORY}}{OUTOFMEMORY}
  \begin{Arguments}
    & \Var{X} & String denoting the type of unallocatable memory.\\
  \end{Arguments}%
  Raise an error because |malloc()| or |realloc()|
  failed. The argument denoted the type of memory for
  which the allocation failed. The program is
  terminated.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ERROR}}{ERROR}
  \begin{Arguments}
    & \Var{X} & Error message.\\
  \end{Arguments}%
  Raise an error. Print the argument as error message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ERROR2}}{ERROR2}
  \begin{Arguments}
    & \Var{X} & First error message.\\
    & \Var{Y} & Continuation of the error message.\\
  \end{Arguments}%
  Raise an error. Print the two arguments as error message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ERROR3}}{ERROR3}
  \begin{Arguments}
    & \Var{X} & First error message.\\
    & \Var{Y} & Continuation of the error message.\\
    & \Var{Z} & Second continuation of the error message.\\
  \end{Arguments}%
  Raise an error. Print the three arguments as error message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{WARNING}}{WARNING}
  \begin{Arguments}
    & \Var{X} & Warning message.\\
  \end{Arguments}%
  Raise a warning. Print the argument as warning message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{WARNING2}}{WARNING2}
  \begin{Arguments}
    & \Var{X} & First warning message.\\
    & \Var{Y} & Continuation of warning message.\\
  \end{Arguments}%
  Raise a warning. Print the two arguments as warning message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{WARNING3}}{WARNING3}
  \begin{Arguments}
    & \Var{X} & First warning message.\\
    & \Var{Y} & Continuation of warning message.\\
    & \Var{Z} & Second continuation of warning message.\\
  \end{Arguments}%
  Raise a warning. Print the thre arguments as warning message
  and continue.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{Err}}{Err}
  \begin{Arguments}
    & \Var{S} & String to print.\\
  \end{Arguments}%
  Print a string to the error stream. This message is
  preceded with an indicator. The message is \emph{not}
  automatically terminated by a newline.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ErrC}}{ErrC}
  \begin{Arguments}
    & \Var{CHAR} & Character to send to output.\\
  \end{Arguments}%
  Print a single character to the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ErrPrint}}{ErrPrint}
  \begin{Arguments}
    & \Var{F} & String to print.\\
  \end{Arguments}%
  Print a string to the error stream. The string is not
  preceded by any indicator not is it automatically
  terminated by a newline.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ErrPrintF}}{ErrPrintF}
  \begin{Arguments}
    & \Var{F} & Format.\\
    & \Var{A} & Argument.\\
  \end{Arguments}%
  Apply a formatting instruction (with |printf()|). This
  macro takes a format string and a second argument
  which is determined by the formatting string.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ErrPrintF2}}{ErrPrintF2}
  \begin{Arguments}
    & \Var{F} & Format\\
    & \Var{A} & First argument.\\
    & \Var{B} & Second argument.\\
  \end{Arguments}%
  Apply a formatting instruction (with |printf()|). This
  macro takes a format string and two additional arguments
  which are determined by the formatting string.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Constant}{void \Mac{FlushErr}}{FlushErr}
  Flush the error stream. This can be useful when single
  characters are written to an error stream which does
  buffering. 
\end{Constant}
\begin{Macro}{void \Mac{VerbosePrint1}}{VerbosePrint1}
  \begin{Arguments}
    & \Var{A} & Verbose message.\\
  \end{Arguments}%
  Print an informative message to the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{VerbosePrint2}}{VerbosePrint2}
  \begin{Arguments}
    & \Var{A} & Verbose message.\\
    & \Var{B} & Continuation of verbose message.\\
  \end{Arguments}%
  Print an informative message consisting of two
  substrings to the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{VerbosePrint3}}{VerbosePrint3}
  \begin{Arguments}
    & \Var{A} & Verbose message.\\
    & \Var{B} & Continuation of verbose message.\\
    & \Var{C} & Second continuation of verbose message.\\
  \end{Arguments}%
  Print an informative message consisting of three
  substrings to the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{VerbosePrint4}}{VerbosePrint4}
  \begin{Arguments}
    & \Var{A} & Verbose message.\\
    & \Var{B} & Continuation of verbose message.\\
    & \Var{C} & Second continuation of verbose message.\\
    & \Var{D} & Third continuation of verbose message.\\
  \end{Arguments}%
  Print an informative message consisting of four
  substrings to the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{DebugPrint1}}{DebugPrint1}
  \begin{Arguments}
    & \Var{A} & Debug message.\\
  \end{Arguments}%
  This Macro is for debugging purposes. The compilation
  determines whether this macro prints its argument or
  simply ignores it. This is achieved by defining or
  undefining the macro |DEBUG| when compiling.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{DebugPrint2}}{DebugPrint2}
  \begin{Arguments}
    & \Var{A} & Debug message.\\
    & \Var{B} & Conitnuation of the debug message.\\
  \end{Arguments}%
  This Macro is for debugging purposes. The compilation
  determines whether this macro prints its arguments or
  simply ignores them. This is achieved by defining or
  undefining the macro |DEBUG| when compiling.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{DebugPrint3}}{DebugPrint3}
  \begin{Arguments}
    & \Var{A} & Debug message.\\
    & \Var{B} & Conitnuation of the debug message.\\
    & \Var{C} & Second conitnuation of the debug message.\\
  \end{Arguments}%
  This Macro is for debugging purposes. The compilation
  determines whether this macro prints its arguments or
  simply ignores them. This is achieved by defining or
  undefining the macro |DEBUG| when compiling.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}

\Module{error.c}{error.c}

To ensure a consistent appearence of error messages \BibTool{}
provides one generic error reporting routine. This routine is
controlled by several arguments to allow maximum flexibility.

Usually it is awkward to fill out all those arguments. To
avoid this trouble the header file |error.h| provides some
macros which cover the most common situation and hide
unneccesary details.

\begin{Function}{void \Fct{error}}{error}
  \begin{Arguments}
    int \ 	&\Var{type};	&Error type: boolean combination of the error bits as
defined in |error.h|. \\
    Uchar *\ 	&\Var{s1};	&1$^\mathrm{st}$ error message or |NULL|.\\
    Uchar *\ 	&\Var{s2};	&2$^\mathrm{nd}$ error message or |NULL|.\\
    Uchar *\ 	&\Var{s3};	&3$^\mathrm{rd}$ error message or |NULL|.\\
    Uchar *\ 	&\Var{line};	&Current line when error occured (for reading errors).\\
    Uchar *\ 	&\Var{err\_pos};	&Error position in line |line|.\\
    int \ 	&\Var{line\_no};	&The line number where the error occurred.\\
    char *\ 	&\Var{fname};	&The file name where the error occurred.
  \end{Arguments}%
  This is the generic error printing routine.
  It prints an error message together with an optional filename,
  the line number, the errorous line and a pointer to the
  problematic position.
  
  All parts of an error message are optional and can be
  suppressed under certain conditions.  The error type
  determines which parts are actually shown. It is a
  boolean combination of the following flags which are
  defined in |error.h|:
  \begin{description}
  \item[ERR\_ERROR] If this bit is set then the error
  message is marked as ``error''. The flag |ERR_WARNING|
  is ignored in this case. This kind of messages can not
  be suppresed.
  \item[ERR\_WARNING]  If this bit is set and
  |ERR_ERROR| is not set then the error message is
  marked as ``warning''. |ERR_WARNING| is ignored 
  in this case.
  \item[ERR\_POINT] If this bit is set then the line |line| is
  shown together with a pointer to the byte pointed to
  by |err_pos|. Otherwise the line is not shown.
  \item[ERR\_FILE] If this bit is set then the name of
  the file |file_name| and the line number |lineno| are
  shown. Otherwise the file name and the line number are
  suppressed.
  \item[ERR\_EXIT] If this bit is set then the error
  routine calles |exit(-1)| at the end. This implicitly
  sets the |ERR_ERROR| bit as well.
  \end{description}
  
  The error message itself can be split in up to three
  strings |s1|, |s2|, and |s3|. Those strings are
  concatenated. They can also be |NULL| in which case
  they are ignored.
  
  The error message is written to the stream determined
  by the variable |err_file|. This variable refers to
  the |stderr| stream initially but can be redirected to
  any other destination.
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/expand.h}{bibtoolexpand.h}

This header file makes available the function defined in
|expand.c|. This file includes the header file |database.h|.

\Module{expand.c}{expand.c}

This module contains functions to expand macros as they are
appearing in right hand sides of equations. This can be used
to get rid of additional macro definitions.

\begin{Function}{char * \Fct{expand\_rhs}}{expand\_rhs}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String to expand\\
    char *\ 	&\Var{pre};	&This is the opening brace character to be used. For
\BibTeX{} the valid values are |{| or |"|. This value
has to match to |post|.\\
    char *\ 	&\Var{post};	&This is the closing brace character to be used. For
\BibTeX{} the valid values are |}| or |"|. This value
has to match to |pre|.\\
    DB \ 	&\Var{db};	&Database containing the macros.
  \end{Arguments}%
  Expand the right hand side of an item. Each macro
  which is defined in this database is replaced by its
  value. The result is kept in a static variable until
  the next invocation of this function overwrites it.
  \begin{Result}
    A pointer to the expanded string. This value is kept in a
    static variable of this function and will be overwritten with
    the next invocation.
  \end{Result}
\end{Function}

\Header{bibtool/init.h}{bibtoolinit.h}

This header file provides the prototype for the global initialization
function which is required to be called before any action can be 
performed.


\Module{init.c}{init.c}

This module contains the global initialization function which
has to be called before any modules in \BibTool{} are
activated.  This is for convenience, thus nobody has to call
the various initialization functions for the different modules
by hand.
\begin{Function}{void \Fct{init\_bibtool}}{init\_bibtool}
  \begin{Arguments}
    char * \ 	&\Var{progname};	&Name of the program for |KPATHSEA|.
  \end{Arguments}%
  Perform any initializations necessary for \BibTool.
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/keynode.h}{bibtoolkeynode.h}

This header file provides the datatype of a keynode.  This is
an internal structure which is used to built parse trees from
format specifications. Usually this is done in |key.c| and
should not be visible outside.

\begin{Typedef}{\Type{KeyNode}}{KeyNode}
  
  
  
  \STRUCT{kEYnODE}
    short int	  \ 	&\Member{kn\_type};	& \\
    short int      \ 	&\Member{kn\_pre};	& \\
    short int      \ 	&\Member{kn\_post};	& \\
    char           *\ 	&\Member{kn\_string};	& \\
    char           *\ 	&\Member{kn\_from};	& \\
    char		  *\ 	&\Member{kn\_to};	& \\
    struct kEYnODE *\ 	&\Member{kn\_next};	& \\
    struct kEYnODE *\ 	&\Member{kn\_then};	& \\
    struct kEYnODE *\ 	&\Member{kn\_else};	& 
  \EndSTRUCT{\Type{*KeyNode}, \Type{SKeyNode}}
\end{Typedef}

\Header{bibtool/key.h}{bibtoolkey.h}

This header file provides functions to deal with keys as they
are defined in |keys.h|. 

This header file automaticall includes the header files
|database.h| and |sbuffer.h| since datatypes defined there are
required. 


\Module{key.c}{key.c}

\begin{Function}{void \Fct{add\_format}}{add\_format}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Specification string
  \end{Arguments}%
  Add a key format specification to the current
  specification.  This specification is used for
  generating new reference keys. Thus the resource
  |rsc_make_key| is turned on aswell.
  
  Several strings are treated special. If a special
  format is encountered then the effect is that the old
  key specification is cleared first before the new
  format is added:
  \begin{description}
  \item[empty] The empty format is activated. This means that
  the format is cleared and without further action the
  default key will be used.
  \item[long] The long format is activated. This means that
  authors names with initials and the first word of
  the title are used.
  \item[short] The short format is activated. This means that
  authors last names and the first word of the title
  are used. 
  \item[new.long] This means that the long format will
  be used but only if the record does not have a key
  already. 
  \item[new.short] This means that the short format will
  be used but only if the record does not have a key
  already. 
  \end{description}
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_ignored\_word}}{add\_ignored\_word}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Word to add.
  \end{Arguments}%
  Add a new word to the list of ignored words for title
  key generation.
  The argument has to be saved by the caller! This means
  that it is assumed that the argument is a symbol.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_sort\_format}}{add\_sort\_format}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Specification string
  \end{Arguments}%
  Add a sort key format specification to the current
  specification.  This specification is used for
  generating new sort keys.
  
  Several strings are treated special. If a special
  format is encountered then the effect is that the old
  key specification is cleared first before the new
  format is added:
  \begin{description}
  \item[empty] The empty format is activated. This means that
  the format is cleared and without further action the
  default key will be used.
  \item[long] The long format is activated. This means that
  authors names with initials and the first word of
  the title are used.
  \item[short] The short format is activated. This means that
  authors last names and the first word of the title
  are used. 
  \item[new.long] This means that the long format will
  be used but only if the record does not have a key
  already. 
  \item[new.short] This means that the short format will
  be used but only if the record does not have a key
  already. 
  \end{description}
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{apply\_fmt}}{apply\_fmt}
  \begin{Arguments}
    StringBuffer *\ 	&\Var{sb};	&Destination string buffer.\\
    char *\ 	&\Var{fmt};	&Format specification,\\
    Record \ 	&\Var{rec};	&Record to consider.\\
    DB \ 	&\Var{db};	&Datrabase containing |rec|.
  \end{Arguments}%
  Expands an arbitrary format specification for a given record.
  The format specification is given as a string.
  The result is stored in a string buffer.
  \begin{Result}
    |1| iff the format is invalid or the evaluation fails. |0|
    otherwise.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{clear\_ignored\_words}}{clear\_ignored\_words}  Delete the list of ignored words. Afterwards no words are
  recognized as ignored words.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{def\_format\_type}}{def\_format\_type}
  \begin{Arguments}
    char *\ 	&\Var{s};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char* \Fct{fmt\_expand}}{fmt\_expand}
  \begin{Arguments}
    StringBuffer *\ 	&\Var{sb};	&destination string buffer\\
    char *\ 	&\Var{cp};	&format\\
    DB \ 	&\Var{db};	&Datrabase containing |rec|.\\
    Record \ 	&\Var{rec};	&Record to consider.
  \end{Arguments}%
  Expands a format specification of the % type into a given
  string buffer.
  
  \begin{Result}
    The first character after the % format.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{foreach\_ignored\_word}}{foreach\_ignored\_word}
  \begin{Arguments}
    int (*\ 	&\Var{fct})(char*); 	&Function to apply.
  \end{Arguments}%
  Iterator a given function |fct| is applied to each
  ignored word in turn. If the function returns 0 then
  the loop is terminated. The different words are
  visited in a fixed order which does not necessarily
  coincide with the natural order of words. Thus don't
  assume this.
  \begin{Result}
    The return status of the last |fct| call.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_key\_node}}{free\_key\_node}
  \begin{Arguments}
    KeyNode \ 	&\Var{kn};	&KeyNode to be freed.
  \end{Arguments}%
  A tree rooted at a given |KeyNode| will be freed.
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char *\Fct{get\_field}}{get\_field}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Datrabase containing |rec|.\\
    Record \ 	&\Var{rec};	&Record to analyze.\\
    char *\ 	&\Var{name};	&Field name to search for. This has to be a symbol if a
normal field is sought. For pseudo fields it can be an
arbitrary string.
  \end{Arguments}%
  Evaluate the record |rec|.
  If name starts with |@| then check the record name.
  If name starts with |$| then return the special info. 
  Else search in Record |rec| for the field name and return its
  value. |NULL| is returned to indicate failure.
  \begin{Result}
    The address of the value or |NULL|.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{make\_key}}{make\_key}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing the record.	\\
    Record \ 	&\Var{rec};	&Record to consider.
  \end{Arguments}%
  Generate a key for a given record.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{make\_sort\_key}}{make\_sort\_key}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing the record.\\
    Record \ 	&\Var{rec};	&Record to consider.
  \end{Arguments}%
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{mark\_key}}{mark\_key}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing the record.\\
    Record \ 	&\Var{rec};	&Record to consider
  \end{Arguments}%
  Set the key mark for the key symbol of a record.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{set\_base}}{set\_base}
  \begin{Arguments}
    char *\ 	&\Var{value};	&String representation of the new value.
  \end{Arguments}%
  Define the key base. This value determines the format
  of the disambiguation string added to a key if
  required. The following values are considered:
  \begin{itemize}
  \item If the value is |upper| or starts with an upper
  case letter then the disambiguation is done with
  uppercase letters. 
  \item If the value is |lower| or starts with a lower
  case letter then the disambiguation is done with
  lowercase letters. 
  \item If the value is |digit| or starts with an digit
  then the disambiguation is done with arabic numbers. 
  \end{itemize}
  The comparison of the keywords is done case
  insensitive. The special values take precedence before
  the first character rules.
  
  If an invalid value is given to this function then an
  error is raised and the program is terminated.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{set\_field}}{set\_field}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Datrabase containing |rec|.\\
    Record \ 	&\Var{rec};	&Record to receive the value.\\
    char *\ 	&\Var{name};	&Field name to add.\\
    char *\ 	&\Var{value};	&String representation of the new value.
  \end{Arguments}%
  Store the given field or pseudo-field in a record.
  If the field is present then the old value is
  overwritten.  Otherwise a new field is added. Fields
  starting with a |$| or |@| are treated special. They
  denote pseudo fields. If such a pseudo field is
  undefined then the assignment simply fails.
  
  In contrast to the function |push_to_record()| this
  function does not assume that the arguments are
  symbols. In addition to |push_to_record()| it also
  handles pseudo-fields.
  \begin{Result}
    |0| if the asignment has succeeded.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{set\_separator}}{set\_separator}
  \begin{Arguments}
    int \ 	&\Var{n};	&Array index to modify.\\
    char *\ 	&\Var{s};	&New value for the given separator. The new value is
stored as a symbol. Thus the memory of |s| need not to
be preserved after this function is completed.
The characters which are not allowed are silently sypressed.
  \end{Arguments}%
  Modify the key\_seps array. This array contains the
  different separators used during key formatting. The
  elements of the array have the following meaning:
  \begin{description}
  \item[0] The default key which is used when the
  formatting instruction fails completely.
  \item[1] The separator which is inserted between
  different names of a multi-authored publication.
  \item[2] The separator inserted between the first name
  and the last name when a name is formatted.
  \item[3] The separator inserted between the last names
  when more then one last name is present
  \item[4] The separator between the name and the title
  of a publication.
  \item[5] The separator inserted between words of the
  title.
  \item[6] The separator inserted before the number
  which might be added to disambiguate reference keys.
  \item[7] The string which is added when a list of
  names is truncated. (|.ea|)
  \end{description}
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/macros.h}{bibtoolmacros.h}

This header file contains definitions for the |Macro|
structure. |Macro| is the pointer type corresponding to the
structure |SMacro|. All C macros and functions provided
through this header file deal with the pointer type. The
structure itself is used in the allocation function only.

\begin{Typedef}{\Type{Macro}}{Macro}
  This is a pointer type to represent a mapping from a
  string to another string.  This mapping is accompanied
  by a counter which can be used as a reference count.
  \STRUCT{mACRO}
    char		*\ 	&\Member{mc\_name};	& Name of the macro.     \\
    char		*\ 	&\Member{mc\_value};	& Value of the macro.    \\
    int		\ 	&\Member{mc\_used};	& Reference count.	     \\
    struct mACRO *\ 	&\Member{mc\_next};	& Pointer the next macro.
  \EndSTRUCT{\Type{SMacro}, \Type{*Macro}}
\end{Typedef}
\begin{Constant}{Macro \Mac{MacroNULL}}{MacroNULL}
  This is the |NULL| pointer for the |Macro| type. It
  can be used as a special or illlegal macro.
\end{Constant}
\begin{Macro}{char * \Mac{MacroName}}{MacroName}
  \begin{Arguments}
    & \Var{M} & |Macro| to consider\\
  \end{Arguments}%
  This is the functional representation of the name
  component of a |Macro|. It can be used to extract this
  information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{char * \Mac{MacroValue}}{MacroValue}
  \begin{Arguments}
    & \Var{M} & |Macro| to consider\\
  \end{Arguments}%
  This is the functional representation of the value
  component of a |Macro|. It can be used to extract this
  information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{int \Mac{MacroCount}}{MacroCount}
  \begin{Arguments}
    & \Var{M} & |Macro| to consider\\
  \end{Arguments}%
  This is the functional representation of the counter
  component of a |Macro|. It can be used to extract this
  information. It can also be used as a lvalue.
\end{Macro}
\begin{Macro}{Macro \Mac{NextMacro}}{NextMacro}
  \begin{Arguments}
    & \Var{M} & |Macro| to consider\\
  \end{Arguments}%
  This is the functional representation of the next
  |Macro|. It can be used to extract this information.
  It can also be used as a lvalue.
\end{Macro}

\Module{macros.c}{macros.c}

\begin{Function}{void \Fct{def\_field\_type}}{def\_field\_type}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String containing an equation.	
  \end{Arguments}%
  This function adds a printing representation for a
  field name to the used list. The argument is an
  equation of the following form
  
  \textit{type = value}
  
  \textit{type} is translated to lower case and compared
  against the internal representation. \textit{value} is
  printed at the appropriate places instead.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{def\_macro}}{def\_macro}
  \begin{Arguments}
    char *\ 	&\Var{name};	&name of the macro.\\
    char *\ 	&\Var{val};	&NULL or the value of the new macro\\
    int \ 	&\Var{count};	&initial count for the macro.
  \end{Arguments}%
  Define or undefine a macro.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{dump\_mac}}{dump\_mac}
  \begin{Arguments}
    char *\ 	&\Var{fname};	&File name of the target file.\\
    int \ 	&\Var{allp};	&if == 0 only the used macros are written.
  \end{Arguments}%
  Write macros to a file.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{foreach\_macro}}{foreach\_macro}
  \begin{Arguments}
    int (*fct) (char *,char *);
  \end{Arguments}%
  Apply a function to each macro in turn. The function
  is called with the name and the value of the macro. If
  it returns |FALSE| then the processing of further
  macros is suppressed.
  
  The function given as argument is called with two
  string arguments. The first is the name of the macro
  and the second is its value. Both are symbols and must
  not be modified in any way.
  
  The order of the enumeration of the macros is
  determined by the implementation. No specific
  assumptions should be made about this order.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_macro}}{free\_macro}
  \begin{Arguments}
    Macro \ 	&\Var{mac};	&First Macro to release.
  \end{Arguments}%
  Free a list of macros. The memory allocated for the
  |Macro| given as argument and all struictures
  reachable via the |NextMacro| pointer are released.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{get\_item}}{get\_item}
  \begin{Arguments}
    char * \ 	&\Var{name};	&Symbol to get the print representation for.\\
    int \ 	&\Var{type};	&One of the values |SYMBOL\_TYPE\_UPPER|, |SYMBOL\_TYPE\_LOWER|, or
|SYMBOL\_TYPE\_CASED| as they are defined in |type.h|.
  \end{Arguments}%
  Return the print representation of a \BibTeX{} string.
  The appearance is determined by the |items| mapping.
  If no approriate entry is found then |type| is used to
  decide whether the item should be returned as
  uppercase, lowercase or first upper only.
  \begin{Result}
    A pointer to a static string. This location  is reused
    upon the next invocation of this function.
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{get\_key\_name}}{get\_key\_name}
  \begin{Arguments}
    char *\ 	&\Var{s};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{init\_macros}}{init\_macros}  Initialize some macros from a table defined in the
  configuration file or given as define to the C
  compiler. This function has to be caled to initialize
  the global macros.
  
  Note that this function is for internal purposes
  only. The normal user should call |init_bibtool()|
  instead.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{look\_macro}}{look\_macro}
  \begin{Arguments}
    char *\ 	&\Var{name};	&The name of the macros to find. This needs not to be a symbol.\\
    int \ 	&\Var{add};	&Initial reference count or indicator that no new macro
is required.
  \end{Arguments}%
  Return the value of a macro if it is defined. This
  value is a symbol. 
  If the macro is undefined then |NULL| is returned.  In
  this case the value of |add| determines whether or not
  the macro shpould be defined. If it is less than 0
  then no new macros is defined. Otherwise a new macro
  is defined. The value is the empty string and the
  initial reference count is |add|.
  \begin{Result}
    The value or |NULL|.
  \end{Result}
\end{Function}
\begin{Function}{Macro \Fct{new\_macro}}{new\_macro}
  \begin{Arguments}
    char *\ 	&\Var{name};	&Name of the macro. This must be a symbol.\\
    char *\ 	&\Var{val};	&The value of the macro. This must be a symbol.\\
    int \ 	&\Var{count};	&The initial reference count.\\
    Macro \ 	&\Var{next};	&The next pointer of the |Macro| structure.
  \end{Arguments}%
  Allocate a new macro structure and fill it with initial values.
  Upon failure an error is raised and |exit()| is called.
  \begin{Result}
    The new |Macro|.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{save\_key}}{save\_key}
  \begin{Arguments}
    char * \ 	&\Var{s};	&\\
    char * \ 	&\Var{key};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/names.h}{bibtoolnames.h}

\begin{Typedef}{\Type{SNameNode}}{SNameNode}
  The name format is translated internally into a list
  of nodes which are easier to evaluate since they avoid
  the reparsing of the format. This structure contains
  such a node.
  \STRUCT{nameNODE}
    int		   \ 	&\Member{nn\_type};	& \\
    int		   \ 	&\Member{nn\_strip};	& \\
    char		   *\ 	&\Member{nn\_pre};	& \\
    char		   *\ 	&\Member{nn\_mid};	& \\
    char		   *\ 	&\Member{nn\_post};	& \\
    struct nameNODE *\ 	&\Member{nn\_next};	& Pointer to the next    
			name node             
  \EndSTRUCT{\Type{SNameNode}, \Type{*NameNode}}
\end{Typedef}
\begin{Constant}{NameNode \Mac{NameNULL}}{NameNULL}
  The |NULL| pointer to a |NameNode| which can be used
  as a special value to indicate the end of a |NameNode|
  list.
\end{Constant}
\begin{Macro}{int \Mac{NameType}}{NameType}
  \begin{Arguments}
    & \Var{NN} & \\
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{NameStrip}}{NameStrip}
  \begin{Arguments}
    & \Var{NN} & \\
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{char* \Mac{NamePre}}{NamePre}
  \begin{Arguments}
    & \Var{NN} & \\
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{char* \Mac{NameMid}}{NameMid}
  \begin{Arguments}
    & \Var{NN} & \\
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{char* \Mac{NamePost}}{NamePost}
  \begin{Arguments}
    & \Var{NN} & \\
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{NameNode \Mac{NextName}}{NextName}
  \begin{Arguments}
    & \Var{NN} & |NameNode| to consider.\\
  \end{Arguments}%
  Functional representation of the pointer to the next
  |NameNode|.
  \begin{Result}
    The next |Namenode|.
  \end{Result}
\end{Macro}

\Module{names.c}{names.c}

\begin{Function}{NameNode \Fct{name\_format}}{name\_format}
  \begin{Arguments}
    char *\ 	&\Var{s};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{pp\_list\_of\_names}}{pp\_list\_of\_names}
  \begin{Arguments}
    char **\ 	&\Var{wa};	&Word array of name constituents\\
    NameNode \ 	&\Var{format};	&\\
    char *\ 	&\Var{trans};	&Translation table\\
    int \ 	&\Var{max};	&maximum or 0\\
    char *\ 	&\Var{comma};	&","\\
    char *\ 	&\Var{and};	&name separator\\
    char *\ 	&\Var{namesep};	&\\
    char *\ 	&\Var{etal};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    Pointer to static string which is reused upon the next
    invocation of this function.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{set\_name\_format}}{set\_name\_format}
  \begin{Arguments}
    NameNode *\ 	&\Var{nodep};	&\\
    char *\ 	&\Var{s};	&
  \end{Arguments}%
  
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/parse.h}{bibtoolparse.h}

This header file contains functions which deal with the
parsing of \BibTeX{} files. They are defined in |parse.c| and
declared in this file.


\Module{parse.c}{parse.c}

\begin{Function}{void \Fct{init\_read}}{init\_read}  Initialize the reading apparatus.
  Primarily try to figure out the file search path.
  
  Note that this function is for internal purposes
  mainly. The normal user should call |init_bibtool()|
  instead. Just in case the search paths are changed
  afterwards this function has to be called again to
  propagate the information.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{parse\_bib}}{parse\_bib}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Record to store the result in.
  \end{Arguments}%
  Read one entry and fill the internal record structure.
  Return the type of the entry read.
  
  |BIB_EOF| is returned if nothing could be read and
  the end of the file has been encountered.
  
  |BIB_NOOP| is returned when an error has occured. This is
  an indicator that no record has been read but the
  error recovery is ready to try it again.
  
  This function is for internal purposes mainly. See
  |read_db()| for a higher level function to read a
  database. 
  \begin{Result}
    The type of the entry read, |BIB_EOF|, or |BIB_NOOP|.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{read\_rsc}}{read\_rsc}
  \begin{Arguments}
    char *\ 	&\Var{name};	&Name of the file to read from.
  \end{Arguments}%
  Read a resource file and evaluate all instructions
  contained.
  
  The characters |#|, |%|, and |;| start an endline
  comment but only between resource instructions. They
  are not recogniized between a resource instructiuon
  and its value or inside the value braces.
  
  This function is contained in this module because it
  shares several functions with the \BibTeX{} parsing
  routines. 
  \begin{Result}
    
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{see\_bib}}{see\_bib}
  \begin{Arguments}
    char * \ 	&\Var{fname};	&Name of the file or |NULL|.
  \end{Arguments}%
  Open a \BibTeX{} file to read from. 
  If the argument is |NULL| then |stdin| is used as
  input stream.
  
  This function has to be called before |parse()| can be
  called. It initializes the parser routine and takes
  care that the next reading is done from the given
  file.
  
  The file opened with this function has to be closed
  with |seen()|.
  
  This function is for internal purposes mainly. See
  |read_db()| for a higher level function to read a
  database. 
  \begin{Result}
    |TRUE| iff the file couls be opened for reading.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{seen}}{seen}  Close input file for the \BibTeX{} reading apparatus.
  After this function has been called |parse()| might
  not return sensible results.
  
  This function is for internal purposes mainly. See
  |read_db()| for a higher level function to read a
  database. 
  \begin{Result}
    |FALSE| if an attempt was made to close an already
    closed file.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{set\_rsc\_path}}{set\_rsc\_path}
  \begin{Arguments}
    char * \ 	&\Var{val};	&The string representation of the file search path.
  \end{Arguments}%
  Initialize the resource file reading apparatus.
  Primarily try to figure out the file search path.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/print.h}{bibtoolprint.h}

This header file provides access to the functions and
variables defined in |print.c|. Consult also the documentation
of this file for details.

This header file automatically includes |record.h| and |database.h|.


\Module{print.c}{print.c}

This module provides also access to the functions and
variables defined in |entry.c|. Consult also the documentation
of this file for details.


\begin{Function}{void \Fct{fput\_record}}{fput\_record}
  \begin{Arguments}
    FILE *\ 	&\Var{file};	&Stream to print onto.\\
    DB \ 	&\Var{db};	&Database containing the record.\\
    Record \ 	&\Var{rec};	&Record to print.\\
    char *\ 	&\Var{start};	&Initial string used before the type. Should be "@" normally.
  \end{Arguments}%
  Format and print a complete record onto a given stream.
  for further details see |put_record()|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{put\_record}}{put\_record}
  \begin{Arguments}
    int (*\ 	&\Var{fct})(int); 	&function to use for writing a character.\\
    Record \ 	&\Var{rec};	&Record to print.\\
    DB \ 	&\Var{db};	&Database containing the record.\\
    char *\ 	&\Var{start};	&Initial string used before the type. Should be "@" normally.
  \end{Arguments}%
  Format and print a complete record.
  The record type and several resources are taken into
  account. The following external variables (from
  |rsc.c|) are taken into account:
  \begin{description}
  \item[rsc\_parentheses] If this boolean variable is
  |TRUE| then |(| and |)| are used to delimit the
  record. Otherwise |{| and |}| are used.
  \item[rsc\_col\_p] This integer variable controlls the
  indentation of preamble records.
  \item[rsc\_col\_s] This integer variable controlls the
  indentation of string records.
  
  \item[rsc\_expand\_macros] If this boolean variable is
  set then macros are expanded before the record is
  printed. This does not effect the internal
  representation. 
  \item[rsc\_col] This integer variable controlls the
  indentation of normal records.
  \item[rsc\_col\_key] This integer variable controlls the
  indentation of the key in a normal record.
  \item[rsc\_newlines] This integer variable controlls
  the number of newlines printed after a normal record.
  
  \item[rsc\_linelen] This integer variable controlls
  the length of the line. The line breaking algorithm
  is applied if this column is about to be violated.
  \item[rsc\_indent] This integer variable controlls the
  indentation of equations.
  \item[rsc\_eq\_right] This boolean variable controlls
  the alignment of the |=| in equations. It it is set
  then the equality sign is flused right. Otherwise it
  is flushed left.
  \end{description}
  
  The field in the record are sorted with
  |sort_record()| before they are printed.
  
  In normal records all fields not starting with an
  allowed character are ignored. Thus it is possible to
  store private and invisible information in a
  field. Simply start the field name with an not allowed
  character like |%|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{set\_symbol\_type}}{set\_symbol\_type}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String description of the value.
  \end{Arguments}%
  Function to set the symbol type which is used by the
  printing routine. The argument is a string describing
  the value to use. Possible values are |"upper"|,
  |"lower"|, and |"cased"|. The comparison of the values
  is performed case insensitive.
  
  If no appropriate value is found then an error message
  is issued as the only action.
  
  This function is called from |rsc.c|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{sput\_record}}{sput\_record}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing the record.\\
    Record \ 	&\Var{rec};	&Record to print.\\
    char *\ 	&\Var{start};	&Initial string used before the type. Should be "@" normally.
  \end{Arguments}%
  Format and print a complete record into a string and return it.
  The string returned points to static memory which is
  reused upon the next invocation of this function.
  \begin{Result}
    The string containing the printed representation.
  \end{Result}
\end{Function}

\Header{bibtool/pxfile.h}{bibtoolpxfile.h}

This module provides access to the functions and
variables defined in |pxfile.c|. Consult also the documentation
of this file for details.

This header file automatically includes |bibtool.h| and |<stdio.h>|.


\Module{pxfile.c}{pxfile.c}

This file provides routines for extended file opening. Files
are sought in a list of directories and optionally with a set
of extensions appended to them.

Patterns may be given which are used to determine the full file 
name.
The patterns are stored in a special data structure.  A
function is provided to allocate a pattern structure and fill
it from a string specification.

\begin{Variable}{\Mac{px\_filename}}{pxfilename}
  This variable contains the file name actually used by
  the last |px_fopen()| call. The memory is automatically
  managed and will be reused by the next call to
  |px_fopen()|.  Thus if you need to use it make a
  private copy immediately after the call to the
  function |px_fopen()|.
\end{Variable}
\begin{Function}{FILE * \Fct{px\_fopen}}{px\_fopen}
  \begin{Arguments}
    char * \ 	&\Var{name};	&(base) name of the file to open.\\
    char * \ 	&\Var{mode};	&Mode for opening the file like used with |fopen()|.\\
    char **\ 	&\Var{pattern};	&A |NULL| terminated array of patterns.\\
    char **\ 	&\Var{path};	&The |NULL| terminated array of directories.\\
    int (*\ 	&\Var{show})(char*); 	&A function pointer or |NULL|.
  \end{Arguments}%
  Open a file using path and pattern.
  
  
  \begin{Result}
    A file pointer refering to the file or |NULL|.
  \end{Result}
\end{Function}
\begin{Function}{char **\Fct{px\_s2p}}{px\_s2p}
  \begin{Arguments}
    char * \ 	&\Var{s};	&\\
    int \ 	&\Var{sep};	&
  \end{Arguments}%
  Translate a path string specification into an array of the 
  components.
  The memory of the array is malloced and should be freed when
  not used any longer.
  \begin{Result}
    The array of the components
  \end{Result}
\end{Function}

\Header{bibtool/record.h}{bibtoolrecord.h}

This module contains functions which deal with records in databases. 


\begin{Typedef}{\Type{Record}}{Record}
  This data type represents a record in a \BibTeX{}
  database.  Since the record can contain an arbitrary
  number of fields the central r\^ole is taken by the
  dynamic array |rc_heap|. This array contains at even
  positions the name of the field and the following odd
  position the associated value. In normal records the
  position 0 contains the reference key of the record.
  
  If a field is deleted then the name is replaced by a
  |NULL|. The structure member |rc_free| contains the
  size of the heap.
  
  The type of the record is determined by the integer
  |rc_type|. 
  
  \STRUCT{rECORD}
    char	  * \ 	&\Member{rc\_key};	& The sort key.             \\
    char	  * \ 	&\Member{rc\_old\_key};	& The old sort key.         \\
    int		    \ 	&\Member{rc\_type};	& The type of the record.   \\
    int		    \ 	&\Member{rc\_flags};	& Some bits; e.g. used      
			during selecting aux     
			records.                 \\
    int		    \ 	&\Member{rc\_free};	& The size of the heap. This
			is purely internal and   
			must not be modified.    \\
    char	  **\ 	&\Member{rc\_heap};	& The heap.                 \\
    char          * \ 	&\Member{rc\_comment};	& The comment following     
			the given record.        \\
    char	  * \ 	&\Member{rc\_source};	& The source of the record. 
			I.e. the file name it    
			has been read from.      \\
    struct rECORD * \ 	&\Member{rc\_next};	& Pointer to the next       
			record.                  \\
    struct rECORD * \ 	&\Member{rc\_prev};	& Pointer to the previous   
			record.                  
  \EndSTRUCT{\Type{SRecord}, \Type{*Record}}
\end{Typedef}
\begin{Constant}{Record \Mac{RecordNULL}}{RecordNULL}
  Symbolic constant for the NULL pointer of type
  |Record|. This is used as special (invalid) record.
\end{Constant}
\begin{Macro}{int \Mac{RecordType}}{RecordType}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Functional representation of the record
  token. This can be used to access the token component
  of a record. It can also be used as lvalue.
  
  \begin{Result}
    The pure token.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{RecordFlags}}{RecordFlags}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Functional representation of the record type.  This
  can be used to access the token component of a
  record. It can also be used as lvalue. 
  \begin{Result}
    The flags as integer.
  \end{Result}
\end{Macro}
\begin{Constant}{int \Mac{RecordFlagMARKED}}{RecordFlagMARKED}
  Bit mask for the |MARKED| flag of a record.  The mark
  is used temporarily to determine certain records;
  e.g. during gc.
  
  This macro is usually not used directly but implicitly
  with other macros from this header file. 
\end{Constant}
\begin{Constant}{int \Mac{RecordFlagXREF}}{RecordFlagXREF}
  Bit mask for the |XREF| flag of a record. This flag is
  maintained to indicate that the record contains an
  |crossref| field. This is done for efficiency reasons
  only. 
  
  This macro is usually not used directly but implicitly
  with other macros from this header file. 
\end{Constant}
\begin{Constant}{int \Mac{RecordFlagDELETED}}{RecordFlagDELETED}
  Bit mask for the |DELETED| flag of a record.  This
  flag indicates that the record has been deleted.  To
  avoid dangling pointers the deleted records are not
  removed from the database immediately but a call to
  |record_gc()| performs this cleanup. In the meantime
  the deleted records are just left in the chain. Many
  operations automatically ignore deleted records.
  
  This macro is usually not used directly but implicitly
  with other macros from this header file. 
\end{Constant}
\begin{Macro}{int \Mac{SetRecordXREF}}{SetRecordXREF}
  \begin{Arguments}
    & \Var{R} & The record to consider.\\
  \end{Arguments}%
  Mark the record with the |XREF| flag. If it is marked
  already nothing is done.
  
  The |XREF| flag is used to mark those records which
  contain a |crossref| field. This is done for
  efficiency only.
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{ClearRecordXREF}}{ClearRecordXREF}
  \begin{Arguments}
    & \Var{R} & The record to consider.\\
  \end{Arguments}%
  Remove the XREF mark.
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{RecordIsXREF}}{RecordIsXREF}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Check whether the |XREF| flag of a record is set.
  \begin{Result}
    |FALSE| iff the |XREF| flag is not set.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{SetRecordDELETED}}{SetRecordDELETED}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Mark the record with the |DELETED| flag. If it is marked
  already nothing is done.
  
  The |DELETED| flag is used to mark those records which
  should be treated as non existent. Deleted records are
  ignored for most operations.
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{ClearRecordDELETED}}{ClearRecordDELETED}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Remove the deleted flag. Thus you can effictively
  undelete a record as long as its memory has not been
  released. 
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{RecordIsDELETED}}{RecordIsDELETED}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Check whether the record is marked as deleted.
  \begin{Result}
    |FALSE| iff the |DELETED| flag is not set.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{SetRecordMARK}}{SetRecordMARK}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Mark the record. The mark is used temporarily. Do not
  assume that the mark is preserved in each function.
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{ClearRecordMARK}}{ClearRecordMARK}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Remove the deleted flag. Thus you can effictively
  undelete a record as long as its memory has not been
  released. 
  \begin{Result}
    The new value of the record flags.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{RecordIsMARKED}}{RecordIsMARKED}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  Check whether the record is marked as deleted.
  \begin{Result}
    |FALSE| iff the |DELETED| flag is not set.
  \end{Result}
\end{Macro}
\begin{Macro}{char * \Mac{RecordOldKey}}{RecordOldKey}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  
  
  
\end{Macro}
\begin{Macro}{char * \Mac{RecordSortkey}}{RecordSortkey}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  This is the functional representation of the sort key
  of a record. This can be used to access the key component
  of a record. It can also be used as lvalue.
  
  Note that the reference key of a normal record is
  stored in the heap at position 0.
\end{Macro}
\begin{Macro}{char ** \Mac{RecordHeap}}{RecordHeap}
  \begin{Arguments}
    & \Var{R} & Record to consider.\\
  \end{Arguments}%
  The heap of a record is a array of strings. The even
  positions contain the names of fields and the
  following array cell contains its value. If the name
  or value is |NULL| then this slot is not used. Thus it
  is easy to delete a field. Simply write a |NULL| into
  the appropriate place.
\end{Macro}
\begin{Macro}{Record \Mac{NextRecord}}{NextRecord}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  This is the functional representation of the next
  record of a record. It can be used to get this value
  as well as an lvalue to set it.
\end{Macro}
\begin{Macro}{Record \Mac{PrevRecord}}{PrevRecord}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  This is the functional representation of the previous
  record of a record. It can be used to get this value
  as well as an lvalue to set it.
\end{Macro}
\begin{Macro}{char * \Mac{RecordComment}}{RecordComment}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  This is the functional representation of the comment
  component of a record. It can be used to get this value
  as well as an lvalue to set it.
\end{Macro}
\begin{Macro}{char * \Mac{RecordSource}}{RecordSource}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  This is the functional representation of the source
  indicator of a record. It is a string containing the
  file name from which this record has been read. The
  empty string is used to denote unknown sources.
  \begin{Result}
    
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{RecordFlags}}{RecordFlags}
  \begin{Arguments}
    & \Var{R} & Record to consider\\
  \end{Arguments}%
  This is the functional representation of the record
  flags. They are extra bits used for arbitrary
  purposes. Right now only the bit with the mask 1  is
  used for selecting the records found in an aux file.
  \begin{Result}
    
  \end{Result}
\end{Macro}

\Module{record.c}{record.c}

\begin{Function}{void \Fct{add\_sort\_order}}{add\_sort\_order}
  \begin{Arguments}
    char *\ 	&\Var{val};	&string resource of the order.
  \end{Arguments}%
  Insert the sort order into the order list.
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{Record \Fct{copy\_record}}{copy\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&The record to copy.
  \end{Arguments}%
  Copy a record and return a new instance.
  If no memory is left then an error is raised and the
  program is terminated. 
  \begin{Result}
    The new copy of |rec|.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_1\_record}}{free\_1\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&record to free
  \end{Arguments}%
  Free the memory occupied by a single record.
  This does not ensure that there is no dangling pointer to
  the record. Thus beware!
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_record}}{free\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Arbitrary Record in the chain.
  \end{Arguments}%
  Release a list of records. All records reachable through a
  previous/next chain are deallocated.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{Record \Fct{new\_record}}{new\_record}
  \begin{Arguments}
    int \ 	&\Var{token};	&The token type of the record.\\
    int \ 	&\Var{size};	&The initial heap size.
  \end{Arguments}%
  Create a new record and return it.
  If no memory is left then an eror is raised and the
  program is terminated. 
  \begin{Result}
    The new record.
  \end{Result}
\end{Function}
\begin{Function}{WordList \Fct{new\_wordlist}}{new\_wordlist}
  \begin{Arguments}
    char * \ 	&\Var{s};	&Initial string to fill in the WordList structure
  \end{Arguments}%
  Allocate a WordList and fill its slots.
  \begin{Result}
    
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{push\_to\_record}}{push\_to\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Pointer to any entry in the chain.\\
    char *\ 	&\Var{s};	&Left hand side of the equation.\\
    char *\ 	&\Var{t};	&Right hand side of the equation.
  \end{Arguments}%
  Put an equation s=t onto the heap of a record.
  If a field s is already there then the value is
  overwritten.  The arguments are expected to be
  synbols. Thus it is not necessary to make private
  copies and it is possible to avoid expensive string
  comparisons. 
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{Record \Fct{record\_gc}}{record\_gc}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Pointer to any entry in the chain.
  \end{Arguments}%
  Garbage collecting a record list. The entries marked
  as deleted are unlinked and the memory is freed. Any
  pointers to such a deleted entry become invalid.
  
  Be careful when using this function!
  \begin{Result}
    Pointer to some entry in the cleared chain or
    |RecordNULL| if none is left.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{sort\_record}}{sort\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Record to sort
  \end{Arguments}%
  The heap is reordered according to the sorting order
  determined by the record type.
  For this purpose a copy of the original record is made and the
  original record is overwritten. The copy is released at the
  end.
  Memory management is easy since all strings are in fact
  symbols, i.e. they must not be freed and comparison is done
  by pointer comparison.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{Record \Fct{unlink\_record}}{unlink\_record}
  \begin{Arguments}
    Record \ 	&\Var{rec};	&Record to free.
  \end{Arguments}%
  Remove a record from a chain and free its memory. The
  chain is modified such that the freed Record is not
  referenced any more. A neighbor in the chain of the
  given record is returned or |NULL| if there is none.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/rewrite.h}{bibtoolrewrite.h}


\Module{rewrite.c}{rewrite.c}

\begin{Function}{void \Fct{add\_check\_rule}}{add\_check\_rule}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Rule to save.
  \end{Arguments}%
  Save a check rule for later use.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_extract}}{add\_extract}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Rule to save.
  \end{Arguments}%
  Save an extraction rule for later use. The argument is
  interpreted as regular expression to be matched
  against the field value.
  
  The value of |rsc_case_select| at the invocation of
  this function determines whether the matching is
  performed case sensitive or not.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_field}}{add\_field}
  \begin{Arguments}
    char *\ 	&\Var{spec};	&A string of the form
  token=value
  \end{Arguments}%
  Save a token and value for addition.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_rewrite\_rule}}{add\_rewrite\_rule}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Rule to save.
  \end{Arguments}%
  Save a rewrite rule for later use.
  The main task is performed by |add_rule()|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{add\_s\_extract}}{add\_s\_extract}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Rule to save.
  \end{Arguments}%
  Save an extraction rule for later use. The argument is
  interpreted as string to be found in the field value.
  The value of |rsc_case_select| at the search time
  determines whether the matching is performed case
  sensitive or not.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{clear\_addlist}}{clear\_addlist}  Reset the addlist to the empty list.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{is\_selected}}{is\_selected}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database containing the record.\\
    Record \ 	&\Var{rec};	&Record to look at.
  \end{Arguments}%
  Boolean function to decide whether a record should be
  considered. These selections are described by a set of
  regular expressions which are applied. If none are
  given then the match simply succeeds.
  \begin{Result}
    |TRUE| iff the record is seleced by a regexp or none is
    given.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{remove\_field}}{remove\_field}
  \begin{Arguments}
    char *\ 	&\Var{field};	&This is a symbol containing the name of the field to remove.\\
    Record \ 	&\Var{rec};	&Record in which the field should be removed.
  \end{Arguments}%
  Remove the given field from record.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{rewrite\_record}}{rewrite\_record}
  \begin{Arguments}
    DB \ 	&\Var{db};	&The database record is belonging to.\\
    Record \ 	&\Var{rec};	&Actual record to apply things to.
  \end{Arguments}%
  Apply deletions, checks, additions, and rewriting steps
  in this order.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{save\_regex}}{save\_regex}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Regular expression to search for.
  \end{Arguments}%
  Save an extraction rule for later use.
  Only the regular expression of the rule is given as argument.
  The fields are taken from the resource select.fields.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/resource.h}{bibtoolresource.h}

This file is the central component of the resource evaluator.
To reduce redundancy everything in this file is encapsulated
with macros. Thus it is possible to adapt the meaning
according to the task to be performed.

This file is included several times from different places. One
task is the definition of certain variables used in this
file. Another task is the execution of the commands associated
with a command name.

This is one place where the power and the beauty of the C
preprocessor make live easy. It should also be fun to find the
three ways in which this file is used. Read the sources and
enjoy it! 

For the normal user this file is consulted automatically when
the header file |rsc.h| is used.


\Header{bibtool/rsc.h}{bibtoolrsc.h}

This header file provides definitions for all resource
variables, i.e.\ the variables defined in the header file
|resource.h|. 

In addition the functions defined in |resource.c| are made
accessible to those modules including this header file.

\Module{rsc.c}{rsc.c}

This module contains functions which deal with resources.
Resources are commands to configure the behaviour of
\BibTool. They can be read either from a file or from a
string. 

The syntax of resources are modelled after the syntax rules
for \BibTeX{} files. See the user's guide for details of the syntax.

\begin{Function}{int \Fct{load\_rsc}}{load\_rsc}
  \begin{Arguments}
    char *\ 	&\Var{name};	&The name of the resource file to read.
  \end{Arguments}%
  This function tries to load a resource file. 
  Details:
  Perform initialization if required.
  The main job is done by |read_rsc()|. This function is located
  in |parse.c| since it shares subroutines with the parser.
  \begin{Result}
    |FALSE| iff the reading failed.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{rsc\_print}}{rsc\_print}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String to print.
  \end{Arguments}%
  Print a string to the error stream as defined in
  |error.h|. The string is automatically augmented by a
  trailing newline.
  This wrapper function is used for the resource |print|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{search\_rsc}}{search\_rsc}  Try to open the resource file at different places:
  \begin{itemize}
  \item In the place indicated by the environment variable
  |RSC_ENV_VAR|. This step is skipped if the macro
  |RSC_ENV_VAR| is not defined (at compile time of the
  module).
  \item In the home directory.  The home directory is
  determined by an environment variable.  The macro
  |HOME_ENV_VAR| contains the name of this environment
  variable. If this macro is not defined (at
  compile time of the module) then this step is skipped.
  \item In the usual place for resource files.
  \end{itemize}
  For each step |load_rsc()| is called until it
  succeeds.
  
  The files sought is determined by the macro
  |DefaultResourceFile| at compile time of the
  module. (see |bibtool.h|)
  \begin{Result}
    |TRUE| iff the resource loading succeeds somewhere.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{set\_rsc}}{set\_rsc}
  \begin{Arguments}
    char * \ 	&\Var{name};	&Name of the resource to set.\\
    char * \ 	&\Var{val};	&The new value of the resource.
  \end{Arguments}%
  Set the resource to a given value. Here the assignment
  is divided into two parts: the name and the value.
  Both arguments are assumed to be symbols.
  \begin{Result}
    |FALSE| iff everything went right.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{use\_rsc}}{use\_rsc}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String containg a resource command.
  \end{Arguments}%
  This function can be used to evaluate a single
  resource instruction. The argument is a string which
  is parsed to extract the resource command.
  
  This is an entry point for command line options which
  set resources. 
  \begin{Result}
    |FALSE| iff no error has occurred.
  \end{Result}
\end{Function}

\Header{bibtool/s\_parse.h}{bibtoolsparse.h}



\Module{s\_parse.c}{sparse.c}

\begin{Function}{char * \Fct{s\_parse}}{s\_parse}
  \begin{Arguments}
    int \ 	&\Var{type};	&is the type of construct to parse. it is defined in s\_parse.h\\
    char **\ 	&\Var{sp};	&is a pointer to the string which is parsed. The value is
changed to hold the remaining characters at the end.\\
    int \ 	&\Var{errp};	&this boolean indicated whether or not a verbose error
message should be created in case of an error.
  \end{Arguments}%
  Parse a string for a certain entity. Leading
  whitespace is ignored. |type| determines which kind of
  entity should be exepected. It can take the following
  values which are defined in |s_parse.h|:
  \begin{description}
  \item[StringParseValue] The string is analyzed and the
  proper type is determined automatically. This can be
  considered as the normal way of operation.
  \item[StringParseSymbol] The string is analyzed and
  only a symbol is accepted, i.e.\ a sequence of
  allowed characters.
  \item[StringParseNumber] The string is analyzed and
  only a number is accepted.
  \item[StringParseBraces] The string is analyzed and
  only an expression in braces is accepted. The braced
  contained must come in matching pairs. The whole
  expression -- including the braces -- is returned.
  \item[StringParseUnquotedBraces] The string is analyzed and
  only an expression in braces is accepted. The braced
  contained must come in matching pairs. The
  expression without the outer braces is returned.
  \item[StringParseString] The string is analyzed and
  only a string enclosed in double quotes is
  accepted. The string must contain braces in matching
  pairs. Double quotes which are inside of braces are
  not considered as end of the string. The whole
  string -- including the double quotes is returned.
  \item[StringParseUnquotedString] The string is analyzed and
  only a string enclosed in double quotes is
  accepted. The string must contain braces in matching
  pairs. Double quotes which are inside of braces are
  not considered as end of the string. The string
  without the outer double quotes is returned.
  \item[StringParseSkip] The string is analyzed and the
  first position not containing whitespace, |=|, or |#|
  is returned. In this case the returned value is not
  translated into a symbol.
  \item[StringParseEOS] The string is analyzed and any
  remaining characters which are not whitespace are
  reported as error. A pointer to the terminating 0 byte
  is returned upon success
  \end{description}
  If an error occurs or the requested entity is not
  found then |NULL| is returned. As a side effect |sp|
  is advanced to point to the next unprocessed
  character.
  
  The string analyzed should be opened at the beginning
  with |sp_open()| in order to get an appropriate error
  message. 
  
  This function is usually not called directly but the
  convenience macros defined in |s_parse.h| should be
  used instead.
  \begin{Result}
    A symbol containing the requested entity or |NULL|.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sp\_open}}{sp\_open}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String to open for parsing.
  \end{Arguments}%
  Open a string for parsing. The argument string is used
  for the parsing process.  Thus this string should not
  be modified during this time.  Especially it should
  not be freed if it is a pointer to dynamically
  allocated memory.
  \begin{Result}
    |TRUE|
  \end{Result}
\end{Function}

\Header{bibtool/stack.h}{bibtoolstack.h}

This module provides access to the functions defined in the
module |stack.c|. The the documentation of this module for
details.


\Module{stack.c}{stack.c}

This module provides a single stack of strings. There are two
operations on this stack, namely to push a string onto the
stack and a pop operation to get the topmost element from the
stack and remove it or to get a signal that the stack is
empty. 

The stack is implemented as an array which grows on demand.
Currently the memory of the stack is not returned to the
operating system. This seems to be not problemeatic since this
memory is not assumed to be really large. Normally just a few
strings are pushed to the stack at any time.

\begin{Function}{char * \Fct{pop\_string}}{pop\_string}  Pop a string from the stack. It the stack is empty
  then |NULL| is returned. Thus the |NULL| value should
  not be pushed to the stack since this can be confused
  with the end of the stack.
  \begin{Result}
    The old top element or |NULL| if the stack is empty.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{push\_string}}{push\_string}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String to push to the stack.
  \end{Arguments}%
  Push a string onto the stack. Only the memory for the
  stack is allocated. The string is stored as pointer to
  existing memory. No copy of the string is made.
  
  If no memory is left then an error is raised and the program
  is terminated.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/sbuffer.h}{bibtoolsbuffer.h}

This header file makes accessible the functions to treat
strings like streams In addition to the functions defined in
|sbuffer.c| one macro is defined here.

\begin{Macro}{\Mac{sbputchar}}{sbputchar}
  \begin{Arguments}
    & \Var{C} & Character to put.\\
    & \Var{SB} & Destination string buffer.\\
  \end{Arguments}%
  Put the character |C| into the string buffer |SB|.
  
  This macro is not sane. The arguments are expanded
  several times. Thus they must not contain side
  effects. 
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}

\Module{sbuffer.c}{sbuffer.c}

This module contains functions for dealing with strings of
aribtrary size. The allocation of memory is done automatically
when more characters are added.

The functions are modeled after the stream functions of C.
Currently a |printf|-like function is missing because one was
not needed yet and it is not so easy to implement---portably. 

The functions in this module are very handy to deal with
strings of arbitrary length where the length is not known in
advance. E.g. consider the case that a line has to be read
from a file |file| and the line length should not be restricted by
some artificial boundry. This can be implemented as follows:
\\
|{ StringBuffer *sb = sb_open();|\Ccomment{Declare and
initialize a string buffer.}\\
|  int c;|\Ccomment{Variable to store a single character.}\\
|  char *s;|\Ccomment{Variable to hold the string at the end.}\\
|  while ( (c=fgetc(file) != EOF|\\
|          && c != '\n')|\\
|  { sbputchar(c,sb); }|\Ccomment{Store each character in the
string buffer.}\\
|  s = sbflush(sb);|\Ccomment{Get the string from the
string buffer.}\\
|  puts(s);|\Ccomment{Process the string; e.g. print it.}\\
|  sb_close(sb);|\Ccomment{Free the string buffer.}\\
|}|

Note that the flushing of the string buffer returns a C string
which is managed by the string buffer.  This memory is freed
or reused whenever the string buffer needs to. Thus you should
make a private copy of this string if it should survive the
next operation of the string buffer. Especially, after the
call to |sb_close()| this memory has been returned to the
operating system and is not available any more.

\begin{Function}{int \Fct{sbclose}}{sbclose}
  \begin{Arguments}
    StringBuffer* \ 	&\Var{sb};	&Pointer to string buffer which should be closed
  \end{Arguments}%
  Free an old string buffer.
  \begin{Result}
    Return 0 upon failure.
  \end{Result}
\end{Function}
\begin{Function}{char* \Fct{sbflush}}{sbflush}
  \begin{Arguments}
    StringBuffer* \ 	&\Var{sb};	&String buffer to close.
  \end{Arguments}%
  Close a string buffer with a trailing |\0| and reset the
  current pointer to the beginning.
  The next write operation starts right at the end. Thus
  additional write operations will overwirte the
  terminating byte.
  \begin{Result}
    The string contained in the string buffer as a proper
    C string.
  \end{Result}
\end{Function}
\begin{Function}{StringBuffer* \Fct{sbopen}}{sbopen}  Allocate a new string buffer.
  Return a pointer to the new string buffer or |NULL| if
  none was available.
  \begin{Result}
    pointer to new string buffer or NULL
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sbputc}}{sbputc}
  \begin{Arguments}
    int \ 	&\Var{c};	&Character to put to the string buffer.\\
    StringBuffer* \ 	&\Var{sb};	&Destination string buffer.
  \end{Arguments}%
  Push a single character onto a string buffer. In
  contrast to the macro this function handles the
  reallocation of the memory. For the user it should not
  make a difference since the macros uses this function
  when needed.
  
  When no memory is left then the character is discarted
  and this action is signalled via the return value.
  \begin{Result}
    |FALSE| if no memory is left.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sbputs}}{sbputs}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String to be pushed.\\
    StringBuffer* \ 	&\Var{sb};	&Destination string buffer.
  \end{Arguments}%
  Push a whole string onto a string buffer.
  \begin{Result}
    |FALSE| if something went wrong.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{sbrewind}}{sbrewind}
  \begin{Arguments}
    StringBuffer* \ 	&\Var{sb};	&String buffer to consider.
  \end{Arguments}%
  Reset the string buffer pointer to the beginning.
  The next write or read will operate there.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sbseek}}{sbseek}
  \begin{Arguments}
    StringBuffer* \ 	&\Var{sb};	&String buffer to reposition.\\
    int \ 	&\Var{pos};	&New position of the string buffer.
  \end{Arguments}%
  Reset the current pointer to the position given. If
  the position is outside the valid region then |TRUE|
  is returned and the position is left unchanged.
  \begin{Result}
    |FALSE| if everything went right.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sbtell}}{sbtell}
  \begin{Arguments}
    StringBuffer* \ 	&\Var{sb};	&String buffer to consider.
  \end{Arguments}%
  Return the current pointer to the string buffer position.
  This can be used with |sbseek()| to reset it.
  \begin{Result}
    The relative byte position of the current writing
    position. This is an integer offset from the beginning
    of the string buffer.
  \end{Result}
\end{Function}

\Header{bibtool/symbols.h}{bibtoolsymbols.h}

This header file contains definitions dealing with symbols.

\BibTool{} uses symbols as the basic representation for
strings.  Symbols are stored in a symbol table and shared
amoung different instances. Thus the same string occurring at
different places has to be stored only once.

Another advantage of symbols is that once you have got two
symbols at hand it is rather easy to compare them for
equality.  A simple pointer comparison is enough. It is not
neccesary to compare them character by character.

The disadvantage of a symbol is that you can not simply modify
it temporarily since it is part of the symbol table. This
symbol table would be in an insane state otherwise. Thus you
always have to make a copy if you want to modify a symbol.

The functions defined in |symbols.c| are exported with this
header file aswell.

\begin{Macro}{char * \Mac{symbol}}{symbol}
  \begin{Arguments}
    & \Var{STR} & String to translate into a symbol.\\
  \end{Arguments}%
  Translate a string into a symbol.
  The symbol returned is either created or an existing
  symbol is returned.
  \begin{Result}
    The symbol corresponding to the argument.
  \end{Result}
\end{Macro}
\begin{Macro}{void \Mac{ReleaseSymbol}}{ReleaseSymbol}
  \begin{Arguments}
    & \Var{SYM} & Symbol to release.\\
  \end{Arguments}%
  The symbol given as argument is released. In fact the
  memory is not really freed but one instance is marked
  as not used any more. At other places the symbol might
  be still required. The freeing of memory is performed
  by the garbage collector |sym_gc()|.
  \begin{Result}
    nothing
  \end{Result}
\end{Macro}
\begin{Variable}{char * \Mac{sym\_empty}}{symempty}
  The empty symbol. This is a symbol pointing
  immediately to a |\0| byte.  This needs
  |init_symbols()| to be called first.
\end{Variable}
\begin{Variable}{char * \Mac{sym\_crossref}}{symcrossref}
  The symbol |crossref|. This variable needs
  |init_symbols()| to be called first.
\end{Variable}

\Module{symbols.c}{symbols.c}

This module contains functions which deal with symbols and
general memory management. 
This module implements a single symbol table.

This module required initialization before all functions can
be used. Especially the symbol table does not exist before
initialization. 

\begin{Function}{void \Fct{init\_symbols}}{init\_symbols}  Initialize the symbols module.
  The symbol table is cleared. This is not secure when
  the symbols have already been initialized because it
  would lead to a memory leak and a violation of the
  symbol comparison assumtion. Thus this case is caught
  and nothing is done when the initialization seems to
  be requested for the second time.
  
  If no more memory is available then an error is raised
  and the program is terminated.
  
  Note that this function is for internal purposes
  only. The normal user should call |init_bibtool()|
  instead.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{new\_string}}{new\_string}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String to duplicate
  \end{Arguments}%
  Allocate a space for a string and copy the argument
  there. Note this is just a new copy of the memory not
  a symbol!
  
  If no more memory is available then an error is raised
  and the program is terminated.
  \begin{Result}
    Pointer to newly allocated memory containing a
    duplicate of the argument string.
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{sym\_add}}{sym\_add}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String which should be translated into a symbol.\\
    int \ 	&\Var{count};	&The use count which should be added t the symbol
  \end{Arguments}%
  Add a symbol to the global symbol table. If the string
  already has a symbol assigned to it then this symbol
  is returned. If the symbol is not static then the use
  count is incremented by |count|.
  
  If the symbol does not exist already then a new symbol
  is added to the symbol table and the use count is
  initialized to |count|. A negative value for |count|
  indicates that a static symbol is requested. A static
  symbol will never bee deleted from the symbol
  table. Static can be used at places where one does not
  care about the memory occupied.
  
  If no more memory is available then an error is raised
  and the program is terminated.
  
  See also the macro |symbol()| in |symbols.h| for a
  convenient alternative to this function.
  \begin{Result}
    The new symbol.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{sym\_dump}}{sym\_dump}  Dump the symbol table to the error stream---see module
  |error.c|. 
  The symbols are printed according to their hash value
  and the sequence they are occurring in the buckets.  A
  summary of the memory used is also printed.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{sym\_flag}}{sym\_flag}
  \begin{Arguments}
    char * \ 	&\Var{s};	&Symbol
  \end{Arguments}%
  Get the flags of the symbol given as argument.
  \begin{Result}
    The flags of the recently touched |StringTab|.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{sym\_set\_flag}}{sym\_set\_flag}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Symbol to augment.\\
    int \ 	&\Var{flags};	&New flags to add.
  \end{Arguments}%
  Add the flags to the symbol corresponding to the
  argument |s| by oring them together with the given
  value. 
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{sym\_unlink}}{sym\_unlink}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Symbol to be released.
  \end{Arguments}%
  Free a symbol since it is no longer used.
  This does not mean that the memory is also freed. The
  symbol can be static or used at other places. The real
  free operation requires that the garbage collector
  |sym_gc()| to be called.
  
  If the argument is |NULL| or an arbitrary string (no
  symbol) then this case is also dealt with.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/tex\_aux.h}{bibtooltexaux.h}


\Module{tex\_aux.c}{texaux.c}

\begin{Function}{int \Fct{apply\_aux}}{apply\_aux}
  \begin{Arguments}
    DB \ 	&\Var{db};	&Database to clean.
  \end{Arguments}%
  This function deletes all entries which are not
  requested by the recently read aux file. This means
  that the entry to be kept is either mentioned directly,
  it is crossreferenced, or all entries are requested
  with the |\nocite{*}| feature.
  
  Note that the entries are in fact not deleted but only
  marked as deleted. Thus they can be recovered if
  necessary. 
  \begin{Result}
    |FALSE| iff all entries are kept because of an
    explicit or implicit star (*).
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{aux\_used}}{aux\_used}
  \begin{Arguments}
    char * \ 	&\Var{s};	&reference key to check
  \end{Arguments}%
  Check whether a reference key has been requested by the
  previously read aux file. The request can either be expicit
  or implicit if a * is used.
  \begin{Result}
    
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{clear\_aux}}{clear\_aux}  Reset the aux table to the initial state.
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{foreach\_aux}}{foreach\_aux}
  \begin{Arguments}
    int (\ 	&\Var{fct})(char*); 	&funtion to apply
  \end{Arguments}%
  Apply the function to all words in the citation list of the
  aux file.
  
  \begin{Result}
    |cite_star|
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{read\_aux}}{read\_aux}
  \begin{Arguments}
    char *\ 	&\Var{fname};	&The file name of the aux file.\\
    void (*\ 	&\Var{fct})(char*); 	&A function to be called for each \BibTeX{} file requested.\\
    int \ 	&\Var{verbose};	&Boolean indicating whether messages should be produced
indicating the status of the operation.
  \end{Arguments}%
  Analyze an aux file. If additional files are
  requested, e.g. by |\include| instructions in the
  original source file then those are read as well. Each
  citation found is remembered and can be queried
  afterwards. If a |\cite{*}| has been used then only a
  flag is set and all citation keys are discarted.
  
  The aux file contains also the information about the
  \BibTeX{} files used. For each such file the function
  |fct| is called with the file name as argument. This
  function can arrange things that those \BibTeX{} files
  are read into a database.
  
  This function has only a very simple parser for the
  aux file. Thus it can be confused by legal
  contents. But a similar thing can happen to \BibTeX{}
  aswell. 
  \begin{Result}
    |TRUE| iff the file could not be opened.
  \end{Result}
\end{Function}

\Header{bibtool/tex\_read.h}{bibtooltexread.h}

This header file provides definitions for the use of functions
to immitate the reading apparatus of \TeX{} which are defined
in |tex_read.c|. 


\Module{tex\_read.c}{texread.c}

This module contains functions which immitate the reading
apparatus of \TeX{}. Macro expansion can be performed. 


\begin{Function}{void \Fct{TeX\_active}}{TeX\_active}
  \begin{Arguments}
    int \ 	&\Var{c};	&Character to make active.\\
    int \ 	&\Var{arity};	&Arity of the macro assigned to the active character.\\
    char * \ 	&\Var{s};	&Body of the definition as string.
  \end{Arguments}%
  Assign a macro to an active character. If the
  character is not active then the catcode is changed.  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_close}}{TeX\_close}  Gracefully terminate the reading of \TeX{} tokens. Any
  remaining pieces of text which have already been
  consumed are discarted.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_def}}{TeX\_def}
  \begin{Arguments}
    char *\ 	&\Var{s};	&
  \end{Arguments}%
  Define a macro.
  The argument is a string specification of the following form:
  
  |\name[arity]=replacement text|\\
  |\name=replacement text|
  
  \(0 <= arity <= 9\)
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_define}}{TeX\_define}
  \begin{Arguments}
    char *\ 	&\Var{name};	&\\
    int \ 	&\Var{arity};	&\\
    char *\ 	&\Var{body};	&
  \end{Arguments}%
  Add a new \TeX{} macro definition.
  
  
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_open\_file}}{TeX\_open\_file}
  \begin{Arguments}
    FILE * \ 	&\Var{file};	&File pointer of the file to read from.
  \end{Arguments}%
  Prepare things to parse from a file.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_open\_string}}{TeX\_open\_string}
  \begin{Arguments}
    char * \ 	&\Var{s};	&String to read from.
  \end{Arguments}%
  Prepare things to parse from a string.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{TeX\_read}}{TeX\_read}
  \begin{Arguments}
    char * \ 	&\Var{cp};	&Pointer to position where the character is stored.\\
    char **\ 	&\Var{sp};	&Pointer to position where the string is stored.
  \end{Arguments}%
  Read a single Token and return it as a pair consisting
  of an ASCII code and possibly a string in case of a
  macro token.
  \begin{Result}
    |FALSE| iff everything went right.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{TeX\_reset}}{TeX\_reset}  Reset the \TeX{} reading apparatus to its initial
  state.  All macros and active characters are cleared
  and the memory is released. Thus this function can
  also be used for this purpose.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/type.h}{bibtooltype.h}

This module is a replacement for the system header file
|ctype.h|. in contrast to some implemetations of the |isalpha|
and friends the macros in this header are stable. This means
that the argument is evaluated exactely once and each macro
consistes of execately one C statement. Thus these macros can
be used even at those places where only a single statement is
allowed (conditionals without braces) or with arguments
containing side effects.

In addition this is a starting point to implement an xord
array like \TeX{} has one (some day\dots)

This header file requires the initializaation function
|init_type()| to be called before all macros will work as
described. 

This header file also provides the functions and varaibles
defined in |type.c|

\begin{Variable}{char* \Mac{trans\_lower}}{translower}
  Translation table mapping upper case letters to lower
  case. Such a translation table can be used as argument
  to the regular expression functions.
\end{Variable}
\begin{Variable}{char* \Mac{trans\_upper}}{transupper}
  Translation table mapping lower case letters to upper
  case. Such a translation table can be used as argument
  to the regular expression functions.
\end{Variable}
\begin{Variable}{char* \Mac{trans\_id}}{transid}
  Translation table performing no translation. Thus it
  implements the identity a translation table can be
  used as argument to the regular expression functions.
\end{Variable}
\begin{Macro}{int \Mac{is\_allowed}}{isallowed}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is an
  allowed character in the sense of \BibTeX.
  \begin{Result}
    |TRUE| iff the argument is an allowed character.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_upper}}{isupper}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  upper case letter.
  (Characters outside the ASCII range are not considered
  letters yet)
  \begin{Result}
    |TRUE| iff the character is an uppercase letter.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_lower}}{islower}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  lower case letter.
  (Characters outside the ASCII range are not considered
  letters yet)
  \begin{Result}
    |TRUE| iff the character is a lowercase letter.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_alpha}}{isalpha}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  letter.
  (Characters outside the ASCII range are not considered
  letters yet)
  \begin{Result}
    |TRUE| iff the character is a letter.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_digit}}{isdigit}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  digit.
  (Characters outside the ASCII range are not considered
  letters yet)
  \begin{Result}
    |TRUE| iff the character is a digit.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_space}}{isspace}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  space character. |'\0'| is not a space character.
  \begin{Result}
    |TRUE| iff the character is a space character.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_extended}}{isextended}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is an
  extended character outside the ASCII range.
  \begin{Result}
    |TRUE| iff the character is an extended character.
  \end{Result}
\end{Macro}
\begin{Macro}{int \Mac{is\_wordsep}}{iswordsep}
  \begin{Arguments}
    & \Var{C} & Character to consider\\
  \end{Arguments}%
  Decide whether the character given as argument is a
  word separator which denotes no word constituent.
  \begin{Result}
    |TRUE| iff the character is a word separator.
  \end{Result}
\end{Macro}
\begin{Macro}{char \Mac{ToLower}}{ToLower}
  \begin{Arguments}
    & \Var{C} & Character to translate\\
  \end{Arguments}%
  Translate a character to it's lower case dual. If the
  character is no upper case letter then the character
  is returned unchanged.
  \begin{Result}
    The lower case letter or the character itself.
  \end{Result}
\end{Macro}
\begin{Macro}{char \Mac{ToUpper}}{ToUpper}
  \begin{Arguments}
    & \Var{C} & Character to translate\\
  \end{Arguments}%
  Translate a character to it's upper case dual. If the
  character is no lower case letter then the character
  is returned unchanged.
  \begin{Result}
    The upper case letter or the character itself.
  \end{Result}
\end{Macro}

\Module{type.c}{type.c}

This file contains functions to support a separate treatment of
character types. The normal functions and macros in |ctype.h| are 
replaced by those in |type.h|. This file contains an initialization
function which is required for the macros in |type.h| to work
properly. 

See also the documentation of the header file |type.h| for
further information.

\begin{Function}{int \Fct{case\_cmp}}{case\_cmp}
  \begin{Arguments}
    char * \ 	&\Var{s};	&First string to consider.\\
    char * \ 	&\Var{t};	&Second string to consider.
  \end{Arguments}%
  Compare two strings ignoring cases. If the strings are
  identical up to differences in case then this function
  returns |TRUE|.
  \begin{Result}
    |FALSE| iff the strings differ.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{init\_type}}{init\_type}  This is the initialization routine for this file. This
  has to be called before some of the macros in |type.h|
  will work as described. It does no harm to call this
  initialization more than once. It just takes some time.
  
  Note that this function is for internal purposes
  only. The normal user should call |init_bibtool()|
  instead.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{char * \Fct{lower}}{lower}
  \begin{Arguments}
    char * \ 	&\Var{s};	&string to convert
  \end{Arguments}%
  Function to translate all letters in a string to lower case.
  \begin{Result}
    The converted string
  \end{Result}
\end{Function}

\Header{bibtool/version.h}{bibtoolversion.h}


\Module{version.c}{version.c}

\begin{Variable}{char * \Mac{bibtool\_version}}{bibtoolversion}
  This string variable contains the version number of
  \BibTool. Usually it is of the form
  \textit{major.minor} where \textit{major} and
  \textit{minor} are the major and minor version
  numbers.  In addition a postfix like |alpha| or a
  patchlevel like |p1| can be present.
\end{Variable}
\begin{Function}{void \Fct{show\_version}}{show\_version}  Print the version number and a short copyright notice
  onto the error stream.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}

\Header{bibtool/wordlist.h}{bibtoolwordlist.h}

\begin{Typedef}{\Type{WordList}}{WordList}
  This data type represents a node in a list of
  strings. This list only provides a next pointer. and
  is prety generic.
  \STRUCT{wORDlIST}
    char            *\ 	&\Member{wl\_word};	& String value of	     
			this node.            \\
    struct wORDlIST *\ 	&\Member{wl\_next};	& Pointer to the next    
			node.                 
  \EndSTRUCT{\Type{SWordList}, \Type{*WordList}}
\end{Typedef}
\begin{Constant}{WordList \Mac{WordNULL}}{WordNULL}
  This is the |NULL| value for a |WordList|. It
  terminates the list and represents the empty node.
\end{Constant}
\begin{Macro}{char * \Mac{ThisWord}}{ThisWord}
  \begin{Arguments}
    & \Var{WL} & |WordList| to consider which is not |WordNULL|.\\
  \end{Arguments}%
  This macro returns the string of a |WordList| node.
  \begin{Result}
    The word stored in this node.
  \end{Result}
\end{Macro}
\begin{Macro}{WordList \Mac{NextWord}}{NextWord}
  \begin{Arguments}
    & \Var{WL} & |WordList| to consider which is not |WordNULL|.\\
  \end{Arguments}%
  This macro returns the next |WordList| node of a given
  |WordList| if this is not |WordNULL|.
  \begin{Result}
    The next |WordList|.
  \end{Result}
\end{Macro}

\Module{wordlist.c}{wordlist.c}

This module contains functions which deal with lists of
words. Those words are in fact simple strings. Thus this
module provides a very general functionality, namely a list of
strings and the associated methods.

\begin{Function}{void \Fct{add\_word}}{add\_word}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String to add to the wordlist.\\
    WordList *\ 	&\Var{wlp};	&Pointer to a wordlist.
  \end{Arguments}%
  Put a string into a word list. The string itself is
  \emph{not} copied. Thus it is highly recommended to
  use symbols as words nevertheless this is not
  required as long as the string |s| persists as long as
  the word list exists. 
  
  The second argument is a pointer to a |WordList|. This
  destination is modified by adding a new node. The use
  of a pointer allows a uniform treatment of empty and
  not empty word lists.
  
  If no memory is left then an error is raised and the program
  is terminated.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{delete\_word}}{delete\_word}
  \begin{Arguments}
    char *\ 	&\Var{s};	&Word to remove.\\
    WordList *\ 	&\Var{wlp};	&Pointer to the wordlist to modify.\\
    void (*\ 	&\Var{fct})(char*); 	&Function to call to free the memory occupied by the word.
  \end{Arguments}%
  Remove a word from a |WordList|. Only the first
  appearance of such a word is removed. I a word is
  found which contains the same string as |s| then the
  associated node is removed from the list and the
  function |fct| is called to free the memory of the
  string in the |WordList| node if the function is not
  |NULL|. In this case the function returns
  |0|. Otherwise |1| is returned. 
  \begin{Result}
    |0| if the word was not found. |1| otherwise.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{find\_word}}{find\_word}
  \begin{Arguments}
    char *\ 	&\Var{s};	&String to find.\\
    WordList \ 	&\Var{wl};	&Word list to search in.
  \end{Arguments}%
  Look up a word in a word list. The comparison is done
  case insensitive. 
  \begin{Result}
    |FALSE| iff the word does not occur in the wordlist.
  \end{Result}
\end{Function}
\begin{Function}{int \Fct{foreach\_word}}{foreach\_word}
  \begin{Arguments}
    WordList \ 	&\Var{wl};	&WordList to traverse.\\
    int (*\ 	&\Var{fct})(char*); 	&function to apply.
  \end{Arguments}%
  Applies the given function |fct| to all elements in
  the |WordList| as long as the function does not return
  0. Thus it can be used to search for a specified word
  -- e.g. determined by matching against a
  template. Another application the the processing of
  all elements in the |WordList|. In this case |fct|
  must always return |TRUE|.
  \begin{Result}
    return value of last function or 1.
  \end{Result}
\end{Function}
\begin{Function}{void \Fct{free\_words}}{free\_words}
  \begin{Arguments}
    WordList *\ 	&\Var{wlp};	&Pointer to the |WordList|.\\
    void (*\ 	&\Var{fct})(char*); 	&Function to be called to free the memory of the word itself.
If it is |NULL| then no function is called.
  \end{Arguments}%
  Release the memory allocated for a list of words.
  All nodes in the list are freed. The function |fct| is
  called to free the memory occupied by the string
  component if it is not |NULL|.
  \begin{Result}
    nothing
  \end{Result}
\end{Function}
