Bibliographic/OOoBib Functional Requirements

Original Author: Manish Agrawal, 2003

This document needs considerate work to bring it up to date and to make it comprehensive. It has been place on this wiki so the OOo bibliographic community can contribute to its development. Please feel free to add, improve or dispute entries here. Please do not just delete entries you do not like, put in a statement in bold text explaining why you disagree.

Introduction

Description:

The Bibliographic module in OpenOffice is designed to provide authors with all the required functionality to manage and use bibliographies and references in writing research papers. In addition, the Bibliographic module will allow users to share bibliographies with co-authors using other popular bibliographic software such as Endnote.

This document should contain a comprehensive list of user functional requirements for the bibliographic module. The use cases presented here describe how the bibliographic module should interact with the users. That is, it presents the user experience and does not deal with the underlying technical issues.

The information in this document can be used to develop the user interface and the software design of the bibliographic module.

Offering input:

The best place to provide input is the mailing lists of the OpenOffice Bibliographic module. You may join these lists by going to http://bibliographic.openoffice.org. It is desirable that the bibliographic module focuses on functionality that is really required by authors on a day-to-day basis. In the opensource spirit, please feel free to express your needs and every effort will be made to incorporate the functionality if it really meets day-to-day needs.

Purpose and scope of the Bibliographic module

The Bibliographic module will do the following:

• Serve as the personal Bibliographic library and library for 'serious' writers
• Serve as the repository of encyclopedic information for 'young' writers
• Allow 1-click switching between bibliographic styles
• Export bibliographic references in all popular formats such as Bibtex, RIS (Endnote)
• Import bibliographic references from all popular formats such as Bibtex and RIS
• Allow easy sharing of bibliographic styles
• Allow easy creation of bibliographic styles
• Provide intuitive and friendly GUIs for all these functions
• Many functions of the biblio module resemble those that would be desirable in a mini photo-album software. These features include storing images, assigning captions to them, searching them through captions etc. Some time should therefore be spent on identifying the extent to which the design of the biblio module should be capable of morphing into a photo-album module for OpenOffice.

Users

We have identified three categories of users of the Bibliographic module Academic authors in the scientific disciplines: These are the mainstream users who typically use the Endnotes-style references. Other scholars: These are users who make extensive use of footnote-style references Young authors and common users: These are students in K-12 schools who write term papers making extensive use of multimedia and encyclopedia-style references in their class projects. These users will be very interested in creating class presentations on Impress/ Draw. They are a very important category of users because they serve a critical marketing function for OO. Another group of users falls into this category. They are laymen with no interest in publishing scientific articles, but looking for an easy way to store and retrieve information. I am thinking of storing pictures, songs, videos etc. Since we plan to make the libraries available across networks, the Biblio module can serve as a library for all digitizable information that people collect. Though the biblio functionality will only appeal to a small subset of highly technical users, every computer owner can find value in an information store.

Definitions

Priority

Reflects the priority of the use case on a scale from 1 (highest) to 5 (lowest)

Visible references: The user may like to work with only a subset of references in the selected library at any given time. Visible references are the references that are currently available to work with.

Note: there is some confusion with definitions in this page. Our preferred definitions are as follows.

citation

a short description that points to a fuller description elsewhere, either in a note or a reference list

reference item

a fuller description; also called a bibliographic entry or item

reference list

a collection of references; also called a bibliography

However the following definitions have been used in this document and need to be rectified. -

Reference: Used interchangeably with citations and bibliographic references. A reference is the description of an article in a media outlet such as a magazine, journal, conference, report, personal communications. All references in a document are usually listed together in one place in the document and a label to the reference is placed at the appropriate place in the document.

Bibliography: Used interchangeably with library

Template

If you wish to add a a function use case please use the template -

What this function should do, in layman's terms

Priority

1 for highest, 5 for lowest

Inputs

From the user ; Pre-conditions for the input : Any pre-condition before the input

Action on input

This is the detailed section where the motivation for the requirement and the desired action are specified.

Options

Any options associated with the function

Output

What the function should do in as fine level of granularity as possible

Possible errors

Status

This will indicate the status of this function as the module evolves. The function may be voted down, the target milestone etc.

Using references in documents

Switch to biblio for selecting and inserting citations from local library into Writer/ Impress document in Endnotes format

CLARIFY: why the phrase "Endnotes format"? This is a general issue, no?

Priority

1

Inputs

A Writer/ Impress document and a biblio library

Pre-conditions for the input

A library that can be opened

Action on input

This is the basic function of the bibliographic module while working with documents. The user will use a key combination such as ALT-1 or a menu entry (tools -> biblio -> goto library) to switch to the biblio library. If the biblio module is not open, the default library is opened. The user selects references to be entered into the document and indicates that these should be inserted (ALT-2 or menu item references -> insert into document). These citations should be inserted into the document and the document should be formatted as per the specified style.

Options

The user may select 1 or more citations in the Biblio library at the same time, using the ctrl or shift keys.

Output

The document will include the in-text citation and bibliography in formatted form.

Status

Insert a selected object from the list of available objects in the selected citation from local library into Impress/ Writer document

CLARIFY: heading wording is confusing

Priority

Preferably 1, maybe 2

bruce: I don't see this as a high priority; more nice to have

Inputs

A selected reference in the Biblio library along with a list of selected multimedia objects within the library.

Pre-conditions for the input

Action on input

I am looking at this feature as a way to build unique functionality in OO that will appeal to the K-12 market. The most common activities these students and teachers do is to create projects with a lot of images. Think of a project on the life-cycle of a butterfly, or a travelogue of the trip during summer break. Each of these concepts combines a list of images into a common idea and should therefore be saved as one Now, it is possible that

Options

Output

Status

Merge neighboring citations

Priority

1

Inputs

A citation is inserted adjacent to citations that were inserted earlier. Adjacent is defined as being separated only by blank spaces.

Pre-conditions for the input

Citations inserted earlier and a newly inserted citation

Action on input

If this citation is not present in the earlier adjacent list, the previous list is expanded to include the new citation. Say, we have a sentence that reads: It has been stated (Agrawal 2001; Wilson 2000) that Bibliographies are a dumb feature in writer. Now if I add a citation (D'Arcus 1998) either before, after or inside the existing citations, the list should expand to (Agrawal 2001; D'Arcus 1998; Wilson 2000).

