Jump to content

Extension:BiblioPlus

Issue tracker: #MediaWiki-extensions-BiblioPlus
From mediawiki.org
Translate this page
Languages:
MediaWiki extensions manual
BiblioPlus
Release status: stable
Implementation Tag
Description Performs automated retrieval and formatting of citations from PubMed and the ISBN database.
Author(s) Karen Eddy; based on the Biblio extension, written by Martin Jambon and others. (Karen Eddytalk)
Latest version 1.2.0 (October 2017)
MediaWiki 1.23+
PHP 5.3+
License GNU General Public License 2.0 or later
Download
Download extension
Git [?]:
Template:WikimediaDownload/gerritonly
Example cazypedia.org
Parameters
  • $wgBiblioPlusForce
  • $wgBiblioPlusVersion
Tags
‎<biblio>, ‎<cite>, ‎<nocite>
Hooks used
Quarterly downloads 8 (Ranked 125th)
Translate the BiblioPlus extension if it is available at translatewiki.net
Issues Open tasks · Report a bug

BiblioPlus performs automated retrieval and formatting of citations from PubMed and the ISBN databases in MediaWiki pages. BiblioPlus automatically numbers in-text citations and generates a reference section with links to original sources, typically at the bottom of a page.

BiblioPlus was created to correct an issue with PubMed references containing special characters in the original Biblio extension. The Biblio extension uses the National Center for Biotechnology Information (NCBI) SOAP service, which returns data in ISO 8859-1, but does not specify this encoding type in the XML header. Consequently, the SOAP parser (NuSOAP) included with the original Biblio extension reads the data as UTF-8 (the default), which results in parsing issues with some special characters leading to broken output. BiblioPlus uses the NCBI Entrez Programming Utilities (E-utilities) instead, which returns XML data in UTF-8, thus solving the problem by avoiding NuSOAP altogether.

BiblioPlus uses the same tags as the Biblio extension, so users of Biblio can switch to BiblioPlus without having to alter MediaWiki page markup. Note, however, that any existing include statement for Biblio must be commented-out, as both can not be run simultaneously.

Installation

  1. Download and place the BiblioPlus folder in the extensions subdirectory of your MediaWiki installation. If for some reason you don't want to use the citation tooltips (detailed below), delete the resources folder from inside the BiblioPlus folder.
  2. Make sure you have the following variables set in LocalSettings.php. These variables are used to make the call to the PubMed database. 
    $wgSitename = YourSiteName

    $wgEmergencyContact = YourEmailAddress
  3. You are strongly encouraged to register your site name and email address with the NCBI. The reason for this is outlined here: NCBI (See Frequency, Timing and Registration of E-utility URL Requests). The values you register with them must be the values of variables $wgSitename and $wgEmergencyContact that you set in LocalSettings.php. To do this, simply send an e-mail to NCBI EUtilities including these values, along with a contact name.
  4. Get an access key for the ISBN database, otherwise, you would share a key with everyone else. Create an ISBN account here. It is also recommended to contact ISBN support to increase your quota beyond the default daily query limit of 500. Tell them you are using the BiblioPlus extension for Mediawiki, and that it links each ISBN-referenced book to their site.
  5. Update your LocalSettings.php file with these lines, in that order: 
    $wgBiblioPlusIsbnDbKey = '12345678'; // your access key

    wfLoadExtension( 'BiblioPlus' );

How To Use

BiblioPlus provides the tags <cite> and <biblio>.

New in BiblioPlus: When you hover over an in-text citation, a tooltip containing the corresponding hyperlinked reference will appear. Thanks to Craig Thompson for the fantastic, open source qTip2 jQuery plugin.

Overview

In some sense, BiblioPlus works a bit like EndNote and other reference manager software, in that it automatically numbers the bibliography based on the order that citations appear in the text. Also like other reference managers, BiblioPlus relies on two pieces of information to make this happen:

  1. a bibliography section containing a list of the references you would like to cite in the text, and,
  2. an in-text citation, which "calls" the reference from the bibliography.

Inclusion of a pair of <cite> </cite> tags creates a citation at a specific place within the text. Each <cite> tag is used to refer to a unique key for a reference included in the <biblio> section. A pair of <cite> </cite> tags can contain one or more reference keys, separated by spaces. A reference key can be any string with no spaces, and does not have to be a number or presented in the text in any particular order; the citations are numbered automatically when the page is rendered.

