Biblio documentation wiki

The Bibliography Module needs better documentation and Wikis seem to be ideal for working on manuals. Anything that gets created here can then be moved over to the http://drupal.org/node/111016. I copied what is there now here:

Overview

The Bibliography Module allows you to create and maintain bibliographic lists of publications. The full (HTML) text of the publication can be included if so desired. Other files such as PDF or Word documents can be attached using the upload module.

Bibliographic entries can be imported from EndNote (versions 7,8,9,10 in XML or tagged format) and BibTex. The bibliographic lists can be formated in a number of styles including: American Psychological Association (APA), Council of Science Editors (CSE) and Institute of Electrical and Electronics Engineers (IEEE). Additional styles can be added by editing the biblio_style_stylename.inc file.

1) Installation and updating

5.x and greater

Create a directory called biblio in the sites/all/modules directory, then place all of the files packaged with this module in that directory.

This module will auto-install the required database tables the first time you enable it on the admin/modules page. This will also setup a number of pre-defined publication types. These types can be changed or deleted on the admin/settings/biblio/types page (see advanced use).

Updating

• First of all, back up your data. If something goes wrong, you will be able to roll back without losing anything.
  IMPORTANT! If you are upgrading from one of the beta releases or RC1 to the latest version in the 6.x series, you should follow these instructions.
• If you have any custom style in the biblio folder, remember to copy it to somewhere safe.
• Remove completely the directory with the previous version. If you keep both directories in the modules folder, Drupal will get confused.
• Unpack the new version of the module in your modules installation directory. Copy back any custom style to the module folder.
• Finally, run update.php.

Older Versions

2) Configuration

Basic preferences

A number of settings are available at admin/settings/biblio. There, it is possible do the following:

• Change the base URL of the biblio module, as well as the title displayed in the biblio list.
• Change the number of entries showed per page.
• Restrict users from viewing biblio entries other than their own.
• Create a Drupal block to display a number of publications. The number of items is also configurable.
• Control the automatic generation of citekeys for new entries - especially useful when exporting the entries from the biblio module to other formats such as Bibtex.
• Control the integration with the Footnotes module.
• Control how the module identifies and manages keywords.
• Control how links to external sites are handled.
• Control the generation of an OpenURL for each entry.
• Control how each user is allowed to override the global settings of this module; control if a list of publications by user is to be shown in the profile pages.
• Enable/disable a search box in the module.
• Control the default sorting and ordering in the biblio list.
• Choose the display style to be used when displaying the list of entries (see "Display styles" for more information)
• Control whether a RSS feed with the newest items is to be created and how many items it will show.

Publication types

Biblio comes with a large number of pre-defined publication types, such as books, journal articles, conference papers, newspaper articles, etc. For each type, a set of compulsory and optional fields are defined, as well as the order that they are presented to the end user. You will probably want to fine-tune the settings, in order to avoid unnecessary complexity in the new publications form.

You can alter the fields for all publication types, both the default ones and the ones you create yourself.

Selecting possible publication types

In the Biblio Settings, click on Fields, and then Publication Types (/admin/settings/biblio/fields/type). A list of existing publication types is presented. You can show/hide types according to your needs.

By selecting "Add new type" you can create a new publication type from scratch. When a new publication type is added, it will contain all the default fields. This also allows the administrator to override any of the default settings for any given type.

"Reset all types to default" will remove all customizations made to the existing publication types. It will also delete all the fields from custom publication types - but you will have to delete them yourself, by clicking on the "Delete" link in the list of publication types (visible only to custom publication types).

Customizing fields for existing publication types

In the Biblio Settings page (/admin/settings/biblio), click on the "Fields" tab (it will take you to /admin/settings/biblio/fields). You will see a list of field settings that are common to all publications types.

• The checkbox "Common" indicates which fields will always have the same settings for all types.
• Use "Title" and "Hints" to set the texts which will be display on the input form.
• Checking "Required" will force the user to supply a value for this field.
• The weight value changes the order which it is rendered on the form with smaller values floating to the top of the form. Drupal 6.x only: the order that the fields are shown can also be changed by dragging and dropping the row using the four-arrow icon on the left of each row.
• Drupal 6.x only: "Autocomplete" controls if the form will suggest values to the user based on existing entries in the database.
• Finally, for each author field you can choose a set of author roles. Assigning different roles to authors within the same field, e.g. primary and secondary authors within the authors field, allows to theme them differently.

