Title: Draft functional requirements of OpenOffice Bibliographic module
Date: 06/27/2003
Editor: Manish Agrawal
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.
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.
These
functions are summarized in the illustration below.
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)
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
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.
Requirements
Using references in documents
Use case: Switch to biblio for selecting and inserting citations from local library into Writer/ Impress document in Endnotes format
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:
Use case: Insert a selected object from the list of available objects in the selected citation from local library into Impress/ Writer document
Priority: Preferably 1, maybe 2
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:
Use case: 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:
Use case: Reformatting a document and the bibliography
Priority: 2
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
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.
Output: The document with new information for all the used citations.
Possible errors: Some matching references are not found.
Status:
Use case: Save bibliography inline with document
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:
Use case: Searching for references in the library
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:
Use case: Specify location of Endnotes-style bibliography in document
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:
Use case: 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.
Status:
Use case: Associating paragraph and character styles for the endnotes style bibliographies
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:
Use case: Change endnote-style bibliography easily
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:
Use case: Quick search for a specific reference
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:
Use case: Visible fields in the library
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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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.
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:
Use case: 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:
Use case: 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:
Use case: 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 case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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 case: 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:
Use case: 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:
Use case: 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:
Use case: 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
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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
Use case: 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:
Use case: Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Use case: 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:
Template
Use case: 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.