Options

Output

Possible errors

New citation is a duplicate of citations already in the list.

Status

Reformatting a document and the bibliography

Priority

2

bruce: to me this is THE most important issue, because everything revolves around it. I'd call this 1 then.

Inputs

A writer/ Impress document with some citations inline.

Pre-conditions for the input

A library is open

Action on input

All inline citations are compared to the respective entries in the library. All old in-text citations and the bibliography are deleted and replaced by the new information from the library. A list of all references for which matches are not found is displayed on the screen. The non-matching place-holders are retained in-line but some keyphrase indicating error is shown in the document in bold text. This could be: ERROR: No matching reference found. We need to make sure that the error message is not the same as is Endnote or other software.

bruce: I'd be more precise in the wording. Citations are not "deleted"; the rendered text (contained in cite:citation-body) is regenerated.

Options

User should be allowed to select the bibliography. This suggests that references are identified only by reference number, not by bibliography name and reference number. User should be able to save a copy of the used bibliography, give it a different name and still format the document with the new bibliography.

bruce: I think we should use uris as identifiers for just this reason; e.g. urn:isbn:34231856 or info:doi/13432u85845.

I think we also might allow citations to be inserted of this sort that are not already in the local database (?).

Output

The document with new information for all the used citations.

Possible errors

Some matching references are not found.

Status

Save bibliography inline with document

bruce: needs to be updated to reflect OpenDocument. We need to decide this issue ASAP; does formatting get generated from an embedded XML file, or from elsewhere? If the former, the bib data should be ALWAYS embedded (which would be my preference).

Priority

2

Inputs

A formatted OO document that includes bibliographic references. This document could possibly be in writer or Impress.

Pre-conditions for the input

The OO document should have at least 1 included reference.

Action on input

The citations used in the current document should be retrieved from the user's biblio library and saved as a separate file (biblio.xml) in the document.

Options

(1) Users should be able to specify whether they want to save the bibliography inline with the document (2) Users should be able to specify the format in which the bibliography is to be stored, possibilities include Bibtex and RIS (for Endnote).

Output

.sxw or .sxi file that includes the biblio.xml file, which is compressed along with content.xml and DTD files.

Possible errors

(1) Bibliography library is no longer available (if on the network)

Status

Searching for references in the library

bruce: I disagree with the specificy of this, which already makes all kinds of assumptions about the GUI. I also disagree we want this sort of complex search. Google has proven it is generally unnecessary.

My vision has always been of a little table of reference results, and a filtering search field at the top of that.

Priority

1

Inputs

User entries in a search form. The search form should come up either through the menu entry references -> search or through the key combination CTRL-F or through the function key F2.

Pre-conditions for the input

Action on input

This is a universal search capability for references in the current library. Users should be able to specify an unlimited number of search conditions to search within the library. Each criterion specifies the value of the keyword to be searched for within the specified field. An example of a criterion is “last name contains smith”. One of the available fields should be “any field”. For users with libraries that are not very large, I very much like the way Endnote's default search criterion is “any field contains”.

Options

Comparison operators should include equals, does not equal, contains, is less than, is greater than. Search criteria may be joined using AND, OR, NOT

Output

The references that match the search criteria are shortlisted. If the biblio module has a filter function to enable the user to work only with a subset of references at a time, the search function may also have the semantics of a filter. This is how Endnote works. The default view may be “show all references” which changes to “show selected references” when a search is applied.

Possible errors

No reference matches search criteria.

Status

Specify location of Endnotes-style bibliography in document

bruce: this is a styling issue

Priority

3

Inputs

Pre-conditions for the input

Action on input

Most journals expect the bibliography to be the last section of the paper, after all appendices and tables and figures. This is how biblio should function by default. However, it may be useful to allow users to specify the location in the document where they would like to place their endnotes-style bibliography. The utility of this flexibility is that users can place miscellaneous information (such as phone conversation transcripts) in the document after the bibliography while creating drafts. I do not know the exact utility of this functionality, but I have often felt powerless with Endnote because I cannot specify to Endnote where it should create the biblio.

Options

Output

Possible errors

Status

Associating paragraph and character styles with in-text citations

Priority

2

Inputs

Pre-conditions for the input

Action on input

This use-case is inspired by a limitation I find in Endnote. I prefer to use Garamond as my preferred font. However, I have not changed normal.dot and therefore, the body-text font in normal.dot is Times New Roman (TNR). I find that when Endnote formats the in-text citations, it formats them in TNR and I have to go in and change the fonts in the in-text citations to Garamond and it is very irritating. I therefore believe that users will find it very appealing if biblio uses the character and paragraph styles used in the current document to format the citations rather than the specifications in normal.swt.

Options

Output

Possible errors

If users have not rigidly followed style rules and have simply changed fonts inline without applying styles, the proposed mechanism will still fail. Should biblio then draw formatting information from the formatting of the adjacent text? That may actually not be a bad idea. All it means is that biblio should not apply any character and paragraph formatting of its own and simply insert the citations in place and allow the currently applied formatting to act on the citations.

bruce: the styling (we need a separate section for this) should be all based around styles. Users should not be doing local modifications. This, BTW, is one good reason to include better bib styling support in ODF; one could create a template that took care of all of this.

Status

Associating paragraph and character styles for the endnotes style bibliographies

bruce: again, why is this specific to "endnotes style bibliographies"? Also, see previous comments on citation styling. We can do better than Endnote.

Priority

2

Inputs

Pre-conditions for the input

Action on input

This use-case is inspired by my observation that I cannot specify the paragraph style for the bibliography generated by Endnote. In particular, though I can specify the line spacing and other paragraph style specifications, I am unable to specify the justification for the bibliography and have to do it manually.

Options

Output

Possible errors

Status

Change endnote-style bibliography easily

bruce: this is redundant (covered already by the "reformatting" requirement); merge and clarify them. Also, again, why the focus on the "endnotes-style"?

Priority

1

Inputs

Choice of bibliographic style from the available list of styles

Pre-conditions for the input

Action on input

