Extension:BiblioPlus/en

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.
 * 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 [mailto:eutilities@ncbi.nlm.nih.gov 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 [mailto:support@isbndb.com 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:
 * 1) 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 [mailto:support@isbndb.com 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.
 * 2) Update your LocalSettings.php file with these lines, in that order:

How To Use
BiblioPlus provides the tags  and.

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  tags creates a citation at a specific place within the text. Each  tag is used to refer to a unique key for a reference included in the   section. A pair of  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  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.

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


 * 1) Comfort2007 pmid=17323919
 * 2) He1999 pmid=9312086
 * 3) StickWillams2009 isbn=978-0-240-52118-3 //Figure 5, page 72 is particularly interesting.
 * 4) Sinnott1990 Sinnott, M.L. (1990) Catalytic mechanisms of enzymic glycosyl transfer. Chem. Rev. 90, 1171-1202. DOI: 10.1021/cr00105a006

Note that:
 * The reference key can be any combination of alphanumeric characters, however keys in Harvard-style Author-Year format (e.g.,  , etc) often simplify including and troubleshooting in-text citations.
 * References can be in one of three different forms:
 * PubMed IDs ( 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  and   refs. above.)
 * ISBN ( number): For books, this will insert the full reference automatically, based only on the ISBN. (See   ref. above.)
 * 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   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   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  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 StickWillams2009.
 * The catalytic mechanisms of enzymic glycosyl transfer have been reviewed Sinnott1990.
 * If you want to include multiple references in one place, that is OK, too. Just separate them with spaces in one pair of   tags, like this: He1999 Comfort2007.

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