  
  [1X7 Utilities for Bibliographies[0X
  
  A  standard  for collecting references (in particular to mathematical texts)
  is  BibTeX  ([7Xhttp://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/[0m). A
  disadvantage  of BibTeX is that the format of the data is specified with the
  use by LaTeX in mind. The data format is less suited for conversion to other
  document types like plain text or HTML.
  
  In  the first section we describe utilities for using data from BibTeX files
  in [5XGAP[0m.
  
  In the second section we introduce a new XML based data format BibXMLext for
  bibliographies  which seems better suited for other tasks than using it with
  LaTeX.
  
  Another section will describe utilities to deal with BibXMLext data in [5XGAP[0m.
  
  
  [1X7.1 Parsing BibTeX Files[0X
  
  Here  are functions for parsing, normalizing and printing reference lists in
  BibTeX format. The reference describing this format is [Lam85, Appendix B].
  
  [1X7.1-1 ParseBibFiles[0m
  
  [2X> ParseBibFiles( [0X[3Xbibfile1[, bibfile2[, ...]][0X[2X ) _____________________[0Xfunction
  [2X> ParseBibStrings( [0X[3Xstr1[, str2[, ...]][0X[2X ) ___________________________[0Xfunction
  [6XReturns:[0X  list [10X[list of bib-records, list of abbrevs, list of expansions][0m
  
  The  first  function parses the files [3Xbibfile1[0m and so on (if a file does not
  exist the extension [10X.bib[0m is appended) in BibTeX format and returns a list as
  follows:  [10X[entries,  strings, texts][0m. Here [10Xentries[0m is a list of records, one
  record  for  each  reference contained in [3Xbibfile[0m. Then [10Xstrings[0m is a list of
  abbreviations  defined  by  [10X@string[0m-entries  in  [3Xbibfile[0m and [10Xtexts[0m is a list
  which  contains  in  the  corresponding  position  the full text for such an
  abbreviation.
  
  The  second  function  does  the same, but the input is given as [5XGAP[0m strings
  [3Xstr1[0m and so on.
  
  The  records  in  [10Xentries[0m store key-value pairs of a BibTeX reference in the
  form  [10Xrec(key1  = value1, ...)[0m. The names of the keys are converted to lower
  case.  The type of the reference (i.e., book, article, ...) and the citation
  key are stored as components [10X.Type[0m and [10X.Label[0m. The records also have a [10X.From[0m
  field that says that the data are read from a BibTeX source.
  
  As an example consider the following BibTeX file.
  
  [4X-------------------------  doc/test.bib  -------------------------[0X
    [4X@string{ j  = "Important Journal" }[0X
    [4X@article{ AB2000, Author=  "Fritz A. First and Sec, X. Y.", [0X
    [4XTITLE="Short", journal = j, year = 2000 }[0X
  [4X------------------------------------------------------------------[0X
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibFiles("doc/test.bib");[0X
    [4X[ [ rec( From := rec( BibTeX := true ), Type := "article", [0X
    [4X          Label := "AB2000", author := "Fritz A. First and Sec, X. Y."[0X
    [4X            , title := "Short", journal := "Important Journal", [0X
    [4X          year := "2000" ) ], [ "j" ], [ "Important Journal" ] ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.1-2 NormalizedNameAndKey[0m
  
  [2X> NormalizedNameAndKey( [0X[3Xnamestr[0X[2X ) __________________________________[0Xfunction
  [6XReturns:[0X  list of strings and names as lists
  
  [2X> NormalizeNameAndKey( [0X[3Xr[0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  The  argument  [3Xnamestr[0m  must  be  a string describing an author or a list of
  authors as described in the BibTeX documentation in [Lam85, Appendix B 1.2].
  The  function  [2XNormalizedNameAndKey[0m  returns a list of the form [ normalized
  name  string,  short  key,  long  key, names as lists]. The first entry is a
  normalized  form  of  the  input where names are written as "lastname, first
  name initials". The second and third entry are the name parts of a short and
  long  key  for  the  bibliography  entry, formed from the (initials of) last
  names.  The fourth entry is a list of lists, one for each name, where a name
  is described by three strings for the last name, the first name initials and
  the first name(s) as given in the input.
  
  Note  that  the  determination of the initials is limited to names where the
  first  letter  is described by a single character (and does not contain some
  markup, say for accents).
  
  The  function  [2XNormalizeNameAndKey[0m  gets  as  argument  [3Xr[0m  a  record  for  a
  bibliography  entry  as  returned  by  [2XParseBibFiles[0m ([14X7.1-1[0m). It substitutes
  [10X.author[0m  and  [10X.editor[0m  fields  of  [3Xr[0m  by their normalized form, the original
  versions are stored in fields [10X.authororig[0m and [10X.editororig[0m.
  
  Furthermore  a  short  and  a  long  citation key is generated and stored in
  components [10X.printedkey[0m (only if no [10X.key[0m is already bound) and [10X.keylong[0m.
  
  We continue the example from [2XParseBibFiles[0m ([14X7.1-1[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibFiles("doc/test.bib");;[0X
    [4Xgap> NormalizedNameAndKey(bib[1][1].author);[0X
    [4X[ "First, F. A. and Sec, X. Y.", "FS", "firstsec", [0X
    [4X  [ [ "First", "F. A.", "Fritz A." ], [ "Sec", "X. Y.", "X. Y." ] ] ][0X
    [4Xgap> NormalizeNameAndKey(bib[1][1]);[0X
    [4Xgap> bib[1][1];[0X
    [4Xrec( From := rec( BibTeX := true ), Type := "article", [0X
    [4X  Label := "AB2000", author := "First, F. A. and Sec, X. Y.", [0X
    [4X  title := "Short", journal := "Important Journal", year := "2000", [0X
    [4X  authororig := "Fritz A. First and Sec, X. Y.", printedkey := "FS00",[0X
    [4X  keylong := "firstsec2000" )[0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.1-3 WriteBibFile[0m
  
  [2X> WriteBibFile( [0X[3Xbibfile, bib[0X[2X ) _____________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  This  is  the converse of [2XParseBibFiles[0m ([14X7.1-1[0m). Here [3Xbib[0m either must have a
  format as list of three lists as it is returned by [2XParseBibFiles[0m ([14X7.1-1[0m). Or
  [3Xbib[0m  can  be  a  record as returned by [2XParseBibXMLextFiles[0m ([14X7.3-4[0m). A BibTeX
  file  [3Xbibfile[0m is written and the entries are formatted in a uniform way. All
  given abbreviations are used while writing this file.
  
  We continue the example from [2XNormalizeNameAndKey[0m ([14X7.1-2[0m). The command
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> WriteBibFile("nicer.bib", bib);[0X
  [4X------------------------------------------------------------------[0X
  
  produces a file [11Xnicer.bib[0m as follows:
  
  [4X--------------------------  nicer.bib  ---------------------------[0X
    [4X@string{j = "Important Journal" }[0X
    [4X[0X
    [4X@article{ AB2000,[0X
    [4X  author =           {First, F. A. and Sec, X. Y.},[0X
    [4X  title =            {Short},[0X
    [4X  journal =          j,[0X
    [4X  year =             {2000},[0X
    [4X  authororig =       {Fritz A. First and Sec, X. Y.},[0X
    [4X  keylong =          {firstsec2000},[0X
    [4X  printedkey =       {FS00}[0X
    [4X}[0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.1-4 InfoBibTools[0m
  
  [2X> InfoBibTools____________________________________________________[0Xinfo class
  
  The  default  level  of  this  info class is 1. Functions like [2XParseBibFiles[0m
  ([14X7.1-1[0m), [10XStringBibAs...[0m are then printing some information. You can suppress
  it by setting the level of [2XInfoBibTools[0m to 0. With level 2 there may be some
  more information for debugging purposes.
  
  
  [1X7.2 The BibXMLext Format[0X
  
  Bibliographical  data  in BibTeX files have the disadvantage that the actual
  data  are given in LaTeX syntax. This makes it difficult to use the data for
  anything but for LaTeX, say for representations of the data as plain text or
  HTML.  For  example:  mathematical  formulae  are  in  LaTeX [10X$[0m environments,
  non-ASCII  characters  can  be  specified  in  many strange ways, and how to
  specify URLs for links if the output format allows them?
  
  Here  we propose an XML data format for bibliographical data which addresses
  these problems, it is called BibXMLext. In the next section we describe some
  tools  for  generating  (an  approximation  to) this data format from BibTeX
  data, and for using data given in BibXMLext format for various purposes.
  
  The   first   motivation   for   this   development   was  the  handling  of
  bibliographical  data  in [5XGAPDoc[0m, but the format and the tools are certainly
  useful for other purposes as well.
  
  We  started  from  a  DTD  [11Xbibxml.dtd[0m  which is publicly available, say from
  [7Xhttp://bibtexml.sf.net/[0m.   This   is  essentially  a  reformulation  of  the
  definition  of  the  BibTeX  format,  including  several of some widely used
  further fields. This has already the advantage that a generic XML parser can
  check  the  validity of the data entries, for example for missing compulsary
  fields in entries. We applied the following changes and extensions to define
  the  DTD  for BibXMLext, stored in the file [11Xbibxmlext.dtd[0m which can be found
  in the root directory of this [5XGAPDoc[0m package (and in Appendix [14XC[0m):
  
  [8Xnames[0m
        Lists of names in the [10Xauthor[0m and [10Xeditor[0m fields in BibTeX are difficult
        to  parse.  Here  they  must be given by a sequence of [10X<name>[0m-elements
        which  each  contain an optional [10X<first>[0m- and a [10X<last>[0m-element for the
        first and last names, respectively.
  
  [8X[10X<M>[0m[8X and [10X<Math>[0m[8X[0m
        These  elements  enclose  mathematical  formulae, the content is LaTeX
        code  (without  the [10X$[0m). These should be handled in the same way as the
        elements  with  the  same  names  in  [5XGAPDoc[0m,  see [14X3.8-2[0m and [14X3.8-1[0m. In
        particular,  simple  formulae  which  have  a  well defined plain text
        representation can be given in [10X<M>[0m-elements.
  
  [8XEncoding[0m
        Note  that  in  XML  files  we  can  use  the  full  range  of unicode
        characters,  see  [7Xhttp://www.unicode.org/[0m.  All  non-ASCII  characters
        should  be  specified  as  unicode characters. This makes dealing with
        special  characters  easy  for  plain  text or HTML, only for use with
        LaTeX some sort of translation is necessary.
  
  [8X[10X<URL>[0m[8X[0m
        These  elements  are  allowed  everywhere  in  the  text and should be
        represented by links in converted formats which allow this. It is used
        in  the  same  way  as  the  element with the same name in [5XGAPDoc[0m, see
        [14X3.5-5[0m.
  
  [8X[10X<Alt Only="...">[0m[8X and [10X<Alt Not="...">[0m[8X[0m
        Sometimes  information should be given in different ways, depending on
        the   output   format   of   the  data.  This  is  possible  with  the
        [10X<Alt>[0m-elements with the same definition as in [5XGAPDoc[0m, see [14X3.9-1[0m.
  
  [8X[10X<C>[0m[8X[0m
        This  element  should  be  used  to  protect text from case changes by
        converters (the extra [10X{}[0m characters in BibTeX title fields).
  
  [8X[10X<string key="..." value="..."/>[0m[8X and 
  [10X<value key="..."/>[0m[8X[0m
        The  [10X<string>[0m-element defines key-value pairs which can be used in any
        field  via  the  [10X<value>[0m-element  (not  only for whole fields but also
        parts of the text).
  
  [8X[10X<other type="...">[0m[8X[0m
        This  is  a  generic  element  for  fields  which  are  otherwise  not
        supported.  An  arbitrary number of them is allowed for each entry, so
        any kind of additional data can be added to entries.
  
  [8X[10X<Wrap Name="...">[0m[8X[0m
        This generic element is allowed inside all fields. This markup will be
        just  ignored (but not the element content) by our standard tools. But
        it  can be a useful hook for introducing arbitrary further markup (and
        our tools can easily be extended to handle it).
  
  [8XExtra entities[0m
        The  DTD  defines  the  standard XML entities ([14X2.1-10[0m and the entities
        [10X&nbsp;[0m  (non-breakable space), [10X&ndash;[0m and [10X&copyright;[0m. Use [10X&ndash;[0m in
        page ranges.
  
  For  further  details  of  the DTD we refer to the file [11Xbibxmlext.dtd[0m itself
  which  is  shown in appendix [14XC[0m. That file also recalls some information from
  the  BibTeX  documentation  on  how the standard fields of entries should be
  used.  Which entry types and which fields are supported (and the ordering of
  the  fields  which  is  fixed  by  a DTD) can be either read off the DTD, or
  within [5XGAP[0m one can use the function [2XTemplateBibXML[0m ([14X7.3-10[0m) to get templates
  for the various entry types.
  
  Here is an example of a BibXMLext document:
  
  [4X-----------------------  doc/testbib.xml  ------------------------[0X
    [4X<?xml version="1.0" encoding="UTF-8"?>[0X
    [4X<!DOCTYPE file SYSTEM "bibxmlext.dtd">[0X
    [4X<file>[0X
    [4X<string key="j" value="Important Journal"/>[0X
    [4X<entry id="AB2000"><article>[0X
    [4X  <author>[0X
    [4X    <name><first>Fritz A.</first><last>First</last></name>[0X
    [4X    <name><first>X. Y.</first><last>Sec&#x0151;nd</last></name>[0X
    [4X  </author>  [0X
    [4X  <title>The <Wrap Name="Package"> <C>F</C>ritz</Wrap> package for the [0X
    [4X         formula <M>x^y - l_{{i+1}} \rightarrow \mathbb{R}</M></title>[0X
    [4X  <journal><value key="j"/></journal>[0X
    [4X  <year>2000</year>[0X
    [4X  <number>13</number>[0X
    [4X  <pages>13&ndash;25</pages>[0X
    [4X  <note>Online data at <URL Text="Bla Bla Publisher">[0X
    [4X                  http://www.publish.com/~ImpJ/123#data</URL></note>[0X
    [4X  <other type="mycomment">very useful</other>[0X
    [4X</article></entry>[0X
    [4X</file>[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  There  is  a  standard  XML header and a [10XDOCTYPE[0m declaration refering to the
  [11Xbibxmlext.dtd[0m  DTD  mentioned  above. Local entities could be defined in the
  [10XDOCTYPE[0m  tag  as  shown  in  the example in [14X2.2-3[0m. The actual content of the
  document   is   inside  a  [10X<file>[0m-element,  it  consists  of  [10X<string>[0m-  and
  [10X<entry>[0m-elements.  Several  of  the  BibXMLext markup features are shown. We
  will use this input document for some examples below.
  
  
  [1X7.3 Utilities for BibXMLext data[0X
  
  
  [1X7.3-1 Translating BibTeX to BibXMLext[0X
  
  First  we  describe  a  tool  which  can translate bibliography entries from
  BibTeX  data  to BibXMLext [10X<entry>[0m-elements. It also does some validation of
  the  data.  In  some  cases  it  is  desirable to improve the result by hand
  afterwards  (editing  formulae, adding [10X<URL>[0m-elements, translating non-ASCII
  characters to unicode, ...).
  
  See  [2XWriteBibXMLextFile[0m  ([14X7.3-5[0m)  below  for  how  to write the results to a
  BibXMLext file.
  
  [1X7.3-2 HeuristicTranslationsLaTeX2XML.Apply[0m
  
  [2X> HeuristicTranslationsLaTeX2XML.Apply( [0X[3Xstr[0X[2X ) ______________________[0Xfunction
  [6XReturns:[0X  a string
  
  [2X> HeuristicTranslationsLaTeX2XML.ApplyFile( [0X[3Xfnam[, outnam][0X[2X ) _______[0Xfunction
  [6XReturns:[0X  nothing
  
  These  utilities  translate some LaTeX code into text in UTF-8 encoding. The
  input is given as a string [3Xstr[0m, or a file name [3Xfnam[0m, respectively. The first
  function  returns  the  translated  string.  The  second  function  with one
  argument overwrites the given file with the translated text. Optionally, the
  translated file content can be written to another file, if its name is given
  as second argument [3Xoutnam[0m.
  
  The  record  [10XHeuristicTranslationsLaTeX2XML[0m  mainly contains translations of
  LaTeX  macros  for special characters which were found in hundreds of BibTeX
  entries  from MathSciNet ([7Xhttp://www.ams.org/mathscinet/[0m). Just look at this
  record  if  you  want to know how it works. It is easy to extend, and if you
  have  improvements which may be of general interest, please send them to the
  [5XGAPDoc[0m author.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> s := "\\\"u\\'{e}\\`e{\\ss}";;[0X
    [4Xgap> Print(s, "\n");               [0X
    [4X\"u\'{e}\`e{\ss}[0X
    [4Xgap> Print(HeuristicTranslationsLaTeX2XML.Apply(s),"\n");[0X
    [4Xüéèß[0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.3-3 StringBibAsXMLext[0m
  
  [2X> StringBibAsXMLext( [0X[3Xbibentry[, abbrvs, vals][, encoding][0X[2X ) ________[0Xfunction
  [6XReturns:[0X  a string with XML code, or [9Xfail[0m
  
  The  argument [3Xbibentry[0m is a record representing an entry from a BibTeX file,
  as  returned  in  the first list of the result of [2XParseBibFiles[0m ([14X7.1-1[0m). The
  optional  two  arguments  [3Xabbrvs[0m  and [3Xvals[0m can be lists of abbreviations and
  substitution  strings,  as  returned as second and third list element in the
  result  of  [2XParseBibFiles[0m  ([14X7.1-1[0m). The optional argument [3Xencoding[0m specifies
  the  character encoding of the string components of [3Xbibentry[0m. If this is not
  given  it is checked if all strings are valid UTF-8 encoded strings, in that
  case it is assumed that the encoding is UTF-8, otherwise the latin1 encoding
  is assumed.
  
  The  function  [2XStringBibAsXMLext[0m  creates  XML code of an [10X<entry>[0m-element in
  [10XBibXMLext[0m  format.  The  result  is  in  UTF-8  encoding  and  contains some
  heuristic  translations,  like  splitting  name  lists,  finding  places for
  [10X<C>[0m-elements,   putting   formulae   in   [10X<M>[0m-elements,   substituting  some
  characters.  The result should always be checked and maybe improved by hand.
  Some  validity  checks  are  applied  to  the given data, for example if all
  non-optional  fields  are  given.  If  this check fails the function returns
  [9Xfail[0m.
  
  If your BibTeX input contains LaTeX markup for special characters, it can be
  convenient to translate this input with [2XHeuristicTranslationsLaTeX2XML.Apply[0m
  ([14X7.3-2[0m)  or  [2XHeuristicTranslationsLaTeX2XML.ApplyFile[0m ([14X7.3-2[0m) before parsing
  it as BibTeX.
  
  As  an example we consider again the short BibTeX file [11Xdoc/test.bib[0m shown in
  the example for [2XParseBibFiles[0m ([14X7.1-1[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibFiles("doc/test.bib");;[0X
    [4Xgap> str := StringBibAsXMLext(bib[1][1], bib[2], bib[3]);;[0X
    [4Xgap> Print(str, "\n");[0X
    [4X<entry id="AB2000"><article>[0X
    [4X  <author>[0X
    [4X    <name><first>Fritz A.</first><last>First</last></name>[0X
    [4X    <name><first>X. Y.</first><last>Sec</last></name>[0X
    [4X  </author>  [0X
    [4X  <title>Short</title>[0X
    [4X  <journal><value key="j"/></journal>[0X
    [4X  <year>2000</year>[0X
    [4X</article></entry>[0X
  [4X------------------------------------------------------------------[0X
  
  The following functions allow parsing of data which are already in BibXMLext
  format.
  
  [1X7.3-4 ParseBibXMLextString[0m
  
  [2X> ParseBibXMLextString( [0X[3Xstr[0X[2X ) ______________________________________[0Xfunction
  [2X> ParseBibXMLextFiles( [0X[3Xfname1[, fname2[, ...]][0X[2X ) ___________________[0Xfunction
  [6XReturns:[0X  a record with fields [10X.entries[0m, [10X.strings[0m and [10X.entities[0m
  
  The  first  function  gets a string [3Xstr[0m containing a [10XBibXMLext[0m document or a
  part  of  it.  It  returns  a  record  with the three mentioned fields. Here
  [10X.entries[0m  is  a  list of partial XML parse trees for the [10X<entry>[0m-elements in
  [3Xstr[0m.   The   field   [10X.strings[0m   is  a  list  of  key-value  pairs  from  the
  [10X<string>[0m-elements  in [3Xstr[0m. And [10X.strings[0m is a list of name-value pairs of the
  named entities which were used during the parsing.
  
  The second function [2XParseBibXMLextFiles[0m uses the first on the content of all
  files  given  by  filenames  [3Xfname1[0m  and so on. It collects the results in a
  single record.
  
  As an example we parse the file [11Xtestbib.xml[0m shown in [14X7.2[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibXMLextFiles("doc/testbib.xml");;[0X
    [4Xgap> RecFields(bib);[0X
    [4X[ "entries", "strings", "entities" ][0X
    [4Xgap> bib.entries;[0X
    [4X[ <BibXMLext entry: AB2000> ][0X
    [4Xgap> bib.strings;[0X
    [4X[ [ "j", "Important Journal" ] ][0X
    [4Xgap> bib.entities[1]; [0X
    [4X[ "amp", "&#38;#38;" ][0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.3-5 WriteBibXMLextFile[0m
  
  [2X> WriteBibXMLextFile( [0X[3Xfname, bib[0X[2X ) _________________________________[0Xfunction
  [6XReturns:[0X  nothing
  
  This function writes a BibXMLext file with name [3Xfname[0m.
  
  There  are  three  possibilities  to specify the bibliography entries in the
  argument  [3Xbib[0m.  It can be a list of three lists as returned by [2XParseBibFiles[0m
  ([14X7.1-1[0m).  Or  it can be just the first of such three lists in which case the
  other  two lists are assumed to be empty. To all entries of the (first) list
  the  function [2XStringBibAsXMLext[0m ([14X7.3-3[0m) is applied and the resulting strings
  are written to the result file.
  
  The  third  possibility is that [3Xbib[0m is a record in the format as returned by
  [2XParseBibXMLextString[0m  ([14X7.3-4[0m)  and [2XParseBibXMLextFiles[0m ([14X7.3-4[0m). In this case
  the  entries  for  the  BibXMLext  file  are  produced with [2XStringXMLElement[0m
  ([14X5.2-2[0m), and if [3Xbib[0m[10X.entities[0m is bound then it is tried to resubstitute parts
  of the string by the given entities with [2XEntitySubstitution[0m ([14X5.2-3[0m).
  
  As   an  example  we  write  back  the  result  of  the  example  shown  for
  [2XParseBibXMLextFiles[0m ([14X7.3-4[0m) to an equivalent XML file.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibXMLextFiles("doc/testbib.xml");;[0X
    [4Xgap> WriteBibXMLextFile("test.xml", bib);[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X7.3-6 Bibliography Entries as Records[0X
  
  For  working with BibXMLext entries we find it convenient to first translate
  the parse tree of an entry, as returned by [2XParseBibXMLextFiles[0m ([14X7.3-4[0m), to a
  record  with  the  field names of the entry as components whose value is the
  content  of the field as string. These strings are generated with respect to
  a result type. The records are generated by the following function which can
  be customized by the user.
  
  [1X7.3-7 RecBibXMLEntry[0m
  
  [2X> RecBibXMLEntry( [0X[3Xentry[, restype][, strings][, options][0X[2X ) _________[0Xfunction
  [6XReturns:[0X  a record with fields as strings
  
  This  function  generates  a content string for each field of a bibliography
  entry  and assigns them to record components. This content may depend on the
  requested result type and possibly some given options.
  
  The  arguments are as follows: [3Xentry[0m is the parse tree of an [10X<entry>[0m element
  as  returned by [2XParseBibXMLextString[0m ([14X7.3-4[0m) or [2XParseBibXMLextFiles[0m ([14X7.3-4[0m).
  The optional argument [3Xrestype[0m describes the type of the result. This package
  supports  currently  the  types  [10X"BibTeX"[0m, [10X"Text"[0m and [10X"HTML"[0m. The default is
  [10X"BibTeX"[0m. The optional argument [3Xstrings[0m must be a list of key-value pairs as
  returned  in  the  component  [10X.strings[0m in the result of [2XParseBibXMLextString[0m
  ([14X7.3-4[0m). The argument [3Xoptions[0m must be a record.
  
  If  the  entry  contains an [10Xauthor[0m field then the result will also contain a
  component  [10X.authorAsList[0m  which  is a list containing for each author a list
  with  three entries of the form [10X[last name, first name initials, first name][0m
  (the  third  entry means the first name as given in the data). Similarly, an
  [10Xeditor[0m field is accompanied by a component [10X.editorAsList[0m.
  
  The following [3Xoptions[0m are currently supported.
  
  If [10Xoptions.fullname[0m is bound and set to [9Xtrue[0m then the full given first names
  for  authors and editors will be used, the default is to use the initials of
  the  first  names.  Also,  if [10Xoptions.namefirstlast[0m is bound and set to [9Xtrue[0m
  then  the  names  are  written  in  the  form "first-name(s) last-name", the
  default is the form "last-name, first-name(s)".
  
  If [10Xoptions.href[0m is bound and set to [9Xfalse[0m then the [10X"BibTeX"[0m type result will
  not  use  [10X\href[0m  commands.  The  default  is  to produce [10X\href[0m commands from
  [10X<URL>[0m-elements  such  that LaTeX with the [10Xhyperref[0m package can produce links
  for them.
  
  The  content  of an [10X<Alt>[0m-element with [10XOnly[0m-attribute is included if [3Xrestype[0m
  is given in the attribute and ignored otherwise, and vice versa in case of a
  [10XNot[0m-attribute.  If  [10Xoptions.useAlt[0m is bound, it must be a list of strings to
  which  [3Xrestype[0m  is  added.  Then  an  [10X<Alt>[0m-element  with  [10XOnly[0m-attribute is
  evaluated  if  the intersection of [10Xoptions.useAlt[0m and the types given in the
  attribute  is not empty. In case of a [10XNot[0m-attribute the element is evaluated
  if this intersection is empty.
  
  If  [3Xrestype[0m is [10X"BibTeX"[0m then the string fields in the result will be recoded
  with  [2XEncode[0m  ([14X6.2-2[0m) and target [10X"LaTeX"[0m. If [10Xoptions.hasLaTeXmarkup[0m is bound
  and  set  to  [9Xtrue[0m  (for  example, because the data are originally read from
  BibTeX files), then the target [10X"LaTeXleavemarkup"[0m will be used.
  
  We use again the file shown in the example for [2XParseBibXMLextFiles[0m ([14X7.3-4[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibXMLextFiles("doc/testbib.xml");;[0X
    [4Xgap> e := bib.entries[1];; strs := bib.strings;;[0X
    [4Xgap> Print(RecBibXMLEntry(e, "BibTeX", strs), "\n");[0X
    [4Xrec([0X
    [4X  From := rec([0X
    [4X      BibXML := true,[0X
    [4X      type := "BibTeX",[0X
    [4X      options := rec([0X
    [4X           ) ),[0X
    [4X  Label := "AB2000",[0X
    [4X  Type := "article",[0X
    [4X  authorAsList := [0X
    [4X   [ [ "First", "F. A.", "Fritz A." ], [ "Sec\305\221nd", "X. Y.", [0X
    [4X          "X. Y." ] ],[0X
    [4X  author := "First, F. A. and Sec{\\H o}nd, X. Y.",[0X
    [4X  title := [0X
    [4X   "The \\textsf{ {F}ritz} package for the \n         formula $x^y - l\[0X
    [4X_{{i+1}} \\rightarrow \\mathbb{R}$",[0X
    [4X  journal := "Important Journal",[0X
    [4X  year := "2000",[0X
    [4X  number := "13",[0X
    [4X  pages := "13{\\textendash}25",[0X
    [4X  note := [0X
    [4X   "Online data at \\href {http://www.publish.com/~ImpJ/123#data} {Bla\[0X
    [4X Bla Publisher}",[0X
    [4X  mycomment := "very useful",[0X
    [4X  printedkey := "FS00" )[0X
    [4Xgap> Print(RecBibXMLEntry(e, "HTML", strs).note, "\n");[0X
    [4XOnline data at <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla\[0X
    [4X Publisher</a>[0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.3-8 AddHandlerBuildRecBibXMLEntry[0m
  
  [2X> AddHandlerBuildRecBibXMLEntry( [0X[3Xelementname, restype, handler[0X[2X ) ___[0Xfunction
  [6XReturns:[0X  nothing
  
  The argument [3Xelementname[0m must be the name of an entry field supported by the
  BibXMLext  format, the name of one of the special elements [10X"C"[0m, [10X"M"[0m, [10X"Math"[0m,
  [10X"URL"[0m  or  of  the  form  [10X"Wrap:myname"[0m  or  any string [10X"mytype"[0m (which then
  corresponds  to entry fields [10X<other type="mytype">[0m). The string [10X"Finish"[0m has
  an exceptional meaning, see below.
  
  [3Xrestype[0m  is  a  string  describing  the result type for which the handler is
  installed, see [2XRecBibXMLEntry[0m ([14X7.3-7[0m).
  
  For  both  arguments,  [3Xelementname[0m  and [3Xrestype[0m, it is also possible to give
  lists of the described ones for installing several handler at once.
  
  The  argument  [3Xhandler[0m  must  be  a function with five arguments of the form
  [3Xhandler[0m[10X(entry,  r, restype, strings, options)[0m. Here [3Xentry[0m is a parse tree of
  a  BibXMLext  [10X<entry>[0m-element,  [3Xr[0m  is  a  node  in  this tree for an element
  [3Xelementname[0m,   and   [3Xrestype[0m,  [3Xstrings[0m  and  [3Xoptions[0m  are  as  explained  in
  [2XRecBibXMLEntry[0m ([14X7.3-7[0m). The function should return a string representing the
  content  of  the  node  [3Xr[0m.  If  [3Xelementname[0m is of the form [10X"Wrap:myname"[0m the
  handler is used for elements of form [10X<Wrap Name="myname">...</Wrap>[0m.
  
  If  [3Xelementname[0m  is  [10X"Finish"[0m the handler should look like above except that
  now  [3Xr[0m  is  the record generated by [2XRecBibXMLEntry[0m ([14X7.3-7[0m) just before it is
  returned.  Here  the  handler  should  return  nothing.  It  can  be used to
  manipulate  the  record  [3Xr[0m,  for  example  for  changing the encoding of the
  strings or for adding some more components.
  
  The  installed  handler  is called by [10XBuildRecBibXMLEntry([0m[3Xentry[0m, [3Xr[0m, [3Xrestype[0m,
  [3Xstrings[0m,  [3Xoptions[0m[10X)[0m.  The  string  for the whole content of an element can be
  generated   by   [10XContentBuildRecBibXMLEntry([0m[3Xentry[0m,   [3Xr[0m,   [3Xrestype[0m,  [3Xstrings[0m,
  [3Xoptions[0m[10X)[0m.
  
  We  continue  the  example from [2XRecBibXMLEntry[0m ([14X7.3-7[0m) and install a handler
  for  the [10X<Wrap Name="Package">[0m-element such that LaTeX puts its content in a
  sans serif font.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX",[0X
    [4X> function(entry,  r, restype,  strings, options)[0X
    [4X>   return Concatenation("\\textsf{", ContentBuildRecBibXMLEntry([0X
    [4X>             entry, r, restype,  strings, options), "}");[0X
    [4X> end);[0X
    [4Xgap> [0X
    [4Xgap> Print(RecBibXMLEntry(e, "BibTeX", strs).title, "\n");[0X
    [4XThe \textsf{ {F}ritz} package for the [0X
    [4X         formula $x^y - l_{{i+1}} \rightarrow \mathbb{R}$[0X
    [4Xgap> Print(RecBibXMLEntry(e, "Text", strs).title, "\n");  [0X
    [4XThe  Fritz package for the [0X
    [4X         formula x^y - l_{i+1} -> R[0X
  [4X------------------------------------------------------------------[0X
  
  [1X7.3-9 StringBibXMLEntry[0m
  
  [2X> StringBibXMLEntry( [0X[3Xentry[, restype][, strings][, options][0X[2X ) ______[0Xfunction
  [6XReturns:[0X  a string
  
  The  arguments  of  this function have the same meaning as in [2XRecBibXMLEntry[0m
  ([14X7.3-7[0m) but the return value is a string representing the bibliography entry
  in a format specified by [3Xrestype[0m (default is [10X"BibTeX"[0m).
  
  Currently, the following cases for [3Xrestype[0m are supported:
  
  [8X[10X"BibTeX"[0m[8X[0m
        A string with BibTeX source code is generated.
  
  [8X[10X"Text"[0m[8X[0m
        A  text  representation  of  the  text is returned. If [10Xoptions.ansi[0m is
        bound  it  must be a record. The components must have names [10XBib_Label[0m,
        [10XBib_author[0m,  and so on for all fieldnames. The value of each component
        is  a  pair  of strings which will enclose the content of the field in
        the result or the first of these strings in which case the default for
        the  second  is  [10XTextAttr.reset[0m (see [2XTextAttr[0m ([14X6.1-2[0m)). If you give an
        empty record here, some default ANSI color markup will be used.
  
  [8X[10X"HTML"[0m[8X[0m
        An HTML representation of the bibliography entry is returned. The text
        from  each  field  is enclosed in markup (mostly [10X<span>[0m-elements) with
        the  [10Xclass[0m  attribute  set  to  the field name. This allows a detailed
        layout of the code via a style sheet file.
  
  We use again the file shown in the example for [2XParseBibXMLextFiles[0m ([14X7.3-4[0m).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> bib := ParseBibXMLextFiles("doc/testbib.xml");;[0X
    [4Xgap> e := bib.entries[1];; strs := bib.strings;;[0X
    [4Xgap> ebib := StringBibXMLEntry(e, "BibTeX", strs);;[0X
    [4Xgap> PrintFormattedString(ebib);[0X
    [4X@article{ AB2000,[0X
    [4X  author =           {First, F. A. and Sec{\H o}nd, X. Y.},[0X
    [4X  title =            {The  \textsf{  {F}ritz} package for the formula $x^y -[0X
    [4X                      l_{{i+1}} \rightarrow \mathbb{R}$},[0X
    [4X  journal =          {Important Journal},[0X
    [4X  number =           {13},[0X
    [4X  year =             {2000},[0X
    [4X  pages =            {13{\textendash}25},[0X
    [4X  note =             {Online             data            at            \href[0X
    [4X                      {http://www.publish.com/~ImpJ/123#data}    {Bla    Bla[0X
    [4X                      Publisher}},[0X
    [4X  mycomment =        {very useful},[0X
    [4X  printedkey =       {FS00}[0X
    [4X}[0X
    [4Xgap> etxt := StringBibXMLEntry(e, "Text", strs);;      [0X
    [4Xgap> etxt := SimplifiedUnicodeString(Unicode(etxt), "latin1", "single");;[0X
    [4Xgap> etxt := Encode(etxt, GAPInfo.TermEncoding);;                        [0X
    [4Xgap> PrintFormattedString(etxt);[0X
    [4X[FS00] First, F. A. and Second, X. Y., The Fritz package for the formula[0X
    [4Xx^y - l_{i+1} -> R, Important Journal, 13 (2000), 13-25, (Online data at[0X
    [4XBla Bla Publisher (http://www.publish.com/~ImpJ/123#data)).[0X
  [4X------------------------------------------------------------------[0X
  
  The  following  command may be useful to generate completly new bibliography
  entries in BibXMLext format. It also informs about the supported entry types
  and field names.
  
  [1X7.3-10 TemplateBibXML[0m
  
  [2X> TemplateBibXML( [0X[3X[type][0X[2X ) _________________________________________[0Xfunction
  [6XReturns:[0X  list of types or string
  
  Without  an  argument  this  function  returns a list of the supported entry
  types in BibXMLext documents.
  
  With  an  argument [3Xtype[0m of one of the supported types the function returns a
  string  which  is  a  template for a corresponding BibXMLext entry. Optional
  field  elements  have  a [10X*[0m appended. If an element has the word [10XOR[0m appended,
  then  either this element or the next must/can be given, not both. If [10XAND/OR[0m
  is  appended then this and/or the next can/must be given. Elements which can
  appear several times have a [10X+[0m appended. Places to fill are marked by an [10XX[0m.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> TemplateBibXML();[0X
    [4X[ "article", "book", "booklet", "manual", "techreport", [0X
    [4X  "mastersthesis", "phdthesis", "inbook", "incollection", [0X
    [4X  "proceedings", "inproceedings", "conference", "unpublished", "misc" [0X
    [4X ][0X
    [4Xgap> Print(TemplateBibXML("inbook"));[0X
    [4X<entry id="X"><inbook>[0X
    [4X  <author>[0X
    [4X    <name><first>X</first><last>X</last></name>+[0X
    [4X  </author>OR[0X
    [4X  <editor>[0X
    [4X    <name><first>X</first><last>X</last></name>+[0X
    [4X  </editor>[0X
    [4X  <title>X</title>[0X
    [4X  <chapter>X</chapter>AND/OR[0X
    [4X  <pages>X</pages>[0X
    [4X  <publisher>X</publisher>[0X
    [4X  <year>X</year>[0X
    [4X  <volume>X</volume>*OR[0X
    [4X  <number>X</number>*[0X
    [4X  <series>X</series>*[0X
    [4X  <type>X</type>*[0X
    [4X  <address>X</address>*[0X
    [4X  <edition>X</edition>*[0X
    [4X  <month>X</month>*[0X
    [4X  <note>X</note>*[0X
    [4X  <key>X</key>*[0X
    [4X  <annotate>X</annotate>*[0X
    [4X  <crossref>X</crossref>*[0X
    [4X  <abstract>X</abstract>*[0X
    [4X  <affiliation>X</affiliation>*[0X
    [4X  <contents>X</contents>*[0X
    [4X  <copyright>X</copyright>*[0X
    [4X  <isbn>X</isbn>*OR[0X
    [4X  <issn>X</issn>*[0X
    [4X  <keywords>X</keywords>*[0X
    [4X  <language>X</language>*[0X
    [4X  <lccn>X</lccn>*[0X
    [4X  <location>X</location>*[0X
    [4X  <mrnumber>X</mrnumber>*[0X
    [4X  <mrclass>X</mrclass>*[0X
    [4X  <mrreviewer>X</mrreviewer>*[0X
    [4X  <price>X</price>*[0X
    [4X  <size>X</size>*[0X
    [4X  <url>X</url>*[0X
    [4X  <category>X</category>*[0X
    [4X  <other type="X">X</other>*+[0X
    [4X</inbook></entry>[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X7.4 Getting BibTeX entries from [5XMathSciNet[1X[0X
  
  We      provide      utilities     to     access     the     [5X     MathSciNet[0m
  ([7Xhttp://www.ams.org/mathscinet/[0m)  data  base  from within GAP. One condition
  for  this to work is that the [5XIO[0m-package [Neu07] is available. The other is,
  of  course, that you use these functions from a computer which has access to
  [5XMathSciNet[0m.
  
  [1X7.4-1 SearchMR[0m
  
  [2X> SearchMR( [0X[3Xqurec[0X[2X ) ________________________________________________[0Xfunction
  [2X> SearchMRBib( [0X[3Xbib[0X[2X ) _______________________________________________[0Xfunction
  [6XReturns:[0X  a list of strings, a string or [9Xfail[0m
  
  The  first  function  [2XSearchMR[0m  provides  the  same functionality as the Web
  interface  [5X  MathSciNet[0m  ([7Xhttp://www.ams.org/mathscinet/[0m). The query strings
  must  be  given as a record, and the following components of this record are
  recognized:    [10XAuthor[0m,    [10XAuthorRelated[0m,    [10XTitle[0m,    [10XReviewText[0m,   [10XJournal[0m,
  [10XInstitutionCode[0m,   [10XSeries[0m,   [10XMSCPrimSec[0m,   [10XMSCPrimary[0m,  [10XMRNumber[0m,  [10XAnywhere[0m,
  [10XReferences[0m and [10XYear[0m.
  
  Furthermore,  the component [10Xtype[0m can be specified. It can be one of [10X"bibtex"[0m
  (the  default  if not given), [10X"pdf"[0m, [10X"html"[0m and probably others. In the last
  cases  the  function  returns a string with the correspondig PDF-file or web
  page  from  [5XMathSciNet[0m. In the first case the [5XMathSciNet[0m interface returns a
  web  page  with BibTeX entries, for convenience this function returns a list
  of strings, each containing the BibTeX text for a single result entry.
  
  The  format  of  a  [10X.Year[0m  component  can  be  either  a  four digit number,
  optionally  preceded  by one of the characters [10X'<'[0m, [10X'>'[0m or [10X'='[0m, or it can be
  two four digit numbers separated by a [10X-[0m to specify a year range.
  
  The  function [2XSearchMRBib[0m gets a record of a parsed BibTeX entry as input as
  returned  by  [2XParseBibFiles[0m  ([14X7.1-1[0m) or [2XParseBibStrings[0m ([14X7.1-1[0m). It tries to
  generate  some  sensible  input from this information for [2XSearchMR[0m and calls
  that function.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4Xgap> ll := SearchMR(rec(Author:="Gauss", Title:="Disquisitiones"));;[0X
    [4Xgap> ll2 := List(ll, HeuristicTranslationsLaTeX2XML.Apply);;[0X
    [4Xgap> bib := ParseBibStrings(Concatenation(ll2));;[0X
    [4Xgap> bibxml := List(bib[1], StringBibAsXMLext);;[0X
    [4Xgap> bib2 := ParseBibXMLextString(Concatenation(bibxml));;[0X
    [4Xgap> for b in bib2.entries do [0X
    [4Xgap>          PrintFormattedString(StringBibXMLEntry(b, "Text")); od;     [0X
    [4X[Gau95]  Gauss,  C. F., Disquisitiones arithmeticae, Academia Colombiana[0X
    [4Xde  Ciencias  Exactas  Físicas  y  Naturales,  Colección  Enrique  Pérez[0X
    [4XArbeláez   [Enrique  Pérez  Arbeláez  Collection],  10,  Bogotá  (1995),[0X
    [4Xxliv+495  pages,  (Translated  from  the Latin by Hugo Barrantes Campos,[0X
    [4XMichael Josephy and Ángel Ruiz Zúñiga, With a preface by Ruiz Zúñiga).[0X
    [4X[0X
    [4X[Gau86]  Gauss, C. F., Disquisitiones arithmeticae, Springer-Verlag, New[0X
    [4XYork  (1986),  xx+472 pages, (Translated and with a preface by Arthur A.[0X
    [4XClarke,  Revised  by William C. Waterhouse, Cornelius Greither and A. W.[0X
    [4XGrootendorst and with a preface by Waterhouse).[0X
    [4X[0X
    [4X[Gau66]  Gauss,  C.  F.,  Disquisitiones  arithmeticae,  Yale University[0X
    [4XPress,  Translated  into  English  by Arthur A. Clarke, S. J, New Haven,[0X
    [4XConn. (1966), xx+472 pages.[0X
  [4X------------------------------------------------------------------[0X
  
