# Data input

This chapter explains the ways how you can generate reference and extended note data suitable for RefDB databases. We'll cover manual generation of RIS files and automatic conversion of other bibliographic data with the help of input filters. You'll learn about writing risx documents, a new XML data format designed to simplify funneling XML or SGML bibliographic data into RefDB. risx is the preferable format to fully utilize RefDB's capabilities. Finally we'll cover writing extended notes that allow to append additional information to objects in your database or to categorize references in a very flexible way.

To actually import the resulting RIS datasets into the RefDB database, use the addref command of the refdbc command line client, as explained in the next chapter.

## Writing RIS datasets

### Overview

The Reference Manager Manual contains sort of a specification of the RIS data format. This format is a tagged file format with the following general rules:

- A file can hold one or more references

- Each reference starts with a newline. This also means that every RIS file starts with an empty line.

- There can be only one tag per line.

- The tag must be at the very beginning of the line.

- The tags consist of two capital letters denoting the type, followed by two spaces, a dash, and another space.

- The first tag of each reference is the Type tag (TY - )

- The last tag of each reference is the End tag (ER - )

- The sequence of all other elements is arbitrary.

  There is one exception: In the case of multiple authors, editors, or series editors, the sequence of these authors is significant. E.g. the first AU tag will be used as the first author, the last one as the last author.

Therefore a minimal RIS file may look like this:

    TY  - BOOK
    AU  - Hoenicka,M.
    TI  - The RefDB manual
    PY  - 2001
    ER  -

This is the empty line generated by a linefeed character (0x0A) that precedes every RIS citation, even at the start of a RIS file.

This is the mandatory first tag, the type specifier. In this case, we're looking at a BOOK entry.

This and the following lines are the contents proper of the citation. All additional tags would go here as well

This is the mandatory last tag which closes the citation. Although invisible here, this tag also has a trailing space like all others.

### Character encodings

The RIS specification has no built-in means to specify the character encoding of the data. Commercial applications usually expect the data to be supplied in a particular encoding (e.g. Reference Manager uses the Windows ANSI character set). RefDB does not have this limitation, you are free to use any encoding available on your platform (except UTF-16 and UTF-32). However, you should be aware that this may cause an interchange issue if you plan to use these data in a commercial reference management program. In any case, as the datasets do not specify their encoding, you have to use `-E` option of the getref command if your input data use an encoding different from the default (UTF-8).

### RIS tags

The following list shows all available tags and their use.

Please keep in mind that a full tag consists of the letters mentioned below followed by two spaces, a dash, and another space. E.g. the first tag below would be written as `TY -` in a RIS file.

TY

  This tag specifies the type of the reference and must be the first tag of each RIS dataset, preceeded by a newline.

  Format: This can be any of the following strings:

  - ABST (abstract reference)

  - ADVS (audiovisual material)

  - ART (art work)

  - BILL (bill/resolution)

  - BOOK (whole book reference)

  - CASE (case)

  - CHAP (book chapter reference)

  - COMP (computer program)

  - CONF (conference proceeding)

  - CTLG (catalog)

  - DATA (data file)

  - ELEC (electronic citation)

  - GEN (generic)

  - HEAR (hearing)

  - ICOMM (internet communication)

  - INPR (in press reference)

  - JFULL (journal/periodical - full)

  - JOUR (journal/periodical reference)

  - MAP (map)

  - MGZN (magazine article)

  - MPCT (motion picture)

  - MUSIC (music score)

  - NEWS (newspaper)

  - PAMP (pamphlet)

  - PAT (patent)

  - PCOMM (personal communication)

  - RPRT (report)

  - SER (serial - book, monograph)

  - SLIDE (slide)

  - SOUND (sound recording)

  - STAT (statute)

  - THES (thesis/dissertation)

  - UNBILL (unenacted bill/resolution)

  - UNPB (unpublished work reference)

  - VIDEO (video recording)

ER

  This empty tag denotes the end of the reference. It must be the last tag of each RIS dataset.