This is one of the most useful functions of a bibliography management software. Different destinations for the paper (conference, report, journal_1, journal_2) require different styles for formatting the bibliography. It should be possible to re-format the document in the new style by simply specifying a new style. The change should format both the in-text citations and the bibliography. In-text citations may change from author-date to numbered style and the bibliography may change from sort-by-author to sort-by-occurrence.

Options

Output

In-text-citations and bibliography are recreated based on the new style

Possible errors

Status

Quick search for a specific reference

bruce: group this with previous search requirement? Call the other "advanced search"?

Priority

1

Inputs

Keyboard input from the user

Pre-conditions for the input

library sorted by a field

Action on input

As the user types characters, the sort-by field is searched for the first matching reference. This is a very useful function when the library grows in size. Usually, the references of interest are already in the library and the most frequent tasks is to identify the citation and use it. This is therefore a sort of quick-search feature that depends only on keyboard-input.

Options

Output

The first matching reference is selected.

Possible errors

No matching reference is found

Status

Visible fields in the library

bruce: see previous notes on search.

Priority

1

Inputs

Pre-conditions for the input

Action on input

Currently the biblio library appears as a spreadsheet, showing many fields at the same time. However, while browsing through the library, users only really need the first author's last name, year of publication and the title of the article. The more the number of fields that are displayed in the biblio window, the less information about each field that can be shown. Therefore, by default, biblio should only show the author, year and title.

Options

The user may be allowed to select the fields to be displayed in the library in some preferences setting.

Output

Possible errors

Status

Abbreviating author names

Priority

3

Inputs

Output style that specifies formatting of names in some form of abbreviated format such as first initial. last name etc.

Pre-conditions for the input

Action on input

The names in all name fields: authors, editors are scanned and abbreviated in the output as necessary. No change is made to the information in the library.

Options

Output

In-text citations and bibliography are formatted with abbreviated names

Possible errors

Status

Using et al with author names

Priority

2

Inputs

Pre-conditions for the input

Action on input

The list of authors in the field is compared to the specifications of the style. For example, a style might suggest that for articles with more than 3 authors, list only the first author and abbreviate the rest with et. al. in the in-text citation.

Options

The options are really in the style definition. The user should be able to specify the rules for abbreviating author lists in the style definition. Some journals may not want author lists to be abbreviated in any way

Output

The in-text citations and the bibliography are formatting with appropriately formatted lists

Possible errors

Status

Titles and other complexities in author names

Priority

2

Inputs

Author names with titles such as Jr., Sr., III, Ph.D. Etc.

Pre-conditions for the input

Action on input

Options

Output

The in-text citations and bibliography should display names in the appropriate format. Generally, the bibliography shows the titles but the citations do not.

Possible errors

Status

Show status of bibliography in status bar at bottom

Priority

1

Inputs

Open library

Pre-conditions for the input

Action on input

The status bar shows the total number of references in the library and the number of visible references. This becomes very helpful as user feedback when a filter is applied to the library and only a subset of references is visible in the library window.

Options

I am wondering if it would be useful to allow the user to define 1 or 2 fields of information that will be displayed in the status bar when a reference is selected. I am wondering if I would find it useful to see the name of the journal in which the selected article was published, maybe when an author has 10 papers in a range of 2-3 years and I only remember that the paper appeared in management science around 1999. Perhaps it might help if I could configure the status bar in such a way that useful information is displayed there.

Output

Showing x out of y references

Possible errors

Status

Removing field codes

Priority

1

Inputs

A formatted document with embedded bibliography

Pre-conditions for the input

Action on input

The field codes used to represent the citation are removed and the citations and bibliography are pasted into the document. This may be helpful in many cases (1) the document is sent out to other authors who do not have the biblio module or (2) the document is sent for printing and the author wishes to ensure that the bibliography will not get corrupted in any form.

bruce: not relevant for OpenDocument. This is all standardized in the file format (or will be), and there's really no risk of corruption.

Options

Output

All reference information is removed and replaced by formatted text inserted into the document.

Possible errors

Removing biblio field codes may also remove other field codes in the document

Status

Adding prefixes and suffixes to each citation

Priority

2

Inputs

Text such as page numbers or other personal comments around an existing citation

Pre-conditions for the input

An existing citation

Action on input

The new text is added before or after the specified citation. Suppose I have citations (Hopkins 2001; Miller 1998). I want to b able to annotate any of these citations. For example, (Hopkins 2001, page 476; see also Miller 1998).

Options

Text should be insertable both before and after each citation.

Output

The new text annotations are appended to the inline citations

Possible errors

Status

Customizing individual citations

Priority

1

Inputs

A citation or a block of citations in one location

Pre-conditions for the input

Action on input

It is often necessary to modify the standard formatting of a citation. For example if I write: George Smith (Smith 1998) detailed the procedure ..., it does not seem correct. I would like to be able to manually indicate that in this case I do not want the author name to be cited and the sentence should read: George Smith (1998) detailed the procedure .... In some other cases (though less frequently), it may be necessary to delete the year.

In some cases, it is also useful to manually modify the author order compared to default. I can't think of why the default alphabetical order would be inappropriate but let us say, you have many citations at one place summarizing prior work. It is conceivable that authors would prefer to be bale to manually place the seminal article first and the derivatives later.

Options

Exclude author, year, change citation order.

Output

The citations are formatted with the specified preferences.

Possible errors

Status

Ask user whether changes should be tracked when bibliography is formatted

Priority

2

Inputs

User selects to track changes

Pre-conditions for the input

Biblio module is in auto-format citations mode

Action on input

When track changes is on and the biblio module is auto-formatting citations, it is easy to set up a lot of changes by simply inserting a new citation at the beginning of the document, particularly if the bibliography uses an engineering/ numbered style for in-text citations. The user should have some control over how the Biblio module interacts with track-changes. Whenever both features are on, the user should get a prompt to decide whether or not changes to citations and the bibliography should be tracked. The user should also be able to modify this selection easily at any time.

My guess is that the best way to achieve this result is that if the user selects for biblio changes to not be tracked, what Biblio should do is disable tracking before it begins auto-format and then reinstate tracking when auto-format is done.

Options

Output

Possible errors

Status

Inserting references into the library

Use a form to fill in all the fields to create a new text-only scientific, academic reference.

Priority

1

Inputs

Text input into all the relevant fields of the “new reference” form

Pre-conditions for the input

