chap7.txt

  
  7 Utilities for Bibliographies
  
  A  standard  for collecting references (in particular to mathematical texts)
  is  BibTeX  (http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/). 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 GAP.
  
  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 GAP.
  
  
  7.1 Parsing BibTeX Files
  
  Here  are functions for parsing, normalizing and printing reference lists in
  BibTeX format. The reference describing this format is [Lam85, Appendix B].
  
  7.1-1 ParseBibFiles
  
  ParseBibFiles( bibfile1[, bibfile2[, ...]] )  function
  ParseBibStrings( str1[, str2[, ...]] )  function
  Returns:  list [list of bib-records, list of abbrevs, list of expansions]
  
  The  first  function parses the files bibfile1 and so on (if a file does not
  exist the extension .bib is appended) in BibTeX format and returns a list as
  follows:  [entries,  strings, texts]. Here entries is a list of records, one
  record  for  each  reference contained in bibfile. Then strings is a list of
  abbreviations  defined  by  @string-entries  in  bibfile and texts 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 GAP strings
  str1 and so on.
  
  The  records  in  entries store key-value pairs of a BibTeX reference in the
  form  rec(key1  = value1, ...). 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 .Type and .Label. The records also have a .From
  field that says that the data are read from a BibTeX source.
  
  As an example consider the following BibTeX file.
  
    doc/test.bib  
    @string{ j  = "Important Journal" }
    @article{ AB2000, Author=  "Fritz A. First and Sec, X. Y.", 
    TITLE="Short", journal = j, year = 2000 }
  
  
    Example  
    gap> bib := ParseBibFiles("doc/test.bib");
    [ [ rec( From := rec( BibTeX := true ), Label := "AB2000", 
              Type := "article", author := "Fritz A. First and Sec, X. Y."
                , journal := "Important Journal", title := "Short", 
              year := "2000" ) ], [ "j" ], [ "Important Journal" ] ]
  
  
  7.1-2 NormalizedNameAndKey
  
  NormalizedNameAndKey( namestr )  function
  Returns:  list of strings and names as lists
  
  NormalizeNameAndKey( r )  function
  Returns:  nothing
  
  The  argument  namestr  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  NormalizedNameAndKey  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.
  
  The  function  NormalizeNameAndKey  gets  as  argument  r  a  record  for  a
  bibliography  entry  as  returned  by  ParseBibFiles (7.1-1). It substitutes
  .author  and  .editor  fields  of  r  by their normalized form, the original
  versions are stored in fields .authororig and .editororig.
  
  Furthermore  a  short  and  a  long  citation key is generated and stored in
  components .printedkey (only if no .key is already bound) and .keylong.
  
  We continue the example from ParseBibFiles (7.1-1).
  
    Example  
    gap> bib := ParseBibFiles("doc/test.bib");;
    gap> NormalizedNameAndKey(bib[1][1].author);
    [ "First, F. A. and Sec, X. Y.", "FS", "firstsec", 
      [ [ "First", "F. A.", "Fritz A." ], [ "Sec", "X. Y.", "X. Y." ] ] ]
    gap> NormalizeNameAndKey(bib[1][1]);
    gap> bib[1][1];
    rec( From := rec( BibTeX := true ), Label := "AB2000", 
      Type := "article", author := "First, F. A. and Sec, X. Y.", 
      authororig := "Fritz A. First and Sec, X. Y.", 
      journal := "Important Journal", keylong := "firstsec2000", 
      printedkey := "FS00", title := "Short", year := "2000" )
  
  
  7.1-3 WriteBibFile
  
  WriteBibFile( bibfile, bib )  function
  Returns:  nothing
  
  This  is  the converse of ParseBibFiles (7.1-1). Here bib either must have a
  format as list of three lists as it is returned by ParseBibFiles (7.1-1). Or
  bib  can  be  a  record as returned by ParseBibXMLextFiles (7.3-4). A BibTeX
  file  bibfile 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 NormalizeNameAndKey (7.1-2). The command
  
    Example  
    gap> WriteBibFile("nicer.bib", bib);
  
  
  produces a file nicer.bib as follows:
  
    nicer.bib  
    @string{j = "Important Journal" }
    
    @article{ AB2000,
      author =           {First, F. A. and Sec, X. Y.},
      title =            {Short},
      journal =          j,
      year =             {2000},
      authororig =       {Fritz A. First and Sec, X. Y.},
      keylong =          {firstsec2000},
      printedkey =       {FS00}
    }
  
  
  7.1-4 LabelsFromBibTeX
  
  LabelsFromBibTeX( path, keys, bibfiles, style )  function
  Returns:  a list of pairs of strings [key, label]
  
  This  function uses bibtex to determine the ordering of a list of references
  and  a  label  for  each  entry  which is typeset in a document citing these
  references.
  
  The  argument  path  is a directory specified as string or directory object.
  The  argument  bibfiles  must  be  a  list  of  files in BibTeX format, each
  specified  by  a  path  relative  to the first argument, or an absolute path
  (starting  with  '/') or relative to the GAP roots (starting with "gap://").
  The  list  keys must contain strings which occur as keys in the given BibTeX
  files.  Finally  the  string  style must be the name of a bibliography style
  (like "alpha").
  
  The  list returned by this function contains pairs [key, label] where key is
  one  of  the entries of keys and label is a string used for citations of the
  bibliography  entry  in a document. These pairs are ordered as the reference
  list produced by BibTeX.
  
    Example  
    gap> f := Filename(DirectoriesPackageLibrary("gapdoc","doc"), "test.bib");;
    gap> LabelsFromBibTeX(".", ["AB2000"], [f], "alpha");
    [ [ "AB2000", "FS00" ] ]
  
  
  7.1-5 InfoBibTools
  
  InfoBibTools info class
  
  The  default  level  of  this  info class is 1. Functions like ParseBibFiles
  (7.1-1), StringBibAs... are then printing some information. You can suppress
  it by setting the level of InfoBibTools to 0. With level 2 there may be some
  more information for debugging purposes.
  
  
  7.2 The BibXMLext Format
  
  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 $ 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 GAPDoc, but the format and the tools are certainly
  useful for other purposes as well.
  
  We  started  from  a  DTD  bibxml.dtd  which is publicly available, say from
  http://bibtexml.sf.net/.   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 bibxmlext.dtd which can be found
  in the root directory of this GAPDoc package (and in Appendix C):
  
  names
        Lists of names in the author and editor fields in BibTeX are difficult
        to  parse.  Here  they  must be given by a sequence of <name>-elements
        which  each  contain an optional <first>- and a <last>-element for the
        first and last names, respectively.
  
  <M> and <Math>
        These  elements  enclose  mathematical  formulae, the content is LaTeX
        code  (without  the $). These should be handled in the same way as the
        elements  with  the  same  names  in  GAPDoc,  see 3.8-2 and 3.8-1. In
        particular,  simple  formulae  which  have  a  well defined plain text
        representation can be given in <M>-elements.
  
  Encoding
        Note  that  in  XML  files  we  can  use  the  full  range  of unicode
        characters,  see  http://www.unicode.org/.  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.
  
  <URL>
        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 GAPDoc, see
        3.5-5.
  
  <Alt Only="..."> and <Alt Not="...">
        Sometimes  information should be given in different ways, depending on
        the   output   format   of   the  data.  This  is  possible  with  the
        <Alt>-elements with the same definition as in GAPDoc, see 3.9-1.
  
  <C>
        This  element  should  be  used  to  protect text from case changes by
        converters (the extra {} characters in BibTeX title fields).
  
  <string key="..." value="..."/> and <value key="..."/>
        The  <string>-element defines key-value pairs which can be used in any
        field  via  the  <value>-element  (not  only for whole fields but also
        parts of the text).
  
  <other type="...">
        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.
  
  <Wrap Name="...">
        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).
  
  Extra entities
        The  DTD  defines  the  standard XML entities (2.1-10 and the entities
        &nbsp;  (non-breakable space), &ndash; and &copyright;. Use &ndash; in
        page ranges.
  
  For  further  details  of  the DTD we refer to the file bibxmlext.dtd itself
  which  is  shown in appendix C. 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 GAP one can use the function TemplateBibXML (7.3-10) to get templates
  for the various entry types.
  
  Here is an example of a BibXMLext document:
  
    doc/testbib.xml  
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE file SYSTEM "bibxmlext.dtd">
    <file>
    <string key="j" value="Important Journal"/>
    <entry id="AB2000"><article>
      <author>
        <name><first>Fritz A.</first><last>First</last></name>
        <name><first>X. Y.</first><last>Sec&#x0151;nd</last></name>
      </author>  
      <title>The <Wrap Name="Package"> <C>F</C>ritz</Wrap> package for the 
             formula <M>x^y - l_{{i+1}} \rightarrow \mathbb{R}</M></title>
      <journal><value key="j"/></journal>
      <year>2000</year>
      <number>13</number>
      <pages>13&ndash;25</pages>
      <note>Online data at <URL Text="Bla Bla Publisher">
                      http://www.publish.com/~ImpJ/123#data</URL></note>
      <other type="mycomment">very useful</other>
    </article></entry>
    </file>
    
  
  
  There  is  a  standard XML header and a DOCTYPE declaration referring to the
  bibxmlext.dtd  DTD  mentioned  above. Local entities could be defined in the
  DOCTYPE  tag  as  shown  in  the example in 2.2-3. The actual content of the
  document   is   inside  a  <file>-element,  it  consists  of  <string>-  and
  <entry>-elements.  Several  of  the  BibXMLext markup features are shown. We
  will use this input document for some examples below.
  
  
  7.3 Utilities for BibXMLext data
  
  
  7.3-1 Translating BibTeX to BibXMLext
  
  First  we  describe  a  tool  which  can translate bibliography entries from
  BibTeX  data  to BibXMLext <entry>-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 <URL>-elements, translating non-ASCII
  characters to unicode, ...).
  
  See  WriteBibXMLextFile  (7.3-5)  below  for  how  to write the results to a
  BibXMLext file.
  
  7.3-2 HeuristicTranslationsLaTeX2XML.Apply
  
  HeuristicTranslationsLaTeX2XML.Apply( str )  function
  Returns:  a string
  
  HeuristicTranslationsLaTeX2XML.ApplyToFile( fnam[, outnam] )  function
  Returns:  nothing
  
  These  utilities  translate some LaTeX code into text in UTF-8 encoding. The
  input is given as a string str, or a file name fnam, 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 outnam.
  
  The  record  HeuristicTranslationsLaTeX2XML  mainly contains translations of
  LaTeX  macros  for special characters which were found in hundreds of BibTeX
  entries  from MathSciNet (http://www.ams.org/mathscinet/). 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
  GAPDoc author.
  
    Example  
    gap> s := "\\\"u\\'{e}\\`e{\\ss}";;
    gap> Print(s, "\n");               
    \"u\'{e}\`e{\ss}
    gap> Print(HeuristicTranslationsLaTeX2XML.Apply(s),"\n");
    üéèß
  
  
  7.3-3 StringBibAsXMLext
  
  StringBibAsXMLext( bibentry[, abbrvs, vals][, encoding] )  function
  Returns:  a string with XML code, or fail
  
  The  argument bibentry is a record representing an entry from a BibTeX file,
  as  returned  in  the first list of the result of ParseBibFiles (7.1-1). The
  optional  two  arguments  abbrvs  and vals can be lists of abbreviations and
  substitution  strings,  as  returned as second and third list element in the
  result  of  ParseBibFiles  (7.1-1). The optional argument encoding specifies
  the  character encoding of the string components of bibentry. 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  StringBibAsXMLext  creates  XML code of an <entry>-element in
  BibXMLext  format.  The  result  is  in  UTF-8  encoding  and  contains some
  heuristic  translations,  like  splitting  name  lists,  finding  places for
  <C>-elements,   putting   formulae   in   <M>-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
  fail.
  
  If your BibTeX input contains LaTeX markup for special characters, it can be
  convenient to translate this input with HeuristicTranslationsLaTeX2XML.Apply
  (7.3-2) or HeuristicTranslationsLaTeX2XML.ApplyToFile (7.3-2) before parsing
  it as BibTeX.
  
  As  an example we consider again the short BibTeX file doc/test.bib shown in
  the example for ParseBibFiles (7.1-1).
  
    Example  
    gap> bib := ParseBibFiles("doc/test.bib");;
    gap> str := StringBibAsXMLext(bib[1][1], bib[2], bib[3]);;
    gap> Print(str, "\n");
    <entry id="AB2000"><article>
      <author>
        <name><first>Fritz A.</first><last>First</last></name>
        <name><first>X. Y.</first><last>Sec</last></name>
      </author>  
      <title>Short</title>
      <journal><value key="j"/></journal>
      <year>2000</year>
    </article></entry>
  
  
  The following functions allow parsing of data which are already in BibXMLext
  format.
  
  7.3-4 ParseBibXMLextString
  
  ParseBibXMLextString( str[, res] )  function
  ParseBibXMLextFiles( fname1[, fname2[, ...]] )  function
  Returns:  a record with fields .entries, .strings and .entities
  
  The  first  function  gets a string str containing a BibXMLext document or a
  part  of  it.  It  returns  a  record  with the three mentioned fields. Here
  .entries  is  a  list of partial XML parse trees for the <entry>-elements in
  str.   The   field   .strings   is  a  list  of  key-value  pairs  from  the
  <string>-elements  in str. And .strings is a list of name-value pairs of the
  named entities which were used during the parsing.
  
  The  optional  argument  res  can  be  the  result  of a former call of this
  function,  in  that  case  the  newly  parsed entries are added to this data
  structure.
  
  The second function ParseBibXMLextFiles uses the first on the content of all
  files  given  by  filenames  fname1  and so on. It collects the results in a
  single record.
  
  As an example we parse the file testbib.xml shown in 7.2.
  
    Example  
    gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
    gap> RecNames(bib);
    [ "entries", "strings", "entities" ]
    gap> bib.entries;
    [ <BibXMLext entry: AB2000> ]
    gap> bib.strings;
    [ [ "j", "Important Journal" ] ]
    gap> bib.entities[1]; 
    [ "amp", "&#38;#38;" ]
  
  
  7.3-5 WriteBibXMLextFile
  
  WriteBibXMLextFile( fname, bib )  function
  Returns:  nothing
  
  This function writes a BibXMLext file with name fname.
  
  There  are  three  possibilities  to specify the bibliography entries in the
  argument  bib.  It can be a list of three lists as returned by ParseBibFiles
  (7.1-1).  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 StringBibAsXMLext (7.3-3) is applied and the resulting strings
  are written to the result file.
  
  The  third  possibility is that bib is a record in the format as returned by
  ParseBibXMLextString  (7.3-4)  and ParseBibXMLextFiles (7.3-4). In this case
  the  entries  for  the  BibXMLext  file  are  produced with StringXMLElement
  (5.2-2), and if bib.entities is bound then it is tried to resubstitute parts
  of the string by the given entities with EntitySubstitution (5.2-3).
  
  As   an  example  we  write  back  the  result  of  the  example  shown  for
  ParseBibXMLextFiles (7.3-4) to an equivalent XML file.
  
    Example  
    gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
    gap> WriteBibXMLextFile("test.xml", bib);
  
  
  
  7.3-6 Bibliography Entries as Records
  
  For  working with BibXMLext entries we find it convenient to first translate
  the parse tree of an entry, as returned by ParseBibXMLextFiles (7.3-4), 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.
  
  7.3-7 RecBibXMLEntry
  
  RecBibXMLEntry( entry[, restype][, strings][, options] )  function
  Returns:  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: entry is the parse tree of an <entry> element
  as  returned by ParseBibXMLextString (7.3-4) or ParseBibXMLextFiles (7.3-4).
  The optional argument restype describes the type of the result. This package
  supports  currently  the  types  "BibTeX", "Text" and "HTML". The default is
  "BibTeX". The optional argument strings must be a list of key-value pairs as
  returned  in  the  component  .strings in the result of ParseBibXMLextString
  (7.3-4). The argument options must be a record.
  
  If  the  entry  contains an author field then the result will also contain a
  component  .authorAsList  which  is a list containing for each author a list
  with  three entries of the form [last name, first name initials, first name]
  (the  third  entry means the first name as given in the data). Similarly, an
  editor field is accompanied by a component .editorAsList.
  
  The following options are currently supported.
  
  If options.fullname is bound and set to true 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 options.namefirstlast is bound and set to true
  then  the names are written in the form first-name(s) last-name, the default
  is the form last-name, first-name(s).
  
  If options.href is bound and set to false then the "BibTeX" type result will
  not  use  \href  commands.  The  default  is  to produce \href commands from
  <URL>-elements  such  that LaTeX with the hyperref package can produce links
  for them.
  
  The  content  of an <Alt>-element with Only-attribute is included if restype
  is given in the attribute and ignored otherwise, and vice versa in case of a
  Not-attribute.  If  options.useAlt is bound, it must be a list of strings to
  which  restype  is  added.  Then  an  <Alt>-element  with  Only-attribute is
  evaluated  if  the intersection of options.useAlt and the types given in the
  attribute  is not empty. In case of a Not-attribute the element is evaluated
  if this intersection is empty.
  
  If  restype is "BibTeX" then the string fields in the result will be recoded
  with  Encode  (6.2-2) and target "LaTeX". If options.hasLaTeXmarkup is bound
  and  set  to  true  (for  example, because the data are originally read from
  BibTeX files), then the target "LaTeXleavemarkup" will be used.
  
  We use again the file shown in the example for ParseBibXMLextFiles (7.3-4).
  
    Example  
    gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
    gap> e := bib.entries[1];; strs := bib.strings;;
    gap> Print(RecBibXMLEntry(e, "BibTeX", strs), "\n");
    rec(
      From := rec(
          BibXML := true,
          options := rec(
               ),
          type := "BibTeX" ),
      Label := "AB2000",
      Type := "article",
      author := "First, F. A. and Sec{\\H o}nd, X. Y.",
      authorAsList := 
       [ [ "First", "F. A.", "Fritz A." ], 
          [ "Sec\305\221nd", "X. Y.", "X. Y." ] ],
      journal := "Important Journal",
      mycomment := "very useful",
      note := 
       "Online data at \\href {http://www.publish.com/~ImpJ/123#data} {Bla\
     Bla Publisher}",
      number := "13",
      pages := "13{\\textendash}25",
      printedkey := "FS00",
      title := 
       "The  {F}ritz package for the \n         formula $x^y - l_{{i+1}} \
    \\rightarrow \\mathbb{R}$",
      year := "2000" )
    gap> Print(RecBibXMLEntry(e, "HTML", strs).note, "\n");
    Online data at <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla\
     Publisher</a>
  
  
  7.3-8 AddHandlerBuildRecBibXMLEntry
  
  AddHandlerBuildRecBibXMLEntry( elementname, restype, handler )  function
  Returns:  nothing
  
  The argument elementname must be the name of an entry field supported by the
  BibXMLext  format, the name of one of the special elements "C", "M", "Math",
  "URL"  or  of  the  form  "Wrap:myname"  or  any string "mytype" (which then
  corresponds  to entry fields <other type="mytype">). The string "Finish" has
  an exceptional meaning, see below.
  
  restype  is  a  string  describing  the result type for which the handler is
  installed, see RecBibXMLEntry (7.3-7).
  
  For  both  arguments,  elementname  and restype, it is also possible to give
  lists of the described ones for installing several handler at once.
  
  The  argument  handler  must  be  a function with five arguments of the form
  handler(entry,  r, restype, strings, options). Here entry is a parse tree of
  a  BibXMLext  <entry>-element,  r  is  a  node  in  this tree for an element
  elementname,   and   restype,  strings  and  options  are  as  explained  in
  RecBibXMLEntry (7.3-7). The function should return a string representing the
  content  of  the  node  r.  If  elementname is of the form "Wrap:myname" the
  handler is used for elements of form <Wrap Name="myname">...</Wrap>.
  
  If  elementname  is  "Finish" the handler should look like above except that
  now  r  is  the record generated by RecBibXMLEntry (7.3-7) just before it is
  returned.  Here  the  handler  should  return  nothing.  It  can  be used to
  manipulate  the  record  r,  for  example  for  changing the encoding of the
  strings or for adding some more components.
  
  The  installed  handler  is called by BuildRecBibXMLEntry(entry, r, restype,
  strings,  options).  The  string  for the whole content of an element can be
  generated   by   ContentBuildRecBibXMLEntry(entry,   r,   restype,  strings,
  options).
  
  We  continue  the  example from RecBibXMLEntry (7.3-7) and install a handler
  for  the <Wrap Name="Package">-element such that LaTeX puts its content in a
  sans serif font.
  
    Example  
    gap> AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX",
    > function(entry,  r, restype,  strings, options)
    >   return Concatenation("\\textsf{", ContentBuildRecBibXMLEntry(
    >             entry, r, restype,  strings, options), "}");
    > end);
    gap> 
    gap> Print(RecBibXMLEntry(e, "BibTeX", strs).title, "\n");
    The \textsf{ {F}ritz} package for the 
             formula $x^y - l_{{i+1}} \rightarrow \mathbb{R}$
    gap> Print(RecBibXMLEntry(e, "Text", strs).title, "\n");  
    The  Fritz package for the 
             formula x^y - l_{i+1} → R
    gap> AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX", "Ignore");
  
  
  7.3-9 StringBibXMLEntry
  
  StringBibXMLEntry( entry[, restype][, strings][, options] )  function
  Returns:  a string
  
  The  arguments  of  this function have the same meaning as in RecBibXMLEntry
  (7.3-7) but the return value is a string representing the bibliography entry
  in a format specified by restype (default is "BibTeX").
  
  Currently, the following cases for restype are supported:
  
  "BibTeX"
        A string with BibTeX source code is generated.
  
  "Text"
        A  text  representation  of  the  text is returned. If options.ansi is
        bound  it  must be a record. The components must have names Bib_Label,
        Bib_author,  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  TextAttr.reset (see TextAttr (6.1-2)). If you give an
        empty record here, some default ANSI color markup will be used.
  
  "HTML"
        An HTML representation of the bibliography entry is returned. The text
        from  each  field  is enclosed in markup (mostly <span>-elements) with
        the  class  attribute  set  to  the field name. This allows a detailed
        layout of the code via a style sheet file. If options.MathJax is bound
        and  has the value true then formulae are encoded for display on pages
        with MathJax support.
  
  We use again the file shown in the example for ParseBibXMLextFiles (7.3-4).
  
    Example  
    gap> bib := ParseBibXMLextFiles("doc/testbib.xml");;
    gap> e := bib.entries[1];; strs := bib.strings;;
    gap> ebib := StringBibXMLEntry(e, "BibTeX", strs);;
    gap> PrintFormattedString(ebib);
    @article{ AB2000,
      author =           {First, F. A. and Sec{\H o}nd, X. Y.},
      title =            {The  {F}ritz  package  for  the formula $x^y -
                          l_{{i+1}} \rightarrow \mathbb{R}$},
      journal =          {Important Journal},
      number =           {13},
      year =             {2000},
      pages =            {13{\textendash}25},
      note =             {Online          data          at         \href
                          {http://www.publish.com/~ImpJ/123#data}   {Bla
                          Bla Publisher}},
      mycomment =        {very useful},
      printedkey =       {FS00}
    }
    gap> etxt := StringBibXMLEntry(e, "Text", strs);;      
    gap> etxt := SimplifiedUnicodeString(Unicode(etxt), "latin1", "single");;
    gap> etxt := Encode(etxt, GAPInfo.TermEncoding);;                        
    gap> PrintFormattedString(etxt);
    [FS00]  First,  F.  A.  and Second, X. Y., The Fritz package for the
    formula  x^y  -  l_{i+1}  ?  R, Important Journal, 13 (2000), 13-25,
    (Online        data        at        Bla        Bla        Publisher
    (http://www.publish.com/~ImpJ/123#data)).
    gap> ehtml := StringBibXMLEntry(e, "HTML", strs, rec(MathJax := true));;
    gap> ehtml := Encode(Unicode(ehtml), GAPInfo.TermEncoding);;
    gap> PrintFormattedString(ehtml);
    <p class='BibEntry'>
    [<span class='BibKey'>FS00</span>]   
     <b class='BibAuthor'>First, F. A. and Secőnd, X. Y.</b>,
     <i class='BibTitle'>The  Fritz package for the 
             formula \(x^y - l_{{i+1}} \rightarrow \mathbb{R}\)</i>,
     <span class='BibJournal'>Important Journal</span> 
    (<span class='BibNumber'>13</span>)
     (<span class='BibYear'>2000</span>),
     <span class='BibPages'>13–25</span><br />
    (<span class='BibNote'>Online data at 
    <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla 
    Publisher</a></span>).
    </p>
    
  
  
  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.
  
  7.3-10 TemplateBibXML
  
  TemplateBibXML( [type] )  function
  Returns:  list of types or string
  
  Without  an  argument  this  function  returns a list of the supported entry
  types in BibXMLext documents.
  
  With  an  argument type 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 * appended. If an element has the word OR appended,
  then  either this element or the next must/can be given, not both. If AND/OR
  is  appended then this and/or the next can/must be given. Elements which can
  appear several times have a + appended. Places to fill are marked by an X.
  
    Example  
    gap> TemplateBibXML();
    [ "article", "book", "booklet", "conference", "inbook", 
      "incollection", "inproceedings", "manual", "mastersthesis", "misc", 
      "phdthesis", "proceedings", "techreport", "unpublished" ]
    gap> Print(TemplateBibXML("inbook"));
    <entry id="X"><inbook>
      <author>
        <name><first>X</first><last>X</last></name>+
      </author>OR
      <editor>
        <name><first>X</first><last>X</last></name>+
      </editor>
      <title>X</title>
      <chapter>X</chapter>AND/OR
      <pages>X</pages>
      <publisher>X</publisher>
      <year>X</year>
      <volume>X</volume>*OR
      <number>X</number>*
      <series>X</series>*
      <type>X</type>*
      <address>X</address>*
      <edition>X</edition>*
      <month>X</month>*
      <note>X</note>*
      <key>X</key>*
      <annotate>X</annotate>*
      <crossref>X</crossref>*
      <abstract>X</abstract>*
      <affiliation>X</affiliation>*
      <contents>X</contents>*
      <copyright>X</copyright>*
      <isbn>X</isbn>*OR
      <issn>X</issn>*
      <keywords>X</keywords>*
      <language>X</language>*
      <lccn>X</lccn>*
      <location>X</location>*
      <mrnumber>X</mrnumber>*
      <mrclass>X</mrclass>*
      <mrreviewer>X</mrreviewer>*
      <price>X</price>*
      <size>X</size>*
      <url>X</url>*
      <category>X</category>*
      <other type="X">X</other>*+
    </inbook></entry>
  
  
  
  7.4 Getting BibTeX entries from MathSciNet
  
  We      provide      utilities     to     access     the          MathSciNet
  (http://www.ams.org/mathscinet/)  data  base  from within GAP. One condition
  for  this to work is that the IO-package [Neu07] is available. The other is,
  of  course, that you use these functions from a computer which has access to
  MathSciNet.
  
  Please note, that the usual license for MathSciNet access does not allow for
  automated searches in the database. Therefore, only use the SearchMR (7.4-1)
  function for single queries, as you would do using your webbrowser.
  
  7.4-1 SearchMR
  
  SearchMR( qurec )  function
  SearchMRBib( bib )  function
  Returns:  a list of strings, a string or fail
  
  The  first  function  SearchMR  provides  the  same functionality as the Web
  interface    MathSciNet  (http://www.ams.org/mathscinet/). The query strings
  must  be  given as a record, and the following components of this record are
  recognized:    Author,    AuthorRelated,    Title,    ReviewText,   Journal,
  InstitutionCode,   Series,   MSCPrimSec,   MSCPrimary,  MRNumber,  Anywhere,
  References and Year.
  
  Furthermore,  the component type can be specified. It can be one of "bibtex"
  (the  default  if not given), "pdf", "html" and probably others. In the last
  cases  the  function  returns a string with the correspondig PDF-file or web
  page  from  MathSciNet. In the first case the MathSciNet 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  .Year  component  can  be  either  a  four digit number,
  optionally  preceded  by one of the characters '<', '>' or '=', or it can be
  two four digit numbers separated by a - to specify a year range.
  
  The  function SearchMRBib gets a record of a parsed BibTeX entry as input as
  returned  by  ParseBibFiles  (7.1-1) or ParseBibStrings (7.1-1). It tries to
  generate  some  sensible  input from this information for SearchMR and calls
  that function.
  
    Example  
    gap> ll := SearchMR(rec(Author:="Gauss", Title:="Disquisitiones"));;
    gap> ll2 := List(ll, HeuristicTranslationsLaTeX2XML.Apply);;
    gap> bib := ParseBibStrings(Concatenation(ll2));;
    gap> bibxml := List(bib[1], StringBibAsXMLext);;
    gap> bib2 := ParseBibXMLextString(Concatenation(bibxml));;
    gap> for b in bib2.entries do 
    >          PrintFormattedString(StringBibXMLEntry(b, "Text")); od;     
    [Gau95]   Gauss,   C.   F.,  Disquisitiones  arithmeticae,  Academia
    Colombiana   de  Ciencias  Exactas,  Físicas  y  Naturales,  Bogotá,
    Colección   Enrique   Pérez   Arbeláez   [Enrique   Pérez   Arbeláez
    Collection],  10  (1995), xliv+495 pages, (Translated from the Latin
    by  Hugo  Barrantes  Campos,  Michael Josephy and Ángel Ruiz Zúñiga,
    With a preface by Ruiz Zúñiga).
    
    [Gau86]  Gauss, C. F., Disquisitiones arithmeticae, Springer-Verlag,
    New  York  (1986),  xx+472  pages, (Translated and with a preface by
    Arthur  A.  Clarke,  Revised  by  William  C.  Waterhouse, Cornelius
    Greither and A. W. Grootendorst and with a preface by Waterhouse).
    
    [Gau66]  Gauss,  C. F., Disquisitiones arithmeticae, Yale University
    Press, New Haven, Conn.-London, Translated into English by Arthur A.
    Clarke, S. J (1966), xx+472 pages.