ID

  This tag is used to uniquely identify the reference in the database. The value is either the unique ID that RefDB generates when a reference is imported into a database, or a unique citation key. The latter can be supplied by the user. If no citation key is specified when adding a reference, RefDB will automatically generate a unique citation key, based on the name of the first author and the publication year. RefDB will create an unique ID value for internal use regardless of whether a citation key is provided or not.

  ID values are always numerical (e.g. "11"), whereas citation keys are alphanumerical (e.g. "Miller1999").

  While you are free to choose any reasonable citation key (as long as it is unique within the database), you should not attempt to create a ID value manually. It is ignored when adding the dataset, but it may overwrite an existing entry if you update a reference. Along the same line, you should leave the ID tag alone if you retrieve a dataset from the database and plan to update it. The citation key in the retrieved data set is essential to match the modified data with the copy in the database.

  ID Format: Integer >0.

  Citation key Format: A string with up to 255 characters. You should use 7-bit ASCII characters only to avoid character encoding issues. If you want to work with SGML documents, the citation keys should be all uppercase.

TI

  This is the title of a publication. For BOOK and UNPB references this is the same as the BT tag.

  Format: A string with unlimited length.

T2

  This is the secondary title of a publication, e.g. the book title for a CHAP reference.

  Format: A string with unlimited length.

T3

  This is the tertiary title of a publication, e.g. the series title for a CHAP reference.

  Format: A string with unlimited length.

AU

  Synonym: A1. This is the name of one author of the reference. If a reference has multiple authors, each author is specified with an AU tag on a separate line. The number of authors per RIS dataset is not limited. The sequence of the authors in the authorlist will be determined from the sequence as they appear in the RIS dataset.

  Format: A string with up to 255 characters in the form: Lastname[,(F.|First)[(M.|Middle)...][,Suffix]]. First and middle names can either be abbreviated or spelled out. Use periods to separate initials, and spaces to separate spelled-out first or middle names. Lastname can be a corporate name. Some examples for valid entries:

  - King,B.B.

  - Benberg,Steven C.

  - Mellencamp,John Cougar,Jr.

  - Van Zandt,Steven

A2

  Synonym: ED. This is the name of an editor of the reference, e.g. an editor of the book in which a CHAP reference was published. The same formatting requirements as for AU apply.

A3

  This is the name of a series editor of the reference, e.g. an editor of a series of books in one of which a CHAP reference was published. The same formatting requirements as for AU apply.

PY

  Synonym: Y1. This is the primary publication date.

  Format: A string with the format YYYY/MM/DD/otherinfo, where YYYY denotes the four-digit year, MM and DD denote the two-digit month and day, respectively, and otherinfo denotes any other information with up to 255 characters. If any of these parts is not available, it can be left out, but the slashes must be present. E.g. 1999///Christmas edition is a valid string.

Y2

  This is the secondary publication date.

  Format: A string with the format YYYY/MM/DD/otherinfo, where YYYY denotes the four-digit year, MM and DD denote the two-digit month and day, respectively, and otherinfo denotes any other information with up to 255 characters. If any of these parts is not available, it can be left out, but the slashes must be present. E.g. 1999///Christmas edition is a valid string.

N1

  Synonym: AB (this is not logical as it sounds like ABstract, but I'm sure there is a reason in RIS' crooked history). The notes. This can be any form of additional information, like pointers to corrections or editorials, or just personal notes about the contents of the reference.

  Format: A string with unlimited length

N2

  The abstract of a reference.

  Format: A string with unlimited length

KW

  A keyword. If a publication has multiple keywords, each goes on a separate line preceeded with this tag. Keywords are crucial to find references in larger databases.

  Format: A string with up to 255 characters

RP

  The reprint status of a reference. This can be any of the following strings:

  - IN FILE

  - NOT IN FILE

  - ON REQUEST MM/DD/YY