Possibly that every new reference should have an author.

Action on input

There should be a simple interface for the user to add a new reference to the library – something like reference (on main menu) -> new (or ctrl-N) should bring up a blank form for entering a new reference to the library. This is the basic and familiar functionality of inserting new citations into the biblio library. A form would be presented to the user with blank values for all the fields available for the reference type. Users should be able to move between fields using TAB or CTRL-TAB keys. As the user enters data in each field, the entry should be compared with the lists associated with each field and when a match is identified, the user should be assisted with a suggested auto-completion prompt. Pressing TAB should auto-complete the rest of the name, title etc.

For fields that have associated term lists, if the new entry does not exist in the list, it should be automatically added

Options

The user should be able to select the type of scientific reference they want to insert. Common types include journal, book, book section, conference proceedings, report etc. If required the full list could be made a functional requirement as well.

Output

The software should first check to see if this is a duplicate of an existing reference. It may sound absurd but when the library grows big, it happens that you end up inserting a duplicate reference. If it is not a duplicate, a new reference is created and entered into the library. The reference is possibly identified with a unique ID number generated by the biblio module.

Possible errors

Duplicate reference, author-name not included

Status

Edit references

Priority

1

Inputs

A reference in the library is selected by pressing ENTER or CTRL-E (edit)

Pre-conditions for the input

Action on input

The editing window opens and the content in all the fields may be edited.

Options

Output

References are opened in a window which has all the properties of a window. It should be expandable by dragging the borders and have minimize and close buttons.

Possible errors

Status

Undo changes

Priority

2

Inputs

Undo option selected in the edit menu

Pre-conditions for the input

A reference is open for editing

Action on input

This needs careful thought. Once a change is committed to the library, it should normally not be changeable. However, users may expect undo functionality WHILE the reference is being edited. The simplest action would be to remember all changes since the reference was last saved.

Options

Output

The changes made to the references are sequentially deleted in reverse order. Undo is not possible when all the changes made since the reference was last saved are undone.

Possible errors

Status

Deleting references

Priority

1

Inputs

References -> delete; CTRL-D;

Pre-conditions for the input

1 or more references are selected

Action on input

The user receives a prompt to confirm deletion. If confirmed, the selected references are removed from the library. The unique ID numbers assigned to the deleted references are labeled as unavailable for future use. This last requirements ensures that if the user tries to format a document with these deleted references, an error message prints out. If these ID numbers are reassigned to new references, it is possible that documents formatted with the bibliography get wrong citations. Even if the references are reinserted

Options

Output

Possible errors

Status

Cutting and pasting references

Priority

2

Inputs

CTRL-X, edit -> cut

Pre-conditions for the input

At least 1 reference is selected.

Action on input

The reference(s) are deleted from the library and pasted to the clipboard in formatted form based on the currently selected style.

Options

Output

The citations should be saved in such a way that users can insert it into a writer document Also, if the citations are pasted into a different library, they should be entered as completed new citations.

Possible errors

Status

Choosing the reference type for a new or existing citation

Priority

1, maybe 2

Inputs

A new reference that is being entered or an existing reference that is opened for editing. The user selects a reference type (journal, book etc.) that is different from the reference type currently selected

Pre-conditions for the input

Action on input

The reference type for the reference is modified to the new type. Most importantly, this means that the labels for many fields will change and many new fields may get added. For example, the journal name will become book name, journals usually do not have series information or publisher names or ISBN numbers.

The fields should be consistent between publication types. For example, if I change a reference from journal to book, I should not have to retype the author names or title. All existing information should be retained in fields that are labeled appropriately for the new reference type. I have found this feature to be very useful when after entering information for 4-5 fields, I realize that I am entering information for a book, not a journal (my default). When I change the reference type to book, I don't have to re-enter author names or titles or any other information I had entered previously.

Options

User should be able to set the default reference type for all new references. Usually, the most preferred will be journal.

Output

The reference type is changed to the new type. All field labels are appropriately modified and filled with information from the earlier reference.

Possible errors

Populated fields in old reference type that do not have a comparative field in the new reference type.

Status

Entering author names

Priority

1

Inputs

Author names entered in first name last name format or last name, first name format.

Pre-conditions for the input

Action on input

It is very important for author names to be handled correctly. It would be disastrous if the bibliography messed up with first names and last names of authors. It is also important to allow flexibility in entering names. Most people are comfortable entering names in first name last name format. However, some users and many online libraries may prefer using last name, first name format. Biblio must handle both of these natively and parse out the name components.

It is also important to be able to handle corporate names such as “Sun Microsystems Inc.” and author titles such as Jr.. One common mechanism for handling these cases is to specify that these names be entered in a specific format. Endnote specifies that corporate names should end with a comma (so that the whole name is interpreted as the last name) and names with titles such as III, Jr. etc. be entered with separating commas e.g. Smith, Will, Jr. There should be no limit on the number of possible authors for an article

Options

Names may be stored in the library in a preferred standard format after parsing so that the user is always shown names in last name, first name format.

Possible errors

Status

Store references permanently

Priority

1

Inputs

Form window with a modified reference is closed or user presses CTRL-S on reference-entry form.

Pre-conditions for the input

Action on input

The reference open in the current window is permanently saved to disk, immune to computer crashes.

Options

Output

Reference inserted into open library and stored on disk.

Possible errors

Status

This case specifies how legal references are to be entered

Priority

1

Inputs

Pre-conditions for the input

Action on input

The goal of this function is to make the OpenOffice bibliography functions marketable to legal scholars and lawyers. Input is needed to specify this function in great detail. Perhaps a linked list of various commentaries in the case will have to be recorded

Options

Output

Possible errors

Status

Create a new bibliographic entry from a PDF document

Priority

2

Inputs

An open pdf document

Pre-conditions for the input

Action on input

The function of this use-case is to position the bibliographic module as a library of all academic papers of the user. Currently, many libraries (mine included) are discontinuing print subscriptions in favor of online subscription. Also, increasing number of papers are available in pdf format online. Therefore, users are saving these files on hard disks. Many users record whether they have print copies or pdf copies of these papers using the special fields in Endnote. Since these papers are basically intended for academic use anyway, it makes sense to store them within the biblio library itself. This will make the biblio module a complete academic file system.

