Title: User's Guide
Subject: 
Publisher: No publisher
Description: CMFBibliography's User's Guide
Contributors: 
Effective_date: None
Expiration_date: None
Type: Document
Format: text/plain
Language: 
Rights: 
SafetyBelt: 1070968669.54

Basic Concept

  CMFBibliography enables the handling of references to various types
  of publications as they are used mainly in the context of scientific
  publications. In order to allow for interoperability with other
  applications that support reference handling, the information within
  individual references is highly structured. The concrete schema used
  depends on the kind of publication one wants to make reference to,
  so there is a variety of different reference types to choose
  from. The overall schema design follows closely BibTeX's approach, a
  very flexible and powerfull reference management system that comes
  with LaTeX.

Creating References

 The Bibliography Folder

  For reasons that will become obvious as we proceed, references can
  only be created within 'Bibliography Folders'. So in order to make a
  reference object one first has to make such a folder which is just a
  specialized content type that can (per default) be added to any
  folderish object. Just select it from the drop down or add list,
  give it an id and a title and then change into it. There is also a
  variant of the 'Bibliography Folder' called 'Large Bibliography
  Folder' which uses a 'BTreeFolder' as base class. Per default this
  type is not enabled. Ask your site's administrator if you need it.

  Now there are two different ways in which you can add references:
  through the web or via import.

 Adding References Through-the-Web

  Through-the-Web entry of references is as straight forward as with
  any other content type in Plone except maybe for the fact that there
  are a lot of different fields in order to structure the data
  appropriately.  If you are familiar with any other reference
  management system, the meaning of these fields should be obvious. If
  not, look at the examples that come with CMFBibliography to get a
  feeling for how they are meant to be used.

  Two fields, however, may deserve some further explanation: The
  'authors' fields and the 'url' field. The naming convention with
  respect to author names follows the one of BibTex where a full name
  can consist of an arbitrary number of first or given names (first
  field; separate names by blanks), a middle part to hold any
  supplements that usually preceed the last name (e.g., titles like
  *von*; second field), and the last or family name that can also
  consist of as many parts as needed (third field). The last field
  ('homepage') offers the possibility to provide a URL to the authors
  personal web page or any other link that might be appropriate in
  your context. If you have references where some authors appear
  repeatedly, you can specify their homepage URL just once under
  'folder defaults' (see below).

  The 'URL' field is meant to hold any link that you see fit but its
  most natural use is of course to provide a link to the full text
  version of the refered to publication. This full text version can be
  hosted anywhere including your site, a personal page somewhere else,
  a preprint server, a journal's site or whatever. It is not the
  intention of the reference entries, however, to also hold the full
  text.
 
 Importing References

  An alternative to entering reference information through the web is
  to import the entries from a file. In order to do so select the
  Bibliography Folder's 'import' tab, type in the file name or select
  it using the file browser, specify the appropriate format of the
  file and press 'import'.  The references contained in the file will
  be parsed and corresponding entries will be generated in the
  folder. No care is taken to avoid double entries, so it is your
  responsibility to control for that. Ids are generated from the first
  author's last name plus the publication year plus, eventually, a
  letter from the alphabet to make it unique.

  As of this writing (December 2003 over Syberia on my way from Tokyo
  to Paris ;-) only BibTeX and Medline imports are supported but more
  will hopefully come (see the developer's guide if you want to know
  how to contribute a parser).


Further Features

 Exporting References

  If you want to use the references stored within a Bibliography
  Folder in some other application (like for writing a paper) you can
  export the references by selecting the folders 'export' tab and
  specifying the format you want (currently, only BibTeX is
  supported). This will generate a file holding all the information in
  the appropriate format and you will be offered to save this file
  locally on your machine (some versions of MSIE desperatly try to
  open the file because they think they know better than you what you
  want ...).

 Default Author Homepages

  If you are dealing with references where some authors appear
  repeatedly you may want to provide their homepage URLs only once to
  reduce the amount of typing as well as to be able to update it
  conveniently if need be. In order to do so, the Bibliography Folder
  provides a 'defaults' tab that takes you to a form that allows you
  to associate author names with URLs. Whenever an entry is displayed
  with author URLs, the lookup is done in the following way: first, it
  is checked whether the author information within the particular
  entry holds a URL and if so, this is used. If this is not the case,
  the folder defaults are looked up where only the first first name
  and the last name are used to look for a match. If this also fails
  the system continues to see whether it can find a user within the
  site where the full name matches and if this fails it looks for a
  user/login name matching the lastname. In the latter cases a link to
  the author's homepage within your site will be provided.

 Ranking

  Depending on your site's set up it may be that there are places
  where selected references from a folder are displayed. In order to
  control for this selection, you can rank the references by selecting
  the Bibliography Folder's 'defaults' tab and then entering the ids
  of the references you want to be representative one per line into
  the 'Ranking' field.  You may enter as many as you like (including 0
  - in this case the representative references will be ordered by
  publication year backwards and then by author alphabetically). Ids
  that don't occur in the folder are simply ignored.
