You are here: SE » RulesHome » BibtexRules

BibtexRules: Bibliography management

Describes how and where we collect the information about the scientific literature we use and cite.

File format and management tool

  • We use BibTeX as our literature database format, and BibLaTeX when writing articles, whenever the publishing venue allows it.
    • Rationale: It is the natural choice when using LaTeX for writing, which is our most common platform.
  • We exclusively use JabRef as the editor and management tool for working with BibTeX files (adding to them, modifying entries, browsing entries, searching for entries).
    • Rationale: JabRef is a rather powerful and usable tool. Its consistent use provides a basis for avoiding formatting mistakes and inconsistencies, tool incompatibilities with respect to character encoding or line endings, and in particular unwanted tool-induced file reformattings that would wreck our ability to have several people work on the same BibTeX file concurrently (moderated by Git, see below).
  • Everybody must always use the same JabRef version to avoid formatting clashes. We currently all use version 5.1. The person who will currently usually trigger us all to move to a different version is Franz.
  • If you do not have administrative rights on your machine, make sure you use a portable version of JabRef, not one installed by our tech folks.

JabRef settings

Some JabRef preferences (dialog Options→Preferences) must be the same for all of us in order to ensure smooth cooperation. Please set these preferences as follows before you start using JabRef for the first time:
  • import the file jabref.xml from the Git repository (see below) via the button in the bottom left of the Options→Preferences dialog
    • Whenever you reinstall JabRef or your operating system, do the import again.
    • If you also save personal JabRef settings to an XML file, import the personal ones first and the default ones last to make sure the defaults actually become effective.
  • Then set the following options manually in that same dialog:
    • General→Mark new entries with owner name: yes
      (and one's own lowercase lastname is given as the string to be used, say prechelt).
    • External programs→Main file directory:
      Set this to the root of the PDF file tree on your local machine (see below).
  • If you think about modifying any of the other preferences, please consider if that might change many existing entries. If it does, don't do it.

BibTeX database conventions

Here are the rules for the actual content of a literature database: The values of the fields in the BibTeX file.
  • Firstnames of authors should be fully spelled out (unless we simply do not know them)
  • Citation keys are formed as follows:
    • If there is only one author (say, 'Lutz Prechelt'), use his/her complete lastname plus a two-digit year (say, 'Prechelt07')
    • Any lastname prefixes such as 'von', 'van', 'de la' etc. are ignored if they come as separate words.
    • If there is more than one author (say 'Lutz Prechelt, Stephan Salinger, Sebastian Jekutsch, and Christopher Oezbek'), use the first three letters of the lastnames of the first three authors plus a two-digit year (say 'PreSalJek07')
    • Our JabRef settings will automatically generate the right key for you in most multi-author cases, but you will have to adjust the too-short generated key in the single-author case.
    • Note that only ASCII is allowed. Rewrite characters with diacritical marks (including Umlauts) by ignoring the diacritical mark. This is not always what JabRef will do. For instance, 'Hans Müller, Jean de Frère, and Cheung Le' becomes 'MulFreLe07' etc.
  • Make sure you place title words that need to be capitalized (typically product names or other proper nouns and German nouns) in {Curly} {Brackets} (or else most BibTeX styles will remove the capitalization when producing the TeX output): "A Tale of IBM's Eclipse project" becomes "A Tale of {IBM}'s {Eclipse} Project" and will appear in TeX as "A tale of IBM's Eclipse project" rather than as "A tale of ibm's eclipse project".
  • Names of Journals or Conferences should be fully spelled out. For a more concise bibliography in the articles, we use the following abbreviations which are performed automatically through BibLaTeX (see HowTo):
    • Conference → Conf.
    • International → Int'l.
    • Journal → J.
    • Proceedings of the → Proc.
    • Proceedings → Proc.
  • When importing BibTeX entries from external sources, adjust them to fit with our other entries. Most important in that respect is the BibTeX key.
  • Links to PDF files should all be relative to the JabRef "Main file directory" as set above (and JabRef will help determine that path by searching in the tree for you).
  • When you read a paper that somebody else has entered in the BibTeX database, you should add your username at the end of the 'owner' field so that others can quickly find out who may have an opinion about the contents of the paper.
  • A number of fields are used jointly: Everybody can enter their own information in that same field.
    • Review: prefix your text with a line containing only your lastname and a colon: prechelt:
    • Keywords: standardize your keywords to some degree, reuse keywords introduced by others where possible, ask them about the intended semantics if needed (or look at the other entries using that keyword).
  • Everybody can introduce personal fields (prefixed with their lastname) as needed. For instance, Franz uses zieris.readstatus to remember what he has already read, skimmed, or not read. Set them up in Options→Set up general fields.

Other JabRef usage conventions

  • To keep general.bib manageable, we make heavy use of the JabRef 'groups' feature. These are the minimum groups that should be used:
    • Personal groups, at least one per AG SE member, collecting files of interest to that member. The group name is the username of the person, say, 'prechelt' for Lutz Prechelt.
      Use subgroups as you see fit. Do not muddle with others' personal groups.
    • Broad SE topic groups: requirements, design, implementation, test, project management, process. Do not create subgroups of these. Always assign one of them to an entry if one of them fits.
    • Research interest groups: One group per longer-term (3 years or more) research topic, say, pair programming, open source. Create subgroups as you see fit.
    • 'goodstuff' group: Only high-quality and highly relevant publications that are expected to be relevant for more than one person or group a number of times. As a rule of thumb, not more than about 1%-5% of everything should go in there. The typical categories of such material are standard references one does cite again and again (often books or surveys) and high-class papers representing a whole stream of research rather than one individual piece of work.

File and version management

  • We use two types of .bib files: (1) Files that will be used for one single document only and kept with that document and (2) one single file that will be used many times over many years.
  • That latter file is called agse.bib and is kept in a Git repository. The bib repository may be included as a Git submodule in your article repository (see HowTo).
  • Let the environment variable BIBINPUTS point to your working copy of that repository.
  • The PDF file tree for quick access to actual articles directly from JabRef is kept on an OwnCloud server operated by Lutz. To use it, you need your own owncloud account (preferably on your own owncloud instance; if you don't have one, Lutz will give you an account on his) so that Lutz can share the directory tree with you and you can sync it to your local disk(s).
    • join the various bibtex files in the repository into one
    • clean up all their entries: remove/join duplicates, respect our conventions, add PDF filenames insofar as the PDF already exists.

Comments