Options

Add an entry to Acrobat's file menu to export the file to the biblio module. Would it be possible to drag and drop a saved pdf file in windows/ nautilus to the biblio screen to automatically start a new reference dialog for the user to fill in the remaining details? (2) Some users may prefer to use their file system to store files instead of saving them in biblio. For the convenience of those users, we could have create link and goto link options in the references menu. Create link would create a link to the file or web site and goto link would open the file specified in the link in the default program specified for the file-type.

Output

A new bibliographic reference with the pdf file stored into the biblio library

Possible errors

Application to open the file does not exist locally

Status

The previous use case, but with other popular document formats such as word documents, svg files etc.

Priority

Inputs

Pre-conditions for the input

Action on input

Options

Output

Possible errors

Status

Detect duplicate references in the library

Priority

Basic functionality: 1; optional features could be: 2

Inputs

A populated biblio library. Every library should have a set of default criteria for searching duplicates if no user-defined criteria are defined

Pre-conditions for the input

Action on input

Each reference is compared to every other reference for evidence of duplication. Duplication is inferred if search criteria are met. The

Options

User may be allowed to specify the fields to be checked for duplication. In addition, the user may be allowed to specify whether the search should be precise or lenient. In lenient search, leading entries like “a”, “an”, “the” and punctuation in article titles are ignored, author first and middle names are compared based on initials only. In addition, the users may be allowed to select criteria on the basis of which one out of more than 1 duplicates will be retained – the reference with the earliest entry (smallest ID #)? most recently entered (largest ID #)? entry with information in most number of fields ? Entry with most number of overall words of information (entries with detailed abstracts may be preferred over entries with more number of fields with information) ?

Output

A list of duplicate references found along with a checkbox for the user to approve the deletion of duplicates from the bibliography

Possible errors

Incorrect matches. Search should err only on the side of caution, duplicates should not be flagged when they are not actually duplicates

Status

Import references into the library from saved text files in standard formats

Priority

1

Inputs

A biblio library and a text file in bibtex/ RIS or another standard import format

Pre-conditions for the input

Action on input

This is the common technique to import references from online databases such as OVID. The user first downloads selected citations to a text file. This file is then opened using a filter. Each reference in the file is first read into a new reference. The new reference is assigned a unique ID # and is inserted into the library. After all the references have been imported, a search for duplicate references is made if requested by the user.

Options

User should be able to specify the filter to be used to read the import file. Allow user to preview fields before importing. This will be helpful to verify that the import will function as expected without corrupted fields. The user may also be asked whether they would like duplicates to be identified, or deleted without asking, or not identified.

Output

The references in the file are inserted as new references into the biblio library.

Possible errors

Import filter does not match the file format

Status

Preview data file for import with import filter

Priority

3

Inputs

Tagged Biblio file in text format and a selected import filter (RIS/ BibIx etc.)

Pre-conditions for the input

Action on input

The import file is parsed as specified by the filter and displayed in a preview window. This helps the user confirm that the data will be imported correctly and may also alert the user to possible import errors which they can then fix.

Options

Output

Possible errors

Status

Insert references into the local library directly from an online source

Priority

3

Inputs

A local library and a selected reference at an online source

Pre-conditions for the input

Action on input

The selected online reference is directly imported into the library without the intermediate step of saving the file. I am thinking that if possible, this would enormously speed up the importing of 1-off references. Once a bibliography evolves to a certain point, there are not that many references you add to it frequently. Generally it is just one reference at a time. For these cases, it may be useful to have 1-click insertion into the library.

Options

Output

Selected reference(s) are directly inserted into the library

Possible errors

Filters do not match the format in which the reference is downloaded, the reference is not properly formatted

Status

Create and edit term lists of places, publishers, authors, journals

Priority

2

Inputs

(1) Name of a place, publisher, author, journal/ conference being entered in a new reference (2) Data is typed into the term list

Pre-conditions for the input

To be decided. Do we want to specify that city names must be qualified by state and country names?

Action on input

The new entry is compared to existing entries in the specified list. If it is a duplicate, a flag is raised, otherwise, the entry is added to the specified list. Term lists are a user-assist feature and serves two purposes in day-to-day use. The first is that it speeds up the entry of names, places and outlets when a biblio entry is being created manually (a common occurrence). The second is that it minimizes typos in the bibliography as long as the lists have no typos.

Options

(1) Some term lists should be defined and associated with fields from the beginning. Examples are authors and journals (2) Users should be able to define new term lists and associate them with any field (3) It should be possible to export and import term lists (4) It needs to be decided whether term-lists should be associated with a library (like references) or with the computer (like styles)

Output

The specified list is updated with the new entry

Possible errors

Incorrect duplicate detection

Status

Auto-complete names, places, publications based on term lists

Priority

2

Inputs

Entry being typed into one of the fields with an associated list

Pre-conditions for the input

A list should exist for the field being typed in

Action on input

As soon as an entry from the list for the field is identified, the user is prompted with the rest of the entry for the field

Options

User may perhaps be allowed to turn auto-complete off

Output

The field is populated with the entry from the field

Possible errors

Status

Use abbreviations as well as complete names for journals

Priority

2

Inputs

Full journal name or abbreviated name in journal name field

Pre-conditions for the input

Action on input

The term list associated with journals is compared to the new entry. If either the full name or the abbreviation matches an existing entry, the full name of the journal is suggested and entered if the user accepts the suggestion. Currently, in Endnote, you can enter abbreviations, but the field only stores what you enter, so you cannot be confident about whether the reference will be formatted correctly when it is exported to another library that does not have the journal and its abbreviation in its term list.

Options

Output

The full name of the journal in the term list is entered into the journal name field

Possible errors

Status

Connect electronically to remote library

Priority

3

Inputs

Connection file for a remote library such as OVID or a library's catalog

Pre-conditions for the input

The remote library should comply with the Z39.50 protocol.

Action on input

This function allows the user to connect to a remote library. The interface to the remote library should be the biblio search form so that searching a connected remote library should be the same as searching the local library. The results of the search are retrieved in a separate temporary library. Selected references from this temporary library may be inserted into any of the biblio databases on local disk.

Options

Output

Selected references from the remote library are imported into the selected local library

Possible errors

Connection failure, change in remote port/ IP address, remote server down

Status

Reference types

Priority

1

Inputs

Pre-conditions for the input

Action on input

Biblio should come with templates for all the common reference types pre-defined. The important ones from Endnote 5 include journal article, conference proceeding, book, book chapter, magazine article, newspaper article, thesis, report, personal communication, electronic source, case.

Options

Users may be allowed to create their own reference types as well. This includes labels for the generic fields, included fields etc. The ability to define their own styles, though very useful, is only for the master expert users. In general, there should be templates for all commonly occurring reference types.

Output

Possible errors

Status

Storing html pages

Priority

2

Inputs

A web-page stored from IE or Mozilla. This html file is dragged and dropped into the biblio window or inserted into the relevant field of a webpage reference type

Pre-conditions for the input

The main html page that has correct references to objects in the associated folder. The associated folder is located in the same directory as the main page and has the same name as the html page (without the .html extension).

Action on input

These days, a lot of information is gathered from websites. Webpages can however have a very messy structure. Browsers such as IE and Mozilla do a great job of saving them as 2 objects – a <filename>.html file and all the rest of the content in a <filename> folder. Ideally, I would like the following: I drag the .html file to the biblio window. This pulls up a new reference window of type html page and inserts this html page into the top-level page field. What would be really cool is that as soon as the top-level page field is populated, biblio scans the directory for a folder with the name of the file. When the folder is found, it is automatically dropped into the folder field. I anticipate that the most common use for this html page would be to first drop it onto the desktop and then view it. This would imply that when the html file is dragged out, the folder an dits contents are dragged out to the same folder as well.

However, I can easily anticipate that users would like to simply click the file inside their library and view the contents without dragging and dropping to the computer's file-system. This is clearly a wish-list item. However, I also think it is very useful.

Options

Users may be allowed to upload objects into the reference one-by-one.

Output

Possible errors

Status

Creating journal styles

Portability of styles

Priority

1

Inputs

Pre-conditions for the input

Action on input

To make OpenOffice and the biblio module popular, it will be necessary to provide users with styles for all outlets they deal with such as journals and conferences. An initial set of the most popular styles could be made available through the efforts of volunteers but in the long-term, it should be envisaged that the outlets themselves would be responsible for creating the styles for their publications and make them available for download into biblio from their websites. This will ensure that users will have the current styles for all their needs with very little effort. To facilitate this, it should be possible to work with styles as simple files, perhaps text (XML) files. This is one of the great features of Endnote. Styles are as portable in Endnote as the references themselves.

It may even be possible to save the style inline in a document along with the used citations. I often find that when I try to work with a document on multiple computers, I don't have the styles on all computers. If the day comes when styles will be universally available, then it may not be necessary to export the styles into the documents, but until then, this is a very useful function. It has also been mentioned in the requirement for exporting the library inline.

Options

Output

Style specifications stored in a universally portable format.

Possible errors

Status

Selecting favorite styles

Priority

1

Inputs

Selected styles from the list of available styles

Pre-conditions for the input

Action on input

Though the biblio module will eventually have a complete list of styles, presumably one for every journal published and users will download an ever increasing number from the respective publishers, most users only use a subset of available styles on a day-to-day basis. For example, a historian will probably never use an engineering style and an engineer will have no use for most of the social science styles. Therefore, instead of requiring users to select the correct style for a document from the entire list of styles, the styles commonly used should be made readily available for selection. So, if an author frequently submits articles to ACM and IEEE conferences and journals, they will only shortlist the styles used by these outlets.

Options

Output

The selected styles are made available in an easy shorthand manner while formatting documents.

Possible errors

Status

Components of a style in the in-text citation

Priority

1

Inputs

Pre-conditions for the input

Action on input

It should be possible to define which of the available pieces of information about citations should be used in citations. Common values are [Bibliography number] and (Author date). Some of this information is based on information not stored in the references, for example: [Bibliography number].

The separator between multiple citations should be user-defined, though Biblio should provide a default separator. It should be possible to define how papers with multiple authors are cited (how many authors before et al). The format for displaying author names: Last name, first name; First initials, last name etc. Also, how the first author be shown and how the other authors should be shown.

Options

Endnote has only one style definition for a publication. So, all books, reports and journal articles are cited inline in exactly one way, usually in order of appearance or some variation of author-date.

Output

The user interface for defining parameters for inserting citations into documents

Possible errors

Missing fields

Status

Components of a style for bibliography

Priority

1

Inputs

Pre-conditions for the input

Action on input

It should be possible to define the template for formatting each reference-type in bibliographies. Therefore, for each style, it should be possible to define the formatting of each reference-type. The best thing would be to allow WYSIWYG editing. So, if the template for journal articles is written as Author “Title,” Journal (Volume:Issue) Year, Pages, an example output would be:

Abrahamson, E. "Managerial fads and fashions: The diffusion and rejection of innovations," Academy of Management Review (16:3) 1991, pp 586-612.

Options

There should be a template for each reference type for each citation

Output

A GUI for WYSIWYG editing of bibliography templates for all reference types associated with a style.

Possible errors

Status

Rules of dependence and special characters

Priority

2

Inputs

Pre-conditions for the input

Action on input

We need to define how to handle related fields in the Bibliography. For example, what happens if we do not have a issue, though we have a volume number or vice versa?

Related to this requirement is the need to define how to

Options

Output

Possible errors

Status

Formatting the document with a bibliography

Selecting a reference

Priority

1

Inputs

Up or down arrow keys or mouse-click over a reference

Pre-conditions for the input

Action on input

The reference indicated by the cursor or the mouse is selected

Options

Users may be allowed to select references in conjunction with the ctrl (discontinuous) or shift keys (contiguous) to select multiple references at a time.

Output

All references selected before the current sequence of actions are de-selected. The selected reference is made available for insertion into the document, editing and copy/cut operations. If the user presses enter, the first reference in the selection is opened for editing. If the user indicates insertion into document, all the selected references are inserted into the document at the location of the cursor. Selected references are remembered for the rest of the current session until de-selected.

Status

Allow user to specify words for which the case will not be changed

Priority

2

Inputs

A word whose case is not to be changed in the bibliography

Pre-conditions for the input

A list for the words which must be exempted from case-verification must exist

Action on input

While populating bibliographies manually, users often do not specify the cases of all the entries correctly and consistently. For example, in some entries, the user may enter every word beginning with an upper case letter, in other cases, the user may not do so. However, we would like the final bibliography to look smooth and consistent. For this purpose, we have a use-case that the user should be asked to specify the case of the final output. Some choices are: All-caps, sentence case, first-word caps etc. The problem with this approach is that, entries like America may become america and CIO may become cio if the user chooses sentence case. To avoid this, this use-case specifies that the user may be allowed to specify words whose cases are not modified in any way in the final bibliography. It will be the user's responsibility to type these words in correctly.

Options

Output

The new word is added to the list of words whose case is not to be modified while formatting the final bibliography

Possible errors

Status

Allow user to specify case of the bibliography

Priority

2

Inputs

User selects bibliography formatting from the options specified here. These options will be used to format the titles of each bibliographic entry.

Pre-conditions for the input

Action on input

None immediately, the case choice is stored for use when the bibliography is specified. When the bibliography is being formatted, biblio uses the choice specified by the user to format the title of each bibliographic entry. This choice is remembered for future sessions using this bibliographic style.

Options

UPPER CASE, sentence case, First Word Upper Case, no change, use case as entered.

Output

The user's selection is stored on disk

Possible errors

Status

Citing multiple works by the same first author

Priority

2

Inputs

References to multiple articles by the same first author

Pre-conditions for the input

Action on input

Many journal styles require that when there are more than citation by the same first author, the name of the first author be replaced by a – or some other token to improve readability.

Options

The token used to represent the same first author (2) The number of authors to be compared for similarity. Say there are 3 articles by the same 2 authors. Should only the first author be abbreviated or should the names of all authors be abbreviated?

Output

The bibliography is formatted with the appropriate abbreviated name of the author.

Possible errors

Status

Adding text before each reference in the bibliography

Priority

1

Inputs

Text, fields and numbering information to be inserted before each reference in the bibliography

Pre-conditions for the input

Action on input

The most common utility of this requirement is to insert sequence numbers before each reference in the Bibliography. At least, that is the only thing I have added before the bibliography. This feature may perhaps also be used to specify the formats for hanging indents for references. Styles have various ways of formatting the numbering for example 1., 1), (1), 1.<TAB> etc. All variations of these formats should be possible through this feature