AV

  The availability information. This is a hint where you can find a physical copy or offprint of the reference.

  Format: A string with up to 255 characters. This can either be a plain-text description like "methods folder, second drawer from top in the green cabinet on the yellow hallway", or a call number.

SP

  The start page of the reference

  Format: A string with up to 255 characters

EP

  The end page of the reference

  Format: A string with up to 255 characters

JO

  The abbreviated name of a journal or periodical.

  Format: A string with up to 255 characters. The components should be separated by a single space without a period after abbreviated words. If you use periods, these should not be followed by spaces.

JF

  The full name of a journal or periodical.

  Format: A string with up to 255 characters

J1

  The abbreviated name of a journal or periodical (user abbreviation 1).

  Format: A string with up to 255 characters

J2

  The abbreviated name of a journal or periodical (user abbreviation 2).

  Format: A string with up to 255 characters

VL

  The volume of the journal/periodical.

  Format: A string with up to 255 characters

IS

  The issue of the journal/periodical

  Format: A string with up to 255 characters

CY

  City of publication of a book.

  Format: A string with up to 255 characters

PB

  Name of the publisher or the publishing company.

  Format: A string with up to 255 characters

SN

  The ISBN or ISSN number.

  Format: A string with up to 255 characters

AD

  The contact address, usually the any combination of postal or email address and the phone or fax number of the corresponding author.

  Format: A string of unlimited length

UR

  The URL of an online version of the reference.

  Format: A string with up to 255 characters

L1 through L4

  These fields hold the URLs of an offprint (e.g. a PDF or Postscript copy), of the fulltext (often available as HTML in addition to PDF), of a related resource, and of an image, respectively. Multiple entries of each type per reference are allowed. In contrast to the UR field above, these fields hold information which is stored for each user separately.

  The L1 field is meant to store the location of local offprints. It is most common to use the "file://" protocol and specify a full path (starting with another slash on Unix systems) or a relative path. In the latter case the path is expanded with the pdfroot setting before it is displayed to the user. Using this feature requires some thought and is therefore explained in a separate section.

  Format: A string with up to 255 characters