The bibliography (or reference) section is typically placed at the bottom of the page, between the <biblio>...</biblio> tags, often under a suitable heading, e.g., "Reference list". Each reference begins on a new line with a hash sign (#), followed by a reference key, and finally the reference itself. References may be sourced automatically from the PubMed or ISBN databases using only their PubMed IDs or ISBN, respectively, or they may be entered manually.

Examples

The bibliography

A bibliography section might look like this in the wiki editor:

<biblio>
#Comfort2007 pmid=17323919
#He1999 pmid=9312086
#StickWillams2009 isbn=978-0-240-52118-3 //Figure 5, page 72 is particularly interesting.
#Sinnott1990 Sinnott, M.L. (1990) Catalytic mechanisms of enzymic glycosyl transfer. Chem. Rev. 90, 1171-1202. [http://dx.doi.org/10.1021/cr00105a006 DOI: 10.1021/cr00105a006]
</biblio>

Note that:

  • The reference key can be any combination of alphanumeric characters, however keys in Harvard-style Author-Year format (e.g. Sinnott1990, StickWillams2009, etc) often simplify including and troubleshooting in-text citations.
  • References can be in one of three different forms:
    1. PubMed IDs (pmid=number): If the reference has a PubMed ID, placing this after the citation tag will insert the complete reference, as well as DOI and PubMed links, with no additional typing whatsoever. (See Comfort2007 and He1999 refs. above.)
    2. ISBN (isbn=number): For books, this will insert the full reference automatically, based only on the ISBN. (See StickWillams2009 ref. above.)
    3. A full, typed reference: Here, whatever follows the reference code is placed verbatim into the reference list - you can put in any text, with any formatting you want. This should only be used when the reference does not have a PubMed ID or ISBN. (See Sinnott1990 ref. above.)
  • References in the bibliography can be in any order, i.e., the reference list does not have to be in the same order as the citations appear in the text. The BiblioPlus software will automatically number the reference list correctly regardless.
  • References may also include comments, separated from the key listing by // (See StickWillams2009 ref. above.)

In-text citations

To cite a specific reference from the bibliography in a page, the reference key of that reference is placed between the two <cite> </cite> tags in the main text.

For example, citations in the main text might look like this in the wiki editor:

  • Robert Stick and Spencer Williams wrote a book about carbohydrates and enzymes <cite>StickWillams2009</cite>.
  • The catalytic mechanisms of enzymic glycosyl transfer have been reviewed <cite>Sinnott1990</cite>.
  • If you want to include multiple references in one place, that is OK, too. Just separate them with spaces in one pair of <cite> tags, like this: <cite>He1999 Comfort2007</cite>.

Note that:

  • The reference keys will be automatically converted into reference numbers according to their first use in the text. You should not try to (and you won't be able to) type/correct the reference numbers; errors in numbering are usually due to typos in the reference keys themselves (either in the text or in the bibliography).
  • As mentioned above, reference keys in Harvard-style Author-Year format often aid troubleshooting citation problems.
  • Reference keys are case sensitive.

How it will look on the page

If the bibliography and in-text citations from above are combined, the result will look approximately like this:

Note: the mock example below lacks all automatic linking produced by the BiblioPlus extension. For a live version, see this wiki.

Main text:
Robert Stick and Spencer Williams wrote a book about carbohydrates and enzymes [1].
The catalytic mechanisms of enzymic glycosyl transfer have been reviewed [2].
If you want to include multiple references in one place, that is OK, too. Just separate them with spaces in one pair of <cite> tags, like this: [3, 4].

Bibliography/Reference list:
1. Robert V. Stick, Spencer J. Williams. Carbohydrates. Amsterdam; Elsevier, 2009. ISBN:978-0-240-52118-3 [StickWillams2009] 

Figure 5, page 72 is particularly interesting.

2. Sinnott, M.L. (1990) Catalytic mechanisms of enzymic glycosyl transfer. Chem. Rev. 90, 1171-1202. DOI: 10.1021/cr00105a006 [Sinnott1990]
3. He S and Withers SG. Assignment of sweet almond beta-glucosidase as a family 1 glycosidase and identification of its active site nucleophile. J Biol Chem. 1997 Oct 3;272(40):24864-7. PubMed ID:9312086 | HubMed [He1999]
4. Comfort DA, Bobrov KS, Ivanen DR, Shabalin KA, Harris JM, Kulminskaya AA, Brumer H, and Kelly RM. Biochemical analysis of Thermotoga maritima GH36 alpha-galactosidase (TmGalA) confirms the mechanistic commonality of clan GH-D glycoside hydrolases. Biochemistry. 2007 Mar 20;46(11):3319-30. DOI:10.1021/bi061521n | PubMed ID:17323919 | HubMed [Comfort2007]
All Medline abstracts: PubMed | HubMed

Live examples

The above examples, including all hyperlinked information, can be viewed on a live wiki here. Several other examples of referencing using BiblioPlus may be found here.

Acknowledgement

Coding of BiblioPlus was supported by faculty funding to the laboratory of Prof. Harry Brumer at the Michael Smith Laboratories and Department of Chemistry, University of British Columbia, Vancouver, Canada.

See also

Extension:Biblio - the extension that BiblioPlus was based on.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:BiblioPlus/en&oldid=6104328"