Options

Output

The specified text is added before each reference in the formatted bibliography.

Possible errors

Status

Adding text after each reference in the bibliography

Priority

1

Inputs

Text and fields to be inserted after each reference in the bibliography

Pre-conditions for the input

Action on input

The most common utility of this requirement is to add paragraph breaks and perhaps the contents of the notes and/ or abstracts fields. Also, different journal styles have different specifications for the number of blank lines between references. It should be possible to add and remove references by simply clicking buttons

Options

Output

The selected fields and characters are inserted after each reference

Possible errors

Status

Defining sorting method for bibliography

Priority

1

Inputs

User-selected choice for sorting method for bibliographic citations.

Pre-conditions for the input

Action on input

Options

Order of appearance in the paper, author + title, Author + year + title etc. It may even be possible to allow custom sort orders

Output

Possible errors

Status

Defining capitalization method for bibliography

Priority

1-2

Inputs

Pre-conditions for the input

Action on input

This requirement smooths over inconsistencies between citations entered with different forms of capitalization. For example, some sources might capitalize all terms in titles, some others may capitalize all letters in titles and so on. The bibliography would look rather ugly if the titles could only be created using the native text. Like a friendly word-processor, the biblio module could convert all titles to a standard format

Options

Don't change titles, Sentence-style capitalization, Headline-style capitalization where words other than articles and prepositions are capitalized.