U1 through U5

  The user-defined fields 1 through 5. These fields are not intended to be filled with random bits of information. Each database should have a set of rules what information is to be stored in these fields.

  A possible use for these fields is some relevance indicator (e.g. # means low, ##### means high relevance).

  You may also use one of these fields to create the equivalents of folders that some other reference databases praise as the panacea to organize your references. Just assign the same value to one of these fields for all references that belong to the same folder. Retrieve them by specifying this value in addition to your other search criteria.

  Format: A string with up to 255 characters

M1 through M3

  The miscellaneous fields 1 through 3. These fields are used by various reference types to deal with additional information that doesn't fit anywhere else, and the usage differs from one type to another. An important information among the data contained here is the digital object identifier. Please refer to the Reference Manager Manual for the nasty details of these fields.

  Format: A string with up to 255 characters

### Examples

The following listing shows a few examples of valid RIS datasets. See also the example RIS file in the `/usr/local/share/refdb/examples` directory.

Long entries like abstracts were divided into several lines using slashes. This is to make it more human-readable for this manual and should not be used in real data.

    TY  - JOUR
    T1  - T-lymphocytes from normal human peritoneum are phenotypically /
    different from their counterparts in peripheral blood and CD3- lymphocyte /
    subsets contain mRNA for the recombination activating gene RAG-1
    A1  - Hartmann,J.
    A1  - Maassen,V.
    A1  - Rieber,P.
    A1  - Fricke,H.
    Y1  - 1995///
    KW  - Peritoneum
    KW  - T cell
    KW  - T lymphocyte
    KW  - lymphocyte
    KW  - immunology
    KW  - CD3
    KW  - human
    KW  - Adult
    KW  - blood
    RP  - IN FILE
    SP  - 2626
    EP  - 2631
    JF  - European Journal of Immunology
    JA  - Eur.J.Immunol.
    VL  - 25
    N2  - These findings are compatible with the hypothesis that the adult /
    human peritoneum provides a microenvirinment capable of supporting a /
    thymus-independent differentiation of T lymphocytes.
    ER  -

    TY  - BOOK
    T1  - Porphyrins and metalloporphyrins
    A1  - Smith,K.M.
    Y1  - 1975///
    KW  - Porphyrins
    KW  - Metalloporphyrins
    KW  - Spectrophotometry [methods]
    KW  - spectroscopy
    RP  - NOT IN FILE
    CY  - Amsterdam
    PB  - Elsevier Scientific Publishing Company
    ER  -

    TY  - CHAP
    T1  - Physiological studies of the natriuretic peptide family
    A1  - Lewicki,J.A.
    A1  - Protter,A.A.
    Y1  - 1995///
    N1  - Atrial Natriuretic Peptide   Cardiac synthesis and secretion of /
    ANP   Regulation of ANP Gene Expression   Regulation of ANP Release /
    ANP Receptors   Biologic Actions of ANP Brain Natriuretic Peptide (BNP) /
    BNP Structure   Biosynthesis of BNP   Biological Actions of BNP C-Type /
    Natriuretic Peptide (CNP)   Biologic Actions of CNP Modulators of /
    Natriuretic Peptide Clearance   Effects of Clearance Receptor Blockers /
    Effects of Neutral Endopeptidase Inhibitors Role of the Natriuretic /
    Peitedes in Physiology and Disease   Hypertension   Congestive Heart  /
    Failure   Supraventricular Tachyarrhythmias   Acute Renal Dysfunction
    KW  - natriuretic
    KW  - ANF
    KW  - ANP
    KW  - receptors
    KW  - BNP
    KW  - CNP
    KW  - hypertension
    KW  - congestive heart failure
    KW  - review
    KW  - cardiac
    KW  - regulation
    KW  - gene expression
    KW  - expression
    KW  - brain
    KW  - structure
    KW  - biosynthesis
    KW  - receptor
    KW  - inhibitor
    KW  - physiology
    KW  - renal
    KW  - study
    KW  - Peptides
    KW  - atrial natriuretic peptide
    KW  - MODULATOR
    KW  - secretion
    KW  - Gene Expression Regulation
    RP  - IN FILE
    SP  - 1029
    EP  - 1053
    VL  - 2
    T2  - Hypertension: Pathophysiology, Diagnosis, and Management
    A2  - Laragh,J.H.
    A2  - Brenner,B.M.
    IS  - 61
    CY  - New York
    PB  - Raven Press, Ltd.
    ER  -

## The Emacs helpers

If your editor of choice should be Emacs or XEmacs, the separately available refdb-elisp package will come in handy. Please see the installation instructions contained in the source archive. The package consists of a major mode (ris-mode) to edit RIS datasets, and a minor mode (refdb-mode) which provides a general front-end to RefDB. refdb-mode is too powerful to be discussed here in a few lines, please see the separately available manual. The ris major mode can do the following things for you:

- Font-locking will help you to spot syntax errors in the tags. Especially the end tag (ER - ) is prone to lack the trailing space if you're not careful. The ris-mode displays regular tags in blue and the special type (TY - ) and end (ER - ) tags in red. Tags will be displayed in the default foreground color if anything is wrong with them, like invalid specifiers, lowercase specifiers, missing or additional spaces.

- ris-mode provides three commands to insert datasets ("references") and individual tags as described shortly. All of these commands have in common that they always start a new line after the current line if the cursor is not at the start of a line. Thus you can run these commands from any position of the current line and still get something that makes sense as a RIS dataset.

- Run the command `insert-set` (C c C s) to insert a new skeleton dataset (a "reference"). The function will prompt you to enter the publication type. You can use either the auto-completion feature of the minibuffer to enter a valid type or the history feature to select a previously entered type. The function will create a newline, a type tag with the type you selected, and an end tag.

- You can insert a new tag at the beginning of a line with the command `insert-tag` which is bound to C c C t. Use either the auto-completion feature of the minibuffer to enter a valid tag or the history feature to select a previously entered tag.

  Once you have created an empty tag, you can use commands provided by the refdb-mode to enter values from existing entries in the database. This is convenient to avoid spelling errors in author names, or to select keywords which are already used by other references. These commands use minibuffer completion for added convenience.

- You can insert a new line below the current line with the same tag as the current line with the command `duplicate-tag`. This is bound to M RET. This command is convenient if you add multiple keywords or authors, each of which have to go on separate tag lines.

- You can move between RIS datasets with the commands `backward-set` (C x[) and `forward-set` (C x]). You can narrow the buffer to the current RIS set with the command `narrow-to-set` (C xns). To widen to the full buffer contents again use C xnwas usual.

ris-mode does not attempt to validate the buffer contents. You can create invalid tags, leave out the essential type or end tags, forget about the newline preceeding each dataset and ris-mode will not complain. However, you can spot most errors by looking at the font colors: If the first and the last line of a dataset are not displayed in red, you have a problem (you might be using a monochrome display but that's not what I mean). If any tag (except TY and ER) is displayed in the default foreground color (usually black on X displays), you have a problem as well.

## Input filters

RefDB gets all reference data from text files (or from equivalent data read from stdin). These text files can be from various sources: you can enter them manually, you download files from search engines in the web, or you have data exported from a different database application. In almost any case, some kind of filtering has to be applied to those files in order to be valid input for RefDB.

The input filters currently shipped with RefDB are listed below. Please follow the links to the individual filters for further information.

refdb_dos2unix

  A simple (maybe too simple) shell script to convert text files like RIS documents from DOS-style line endings to Unix-style line endings. Most RefDB tools need their input files with Unix-style line endings. This is a valuable tool to import reference databases from Windows reference managers.

med2ris

  A tool to convert Pubmed data in both the tagged and the XML format to RIS. You may use refdb-pubmed to retrieve Pubmed data in the first place.

en2ris

  A tool to convert EndNote "RIS" exported data to RIS

bib2ris

  A tool to convert BibTeX data to RIS

db2ris

  A tool to convert reference data in DocBook SGML/XML documents to RIS

marc2ris

  A tool to convert references in MARC format to RIS.

If you need other formats than those listed above, you'll either have to provide your own input filter or search the web for existing filters that convert your data to one of the supported formats. A decent set of filters is supplied by Chris Putnam's bibutils package, which interconverts bibtex, COPAC, EndNote (Refer), EndNote (XML), ISI, PubMed, MODS, and RIS data. For example, use the following command to import MODS datasets into RefDB:

    # xml2ris modsdata.xml|refdbc -C addref

## Writing risx datasets

XML documents using the risx DTD are an alternative way to add datasets to RefDB databases. You can use your favourite SGML/XML editor to edit these datasets. You can also use DSSSL or XSLT scripts to transform bibliographic data available as SGML or XML documents to risx.

This section provides a quick outline of risx datasets. For a description of all available elements and their relationships, please visit the risx documentation.

As usual, start the document with the processing instructions, followed by the document type declaration. Make sure to include the character encoding if it is different from the default (UTF-8). The other encodings supported by RefDB are UTF-16, ISO-8859-1, and US-ASCII. The first line might then read:

    <?xml version="1.0" encoding="utf-8"?>

The top-level element of a risx XML document is either ris (if the file provides multiple datasets) or entry, which corresponds to a single dataset. The ris element holds one or more entry elements. The type attribute specifies the type of the reference. These are the same types as described above for the RIS TY tag. The id and citekey attributes specify a numeric ID (which will only be used if you update references) and a citation key, respectively. The latter should be all uppercase if you intend to use the references with SGML documents.

Each entry element contains up to five subelements, the first three of which provide the bibliographic information proper. risx distinguishes three levels of bibliographic information. Each entry can specify one or more of these levels:

- The part element corresponds to the analytical level of bibliographic information. This element specifies the information of a work that has been published as a part of a publication. This can be a journal article in a periodical, or a chapter in a book. The part element usually contains information about the authors and the title of the part, as well as volume, issue, and page information.

- The publication element corresponds to the monographic level. This is essentially an individual item that you can find on the shelves of a library, like a book or a journal. The publication element contains information about the authors/editors and the title of the items.

- The set element corresponds to the series level. This provides information about individual items that have been published as a part of a series, like a book about cats within a series of books about mammals. This element usually adds the information about the title of the series and the series editors.

Please refer to the risx documentation for further details about the structure of these elements.

The libinfo element contains the local "housekeeping" information of a particular user. Each dataset may contain libinfo elements of one or more users who are specified with the user attribute. Use this element to specify the notes, the reprint status, and the availability information.

The contents element specifies, you've guessed right, the contents of the reference, i.e. an abstract and an unlimited number of keywords for indexing purposes.

## Writing extended notes

Both the RIS and the risx formats allow to keep user-supplied notes of unlimited length with each dataset. This is a great way to keep additional explanatory information along with the hard bibliographic data, but this approach is still somewhat limited.

Extended notes are kept separately from the reference data, but there is a mechanism to link each note to an unlimited number of references, author names, keywords, or periodical names. Possible applications of this feature include:

- Write a note about a topic and link it to all references relevant to this topic

- Keep biographic data or alternative (mis)spellings with author/editor names

- Store the impact factor, the official web page, or your personal access information to the restricted part of that web page along with a journal name

- Explain alternative spellings or synonyms of keywords

Searching for notes is similar to searching for references. Notes may have keywords, keys, and a title attached to them to easily find them. In addition, you can search for notes that link to a particular reference, author, keyword, or periodical. The inverse works as well: you can search for references that are linked to particular notes.

Extended notes are XML documents according to the xnote DTD. The structure of these documents is simple enough to do without a separate documentation. As usual, start the document with the processing instructions, followed by the document type declaration. Make sure to include the character encoding if it is different from the default (UTF-8). The other encodings supported by RefDB are UTF-16, ISO-8859-1, and US-ASCII. The first line might then read:

    <?xml version="1.0" encoding="utf-8"?>

If you want to write several extended notes in a file, start with an xnoteset element. Each individual extended note is kept in an xnote element. This element carries up to four optional attributes:

id

  An unique identifier supplied by the database engine. This attribute is ignored if you add a new note, but it is respected if you update an existing note.

citekey

  This is a unique short title or tag which identifies a note unambiguously but is more convenient to remember than the id. If you do not supply a citekey, refdbd will create one based on the username and the date.

user

  This is the name of the user that owns the note. If you do not supply a name, refdbd will use the name of the current user, which is most likely what you need anyway.

date

  This is a timestamp (YYYY-MM-DD). refdbd will insert the current date if you do not supply this attribute.

An extended note consists of an optional title, the contents proper encoded in a content element, zero or more keyword elements, and zero or more link elements. The title is a short description of the note. The keywords serve the same purpose as in references.

The content element contains the note proper. The contents of the content element is stored by refdbd as is. It may be plain text or markup. The element uses the following optional attributes:

type

  This description of the content type may be used by processing applications to render the contents properly. Store e.g. the MIME type or the name of a DTD/Schema in this attribute.

xml:lang

  This attribute specifies the language of the contents.

The link element is used to link the note to one or more references, keywords, author names, or periodicals. The empty element uses two attributes:

type

  The type of the link target. This may be one of reference, refid, author, keyword, journalfull, journalabbrev, journalcustabbrev1, journalcustabbrev2.

target

  This attribute specifies the database object that the note should be linked to. In the case of a reference, use the ID (type refid) or citation key (type reference). In all other cases, use the name of the author, keyword, or periodical, respectively.

An example set of extended notes is installed into `/usr/local/share/refdb/examples`.

## Input data mangling

Input data are not stored as a literal chunk of text by RefDB. If you import a dataset, and later retrieve it using the same format, the dataset is not guaranteed to be the same character by character. Instead, the data are sliced up, sometimes slightly modified, and sometimes RefDB creates additional information. This section tries to explain what happens to your data behind the scenes, and why this is good for you.

### Information that RefDB generates for you

In a few cases RefDB fills in some default values if the datasets do not specify them. This happens in the following cases:

- Each reference and extended note will be assigned a unique numeric identifier. This is mainly used internally, but you can also retrieve references and extended notes by their ID. The ID is always created by the database server, there is no way to enforce specific IDs for your datasets.

- Both references and extended notes require a unique alphanumeric key. With a few limitations this is an arbitrary string consisting of letters (at least one) and optional digits. If you do not specify a citation key, RefDB will create one automatically. In the case of references, the publication year is appended to the last name of the first author. If this string is not unique, a sequential suffix starting at "a" through "z", then "aa" and so forth, is tested until a unique string is found. The same algorithm is used for extended note keys, but instead of an author name the user name serves as the base.

- If no reprint status is specified, RefDB inserts "NOT IN FILE" as the default value.

- If your extended notes do not specify a date, RefDB will use the current date and insert that instead.

### Information that RefDB mangles

Citation keys are supposed to work as ID values in SGML and XML documents. To avoid any character encoding hassles, only the first 127 characters of the US-ASCII character set are permitted. These characters work in most character encodings. Some special characters which are not allowed as part of an XML attribute value are stripped. Non-ASCII characters are converted to a reasonable ASCII equivalent, or they are dropped if no replacement is possible.

Periodical names and author/editor names receive some special treatment in order to make them usable for RefDB. Both periodical names and person names should be provided in a particular format. However, if you retrieve your data from an electronic source instead of writing them from scratch, the names may not conform to the rules. In order to make best use of these data, RefDB attempts to normalize the incoming periodical and person names until they conform to the rules.

There is a good reason for this normalization. Consider a periodical name like "The Journal of Biological Chemistry" . Different electronic sources may abbreviate this as one of:

- J.Biol.Chem.

- J. Biol. Chem.

- J Biol Chem

Although a human reader does not have a hard time to guess that we're looking at the same journal in all three cases, a database is too stupid to understand this. If you add the periodical abbreviations as they are, you'll end up having three different journal entries. As a consequence, a query like `getref :JO:='J.Biol.Chem.'` will miss two out of three papers published in that journal. This is not a good thing.

#### Periodical names

RefDB normalizes abbreviated periodical names like this: First, the name is tokenized. Separators are periods and spaces. If a token has a trailing period, it is assumed to be an abbreviated word and used as such. If a token has no trailing period, the token is compared to an internal list of unabbreviated words (see the listword and addword commands for further information about this list). If a match is found, no period is added. If no match is found, the token is assumed to be an abbreviation of something else and a period is added. Spaces after periods will be removed as one separator is sufficient. If we consider the three versions of the journal name above, all versions would be normalized to the first one.

#### Person names

The names of authors and editors are normalized like this: Everything to the left of the first comma is assumed to be the last name and remains untouched. The next item (separated by either a space, a period, or both) is assumed to be the firstname. If it consists of one capital letter, a period is added and any trailing spaces are removed. If the firstname is spelled out, it is used as such. All following name parts to the left of the second comma, if any, are assumed to be middle names. Each part receives the same treatment as a firstname. Finally, everything to the right of the second comma, if any, is assumed to be a honorific or lineage part and used as such. All spaces following either a period or a comma are removed. A few examples should make this procedure clear:

- "Miller, John S" -> "Miller,John S."

- "Chun, H-K" -> "Chun,H.-K."

- "Delorie, DJ" -> "Delorie,DJ"

- "Doe, J S" -> "Doe,J.S."

- "Random,Jane,Jr." -> "Random,Jane,Jr."

The last example shows that your data will not be modified as long as they stick to the input format.