GAP (GAPDoc) - Chapter 7: Utilities for Bibliographies

Goto Chapter: Top 1 2 3 4 5 6 7 A B C Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

7 Utilities for Bibliographies
7.1 Parsing BibTeX Files
7.1-1 ParseBibFiles
7.1-2 NormalizedNameAndKey
7.1-3 WriteBibFile
7.1-4 LabelsFromBibTeX
7.1-5 InfoBibTools
7.2 The BibXMLext Format
7.3 Utilities for BibXMLext data
7.3-1 Translating BibTeX to BibXMLext
7.3-2 HeuristicTranslationsLaTeX2XML.Apply
7.3-3 StringBibAsXMLext
7.3-4 ParseBibXMLextString
7.3-5 WriteBibXMLextFile
7.3-6 Bibliography Entries as Records
7.3-7 RecBibXMLEntry
7.3-8 AddHandlerBuildRecBibXMLEntry
7.3-9 StringBibXMLEntry
7.3-10 TemplateBibXML
7.4 Getting BibTeX entries from MathSciNet
7.4-1 SearchMR

### 7 Utilities for Bibliographies

A standard for collecting references (in particular to mathematical texts) is BibTeX (https://tug.org/bibtex/). 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.

    @string{ j  = "Important Journal" }
    @article{ AB2000, Author=  "Fritz A. First and Sec, X. Y.",
    TITLE="Short", journal = j, year = 2000 }

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "test.bib");;
    gap> bib := ParseBibFiles(f);
    [ [ 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).

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "test.bib");;
    gap> bib := ParseBibFiles(f);;
    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

    gap> WriteBibFile("nicer.bib", bib);

produces a file `nicer.bib` as follows:

    @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.

    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 https://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 https://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:

    <?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. 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.

    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).

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "test.bib");;
    gap> bib := ParseBibFiles(f);;
    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.

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "testbib.xml");;
    gap> bib := ParseBibXMLextFiles(f);;
    gap> Set(RecNames(bib));
    [ "entities", "entries", "strings" ]
    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.

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "testbib.xml");;
    gap> bib := ParseBibXMLextFiles(f);;
    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).

    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "testbib.xml");;
    gap> bib := ParseBibXMLextFiles(f);;
    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.

    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.

`"Markdown"`

  A representation of the bibliography entry in Markdown format is returned. If `options.markup` is bound it must be a record which is used in the same way as `options.ansi` for the `"Text"` version.

We use again the file shown in the example for `ParseBibXMLextFiles` (7.3-4).

       edited for readability
    gap> gddirs := DirectoriesPackageLibrary("gapdoc","doc");;
    gap> f := Filename(gddirs, "testbib.xml");;
    gap> bib := ParseBibXMLextFiles(f);;
    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`.

    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 data base from within GAP. The first condition for this to work is that one of the programs `wget` or `curl` is installed on your system. The second 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. 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 content of the web page returned by 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.

If a component `uri` is bound and set to `true` the function does not actually send a request to MathSciNet but returns a string with the URI that can be called for the request.

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.

    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.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 A B C Bib Ind

generated by GAPDoc2HTML