Output

Status

Miscellaneous

Export references from the library

Priority

1

Inputs

A selected library.

Pre-conditions for the input

If a copy of the entire library is to be made, it should not be necessary to open the library – users should simply have to select it in the file manager. If only selected references are to be exported, the biblio module should be opened and at least one reference should be selected

Action on input

The selected references are saved as a new biblio library.

Options

(1) The user may choose whether or not they would like the pdf files and copies of the actual papers in the library to be exported. Not including the actual files will reduce the size of the exported library, but in some cases the user may want to actually export the files to co-authors (2) if the actual files are not to be exported, the user may be allowed to export to one of the standard biblio forms – RIS, bibIx etc. The Endnote manual specifies 6 pages of possible output formats

Output

A new library or a text file in exchange format

Possible errors

Insufficient disk space to save the library

Status

Specify sort order while viewing references

Priority

1

Inputs

User click on the labels of visible fields

Pre-conditions for the input

A biblio library should be open

Action on input

The references in the currently open library are sorted by the selected field. For example, if the user clicks on the year field, the references should be sorted by year. The selection should work as a toggle switch, between ascending and descending orders.

Options

Default sort order should be specified. I personally prefer sort-by-author

Output

Nothing in the library, however, the references are displayed in the order specified

Possible errors

Status

Maintain multiple databases at the same time on the same computer

Priority

1

Inputs

Pre-conditions for the input

Action on input

This requirement indicates that it should be possible for the user to easily switch between databases while working on a document. Though it is generally advised that a user should have exactly one library for all their references, many users prefer to maintain separate databases for each project. The biblio module must not impose this choice upon users. This also indicates that the entire library should be balled into one file that is easy to work with in windows explorer/ Nautilus

Options

Output

Possible errors

Status

Preview citations

Priority

2

Inputs

A selected reference or style

Pre-conditions for the input

Action on input

User should get a preview of the selected reference in the currently selected style or a citation in the specified style

Options

Output

A frame showing a preview of the style

Possible errors

No style has been selected when a reference is selected for preview or no reference is available when a style is selected. The latter has high probability because there will be many types of entries – journal article, book, report etc. What if the user's bibliography does not have a reference entry for a report but the user would like to see what the entry for a report would look like when formatted as specified.

Status

Print citations

Priority

2

Inputs

Selected citations

Pre-conditions for the input

Action on input

