Wikiomics:Biblio

From OpenWetWare
Jump to navigationJump to search

Biblio or Biblio.php is an extension of the Mediawiki wiki engine that was developed for making citations easier and cleaner than what is available by default. It has the particularity of automatically downloading bibliographic records from online databases such as Medline or isbndb.com.

Of course this extension is installed at Wikiomics:Wikiomics: see how you can use it.

What is it?

Biblio.php is an optional module that can be added to a standard installation of the MediaWiki wiki engine. It provides 2 additional tags <cite> and <biblio> which are used respectively to cite bibliographic entries by their key, and to define bibliographic entries. It was developed for Wikiomics, and you can see it in action on several pages of this wiki such as Wikiomics:Searching for 3D functional sites in a protein structure.


Not only it takes care of the numbering and sorting of the references, but it also downloads bibliographic references from PubMed and formats them using only a given PubMed identifier (PMID). This is achieved by querying PubMed's SOAP server. If you know of any similar referencing system in another field than biomedical research, just let me know and I might implement it.

This results in references which are nicely and identically formatted, exact and complete. They automatically link to the PubMed webpage for the given article, which often provides a summary of the paper and more.

Examples

Example 1: referencing at the bottom of the page

Please use our Sandbox if you want to play with the extension now.

This would be the source code of a wiki page: 

A citation <cite>somebook</cite>.
Three citations <cite>webber2001 schwartz2005 somebook</cite>.

==== References ====
<nowiki><biblio>
#schwartz2005 pmid=16100001 
// see also <cite>stryer somebook</cite> for a smooth introduction
#webber2001 pmid=11751224
#somebook John Smith. ''The art of saying nothing''. Verbose Editions 1999.
#stryer isbn=0-7167-4954-8
</biblio>

</nowiki>

And the result would look like this:

A citation [1]. Three citations [1, 2, 3].

References

<biblio> #schwartz2005 pmid=16100001 // see also <cite>stryer somebook</cite> for a smooth introduction #webber2001 pmid=11751224 #somebook John Smith. ''The art of saying nothing''. Verbose Editions 1999. #stryer isbn=0-7167-4954-8 </biblio>

Example 2: using other pages to store the bibliographic records

Here we use another page of the wiki (biblio sandbox) to store a small bibliographic database. It is now important to display only the references which are actually cited in the text, this is why we specify "force=false". Now let's cite two references, the first one [4] was defined directly on this page, while the second one [5] comes from our biblio sandbox page. There is a third reference though which is not cited in the text. It was forced to appear by using "nocite".

References

<biblio force=false> #localref local reference #[[biblio sandbox]] </biblio>

Source code for the paragraph above: 

Here we use another page of the wiki ([[biblio sandbox]]) to store a
small bibliographic database. It is now important to display only the
references which are actually cited in the text, this is why we
specify "force=false". Now let's cite two references, the first one
<cite>localref</cite> was defined directly on this page, while the
second one <cite>sandbox-isbn</cite> comes from our [[biblio sandbox]]
page. There is a third reference though which is not cited in the
text. It was forced to appear by using
"nocite". <nocite>sandbox-pmid</nocite>

==== References ====
<nowiki><biblio force=false>
#localref local reference
#[[biblio sandbox]]
</biblio>

</nowiki>

Just like local wiki pages, external pages can be used as a source of bibliographic information. The syntax consists in a single pair of square brackets around a URL. For example: 

<biblio>
#[http://www.example.com/bibliodb.txt]
</biblio>

where http://www.example.com/bibliodb.txt should be a real URL that returns text in the suitable format.

Note about interwiki links: interwiki links are shortcuts like [[wikipedia:interwiki]] (rendered as wikipedia:interwiki). Existing interwiki links are unusable because they point to formatted web pages and not wiki source code. So the administrators of wikis have to define another set of interwiki shortcuts that point to the raw data. For example, an interwiki entry for the source code of English Wikipedia pages would be: 

Wikipedia              http://en.wikipedia.org/w/index.php?title=$1&action=raw

License

This program is distributed for free under the terms of the GNU General Public License, like MediaWiki.


Installation

It is assumed that you already have installed MediaWiki and that it is working properly.

1) Download biblio-0.8.1.tar.gz for MediaWiki 1.5 and above.

2) Unpack the archive and copy all the contents of the "extensions" subdirectory into the "extensions" subdirectory of your MediaWiki installation. If you are upgrading, make sure you also install the new version of nusoap which is included.

3) Get an access key for the ISBN database (isbndb.com). It is highly recommended since the daily quota of queries is by default limited to 500. Otherwise, you would share a key with everyone else. Follow this link, register and create a key. If you want to increase your quota, either use several keys (see below) or contact support@isbndb.com. Tell them you are using the Biblio extension for Mediawiki, and that it links each ISBN-referenced book to their site.