After you have defined the global settings for the fields, you can adjust also the fields for each publication type. To do so, click on "Publication types" (/admin/settings/biblio/fields/type/). Select the publication type you want to adjust and click on "edit". The form for adjusting the fields is similar to the previous one, with the following differences:

• Checking the "Visible" box will add the field to the input form. Non-visible fields will still be available in the New Publication form, however they will be grouped in a hidden div under the title of "Other Biblio Fields".
• Fields which are greyed out on this page have been set to "common" on the admin/settings/biblio/fields page.

Don't forget to save your changes to each form before changing pages or clicking in a tab.

Access control

Some permissions related to the Biblio module are controlable on the admin/access page:

• administer biblio - gives access to the administrative area of the module
• create biblio - grants the permission to add a biblio item
• edit all biblio entries - grants permission to edit all biblio entries, included entries made by other users
• edit own biblio entries - grants permission to edit biblio entries created by the user
• import from file - grants permission to import entries from a text file (such as a BibTex or EndNote file)
• show download links - shows the download links for files attached in the biblio entry. The user has to have also the permission to see those files granted by the Upload module.
• show export links - shows the export links (to Bibtex, RIS, Endnote, etc.)
• show filter tab - allows the user to filter the biblio list results
• show own download links - shows download links only to biblio entries created by the user
• show sort links - shows the links to sort and order the list of biblio entries
• view full text- allows the user to see the full (HTML) text of the entry

Authors

Author types

(Multiple roles for a type are possible, write something about it here?)

Other settings

As any other Drupal content type, a Biblio item can also have some default settings to be presented to the users in the Create Content form. By accessing Administer > Content Management > Content types > Edit Biblio, you can change:

• Title field label (default: Title)
• Body field label (default: Body)
• Remove completely the option of adding a body to the item
• Minimum number of words to the body
• Submission guidelines - helpful to give instructions to the end users about adding a Biblio entry
• Default workflow options, such as if the node is published or not, sticky in the top of lists, promoted to the first page, etc.
• Default comment settings.

3) Basic usage

After installing the module, an item called "Biblio" will be created in your Navigation Menu (the default path is /biblio). With that link you can access the list of publications.

The Biblio menu entry has three sub-items that are helpful when managing your publications database.

• Authors (/biblio/authors) takes you to an overview of all authors available in the database. This list is generated automatically according to the authors contained in the publications you insert.
• Keywords (/biblio/keywords) works similarly, listing all the keywords that have been inserted with the publications.
• Import allows you to automatically populate the publications database from a text file. More about this in the "Advanced usage" section.

Adding a Biblio entry

• To add a new biblio entry, navigate to Create content > Biblio (/node/add/biblio).
• Select the publication type. This can be changed later, if needed.
• The form will reload with the options related to the publication type you chose in the previous step.
• Fields marked with a "*" are required.
• Enter one author per line. In Drupal 6.x and above, the authors fields have the autocomplete feature, which means that existing entries in the database will be retrieved and suggested. It is useful to avoid multiple entries referring to one single author. If you need to add more authors, you can click on "More Authors" to get extra lines.
• Drupal 6.x and above: you can use the drag and drop arrows to change the order in which the authors are shown.
• When you see in the form a link with a small arrow icon on the left, it means that extra options are available, but are hidden to reduce the complexity of the form. You can click on the link to show/hide the options.
• Other biblio fields: You can expand this section to see more fields available.

Editing a Biblio entry

You can navigate to the biblio entry you want to edit (either by finding it in the biblio list or via the /admin/content/node section). If you have permissions to edit the entry, you will see the option "Edit" on the top of the item. The options are the same as when adding an entry.

Deleting a Biblio entry

There are two ways of deleting entries:

• Navigate to the entry you want to delete. Click on "Edit". On the bottom of the form, click on the button "Delete".
• Navigate to /admin/content/node. Mark the checkbox related to the item(s) you want to delete. In the Drop-down box "Update options", on the top of the list, select "Delete" and click on "Update".