This feature may be useful to authors if they would like to create a document with the list of references matching some criterion. It may be that this is to share the references with a colleague or to submit as an appendix to a grant proposal. I personally believe that the most common use will be to email the detailed citation to a colleague without retyping or copying and pasting. If no citation is selected, the semantics of the command should be “print all references in the library that are currently shown”. However, if this list exceeds say 10 references, biblio should prompt with “this command will print more than 10 references, are you sure you want to continue?”. If some subset of the visible references is selected, no such prompt is necessary

Note that this function is complementary to the ability to export citations. Generally, the export function would be to send the citations for someone else to import into their bibliography. The print function is for a more casual exchange of information. A colleague may want a list of citations on specified topic, and I could just open my library, select the required citations, right-click and select email recipient. Endnote has a copy formatted function when a citation is right-clicked that does a similar job. The difference is that the formatted citation has to be pasted into an application such as writer or email.

Options

The user may be allowed to print the selected citations to a writer file, pdf file, email client or directly to the printer.

Output

A writer/ pdf file with the selected references formatted according to the current style or the output is sent to the selected printer.

Possible errors

Printer not available, Internet connection not available (for email)

Status

Default library

Priority

1

Inputs

User specified library file

Pre-conditions for the input

Action on input

Biblio should remember the user's choice of a default library across sessions.

Options

Output

User's selection is stored in some file say “preferences.ini”

Possible errors

No library available

Status

Create new library

Priority

1

Inputs

File -> new library or CTRL-N with no library open

Pre-conditions for the input

Action on input

A new library file is created. The user is prompted to specify the name of the library and whether they would like to make the new library the default library. Most users only have one library and this function hand-holds users into creating and using that library in their work. It is a “the application is the computer” kind of function. When users invoke the biblio for the first time, this function walks them through setting up the library with a reasonable name (from system settings perhaps) and file location (my documents or user's home) by default. For future sessions, this library is opened by default whenever biblio is opened unless the user specifies some other action.

Options

Output

A new library is created and saved in the specified directory with the specified name. This is one single file with all the library information.

Possible errors

No file space, file with name already exists

Status

Integration with writer/ Impress

Priority

1

Inputs

Installation of Biblio

Pre-conditions for the input

Action on input

Biblio must be natively integrated into writer and impress during installation of either program. Though it may be useful to see biblio as just another data source, it will be very helpful, particularly for new users to see biblio as just another module of writer/ impress. This integration could be in the form of a biblio toolbar, or a biblio entry in the tools menu or a key combination (Endnote uses ALT-1 ).

Options

Output

Possible errors

Status

Icons and file extensions for biblio databases and styles

Priority

1

Inputs

Pre-conditions for the input

Action on input

We will need very distinct icons and file extensions for biblio databases and styles. Each style and library should be stored in a single, separate file for easy handling and exchange.

Options

Output

Possible errors

Status

GUI for the biblio module

Priority

1

Inputs

Pre-conditions for the input

Action on input

This is the GUI for the biblio module. It should comply with the human interface guidelines (HIG) and be consistent with the interface of all OO applications. Endnote only has a main toolbar, probably biblio can start with one toolbar as well with File, Edit, References etc. entries.

Options

Output

Possible errors

Status

Backup policy for the library

Priority

2

Inputs

Backup location and schedule

Pre-conditions for the input

Action on input

With all the functions being proposed for the biblio module (mainly the storage of pdf files, images etc. inside the biblio library), the library can become a researcher/ writer's most precious resource very quickly. It has to be treated with great care, taking every precaution to save it from damage of any kind.

For well-connected users in Universities, newsrooms and other enterprise environments, this usually means saving the library on a networked drive that is backed up as per policies. It must be remembered that it would not be surprising if the library grows to ~GB in size with the embedded files. For stand-alone computers, users should be given the option of specifying backup policies. This could be prompts for disk backups, ISP backups etc. For stand-alone computers, biblio may even suggest that users not store documents inline because that may make backups difficult. An the other hand, users may find it useful to store all their important documents in biblio to make it a single-point storage location. There should also be a save copy (in addition to save as) command in the file menu for one-off backups.

Options

Backup location, backup schedule

Output

Possible errors

Status

Recover damaged library

Priority

2

Inputs

A biblio library file corrupted for some reason

Pre-conditions for the input

Action on input

The biblio module should do its best to recover as much data in the file as possible. This probably will have implications on the library storage format as well. It may be possible that the job of recovering from error is delegated to the underlying library frogram.

Options

Output

Recovered library file with as much retrieved information as possible.

Possible errors

Status

Portability of databases and styles across platforms

Priority

1

Inputs

Pre-conditions for the input

Action on input

One of the critical features of biblio and in fact, any OO component is portability to every platform to which OO has been ported, preferably with minimal effort. This implies that the programming environment should be portable across platforms (for compiling and building etc). Also, any extra component introduced, such as a library engine to store references, should also have a vision of portability with a vibrant community committed to making it happen.

Options

Output

Application binaries, databases and styles that are transparently portable across platforms.

Possible errors

Status

Defining words whose case is not to be changed

Priority

2

Inputs

Word list

Pre-conditions for the input

Title-case modification is on

Action on input

When the Bibliography is being formatted, and the options to modify title cases is selected, some words may get incorrectly formatted. Most commonly, these are the nouns in the title, such as America and abbreviations like CEO. It should be possible to define a list of words whose cases are not modified during the formatting processes.

Options

Output

Possible errors

Status

Folder locations

Priority

1

Inputs

User defined default locations for saving bibliographies, styles, filters and connection files

Pre-conditions for the input

Action on input

The folder locations should be very intuitive and should allow maximum flexibility and ease-of-use to allow users to edit the respective files.

Options

Output

Possible errors

Status

Defining dictionaries

Priority

2

Inputs

Pre-conditions for the input

Action on input

Since OO has spell-checking functionality, it should be possible to spell-check entries in the data-entry form of biblio using one or more of the dictionaries used by OO (Sun.dic, Sofice.dic etc.)

Options

Dictionary to use for spell-checking

Output

Data entered in new reference is flagged for spelling errors.

Possible errors

Status

Using Biblio on a network

Priority

2

Inputs

Network location of bibliography library

Pre-conditions for the input

Action on input

Some thought should go into how the biblio module should be defined to work on a network. Considering that a target market is K-12 schools, it is conceivable that schools may want to manage a central library to which multiple students can connect at the same time. This model needs to be thought out in more detail

Options

Output

Possible errors

Status