4) Insert the following lines in the LocalSettings.php file of your MediaWiki installation and set the access key to its correct value: 

// Biblio extension
$isbndb_access_key = '??????';  // your access key obtained from isbndb.org
require_once("extensions/Biblio.php");

If the daily quota of 500 requests to isbndb.org is not enough for your site and you are in a hurry, you can use multiple keys instead of one, like this: 

// Biblio extension
$isbndb_access_keys = array('??????', '??????', '??????');  // 3 access keys
require_once("extensions/Biblio.php");

5) Now everything is installed and should work properly if you are connected to the Internet. Test the installation with the example given earlier.

Syntax reference

This is a semi-detailed reference for experts. Follow the links above if you just want to see what the extension provides.

<biblio> usually comes at the end of a page or a section, and after the corresponding citations. Several <biblio> sections are allowed although it is not common practice. A <biblio> ... <biblio> section encloses a list of bibliographic references that have the following form: 

#KEY TEXT [ANNOT]

where KEY is a case-sensitive combination of characters starting with an alphabetic character and continues with any sequence that can contain alphanumeric characters, "_", "-" and "+". There is another form, which represents the inclusion of another web page: 

#LINK

where LINK is either a wiki page name between double square brackets as in [[page]], or a full URL within a single pair of square brackets such as [http://www.example.com/biblio.txt]. The contents behind these URLs can only be a list of bibliographic items of the form #KEY TEXT [ANNOT], further inclusions being forbidden.

ANNOT is optional (and supported from version 0.7.1). If present, it must start with [:space:]// (space, tab or newline followed by "//"). Everything that follows will be displayed as an annotation of the bibliographic record.

TEXT can have several forms. In the current implementation, it is either raw wikitext, a PMID specification or an ISBN specification. The recommended format for a raw reference is: 

Authors. ''Title''. Source.

which is rendered roughly as:

Authors. Title. Source.

A PMID specification has the following form: 

pmid=VALUE

where VALUE is the actual numerical value of the PMID which is an 8-digit number for recent publications.

An ISBN specification has a similar form: 

isbn=VALUE

where VALUE is the actual value of the ISBN, with or without hyphens. This feature has been introduced in Biblio.php version 0.7.0.

<cite> is used to add a link to the reference in the <biblio> section. It simply contains a list of keys that will be automatically replaced by a number which matches the order in which they are cited.

Technical considerations

It supports referencing by PMIDs, which are the unique identifiers which are used by the Medline database of biomedical literature. The cool thing is that you only give the PMID and the corresponding citation is downloaded from the PubMed web service. Suggestions concerning interfaces to similar services in other academic fields are welcome. ISBNs are now supported as well in version 0.7.0 or above: see comment in HTML source of biblio sections if you want to know the version that is installed in a given wiki.

References are sorted in the order of appearance, which allows us to implement this as an in-place text substitution in one pass. It means that if a reference is cited, it must appear at least once before the list of references that contains it. For the same reason, references are sorted in the order of the first citations. Numbering them in alphabetic order does not seem to be possible without patching Mediawiki. So we will stay in the current situation, which is fine anyway, and does not depend on any particular version of Mediawiki.

Integration with Endnote

It is quite useful to integrate biblio with EndNote. This can be done by exporting the Endnote library to text format and make some changes to the endnote style.

  1. Copy one of the Endnote Styles (i.e. C:\Program Files\EndNote\Styles ). I made a copy of Biochemistry.ens and changed the name to Biblio.ens. You can conceivably use any Endnote Style.
  2. Double click on Biblio.ens.
  3. Under Bibliography, Click on Layout.
  4. Change Bibliography Number to #Record Number (Note: Don't forget the #.)
  5. Close this window. Endnote will ask you to save. Click Yes.
  6. Open Library in Endnote.
  7. Select Biblio.ens under the Style Manager.
  8. Be sure that Biblio.ens is selected under the Output Styles.
  9. Under File, click Export...
  10. Save text file.
  11. Check text file under notepad to be sure that all the entries begin with #1, #23, ... etc
  12. You can download the text file to the server or paste the text file into a new wiki page.
  13. You can reference endnote entries by using #160, etc.

I found it useful to have an entry called #Endnote with the date of the endnote library. e.g. #Endnote endnote library is current as of 11/25/06.

For those of you that are interested in the style library or have questions: You can find my email on [1]. Note that I am not the author of this extension.

Example

This is an example of an Endnote Library. You can find out if this is the current Endnote Library by citing #Endnote [7] and you can cite references from the Endnote library [8].

References

<biblio force=false> #[[Current-Endnote]] </biblio>

WIKI for example

 ===Example===
 This is an [[Current-Endnote|example of an Endnote Library]].  You can find out if this is the current endnote  
 library  <cite>Endnote</cite> and you can site references from the Endnote library <cite>#272</cite>.
 ===References===
 <biblio force=false>
 #[[Current-Endnote]]
 </biblio>

Bugs and installation problems

"Cannot redeclare class soapclient"

There seems to be a name clash between some recent versions of PHP5 and nusoap, both declaring a class named soapclient. It is explained there: http://www.oreillynet.com/cs/user/view/cs_msg/56663

Note: If you change the name of the class in nusoap, as the above document suggests, be sure to change it in Biblio.php to exactly the same name!

This is now fixed in version 0.8.0 (the modified version of nusoap is included in the biblio package). --Martin 16:25, 26 September 2006 (PDT)

Signatures don't work in <biblio></biblio> tags

Signatures don't appear to work within the <biblio></biblio> tags, or perhaps just in the annotation bit. --68.163.70.14 14:45, 1 August 2006 (PDT)

<cite>something</cite> replaced by something like UNIQ4bdfd3f54bddd1d-cite-f9370392530472500000003-QINU

Such symptoms already appeared in MediaWiki 1.6 (starting from 1.5.8?) and were fixed in Biblio version 0.7.5, but they reappeared in MediaWiki 1.7.1 (see discussion page). The documentation for writing extensions is there: metawikipedia:Extending wiki markup, if anyone is interested in investigating the problem.

As of today (version 0.8.0), I haven't been able to reproduce the bug, although I haven't tried very hard. From a fresh install of Mediawiki it seems to work well. --Martin 16:23, 26 September 2006 (PDT)

History and future

Wikiomics:Biblio may evolve toward a smaller PHP program that uses the Wikiomics:Wiblio service (currently under development).

History of changes:

  • biblio-0.8.1.tar.gz: provides support for the inclusion of bibliography listings from either local or external web pages. New things:
    • new tag <nocite>,
    • new option "force" for the <biblio> tag (e.g. <biblio force=false>)
    • syntax for including a local page: #[[bibliopage]]
    • syntax for including an external page: #[http://www.example.com/mybibliopage]
  • biblio-0.8.0.tar.gz:
    • caching: uses a patch from Alexandre Gattiker which stores the result of PubMed and Isbndb queries into a 24-hour cache.
    • repackaging: a targz archive with nusoap included (still needed because PHP4 doesn't come with a standard SOAP client)
    • support for PHP5: a slightly modified version of nusoap is redistributed, it now avoids namespace clashes that occur with PHP5 (class soapclient)
    • support for MediaWiki 1.5, 1.6 and 1.7 in the same source file
  • 0.7.5+1 0.7.4+1: libcurl is no longer needed
  • 0.7.5: fixes a bug which caused the content of some special markup ("cite", "biblio", but also others like "math") to be erratically replaced by some illegible sequence of characters in some versions of MediaWiki (1.6.x). This bug was fixed by Austin Che; thank you!
  • 0.7.4: (1) got rid of notices (hopefully all of them but maybe not) on PHP installations that set the E_NOTICE error reporting bit. (2) Biblio.php now only defines things that start with "Biblio" in order to avoid clashes with other PHP scripts. (3) Several access keys for the isbndb.org service can now be used in the same Mediawiki installation.
  • 0.7.2: using a site-specific access key to access isbndb.com is now possible, and highly recommended.
  • 0.7.1: support for inline annotations of bibliographic records (placed after "//"), after a suggestion by Marc Kirchner.
  • 0.7.0: support for citations using ISBNs, downloading info from isbndb.com (suggested by Ty Thomson)
  • 0.6.3: added PubMed redirect links when no DOI is available: good for some articles with a web page at the publisher's site but no DOI; printable version now printer-friendly; added copy-pastable DOIs and PMIDs to the text of the references.
  • 0.6.2: added direct DOI links; minor cosmetic changes; fixed problem of articles with only one author (reported by Jason Stajich).
  • 0.6.1: fixed missing (n-1)th author when n>=3 (contributed by Jason Stajich).
  • 0.6: added "get all abstracts" link; added links to HubMed, which has very nice export features, including BibTeX; no connection to server if the list of pmids is empty; fixed bug causing empty parentheses ()
  • 0.5b: removed blank POSIX character class for compatibility with older PCRE versions. Tested with Mediawiki 1.4 and 1.5.
  • 0.5a: first release

Don't hesitate to add your comments on the discussion page if you encounter problems or if you have brilliant ideas on how to improve the extension.

List of users

This is a list of public wikis which use the Biblio extension, in alphabetic order:

See also

Retrieved from "https://openwetware.org/mediawiki/index.php?title=Wikiomics:Biblio&oldid=417695"