First things first
Initialization
How to display a publication list
Sorts and jumps
Automatic generation of links
Automatic generation of BibTeX files
Team and individual pages
How to create sublists by criterion
How to Import BibTeX files
How to create reference lists
Macro (string) file
Automatic 'New' tagging
How to add publication types (advanced)
Additional notes
This page explains how to use Publist for your publications lists. A list can be embedded in any HTML document, but the document must have a .php postfix, so that your server will know how to handle it correctly (This assumes of course that your web server supports PHP. If it does not, please contact your system administrator.) If you have an existing page in which you'd like to embed your lists, just change its extension from ".html" or whatever it is to ".php". If you prefer to forgo the instructions, or follow them with ease, I suggest you have a look with an editor at the examples in the examples/ directory.
To use Publist, you will need to instantiate (initialize) a new Publist object. An example of how to do this is given in this code:
<?php
require "publist.php";
$pubs = new Publist(array('papers.xml','talks.xml'), $_GET['sort'], 'macros.dat');
?>
The first and last line are required to delimit the PHP code from the rest of the HTML document. The second line tells PHP to read the main Publist program. In the third line we initialize a new Publist object into a variable (called $pubs in this example, but you can choose any name you like). The Publist() function takes three arguments: an array of filenames of the XML file containing the publications (see XML format), a sort criterion, which we'll discuss in a moment, and an optional third filename for macros. This snippet of code should come at the beginning of the document, preferably right after the <body> command.
How to display a publication list
To print the entire list of publications, sorted by the current sort criterion, just call the
print_all() function, as shown in this example:
<?php $pubs->print_all(); ?>
This line can be added anywhere in the document after the initialization code. Note however that
publications are shown in a list context, so you may want to wrap this code with <UL>
or <OL> commands.
In same cases you may choose to only display subsets of the publications, in which case, you'll use other functions. See below for team and query-specific lists.
If you want to allow the viewer to sort publications by different criteria, use the
show_sorts () function by adding this line at the document location where you want the sort
links to appear:
<?php $pubs->show_sorts (); ?>
This function adds links to the same document, but with an additional parameter of the format
sort= and a sort criterion to the link. This parameter is then extracted in the
$_GET['sort'] variable we used to initialize the publications list based on the chosen sort
criterion. The criterion can be one of the following:
Another feature allows you to show links that jump into different headings in the list, depending on the sort criterion. For example, sorting by year will allow jumping to any specific year that had a publication. To use this feature, call the function show_jumps (team):
<?php $pubs->show_sorts ('true'); ?>
The parameter team must be either 'true' or 'false', and denotes whether only team publications 'count' for categories, which is useful when displaying a team publication page.
Whenever Publist displays a publication, it searches for the following files,
and adds a hyperlink to each file it finds:
Automatic generation of BibTeX files
Publist will try to generate a new BibTeX file and link to them for every publication that doesn't have such an entry. This requires that the bibtex/ subdirectory is writable to all, so if your security policy does not allow this, Publist will not create the new file. (One workaround is to create the BibTeX file once, and then change permissions back to read only). Even when it does succeed, Publist tries to do a reasonable job at creating the appropriate BibTeX fields, but some publications will still require manual editing of the resulting file. It is recommended that after invoking Publist for the first time to create the missing files, you go over them and make any corrections yourself. Similarly, if you make changes to the XML data and want Publist to regenerate the BibTeX file, you should remove or move the old BibTeX file.
Publist allows the displaying of both individual and team publication lists from the same data files. A team publication page can read in all the individual publications files (e.g., each user has their own file), and present those publications that are chosen for the team page by setting the <team> tag to true. To accomplish this, use print_team from the team's page, which only selects the appropriate publications (don't forget to also use show_jumps('true') in this case).
An individual's page on the other hand would typically only read the individual's publication XML file at initialization, and then use print_all, so that publications with team set to false will also be displayed.
How to create sublists by criterion
To create a publication sublist anywhere in the document (after initialization),
just add a line like:
<?php $pubs->print_select ("area", "Parallel Job Scheduling"); ?>
This example will show all the publications whose area equals "Parallel Job Scheduling".
You can similarly use it to select all the publications whose year equals 2003, or those whose first
author equals "Denver, John", etc.
A more powerful option is given with print_select_generic, which accepts a function name as a
parameter. This function should receive a publication (of class Publication), and return TRUE iff this
publication should be selected. The following snippet demonstrates how to use this function to select
all the publications where John Doe is one of the authors:
<?php
function get_john ($p) { return in_array ("Doe, John", $p->authors); }
$pubs->print_select_generic ("get_john");
?>
The publications are again in a list context, so you may want to wrap this code with <UL> or <OL> commands.
As of version 1.1, Publist includes a Perl script (bib2xml.pl) that converts most types of simple
BibTeX entries to XML format readable by Publist. Using the script is straightforward: give it
a list of .bib files, and it will output one XML file to standard output, in the same order of the
BibTeX entries.
bib2xml understands BibTeX @Strings and can parse BibTeX entries almost as good as BibTeX itself, but
cannot do much about entries that Publist doesn't support. Those will be embedded in the output as
comments. It is advised that after running bib2xml, you visually inspect the output file and make
any corrections or additions, including additional hyperlinks.
To learn more about bib2xml's features, read the first page of the file bib2xml.pl. Note that
bib2xml requires that the Perl module Text::BibTeX be installed (it can be downloaded from
CPAN).
Caveat There are two bugs I've recently found in BibTeX.pm, both are annoying but easy to overcome: problems parsing the second BibTeX entry and crashing right before the end. For more information, read the first page of bib2xml.pl
How to create reference lists (citations)
Citations have two parts: the citation itself, which can be placed anywhere in the document, and the
full list of references, which should come after all citations (typically at the end of the document).
For citing a paper, use the cite command with a comma-separated list of publication keys,
as in this example:
<?php $pubs->cite("jsspp03,sc02 , design ") ?>
To create the references list, just call the print_refs() function. You would typically want
references to be numbered, so use the HTML <OL> command, as in this example:
<OL> <?php $pubs->print_refs(); ?> </OL>
As of version 1.2, Publist supports a macro file, that works similar to BibTeX's @string. To use it, simply create a plaintext file for your macros. Each line contains two fields, separated by a tab. The first field is the macro name, and the second is the string that replaces it. For examples, look at my own macro file (Also in the examples/ directory).
Publist can prepend a small "New" picture to those publications that appeared within the last n months (or the future), where n is a parameter and defaults to 6. To change this parameter, modify the new_months default value in publist.php (using -1 will disable this feature). If you use this feature, make sure you have a readable file called new.gif in the parent publication directory of appropriate size (one is included with Publist). Note that when using print_refs() or print_select() their default behavior is to use -1 as the "new" parameter, or in other words, the feature is disabled in those modes. If you want to restore it, replace the -1 in those functions with $this->new_months
How to add publication types (advanced)
To add additional types, or to change the behavior/definition of current types, you will be required to change publist.php, and possibly pub.php. In the former, the first two things to look for are the $type_header variable, and the compare_type function (for sorting). These are also good places to look to find the currently-supported types. If you need to change the behavior of any particular type (e.g. treat periodical articles as papers), search in those two files for the type you want to change, and if applicable, search also for the type whose behavior you want to mimic. Most likely, the changes will be trivial.
For any questions, feature requests, bug reports, and comments, by all means, do write me
at a
Back to Publist's homepage