In both cases, you will be required to confirm the action. Remember that deleting items is an action cannot be undone!

Viewing the Biblio list

Sorting and ordering

The links on top of the Biblio list allow you to sort the items by different groups, one at a time. Clicking on the same item twice reverses the order the items are shown.

Filtering

The list can be filtered by author by simply clicking on the author's name on the Biblio list.

However, more complex filtering rules can also be set by clicking on "Filter".

You can define the first filter by selecting the desired facet using the radio button, selecting the respective value you want and clicking on "Filter". This will take you back to the list of entries. if you want to further refine the filter, you can click again on "Filter", choose a new selection, and click on "Refine". The button "Undo" will remove the last filter you defined, and "Reset" will clear all filters.

Filtered lists can also be sorted and ordered as explained in the previous section.

Filters are persistent, and are kept even if you navigate away from the list. If you want to remove them and see the complete list again, you can click on the "Clear all filters" link on the top of the list.

Adding Biblio Citations Inline

First, the Biblio module references filter has to be enabled. This is under:

Home » Administration » Configuration » Content authoring » Text formats

Then you can use the syntax described there to add references to biblio resources within the text of other content:

<cite><bib> or [bib]
Use <bib>citekey</bib> or [bib]citebkey[/bib] to insert automatically numbered references. </cite>

The cite key is available under Identifiers in the bibliographic reference.

Footnotes integration

If the integration with the footnotes module is activated in the settings page, it will convert <bib> tags into <fn> tags. This will cause intermingled <bib> and <fn> tags to be sequentially numbered. For this to work, you must put the <bib> filter ahead of the <fn> filter in the filter chain. If this option is not set, <bib> and <fn> tags will be handled separately.

4) Advanced usage

Direct URL to filtered pages

Here is how to link directly to the pages that can show only filtered publications without going to filter tab:

• in the same way as it is for author: http://yourdrupalsite.com/biblio/author/Lastname
• to show only records from year 2004: http://yourdrupalsite.com/biblio/year/2004
• to show only journal articles: http://yourdrupalsite.com/biblio/type/102 (enter Type ID here). You can look up Type Id in this link - yourdrupalsite.com/admin/settings/biblio/types.
• to show a generic search word: http://yourdrupalsite.com/biblio/search/yourwordhere

Importing items

Import of bibliography is available at
yourdrupal.site.edu/admin/settings/biblio/import

in the following formats:

EndNote Tagged
RIS
EndNote 7 XML
EndNote 8+ XML
BibTex

Assigning imported entries to an specific user

Exporting items

(How to automatically set the type of author: author roles vs. field types. See http://drupal.org/node/332915#comment-1362172 for reference)

5) Display styles

6) Uninstalling

Drupal 5.x and greater

Use these procedures to completely remove Biblio, its tables, settings and all related nodes.

• De-activate the module in the modules list (/admin/build/modules).
• Go to the uninstall page (/admin/build/modules/uninstall) and select Biblio module. It will only appear in this listing if it was de-activated first.
• Remove the biblio folder from your modules installation directory.

NOTE: You will loose any/all bibliographic entries that you have made and this action cannot be undone. So don't say you weren't warned!

Drupal 4.6/4.7

This is a bit trickier since you must delete all "biblio" type entries out of the node table (and in 4.7 the node_revisions table), then you can drop the biblio tables.

Older Versions

Installation

Drupal 4.7

• Unpack the module ".tar" file in the Drupal module directory. (Note: It is often advisable to create a "contrib" directory under the main module directory in order to make house keeping and upgrades easier).
• Now visit the admin/modules page and enable the biblio module. This will install the required database tables and setup a number of pre-defined publication types. These types can be changed or deleted on the admin/settings/biblio/types page.

Updating

Any time you install an new version of the module you should run the update.php script in case there are any database modifications included with the new version.

Drupal 4.6

• Unpack the module ".tar" file in the Drupal module directory, then create the database tables using following command:
  mysql -u {userid} -p {drupaldatabase} < biblio.mysql

• You will also have to enable the module on the admin/modules page.