References bibliographic software


Version 4.3d
Manual updated September 22, 2007

Volker Kiefel

Introduction

Scientific publications are usually accompanied by a list of references. The format of this list is usually described in the “Instructions for authors” document issued by editorial boards of scientific journals. The References software package described in this document is aimed at supporting writers of scientific literature to manage bibliographic references in manuscripts. It supports normal text processors including OpenOffice.org/StarOffice Writer and the TEX/LATEX document preparation system including BibTEX. References is able to create BibTEX database files. Writing References bibliographic format definitions `by hand' is easier than programming a bibliographic style using the language that comes with BibTEX1. The main goal for development of References was to obtain a flexible tool which allows to create lists of references in any format for journals in science and medicine and to create correct citations in the text of manuscripts2. It may also be used as a database program which helps to organize a large collection of literature.

References communicates in a `portable' way with word processors and text editors: it uses text files which – as universal file format – can be imported by most text processors. Up to v4.2, References has been implemented as console-application for win32. Beginning with v4.3, a Linux port has been added, from v4.3b on, Linux installations with utf-8 and latin-1 (ISO-8859-1)/latin-9 (ISO-8859-15) encoding of text files are supported. For the new user it may take some time to get accustomed to the console “user interface”, but – in the hands of the program author – References has proved to be an efficient and reliable tool. As an introduction, the new user should follow the first steps in the tutorial chapter (section 13) of this manual and “play” for a while with the software.

Documentation of the software in this file (refsdok.pdf) is one of the most important components of this distribution. Information on deficiencies of this manual and bug reports are always welcome3. Additional documentation and supplementary material: bibliographic format definitions, macros, step-by-step descriptions are made available on the project homepage (http://references.sourceforge.net).

This version (4.3x) of References comes with major internal changes: the internal representation of the data for both the win32 and Linux port has been changed to latin-1 (similar to the native encoding on win32 systems). On the win32-console, output to the screen (and input from the keyboard) is translated to/from “codepage 850”, and on a Linux console with utf-8 encoding internal latin-1 encoded text is translated to/from utf-8. Details of encoding issues related to References are explained in section 9.4.

Support for formatting bibliographic citations in OpenOffice.org/StarOffice Writer4 and Microsoft Office (Word) documents is supported on the project homepage5. The project homepage also provides updates of this manual and links to useful software including text editors and text processors.



V. K.
Kritzmow, August 2007

Contents

1  Scientific publications and bibliographic software

1.1  General conventions, terminology

This section explains basic terms related to scientific publishing often used in the context of personal bibliographic management software[1, 2, 3, 4, 5, 6]. These terms will also be used in the following chapters of this manual.

The text body of scientific manuscripts will contain citations or in-text citations either in author-date format (as an example: …Ebel and Bliefert, 1998; Grossmann, 1993…) or as numerical citations (for example: …[5, 1]…). The text is usually followed by a detailed list of references (Literature Cited, or Works Cited) with full bibliographic information of quoted work. References lists usually must contain all sources cited in the text. In books containing chapters from different (groups of) authors, lists of references oftem follow the chapters to which they apply. Lists of references may be sorted alphabetically (according to authors' or editors' names) or references have the same order as they appear in the text.

Computer programs used to manage bibliographic databases are often referred to as bibliographic software, personal bibliographic management software, citation management software, or reference management software [7]. A bibliographic record within a bibliographic database is the set of data describing a single published work. Using bibliographic software will often become an essential part of your knowledge management. Work significant to your interests has to be collected, e. g, by filing copies from articles, obtaining books and creating “bookmarks” to electronic documents. Retrieval of bibliographic records is made easier by reference numbers assigned to records in a bibliographic database which may be used at “pointers” to the location of a filed copy in your working environment. In order to make work pertinent to a certain problem accessible in the future, you should enter keywords as part of bibliographic records. Standardized collections of keywords within a field of interest are often called thesauri6. You will search in bibliographic databases with queries: keywords, text fragments or (author) names to be searched for in the appropriate fields (keywords, title, authors' or editors' fields) in the database.

In the process of writing a manuscript you will enter in-text citations in a raw format (e. g. by entering reference numbers using a certain convention). If you have finished writing, you will (1) extract all reference numbers cited, (2) generate a list of references which will be appended to the text body and (3) convert the “raw” in-text citation into their final format. Automatic execution of these processes is a typical tasks for bibliographic software. Work cited in a scientific manuscript can usually be classified in into at least three main document types: article in a journal, chapter or article in a book, complete book. As electronic documents, e. g. those distributed via the internet are becoming more and more important, publishing conventions for citing such material are required [8].

1.2  Features of the References implementation

As References has been planned with publishing conventions in medicine and natural sciences in mind, certain decisions have been made for the initial implementation of this software. As this implies (lack of) certain features, the short description provided here may help your decision, if References can be useful for your work.

Authors'/editors' names: In the current version of References only initials of first names can be processed7. A list of authors/editors may comprise up to 999 items8. Use of institutional authors/editors9 (as opposed to personal authors or editors) is supported in distinct document types (table 6).

Journal names: Journal names are stored in a separate table (file). The journal data records including journal names, one field for an abbreviated form are linked to bibliographic records by a key (“journal code”).

Keywords thesaurus: Each bibliographic database includes one thesaurus (which is only accessible from its “own” database). During entering or editing bibliographic records, the user may enter keywords by their numeric code in the database.

Text field: All bibliographic records may contain a text field which can be used for notes, comments or abstracts (field width of approximately 30 000 characters).

Document types: Document types supported by the current version of References are listed in table 5. References addresses these document types with codes as j1 (article in a journal with personal authors), j2 (article in a journal with institutional authors), b1 (complete book with personal authors or editors), m1 (document type for “miscellanea”, personal authors). All document types are listed in table 5.

Databases: One References installation may be used to run more than one database. Databases are realized as directories (cf. section 11.4) on the same level as the tutorial and data directories10 of the standard installation (figure 33). Installation of new databases is described in section 11.5.

Mode of interaction with text processors: References only reads, produces and manipulates external document files in text format11. Lists of references may be generated as pure text files, in html or LATEX-format. Html-files (or LATEX-files) have to be used if different fonts are required in a list of references. References can be used to generate macros for text processors like OpenOffice.org Writer or Microsoft Word which convert raw citations in a manuscript into formatted in-text citations. Thus References does not depend upon changes of the internal document format of these text processors.

Formatted lists of references: References has a powerful function, which allows the user to write his own bibliographic format definitions to generate lists of references in any format12.

Export, import of data (from online resources): Import of data in the PubMed MEDLINE display format [9] has been implemented. For export of bibliographic data into other formats the user may create his own bibliographic format definitions. A bibliographic database may be exported into text format (archive files, arr-files) so that data can be transferred into a later References version or a References version compiled for another platform.

Support: New versions of the software, supplementary data and general information related to bibliographic computing may be found on the References project homepage [10]. The program author can be reached by email (kiev AT users DOT sourceforge DOT net).

2  What can References do for me?

This short section describes essential features of References and it refers to sections where you can find pertinent information.

2.1  Installation and configuration of References

You may use References on Linux- or on win32-systems. Installation is described in section 11 (win32) and section 12(Linux). Modifications of a References installation which require editing of the configuration file are described in section 8. Necessary steps to create a new database are discussed in 11.5. In its current version (4.3b or later) References requires that your Linux installation uses utf-8, latin-1 or latin-9 encoding for text files.

2.2  Writing scientific documents

As you enter or import references into the database, you will assign reference numbers (unique strings with which you identify records in your database and citations in your manuscript) to these database records. If you write a manuscript, you will have to insert these references numbers as “raw” in-text citations In the most simple situations you will write these raw in-text citations in the following format using “refscite()”:


Platelet glycoproteins with single nucleotide polymorphisms may be responsible for immunization if platelets are transfused into a genetically different individual refscite(b00366). Such polymorphic variants are referred to as platelet alloantigens refscite(b03622), refscite(z03333), refscite(z03335), refscite(z03339).

Section 7.2 explains the methods by which References can process manuscripts with raw in-text citations of the refscite()-type. In brief, References can (1) “extract” these references numbers, it can (2) create the list of references to be included into the manuscript (in general, this will be inserted at the end of the manuscript) and (3) is able to generate macros for the text processor which converts raw in-text citations in the text into formatted citations.

2.2.1  Generate a list of references

Section 4.6 describes how a list of references is generated. Therefore, you will have to provide a list of reference numbers of those references which are to be included in this list. These lists are called batch files and they are described in 4.7. You may wish to create your own style in which a list of references is formatted. These styles are termed bibliographic format definitions. You can get some bibliographic format definitions from the References web site, and some format are included in the standard References installation. Administration of bibliographic format definitions is described in section 4.9. If you wish to write your own bibliographic format definitions, please follow the step by step description in the tutorial (section 13.6).

2.2.2  Generate formatted citations in the text

The text fragment described above is probably intended to appear as


Platelet glycoproteins with single nucleotide polymorphisms may be responsible for immunization if platelets are transfused into a genetically different individual [1]. Such polymorphic variants are referred to as platelet alloantigens [2-4,7].

or


Platelet glycoproteins with single nucleotide polymorphisms may be responsible for immunization if platelets are transfused into a genetically different individual (Meyer, 2001). Such polymorphic variants are referred to as platelet alloantigens (Karl et al., 1999, Mueller et al., 2000, Clausen et al., 2002, Thomas, 2006).

What you have to do if you wish to create such formatted citations is descibed in section 7.2.1. Either OpenOffice.org/StarOffice writer (section 7.2.2), MS Word (section 7.2.3) or LATEX (section 5.3) are supported.

2.3  Retrieve records in a References database

You may wish to search your References database for records meeting certain criteria, e. g. those from a certain author, with certain keywords, published in a (range of) year(s). Principles of such queries are described in section 4.8, a reference of search command terms (the “search command syntax”) is given in section 14.1.

2.4  Enter records into a References database

You can enter records manually: therefore you have to create an empty “form” (a text file), edit it with your text editor, save the form and transfer the record from this form into the References database: section 4.2.

Before entering a record you will have to decide which References document format (e. g. chapter in a book, journal article, complete book electronic document) fits best. Document types processed by References are discussed in section 9.1.

The procedure to edit an existing database record (reference) is outlined in section 4.3. An automated conversion of records from the medline format of the journal article type is described in section 4.10.4.

If you use the PubMed website/database, References offers utilities to import records into your databases. Details are described in section 4.10.4.

2.5  Support LATEX-users

References supports writing of manuscripts with LATEX in many aspects. All References databases or subsets of records from databases can directly be exported into .bib files for BibTEX. You may, however, create your own lists in a thebibliography-environment using \cite{} for citation of references in the manuscript and you may generate lists of references and citations in LATEX-documents without usion BibTEX and \cite{}-commands. LATEX-relatex items are described in section 5.

3  User interface

3.1  References interface

Version 4.3 comes as Linux console program or a console/terminal program compiled for win32 systems. The functions of this software are controlled interactively at the References command prompt. Data are entered into text files (referred to as text file forms in this manual). This software therefore requires a text editor. The rdb subdirectory13 (the directory tree is described in section 11.4) contains the `binary' (database and index) files. Text files produced by References and text file forms are presented in the directory which contains the rdb-subdirectory14.

In the beginning, you will start References at the command line. After calling the program you will see the main menu prompt (figure 1).


MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3 -- [e/l/b/s/d/t/f/i/q]

[menu]:
Figure 1: Main menu prompt

If you press [ENTER] at a menu prompt “[menu]:” you will see the options of the main menu (figure 2). In this situation you did not enter any menu option, but you confirmed the (implicit) default option (“[menu]:” – show menu options) by entering an empty string. If you would wish to select the option

[e] enter, edit, view

you should enter [e] and [ENTER] at the menu prompt. In this manual this selection will be indicated as main-e. To see the text of a menu you may (in any menu of References) select menu. In a menu text, everything in square brackets is an option, it is not necessary that options appear at the beginning of the line. As a example, the options in the batch table functions menu (figure 20) are bt, tb, s1, s2, in, ay, rd, rs, ba, br, ui, ed, q. If you wish to see browse the current database you will have to select main-e c, this means that you should type [e], [Enter], [c], [Enter].


[e] enter, edit, view
[l] compile lists of references etc.
[b] process batch files
[s] search references by keywords, authors, title etc.
[d] bibliographic/macro format definitions
[t] text files, export/import from/into database
[f] file, database and system functions
[i] information about References v4.3
[q] quit, return to the OS

[menu]:
Figure 2: Main menu


   1: all.bbt
  ..: ...
  22: range.bbt

Select file number: 1..22, [q] to abort:
Figure 3: File selection screen


In many situations, the user is required to select a file. As an example, if you wish to see a subset of all bibliographic records referred to in a “bbt-file” (cf. section 4.7), select (beginning from the main menu) main-e b. At the file prompt in figure 3 you may select a file by entering the number assigned to a file name.

3.2  Select/install a text editor, edit text (win32)

All data required by References have to be entered or edited with a text editor. For the first steps with References, Notepad may be used. However due to some deficiencies15 a more powerful and flexible editor may be preferred16. The ideal choice of a simple text editor for use with References is Win32pad17. An editor with intermediate complexity is SciTE18. If you use References in the interactive mode which is switched on by assigning “1” to the configuration variable OPEN_EDITOR_YN (cf. below in this section), it is useful to install a “lightweight” text editor like notepad, win32pad or SciTE, which can be called quickly.

If you prefer a more complete, but also also more complex text editor both Vim19 and Emacs20 are a good choice. The graphical version of Vim is gvim. For the beginner with gvim, it is recommended to use the Easy Vim (evim) mode. Both Emacs and Vim are well documented in books [11, 12] and in documents available via the internet [13, 14]. With these editors, which may have considerably longer loading times on some computers, it will be more practical, to have the text editor open all the time you work with References and change between text editor window and the window with References. In this case you will have to reload text files within the text editor when they are modified by References. This can be made automatically by some text editors21.

Usually you will execute commands in the References window, open the text editor, edit a text file, save it to disk, close the text editor and change back to the References window.

References provides a small additional program (in the following text referred to as the text editor shell) to call the editor with a text file22. It is called at the command line with:

   e-[database-name].bat

if you use the win32 version of References or

   e-[database-name].sh

if you use the Linux version. In the case of the tutorial database, call e-tutorial23, in case of data: e-data24. The main menu of the text editor shell allows to call the text editor25 To enter new bibliographic data into a form or to edit an existing record (see section 4.2), select edit-main-r, to add new keywords to the thesaurus, open the form with edit-main-k (details in section 4.5), open the form for journal data with edit-main-j (details in section 4.4). Search commands are entered into the text file called with edit-main-s. The option edit-main-m opens the file section screen, edit-main-3 opens three files (the references form, search commands form and the keywords thesaurus form) into the text editor. With edit-main-p, a menu (figure 5) accessing AWK-scripts for manipulation of text files is selected. The command edit-main-f opens a tiny file manager26. With edit-main-c, single commands (of the OS shell or command processor may be executed. If you call another instance of the Windows command line shell27, please do not forget to return to the text editor shell with exit.


[r] references form
[s] search command form
[k] keywords thesaurus form
[j] journal data form
[3] three forms: r+k+j
[m] more text files
[t] type text file name
[p] process text files
[f] file and system functions
[h] help, References documentation
[a] about References
[q] quit

[menu] -->           
Figure 4: Main menu of the text editor shell


[htm] convert list of references text file to HTML-file
[ltx] convert list of references text file to LaTeX-file
[exc] excite: extract \cite{} arguments from LaTeX text files
[xex] extended excite: extract arguments of \cite{}-equivalents
[srt] process sorting macro with the sortrefs command
[wdm] citations search-and-replace macro for MS Word
[osw] citations search-and-replace macro for OOOrg/StarOffice writer
[ vi] citations search-and-replace script for vi/vim/gvim
[msr] manual search-and-replace citations list for textprocessors
[rsr] References search-and-replace script for citations
[exa] extract reference numbers from arr-file
[snc] sort groups of numeric citations
[  q] quit

[menu]:
Figure 5: Text editor shell, process text files

Beginning with v4.2, References offers an alternative mode of interaction with the text editor: if in the configuration file the line

   OPEN_EDITOR_YN=1

the, value “1” is assigned to the variable OPEN_EDITOR_YN, References opens the text exitor with the text file of interest automatically after showing the prompt:

   Menu: open editor with file ``C:\refs42\tutorial\sr_form.txt''? [y/n]

In this example, References opens the text editor with the search command file after selecting the main-s command. The installation of References sets OPEN_EDITOR_YN=0, resulting in the behaviour of References as in previous versions.

3.3  Select/install a text editor, edit text (Linux)

On a Linux installation, References writes text files to disk in latin-1 encoding. As modern Linux-versions use utf-8 encoding, References converts text files to this format if it opens the text editor (with a command like main-t ed m or edit-main-r). You can see this from the name of the text file to which “_u8” is appended, e. g. in_form.txt will be converted to a file named in_form.txt_u8. After closing and saving the text editor, the file is converted back to latin-1 encoding and and the filename is in_form.txt. As long as you edit the utf-8 encoded version of the text file, the latin-1 encoded version is not available (i. e. it is temporarily deleted). If you use a Linux implementation of References with utf-8 encoding, you should always open text files with the text editor through the text editor shell or from References itself to make sure that conversions between the different encodings are handled correctly. If you wish to use the edit-main-3 command you will have to use a text editor which is able to open more than one file at the same time.

On Linux systems, good choices for a text editor to be used together with References are nano (simple, see the short description of commands in table 7), vim/gvim, or emacs. On the GNOME-desktop, gedit will be an excellent choice for a text editor with graphical user interface, its equivalent on the KDE is kwrite.

As already mentioned, a list of references generated with the main-l s command will be written by References in latin-1 encoding. If you wish to import this text file into the Linux version of OpenOffice.org/StarOffice writer, you will have to convert encoding from latin-1 to utf-8. This is most easily done with Linux's recode command:

   recode latin-1..utf-8 reflist.txt

To check the current encoding of a text file, type

   file reflist.txt

The message ”reflist.txt: ISO-8859 text, with very long lines” indicates that the file is encoded with ISO-8859 encoding28 After conversion with the recode command, the message will be “reflist.txt: UTF-8 Unicode text, with very long lines”. The problem of encoding and character sets is discussed in section 9.4.

3.4  View text files

In many situations, you will have to browse through a text file in the References text file reader (the view text file function). To see the navigation commands of the view text file function call the menu (figure 6). This function is used to show an abstract text of a bibliographic reference with main-e c [go to a reference with an abstract] a, or you can call it if you explicitly wish to see a text file with main-t vi29.


[f] first page     [l] last page      [n] next page      [p] previous page
[+] line forward   [-] line back      [r] refresh page   [.] first column
[>] one page right [<] one page left  [}] one col. right [{] one col. left
[s] show line no   [g] go to line     [/] find           [q] quit

[menu]:
Figure 6: Menu of the view a text file function

Within the view a text file function you will normally open the text at the beginning with the f command (for the first screen) or with l for the last screen. n brings you to the next page, + scrolls one line forward. Lines which are longer than the screen are indicated as truncated with the dollar character. > brings you one screen to the right (so that you can read more of the truncated line), } shifts the screen one column to the right, . shifts the screen back to the first column. After printing the menu options with menu the command r “refreshes” output of the current page (without the menu text output). You may search a text with /, g prompts you for a line number. The view text file function is closed with q.

For users of the Linux version, References offers the option to use the text-viewing program (“pager”) less instead of the view text file function described above. You simply have to add the line

   USES_LESS=1

to the configuration file (~/.refscfg, for details, see section 8). Less is much more comfortable than References' built-in text viewing function. Use of less with a Linux installation using utf-8 encoding further requires that the recode-tool is available.

3.5  Selection of items from a list

In many situations, References requires that the user selects an item in a list. Therefore, the program writes these items into a temporary text file, and reads this file into the view text file function as described in chapter 3.4. If you have found the item, close the view text file function with q and enter the option to be selected at the prompt.

Examples:

4  Main functions of References

The command main-e (figure 2), selects a group of functions for editing, transferring and reading data. In detail, you can read bibliographic records of the database, create empty forms (text files for entering and editing data), transfer data from text file forms to the database (and back), browse in lists of journal names and in the keywords thesaurus.

Lists of references or macros for various tasks are produced with the functions behind main-l, the options behind main-b manipulate batch tables (bbt-files, tbt-files), options behind main-s search for records in the database, main-d-options process bibliographic format and macro definitions. Functions behind main-t manipulate text files, export database records into archive files, import archive files. Main-f functions check and restructure the database, and provides a simple `file manager'. Main-i issues information on names of input text file forms33.

4.1  View references of the database


[j1] create empty form for j1-type bibliographic record,
     more: [j2], [b1], [b2], [b3], [m1], [m2]
     [ir] import bibliographic record/reference (from form to database),
     [er] export/edit bibliographic record/reference (write to form)
[fj] create empty form for journal data (name, short form ISSN)
     [ij] import journal data (from form to database),
     [ej] export/edit journal data (write to form),
     [lj] list journal data
[fk] create empty form for keywords (to be transferred to the thesaurus),
     [ik] import keywords (from form to thesaurus),
     [lk] list keywords
[ed] edit text files
[ c] browse complete database
[ b] browse database records by BBT-file
[ s] browse records by BBT-file from last search
[ q] back to main menu

[menu]:
Figure 7: Menu: enter, edit, view


[f] first, [l] last, [n] next, [p] previous, [c] current record
[k] go to reference with key number, [#] go to position number
[i] information: show record number, [s] save reference number in BBT-file
[a] show abstract (notes, text) of current record
[q] back to menu `enter, edit, view'

[menu]:
Figure 8: Menu: browse complete database

In order to “browse” (see the records of) the complete database enter main-e c34. Navigate within the database with options of the menu shown in figure 8: With l (“last”) you go to the reference with the highest key number, with p you go back one reference toward the beginning of the database. The option # allows you to jump to the nth record35, with k you may select a reference by its reference number. It is possible to see a subset of references. Subsets of the reference numbers of a database are defined in a bbt-file (cf. section 4.7). The command main-e b (figure 7) prompts for selection of a bbt-file (cf. section 4.7). Then you will encounter the menu with the navigation commands (figure 8). The menu option main-e s opens the bbt-file generated with the last search command.

4.2  Enter references

To enter a bibliographic record for an article of a journal you should first generate an empty form for data entry with main-e j1. The code j1 refers to the document type of an entry, other document types and their codes are described in section 9.1. References prompts you for a reference number and checks if it is really new to the database.

In brief the next steps in the process to enter records are:

  1. enter the form with your text editor, e. g. with the command main-t ed r or edit-main-r,
  2. fill out the fields of the form (see figure 9 as an example),
  3. save the form in the text editor, close the text editor,
  4. press [Enter] at the prompt: “Please press [ENTER] to continue”,
  5. import the file with main-e ir, this command prompts you to view the record with the message: “Check data of citation entered [f/l/n/p/+/-/r/ ... /q]”, to go to the first page of the record, press f,
  6. after checking the file quit the viewing function with q,
  7. References asks you if you really wish to transfer the record with the message: “Write this record into database [y/n]?”.
  8. If the record with the current reference number is already in the database, you will additionally be asked if you wish to overwrite the existing record.

In the rest of this section, details of how to enter the record into the form will be described.


----REFERENCE-NUMBER-[width:12]
a001
----DOCUMENT-TYPE-[width:2]
j1
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----JOURNAL-[width:10]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]

----ISSUE-NUMBER-[width:8]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 9: Data entry form for j1 document type. Text has to be written into the empty lines below the field names as this has already been done automatically with “a001” and “j1”. Field specifications are indicated in [ ]: the maximal number of characters is given as [width:nn], fields with w appended may span over more than one line, num indicates that only (integer) numbers may be entered, num:1..n indicates the valid range.


Fields with a “w36 in the field-width specification: [width:255w]37 may span over more than one line:

   1 ----TITLE-ARTICLE-[width:255w]
   2 A randomized comparison of a sirolimus-eluting stent with a standard stent
   3 for coronary revascularization
   4 ----JOURNAL-[width:4]

Please do not enter an empty line between the last line of a field and and the label for the next field. However, to leave a field empty, you should leave an empty line. Therefore,

   1 ----ISSUE-NUMBER-[width:8]
   2 
   3 ----FIRST-PAGE-[width:10]

is correct. If you do not wish to enter the issue number of the journal for an article in a journal, it may be omitted. Also the STATUS- and ABSTRACT-fields are optional. In every case, AUTHORS- and KEYWORDS (or K-NUMBER)-fields must contain valid entries, otherwise it will not be possible to save the record. The TITLE-ARTICLE, DATE-YEAR, VOLUME, FIRST-PAGE, LAST-PAGE-fields should contain pertinent information, otherwise References will not be able to compile correctly formatted lists of references.

The IDNR-field38 may contain different identifying numbers (hence its abbreviated name) or identifying strings. Here you may enter the string now known as doi39 Each type of identifying string must be labelled with a tag, indicating the type of the identifying number, which precedes the string, separated by a colon (“:”). As an example

   url:http://www.tmed.med.uni-rostock.de/hla.pdf

indicates the URL of an electronic document.

Spaces and percent (%) characters are forbidden in identifying numbers. If such a number contains a space, please insert %20 instead, if an identifying number contains a %-character, insert %2540

Different identifying numbers can be entered separated by spaces.

A complete example of a bibliographic record:

   1 ----REFERENCE-NUMBER-[width:12]
     i06225
     ----DOCUMENT-TYPE-[width:2]
     j1
   5 ----AUTHORS-[width:26,6]
     Ceci,A
     Baiardi,P
     Felisi,M
     Cappellini,MD
  10 Carnelli,V
     De Sanctis,V
     Galanello,R
     Maggio,A
     Masera,G
  15 Piga,A
     Schettini,F
     Stefano,I
     Tricta,F
     ----TITLE-ARTICLE-[width:255w]
  20 The safety and effectiveness of deferiprone in a large-scale, 3-year study in
     Italian patients
     ----JOURNAL-[width:10]
     bjh
     ----IDNR-[width:255]
  25 
     ----DATE-YEAR-[width:4;num]
     2002
     ----DATE-MONTH-[width:2;num:1..12]
     7
  30 ----DATE-DAY-[width:2;num:1..31]
     
     ----VOLUME-[width:20]
     118
     ----ISSUE-NUMBER-[width:8]
  35 1
     ----FIRST-PAGE-[width:10]
     330
     ----LAST-PAGE-[width:10]
     336
  40 ----STATUS-[width:12]
     #001
     ----KEYWORDS-[width:75]
     thalassemia major
     chelation therapy
  45 deferiprone
     ----K-NUMBER-[width:12]
     
     ----ABSTRACT-[width:30600w]
     Ceci et al., 2002
  50 
     In 1997, the Italian Ministry of Health created a special programme for
     the controlled distribution of deferiprone to collect data and to evaluate
     its safety and effectiveness in long-term use. Five hundred and thirty-two
     thalassaemia patients from 86 treatment centres were enrolled in this
  55 programme. One hundred and eighty-seven patients (32%) experienced a total
     of 269 events that led to a temporary interruption or, in some cases, to a
     discontinuation of treatment. The incidence of agranulocytosis and milder
     neutropenias were 0.4/100 and 2.1/100 patient-years respectively.
     Neutropenia occurred predominantly in younger and non-splenectomized
  60 patients. Transient alanine transaminase increase, gastrointestinal
     discomfort and arthralgia were the other most commonly reported events.
     Ferritin levels showed a significant decrease in time after 3 years of
     therapy. This is the largest number of deferiprone-treated patients to
     have been reported to date. These data show that the drug was effective in
  65 reducing serum ferritin levels and the incidence of adverse events was not
     greater than the frequency reported in clinical trials.
     ----END-OF-RECORD

----REFERENCE-NUMBER-[width:12]
a002
----DOCUMENT-TYPE-[width:2]
j2
----INSTITUTIONAL-AUTHOR-[width:140w]

----TITLE-ARTICLE-[width:255w]

----JOURNAL-[width:10]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----VOLUME-[width:20]

----ISSUE-NUMBER-[width:8]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 10: Data entry form for j2 document type
    
----REFERENCE-NUMBER-[width:12]
a003
----DOCUMENT-TYPE-[width:2]
b1
----EDITORS-[width:26,6]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 11: Data entry form for b1 document type


----REFERENCE-NUMBER-[width:12]
a004
----DOCUMENT-TYPE-[width:2]
b2
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----EDITORS-[width:26,6]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 12: Data entry form for b2 document type
    
----REFERENCE-NUMBER-[width:12]
a005
----DOCUMENT-TYPE-[width:2]
b3
----INSTITUTIONAL-EDITOR-[width:140w]

----TITLE-BOOK-[width:255w]

----EDITION-NUMBER-[width:20]

----ISBN-[width:14]

----PLACE-OF-PUBLICATION-[width:255w]

----IDNR-[width:255]

----DATE-YEAR-[width:4]

----PUBLISHER-[width:140w]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 13: Data entry form for b3 document type


----REFERENCE-NUMBER-[width:12]
a006
----DOCUMENT-TYPE-[width:2]
m1
----AUTHORS-[width:26,6]

----TITLE-ARTICLE-[width:255w]

----HOWPUBLISHED-[width:160]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 14: Data entry form for m1 document type
    
----REFERENCE-NUMBER-[width:12]
a007
----DOCUMENT-TYPE-[width:2]
m2
----INSTITUTIONAL-AUTHOR-[width:140w]

----TITLE-ARTICLE-[width:255w]

----HOWPUBLISHED-[width:160]

----IDNR-[width:255]

----DATE-YEAR-[width:4;num]

----DATE-MONTH-[width:2;num:1..12]

----DATE-DAY-[width:2;num:1..31]

----FIRST-PAGE-[width:10]

----LAST-PAGE-[width:10]

----STATUS-[width:12]

----KEYWORDS-[width:75]

----K-NUMBER-[width:12]

----ABSTRACT-[width:30600w]

----END-OF-RECORD
Figure 15: Data entry form for m2 document type

To obtain empty forms for j2-, b1-, b2-, b3-, m1-, m2-documents, enter main-e b1main-e m2, resulting in forms are listed in figures 10, 11, 12, 13, 14, 15.

4.3  Edit existing references

To edit a reference already existing in the database:

  1. look up the record to be changed with main-e c41, quit the browse … function with q. The record shown as you selected q is the current record.
  2. write the current record into the form text file (default in_form.txt) with main-e er.

    Explanantion for current record or current record number: If you leave the function browse complete database or the other two browse … functions, this writes the record number of the current record into a small text file (R_KEY.T in the rdb-subdirectory42). The current record is written into the form text file if main-e er.

  3. Then open form text file with the editor, make the necessary changes and write the form back into the editor with main-e ir.

In this process, you must not change the document type of e record. In such cases, the command main-e ir will not accept the form and issue an error message like:

  (Reading record)

  Problem: Label `----EDITORS-' not found where expected in C:\refs42\tutorial\in_form.txt

  (Record not stored)

This results from a different order of field labels in forms for different document types.

4.4  Enter, edit journal (name, ISSN) data

To enter a record with journal name, ISSN, generate an empty form (figure 16) with main-e fj [Enter a journal code new to the actual database]. After writing details into the form with a text editor, saving the text file, the record is transferred to the database with the command main-e ij. Deleting items from the journal names database table is described in 4.11.4. To change data of a journal record, generate the form with main-e ej.


----JOURNAL-CODE-[width:10]
4lc
----COMPLETE-JOURNAL-NAME-[width:80]

----JOURNAL-SHORT-NAME-[width:60]

----ISSN-[width:14]

----END-OF-FILE
Figure 16: Journal data text file form, default name is jn_form.txt

4.5  Enter keywords thesaurus items


----KEYWORDS-[width:45]

----END-OF-FILE
Figure 17: Text file form for keywords thesaurus items, default name: ky_name.txt


If you wish to add new items to the keywords thesaurus, make an empty for with main-e fk (figure 17), more than one new keywords can be entered, each in a new line. Import these new keywords with main-e ik. Deleting items from the keywords thesaurus is described in 4.11.4. If one or more items are already in the thesaurus, they are ignored.

4.6  Compile lists of references


[s] write list of references in standard format
[u] write list with user defined format,
    [tu] test list with user defined format (read fde file)
[b] create list in BibTeX database format
[m] create macro for text processors, sorting
    [tm] test macro with user defined format (read fde-file)
[t] write text files with journal names, keywords
[a] export abstracts
[q] quit

[menu]:
Figure 18: List of references menu

The main menu option “Compile lists of references” comprises the central functions of this software: lists of bibliographic references are written into text files either in predefined formats43 or in free formats. Some free bibliographic format definitions are provided with the actual References distribution, others may be written by the user (cf. 4.9.2) or obtained from the References website44. Moreover, options main-l m and main-l tm allow to create macros for various purposes.

The most simple way to generate a list of bibliographic items (in a “standard format”):


[1] number only: (n) ...
[2] number and reference key: (n) <REFKEY> ...
[3] reference key: <REFKEY> ...
[4] no leading numbers
[5] REFKEY*00000N: tbt-format, wrapped (65 char)
[6] REFKEY*BBT-TEXT: tbt-format, wrapped (65 char)
[q] quit

[menu]:
Figure 19: Reference number format options

If you want to generate a list of references in a free, user-defined format, select main-l u. After entering the name of the output file, selecting the bbt-file the menu, the message

View list with bibliographic format definitions

prompts you to open the list of bibliographic format definitions. With f you will see the first page, menu opens the menu with the commands for navigation within the list. To proceed, close the list with q. At the prompt

Format definition number, [quit] exit without selection:

please enter the number of the selected format definition. As the next step, select the reference number format (figure 19), the number assigned to the first reference. The command main-l tu (“test user defined format definition”) works in a similar manner, except that it prompts you for format definitions in text file format (text files with the extension .fde). Main-l b creates a list of references in the format of a BibTEX database (for documents written for the LATEX document preparation system [15], cf. chapter 5.1). Main-l m and main-l tm generate lists of references in `macro' format, i. e. references are not separated by empty lines, and the references have no leading reference numbers (as those listed in figure 19). These two options (tu and tm) may be used to make `search and replace' macros for text processors, to generate a list of references for generation of a sorted tbt-file (section 7.4). If the bbt-file contains reference numbers not found in the database, References writes “--ReferenceNo--” into the output file48, “==ReferenceNo==” is inserted into macro format files. This feature can be used deliberately to process manuscripts with reference numbers missing in the database (section 7.3).

The menu option main-l t generates two text files, __jour__.txt and __keyw__.txt. Main-l a writes all abstracts (if they exist) of the references referred to in a bbt-file into a text file.

4.7  Batch files


[bt] convert bbt-file into tbt-file: bbt -> tbt, [tb] convert: tbt -> bbt
[s1] sort bbt-file by reference number field, [s2] sort by text field
[in] invert sequence of records in a bbt-file
[ay] write `author' and `year' into text field of a bbt-file
[rd] remove duplicate records (order of records remains unchanged)
[rs] remove duplicate records and sort by reference number
[ba] write bbt-file with all records from the current database
[br] create bbt-file with range of reference numbers (1st to 2nd record)
[ui] write `unique record identifiers' (URID) into text field of a bbt-file
[ed] extract duplicate records (text field) to a new bbt-file
[ u] union of bbt-files A and B: each record of resulting bbt-file C can be
     found in A or B or both
[ i] intersection of A and B: each record of C can be found in A and B
[ d] difference (complement) of A and B: C contains all records of A which
     are not found in B
[ q] back to main menu

[menu]:
Figure 20: Batch table functions menu

Batch tables (batch files) are files with records containing reference numbers (of records in a References database) in the first and a short text in the second field. They play a central role in the References software as they list (sub)sets of records in a References database49. Batch files provide reference numbers for the following operations (among others):

Batch files (as used by References) occur in two variants, `binary' batch files (or `binary batch tables', hence the filename extension bbt) and `text batch files' (`text batch tables', filename extension tbt). Tbt files are plain text files which you may manipulate with a text editor. Both types of files are referred to in this manual as bbt-files or tbt-files. Batch files are read or written by References in bbt-format, they can be edited with a text editor after conversion into the tbt-format and—after modification—are processed further by References after conversion back into the bbt-format.

The commands for manipulation of batch tables may be found behind the process batch files main-b main menu option. Main-b tb converts the text version of a batch table (.tbt) in the text-directory into its binary (database-like) equivalent (.bbt) and writes it into the ./rdb-subdirectory. The main-b bt command performs a conversion from bbt-file to tbt-file format and localization. A tbt file may be edited with a text editor. The left field between the `*'s is for the reference numbers (obligatory), the right field is a text field, it can be used for sorting. In this example, the text field is empty:

   1 * i05863       *                                      *
   2 * i05862       *                                      *
   3 * i05861       *                                      *
   4 * i05860       *                                      *

If you convert a tbt-file with Main-b tb, leading and trailing spaces in both fields are “trimmed”:

*_i05863_______*

is written as

i05863

into the bbt-file. The command main-b ay writes authors names and year of publication into the text field of a bbt-file. In the previous example it produces a bbt-file which after conversion into a tbt file looks like:

   1 * i05863       * SONNENBERG                FA    2001 *
   2 * i05862       * GOMBOTZ                   H     2000 *
   3 * i05861       * DINKELMANN                S     2002 *
   4 * i05860       * DIETRICH                  G     1999 *

The command main-b s1 sorts records of a bbt-file in ascending order of reference numbers, s2 sorts in ascending order of the text field. main-b in inverts the order of records in a bbt-file. The command main-b rd removes duplicate (or multiplicate) records (with regard to the reference number). This command preserves the order of records,

   1 * i05863       * SONNENBERG                FA    2001 *
   2 * i05862       * GOMBOTZ                   H     2000 *
   3 * i05861       * DINKELMANN                S     2002 *
   4 * i05860       * DIETRICH                  G     1999 *
   5 * i05861       * DINKELMANN                S     2002 *
   6 * i05862       * GOMBOTZ                   H     2000 *
   7 * i05861       * DINKELMANN                S     2002 *

will be converted to

   1 * i05863       * SONNENBERG                FA    2001 *
   2 * i05862       * GOMBOTZ                   H     2000 *
   3 * i05861       * DINKELMANN                S     2002 *
   4 * i05860       * DIETRICH                  G     1999 *

i. e. only the first occurrence of each record is preserved. With the command main-b rs records are sorted into ascending order of reference numbers and the duplicate records are removed. For large bbt-files, processing times are shorter with the main-b rs command. main-b ba writes all references numbers of the current database into a bbt-file (this is required to produce an archive file (filename extension .arr) of the complete database). Main-b br makes a bbt-file with a range of reference numbers. To make a bbt-file with a complete sequence of reference numbers in the database write the reference numbers of the first and last record of the range into the reference number-field of a bbt-file:

   1 * i05860       *                                      *
   2 * i05865       *                                      *

After calling the main-b br command, select this bbt-file and the function will expand this file to:

   1 * i05860       *                                      *
   2 * i05861       *                                      *
   3 * i05862       *                                      *
   4 * i05863       *                                      *
   5 * i05864       *                                      *
   6 * i05865       *                                      *

main-b ui looks up each reference number in the database and writes a `unique record identifier' from each reference into the text field. You may then select i for `case insensitive' (if lower and upper cases of otherwise identical titles, author's numbers shall yield identical unique identifier strings) or s for `case sensitive'.

   1 * i05778       * J1-0C4-00001400-000012B9             *
   2 * i05779       * J1-0C4-00003037-00000949             *
   3 * i05780       * J1-0C4-00001403-00000DE1             *

main-b ed sorts the records of a bbt-file modified with main-b ui by test fields and makes a copy only with the duplicate or multiplicate records (text field). The last two functions are required for identifying duplicate records in the database (and help to eliminate them). Details are described in chapter 7.7.

Three options main-b u (union), main-b i (intersection) main-b d (difference/complement) offer operations on two sets of reference numbers/records (represented by bbt-files, named in the description of the menu `A' and `B') and writes a third one (named `C') (figure 20).

main-b u
each record of the resulting bbt-file `C' can be found in `A' or `B' or both
main-b i
intersection of `A' and `B': each record of `C' can be found in `A' and `B'
main-b d
difference (complement) of `A' and `B': `C' contains all records of `A' which are not found in `B'

These functions are useful to “post-process” bbt-files which are results of search commands (cf. section 4.8).

4.8  Search references

Bibliographic references may be searched e. g. by authors'/editors' names, by keywords, date of publications and many other options. After selecting s from the main menu, References opens the text file with search command50 and name of the bbt-file51 (cf. section 4.7). By default, its name is sr_form.txt (you may change its name as described in chapter 8). Searching is best explained by an example. Open sr_form.txt and write a search command (search command syntax will be explained later) into the first line of this text file and the output bbt-file name into the second line. The example in figure 21 will produce a the bbt-file answ.bbt52 with references containing the string blood in the keywords-field.


keyw=blood
answ

keyw=platelet & keyw=function

keyw=blood transfusion & keyw=infectious disease
bltr-inf

auth=Aster
aster
Figure 21: Example of a search command file. The contents of the third and later lines will be ignored by References. In search command files you may store previously used search commands for later use.

To process a search command, select main-s. In the next menu you may enter c if you wish to search the complete database. The alternative: b may be selected if search shall be restricted to records listed in a bbt-file. In the next menu search may be initiated case sensitive s or case insensitive i. If records fulfilling the search command are found, you can browse in the records with a menu similar to that in figure 8.

In brief the sequence of things to to for searching is:

  1. edit the search command file (default sr_form.txt)
  2. enter main-s c s53 or main-s c i54
  3. (if records were found) browse through the bbt-file with l p p ... (beginning with the last record) or f n n ... (beginning with the first record found).

If you wish to view the records of the resulting bbt-file later, select main-e s, this opens the bbt-file referred to in the second line of the search command file, if it exists. Section 14.1 gives a complete description of the search command syntax.

If the search command file does not exist or if its first line is empty, References prompts you first for the search command and then for the output (bbt) file name.

4.9  Bibliographic format definitions

4.9.1  Importing, exporting, deleting, sorting bibliographic format definitions

Functions for management are selected from the bibliographic format definitions menu (figure 22) main-d. Format definitions are stored in a database file and References produces and reads two text file formats of single format definitions or the complete set of format definitions.


[ef] export format definition into form (.fde)
[if] import format definition (.fde) into database
[mf] make empty form (.fde) for format definition
[ex] export single format definition from database into text file (.fd)
[ea] export all format definitions from database into text file (.fd)
[im] import format definition from file (.fd) into database
[ d] delete format definition in database file
[ s] sort format definitions
[ q] quit

[menu]:
Figure 22: Menu: bibliographic format definitions

“Plain” format definitions with the extension .fd55 are intended for transfer of format defintions from one installation or database to another56. Format definitions with the file name extension .fde57 are intended for development of a format definition and for modification by the user. Fde-files contain interspersed short explanations (cf. section 14.2.1) intended to help writing a format definition:

BIBLIOGRAPHIC STYLE FORMAT DEFINITION -- REFERENCES 4.3

--
-- short name (key) of format definition
--
-- width: 20
--
format definition ''

--
-- description of bibliographic format definition
--
-- width 255
--
description ''

--
-- major elements (lines) for document type `journal article' (j1):
-- sequence of list of authors (%au), title (%ti), localization (%lo)
--
-- width: 3
--
j1 string 1 ''
j1 string 2 ''
j1 string 3 ''

--
-- major elements (lines) for document type `journal article' with
-- institutional author (j2): sequence of author (%au), title (%ti),
-- localization (%lo)
--
-- width: 3
--
j2 string 1 ''
j2 string 2 ''
j2 string 3 ''

In the line:

  format definition '' 

format definition is recognized as a“keyword” by the import format definition command (main-d mf). The “value” or the contents for this field shall be inserted between the s for (as 'nature-bfd').

Main-d ef exports a single bibliographic format definition into a fde-file (text format). Therefore, References shows you a list of all format definitions in the database, after closing this list with q, please enter the numerical code for this format definition. After making changes in this fde-file with the text editor, you may reimport this bibliographic format definition with main-d if. You are then asked if you wish to append it as a new format definition to the database, or if you wish to replace an already existing bibliographic format definition by the definition in the fde-file. In the latter case you will have to select the format definition to be replaced. The command mf writes a new fde text file. All the other commands in the bibliographic format definitions menu (figure 22) explain themselves.

4.9.2  Writing bibliographic and macro format definitions

Different citation styles are discussed in [5, 1]. The following explanation on writing bibliographic format definitions relates to a complete empty form printed in the appendix (section 14.2.1) The format definitions feature provided by References may be used to generate lists of references appended to a publication, such format definitions may be referred as bibliographic format definitions. Moreover, this feature may be used to create macros, e. g. those to automatically replace “raw” reference numbers (refscite(a3467)) into numerical citation in the text ([45] or /45/) or author-date text citations [1]. For smaller publications, it may also be practical to generate a table for manual replacement of “raw” citations by numerical text citations. Such format definitions may be referred to as macro format definitions. An introduction to writing format definitions is given in the tutorial (section 13.6).

4.9.3  Fde-files

As already mentioned, format definition files for editing as produced with the command main-d mf (filename extension .fde) have comments introduced by “--”. The rest of this section describes the fields if a fde-file (line numbers and field names refer to the format definition form in section 14.2.1).

Line 8 (format definition ”): A short abbreviated name for the actual bibliographic format definition, for example:

   format definition 'vanc-1'

This short string (maximal length: 20 characters) is the key for sorting the bibliographic format definition database file (with main-d s).

Line 15 (description ”): A short description of the format definition in 255 characters (line 15).

Line 23–25 (j1 string 1 ” ... j1 string 3 ”): Sequence of major elements for j1-documents (articles in a journal/periodical). You may enter %au (list of authors' names), %ti (title), %lo (items related with the “localization” of the reference: journal name, volume, date of publication, range of pages). These three elements: list of authors line, title line and localization line will be specified in more detail later. If you enter

   j1 string 1 '%au'
   j1 string 2 '%ti'
   j1 string 3 '%lo'

authors' names will appear first in lists of references generated with this format definition, followed by the title, and the localization of the article. This will be the most common case.

Line 34–36 (j2 string 1 ” ... j2 string 3 ”): Sequence of major elements for j2 documents (articles in a journal/periodical with institutional author). You may enter %au (author's name), %ti (title), %lo (items related with the “localization” of the reference: journal name, volume, date of publication, range of pages).

Line 44–46 (b1 string 1 ” ... b1 string 3 ”): Sequence of major elements for b1-documents (complete books). You may enter %ed (list of editors'/book authors' names), %bo (title of book), %so (items related to the “localization” of the reference: year of publication, publisher, place of publisher, range of pages, edition number).

Line 44–47 (b2 string 1 ” ... b2 string 5 ”): Sequence of major elements for b2-documents (chapter/article in a book). You may enter %au (list of authors' names), %bo (title of book), %ti (title of chapter/article), %ed (list of editors'/book authors' names), %so (anything related to the “localization” of the reference: year of publication, publisher, place of publisher, range of pages, edition number).

Line 68–70 (b3 string 1 ” ... b3 string 3 ”): Sequence of major elements for b1-documents (complete books with institutional/no editor). You may enter %ed (editor's name), %bo (title of book), %so (items related to the “localization” of the reference: year of publication, publisher, place of publisher, range of pages, edition number).

Line 78–80 (m1 string 1 ” ... m1 string 3 ”): Sequence of major elements for m1-documents (miscellanea). You may enter %au (list of authors' names), %ti (title), %so (items related to the “localization” of the reference: year of publication, “howpublished”).

Line 89–91 (m2 string 1 ” ... m2 string 3 ”): Sequence of major elements for m1-documents (miscellanea with institutional/no author). You may enter %au (authors name), %ti (title), %so (items related to the “localization” of the reference: year of publication, “howpublished”).

Line 98–105 (j1 authors 0 ” ... j1 authors 7 ”): specification of the list of authors line (j1-document): keywords listed in chapter 14.2.3.9 may be used, their functions are described in section 14.2.2.

Lists of editors, title, book-title and localization lines for all document types are entered analogously as line 98–105.

Line 702–706 (j1 authors string type ” ... m1 editors string type ”): determine the sequence of names and first names in the authors' and editors' lists as described in table 1. In this field only 0, 1, 2 or 3 may be entered.


CodeTypeExample
0 Enters only last names Miller, Smith and Lastwriter
1 Last names before first names Miller A. A., Smith B. B. and Lastwriter Z. Z.
2 First names before names A. A. Miller, B. B. Smith and Z. Z. Lastwriter
3 Type 1 for first author and type 2 for following authors Miller, A. A., B. B. Smith and Z. Z. Lastwriter
Table 1: Sequence of authors' names

Line 715–719, 728-732, 741–745, 754–758, 767–771, 780–784 (j1 delimiter ^1 in authors string ” ... m1 delimiter ^6 in authors string ”) Delimiters between authors' names and forenames are specified with six delimiters (firgure 23). The special keyword %() (see table in chapter 14.2.2) allows to insert the argument in brackets, this may be better readable, but both '%(._)' and '._' yield the same result.


FirstAuth, A. A., B. B. SecondAuth, C. C. ThirdAuth & Z. Z. LastAuth.   
                ^^1               ^^1              ^^^2             ^6  
FirstAuth, A. A., B. B. SecondAuth, C. C. ThirdAuth & Z. Z. LastAuth.   
         ^^5^^3^3      ^4            ^3  ^4                         ^6  
Figure 23: Delimiters for authors' and editors' lists. 1: delimiter between authors' names, 2: delimiter between the last two authors' names, 3: delimiter after first names (forenames), 4: delimiter between first names (forenames) and names, 5: delimiter between names and first names (forenames), 6: delimiter after last name


Line 793–797 (j1 delimiter more names in authors string ” ... m1 delimiter more names in editors string ”): If a list of authors contains more names than the number of authors printed this can be indicated with a clause like “et al.”

Line 806–810, 820–824 (j1 n in authors string ” ... m1 m in editors string ”): Two numbers (m, n) control the numbers of authors printed into the list. They refer to a rule like print all authors if not more than n else print m. The Vancouver convention of citing references [6] may serve as an example: n=6, m=3.

4.10  Manipulation of text files

4.10.1  Export/import of records from/into database (arr-files) – backups of References databases

Main-t ex exports records from a References database into a defined text format (an archive file). Archive files (filename extension .arr) are described in section 14.3. You may either write a complete archive file with c, in this case the archive file will contain the keywords thesaurus and the complete journal names database. Main-t ex e writes an archive without journal names and without keywords thesaurus. The next steps:

It is strongly recommended to make regular backups (as .arr-files)


[im] import data from archive file
[ex] export data into archive file
[lt] write list of references to LaTeX ``thebibliography'' environment
[xr] extract reference numbers from a text file
[sr] search and replace operations
[me] convert medline input to form
[ed] edit text file
[vi] view text file
[ q] back to main menu

[menu]:
Figure 24: Menu: Text files, export/import from/into database

Contents of an archive file are imported with the command main-t im.

The command main-t lt converts a text list of references (generated with main-l s or main-l u in the reference number format <reference-number> ...) into a thebibliography environment for the LATEX text processing software [15]. This issue is described in detail in section 5.2.

The command main-t xr extracts reference numbers from a document in the format of a text file (cf. section 4.10.2), main-t sr automatically performs “search-and-replace” operations. With main-t me you can convert a bibliographic reference from “medline” format into a References input form, this procedure is described in detail in section 4.10.4.


[r] references form
[s] search command form
[k] keywords thesaurus form
[j] journal data form
[3] three forms: r+k+j
[m] more text files
[t] type text file name
[q] quit

[menu] -->        
Figure 25: Menu: Edit text files

main-t vi opens a text file for reading text files, main-t ed opens the menu of figure 25.

4.10.2  Extract reference numbers from a text file

If you write a manuscript you may enter reference numbers directly into the text in a format that allows to extract them. If a commercial text processor is used, it will be necessary to make a copy of the document in the format of a “text only” file60. If you use LATEX or TEX, .tex files may be used directly.

After selecting main-t xr you will be asked to enter a “search pattern”. The default search pattern is refscite(), a second type is refscite{}. Please note that in the second type, curled braces are used and that refscite(} or refscite{) are not valid search patterns61. If you use LATEX with BibTEX, you may use the search pattern \cite{}62.

To get an idea how this function works, enter a small fragment of text into a file (e. g. testxr.txt)

...
Red cell antibodies were detected with a modification of the direct
antiglobulin test refscite(200112Co), eluates were prepared with the acid
elution technique refscite(199401Pa) refscite(199907In).
...

Then process it with References

You may read output by converting it into a tbt-file (main-b bt, cf. section 4.7):

* 200112Co     *                                      *
* 199401Pa     *                                      *
* 199907In     *                                      *

If you wish to use another search pattern, e. g. “//cite()”, reference numbers should be formatted in the text as:

...
Red cell antibodies were detected with a modification of the direct
antiglobulin test //cite(200112Co), eluates were prepared with the acid
elution technique //cite(199401Pa) //cite(199907In).
...

this file can be processed:

Batch files generated from manuscripts with this command are used to produce formatted lists of references for a manuscript (section 4.6) and to generate macros for text processors which can convert “raw” citations as refscite(cite(200112Co)) into properly formatted numeric citations as [12] or citations in author-year format, like: (Mueller et al, 2001) (section 7.2).

4.10.3  Perform automated “Search and replace” operations

With the command main-t sr you have access to a function which can perform automated `search-and-replace' operations. It is used by writing the strings to be replaced and the new text into a search-and-replace script with the filename extension sr. The function is best explained by an example. In the text fragment [12, page 5-6] in text file named book.txt, both “emac” and “Emac” shall be corrected:

To start emac, simply start emac followed by the name of the file to edit. If
you use a filename that doesn't exist, Emac creates a new file. Of course, if
the file you request already exists, Emac reads the file and displays it on
the screen.

If you wish to replace `emac' by `emacs' and `Emac' by `Emacs' you may write this into a `search-and-replace' script (emacs.sr)64:

/emac/emacs/
/Emac/Emacs/

To process the text file book.txt with the script in emacs.sr:

If you open book.txt with a text editor you can see the `corrected' text:

To start emacs, simply start emacs followed by the name of the file to edit. If
you use a filename that doesn't exist, Emacs creates a new file. Of course, if
the file you request already exists, Emacs reads the file and displays it on
the screen.

Each valid line in a sr-script performs a search and replace-operation. The `syntax' for a sr-script:

<Delimiter>text to be searched<Delimiter>text to be inserted<Delimiter>

The following rules apply to sr-scripts:

  1. References understands the first character in each line as the delimiter which indicates beginning and end of the text to searched and the to be inserted in place of the (removed) text to be searched.
  2. The delimiter therefore should not be a characater which appears in the text to searched or in the new text with the replacements done65.
  3. each line is a search-and-replace command, however, characters following the third occurrence of a delimiter will be ignored (or regarded as `comment'). In our example,
    /emac/emacs/ ...lower case
    /Emac/Emacs/ ...upcase
    

    will perform as

    /emac/emacs/
    /Emac/Emacs/
    
  4. lines with identical text for text to searched and new text with the replacements to be done are ignored, therefore strings like
    /././
    '-'-'
    ababa
    

    may be used to introduce a comment. The sr-lines

    * **
    * *
    . ..
    . .
    

    may be used to remove spaces.

  5. The string \n has a special meaning. If it occurs alone in the new text with the replacements to be done-field, in introduces end-of-line characters into the text file.
  6. The search and replace function first processes the the first line of a text file, i. e. it executes all lines in the sr-file, then reads the second line of the text file and so on. Each operation is written into a special log file (srchrepl.log).

Powerful alternatives for complex “search and replace”-operations can be realized with script tools like sed, awk, perl66.

4.10.4  Import bibliographic records from the PubMed MEDLINE display format

Workers in the field of biomedical sciences often use PubMed, a service at the NLM67, which gives access to the contents of the MEDLINE bibliographic database. As of the time of writing, PubMed is accessible under the URL http://www.ncbi.nlm.nih.gov/entrez/query.fcgi.

Users of References may download bibliographic references in the “MEDLINE” display format and enter it directly into a References database. An example of such a bibliographic record:

   1 UI  - 89274408
     PMID- 2471562
     DA  - 19890714
     DCOM- 19890714
   5 LR  - 20001218
     IS  - 0006-4971
     VI  - 73
     IP  - 8
     DP  - 1989 Jun
  10 TI  - The Bra/Brb alloantigen system on human platelets.
     PG  - 2219-23
     AB  - Anti-Bra was first identified in four cases of neonatal alloimmune
           thrombocytopenia (NAIT). The antigen Bra is localized on the glycoprotein
           Ia/IIa complex of platelets. Anti-Bra can best be detected by a
  15       glycoprotein-specific immunoassay using monoclonal antibodies for antigen
           immobilization (MAIPA assay) and radioimmunoprecipitation (RIP). Recently,
           we have identified sera from two polytransfused patients that contain an
           antibody that recognizes Brb, the allele of Bra. Family studies show that
           both antigens are inherited as autosomal codominant characters. The gene
  20       frequency of the new allele Brb is 0.888. Approximately 2,000 anti-Bra
           binding sites are present on homozygous platelets and 1,000 on
           heterozygous platelets. Our findings provide evidence for the first
           polymorphism observed on the glycoprotein Ia/IIa complex. Immunization
           against these alloantigens is implicated in NAIT and poly-transfused
  25       patients.
     AD  - Institute for Clinical Immunology, Justus-Liebig-University, Giessen,
           Federal Republic of Germany.
     FAU - Kiefel, V
     AU  - Kiefel V
  30 FAU - Santoso, S
     AU  - Santoso S
     FAU - Katzmann, B
     AU  - Katzmann B
     FAU - Mueller-Eckhardt, C
  35 AU  - Mueller-Eckhardt C
     LA  - eng
     PT  - Journal Article
     CY  - UNITED STATES
     TA  - Blood
  40 JID - 7603509
     RN  - 0 (Antibodies, Monoclonal)
     RN  - 0 (Binding Sites, Antibody)
     RN  - 0 (Epitopes)
     RN  - 0 (Isoantibodies)
  45 RN  - 0 (Isoantigens)
     RN  - 0 (platelet-specific alloantigen Br(a))
     SB  - AIM
     SB  - IM
     MH  - Antibodies, Monoclonal/analysis
  50 MH  - Antibody Specificity
     MH  - Binding Sites, Antibody
     MH  - Blood Platelets/*immunology
     MH  - Epitopes/analysis/immunology
     MH  - Human
  55 MH  - Isoantibodies/analysis
     MH  - Isoantigens/*analysis/genetics/immunology
     MH  - Pedigree
     MH  - Phenotype
     MH  - Precipitin Tests
  60 MH  - Support, Non-U.S. Gov't
     EDAT- 1989/06/01
     MHDA- 1989/06/01 00:01
     PST - ppublish
     SO  - Blood 1989 Jun;73(8):2219-23.

This record format is able to give information of articles in journals (periodicals). “Fields” are labelled with a “tag” at the beginning of the line. For example UI denotes a unique identifier. The tags indicating fields transferred into a References record are shown alphabetically in table 2.


Tagdescription
AUauthors
ABabstract
DPdate of publication (year)
IPThe number of the issue, part, or supplement of the journal in which the article was published
MHMeSH (Medical Subject Headings) terms (in the controlled NLM vocabulary)
PGrange of pages (first page – last page) of the article
TAjournal title abbreviation
TItitle of the article
VIvolume of the journal
Table 2: Tags of the PubMed Medline format translated by References


To convert the above Medline record (example for a file name: me1.txt68) into an input form69 do the following:

The input form can then be opened with the text editor:

   1 ----REFERENCE-NUMBER-[width:12]
     ChangeMe
     ----DOCUMENT-TYPE-[width:2]
     j1
   5 ----AUTHORS-[width:26,6]
     Kiefel,V
     Santoso,S
     Katzmann,B
     Mueller-Eckhardt,C
  10 ----TITLE-ARTICLE-[width:255]
     The Bra/Brb alloantigen system on human platelets
     ----JOURNAL-[width:4]
     blo
     ----DATE-YEAR-[width:4;num]
  15 1989
     ----DATE-MONTH-[width:2;num:1..12]
     6
     ----DATE-DAY-[width:2;num:1..31]
     
  20 ----VOLUME-[width:20]
     73
     ----ISSUE-NUMBER-[width:8]
     8
     ----FIRST-PAGE-[width:10]
  25 2219
     ----LAST-PAGE-[width:10]
     2223
     ----STATUS-[width:12]
     
  30 ----KEYWORDS-[width:45]
     no MeSH in MEDLINE format
     ----K-NUMBER-[width:12]
     
     ----ABSTRACT-[width:30600]
  35 AB  - Anti-Bra was first identified in four cases of neonatal alloimmune
           thrombocytopenia (NAIT). The antigen Bra is localized on the glycoprotein
           Ia/IIa complex of platelets. Anti-Bra can best be detected by a
           glycoprotein-specific immunoassay using monoclonal antibodies for antigen
           immobilization (MAIPA assay) and radioimmunoprecipitation (RIP). Recently,
  40       we have identified sera from two polytransfused patients that contain an
           antibody that recognizes Brb, the allele of Bra. Family studies show that
           both antigens are inherited as autosomal codominant characters. The gene
           frequency of the new allele Brb is 0.888. Approximately 2,000 anti-Bra
           binding sites are present on homozygous platelets and 1,000 on
  45       heterozygous platelets. Our findings provide evidence for the first
           polymorphism observed on the glycoprotein Ia/IIa complex. Immunization
           against these alloantigens is implicated in NAIT and poly-transfused
           patients.
     
  50 ----END-OF-RECORD

Before importing this record into the database, some items must be checked and edited, if necessary:

line 11:
With some references it may be necessary to change capitalization of the title,
line 13:
check if References was successful in identifying the correct journal name code, correct the code and enter data for a new journal (cf. section 4.4) if necessary,
lines 31, 33:
enter/edit keywords71.

The record may then be entered with main-e ir, then you should have again a look into the converted record in the text view function with f n ... q with y you confirm that the record is written into the database.

4.10.5  View text files

The view text file function may be used directly through the command main-t vi, after selecting the text file and menu, the menu with the commands for navigating in the text file become visible (figure 6). Details have been described in section 3.4.

4.11  File, database and system functions

The menu for file, database and system functions is shown in figure 26. To execute a command of a/the shell of the operation system select main-f s. Main-f v verifies integrity of all database, index and bbt-files, main-f k deletes entries from the keywords thesaurus, j from the journal names database. The option s can be called to execute a shell command, c opens the configuration file in the text editor.


[f] file manager: delete, rename, duplicate files
[r] rebuild current database
[v] verify database integrity
[d] delete references in database
[k] delete keywords in thesaurus
[j] delete journal entry
[s] shell command
[c] edit configuration file
[q] quit

[menu]:
Figure 26: Menu: file, database and system functions

4.11.1  File manager

This fuction provides a primitive “file manager” (figure 27) for the files in the database text files and binary files directories:main-f f. To delete a file, select d, the next menu prompts you for possible extensions of text files (figure 28). The r (rename) command allows to rename a file72, 2 (duplicate file) makes a copy of a file in the same directory.


[d] delete file
[r] rename file
[2] duplicate file
[q] quit

[menu]:
Figure 27: File manager


[bbt] binary batch table (*.bbt)
[tbt] text batch table/file (*.tbt)
[txt] (*.txt), [doc] (*.doc), [bib] (*.bib), [asc] (*.asc), [tex] (*.tex)
[arr] References archive file (*.arr), [fd] format definition (*.fd)
[fde] format definition for editing, [log] (References) log file
[ sr] search and replace script, [html] HTML web document
[  q] quit

[menu]:
Figure 28: Selection for file name extensions of file manager. Files with the extension bbt are expected in the database binary files directory, all other files in the database text files directory

4.11.2  Rebuilding the database

Main-f r brings you to the rebuild database menu (figure 29). Adding and deleting records in a database enlarges database files73, leaving unused space in these files. The restructure database and index files command r writes data into new database files and recreates index files (except the files for the abstract data and the bibliographic format definition table). d rebuilds the abstract data and index files. The i and a commands only refresh the index files. If you wish to create a new database, a set of empty .dat and index (ix) files is created with c. 2 deletes all .dat and .ix-files, 1 deletes the same files except the format definition database formdef.dat.


[i] rebuild index files only
[r] restructure database and index files
[a] rebuild abstract index file
[d] restructure abstract database and index files
[c] create missing database and index files
[1] destroy database files but not format definition database
[2] destroy database files and format definition database
[q] quit

[menu]:
Figure 29: Commands to rebuild index files, database files and to delete database files

4.11.3  Delete bibliographic references in the database

If you wish to delete bibliographic references in the database you will have to get their reference numbers into a bbt-file (see details in chapter 4.7). Before deleting something, it is prudent to export the references referred to in this bbt-file into an archive file (section 4.10), so you can “undo” a deleting-operation. To delete, select main-f d, select the number assigned to the bbt-file with the reference numbers to be deleted, confirm with y. The software confirms that data have been deleted with a message like:

   (Deleting records)

   (Modifying main index file)
   (1 records successfully deleted)
   (Modifying abstract index file)
   (1 abstracts successfully deleted)

4.11.4  Delete items in the keywords thesaurus and in the journal names database

Keywords in the thesaurus are easily deleted with main-f k, to make a list of items of the thesaurus fro selection, References prompts you with

   Substring (empty for all keywords):

if you enter a blank line with [Enter], References writes all keywords into the list. A substring selects a subset of keywords containing this string. f brings you to the first page of the list of keywords74. n selects the next page of this list. If you have found the item to be deleted, quit this list with q and enter the number assigned to the selected keyword entry in the list. You can delete journal names following a similar procedure with main-f k.

5  References and LATEX

References supports writing LATEX documents with bibliographic references in different ways. This software may be used as database which helps to generate .bib files which can be used together with BibTeX [15] (section 5.1) and it generates freely formatted lists of references in a thebibliography-environment [15], which may be used with the \cite{}-command in LATEX-documents (section 5.2). Moreover, References provides tools to “extract” reference numbers from \cite{}-commands in LATEX-documents (section 5.4).

5.1  References and BibTeX

Use of BibTeX is described in [15, 16]. Create a BibTEX-database with main-l b. You are then asked

  1. to enter the name for the output file (the extension .bib will be automatically added),
  2. to select the bbt-file with the reference numbers

then you will have to select the reference number format: with o the original reference numbers are written into the key-position of the record as in

@article{key-from-references-database,
  author={...},
  ...
}

the option n in this menu will generate new keys. Equivalents of References and BibTEX document types are listed in table 3. An example of the output produced by this function is shown in section 14.4.


ReferencesBibTEX
j1, j2@article
b1, b3@book
b2@incollection
m1, m2@misc
Table 3: Corresponding References and BibTEX document types

Writing a document in this standard mode implies inclusion of reference numbers with \cite{}, including the .bib-file at the end of the manuscript and selection of a bibliographic style at the beginning of the document [15].

5.2  Lists of references in the `thebibliography'-environment.

Lists of references in thebibliography-environment are made in two steps:

  1. write a list of references with main-l s or main-l u, in “Menu: Reference number format” select 3. This generates references beginning with <REFERENCE-NUMBER> ...
  2. This list of references (filename extension txt) can be converted with main-t lt into a list in thebibliography-environment (filename extension tex).

The resulting output file looks like:

   1 \begin{thebibliography}{99}
     
     \bibitem{m00009} Lamport L. Das LaTeX-Handbuch. Bonn: Addison-Wesley
     Publishing Company, 1995.
   5 
     \bibitem{m00011} Kopka H. LaTeX: Eine Einf\"uhrung Band 1. 2. ed. Bonn:
     Addison-Wesley Publishing Company, 1996.
     
     \bibitem{m00015} Goossens M, Mittelbach F, Samarin A. Der LaTeX-Begleiter.
  10 1. ed. Bonn, Paris, Reading, Menlo park, New York, Don Mills, Wokingham,
     Amsterdam, Milan, Sydney, Tokyo, Singapore, Madrid, San Juan, Seoul,
     Mexico City, Taipei: Addison-Wesley Publishing Company, 1995.
     
     \end{thebibliography}

In line 1, the argument of the environment should be adjusted, e. g. to `999' if the list of references comprises more than 100 entries, or to `9' if the list is shorter than 10 references.

5.3  Write LATEX-documents using refscite() for citations

This third option to produce LATEX-documents with lists of references and appropriate citations in the text is perhaps the most flexible and the least comfortable. It may be appropriate to write single book chapters for a multi-author-book or a manuscript for a scientific journal with special formal requirements for the list of references and citations (for details cf. section 1.1). The following steps are required75:

  1. Insert citations in the LATEX-document with refscite() or in an equivalent format (cf. explanation on search patterns in section 4.10.2),
  2. extract reference numbers with main-t xr, this generates a bbt-file (cf. section 4.10.2),
  3. remove duplicate citations from this bbt-file (cf. section 4.7),
  4. sort the bbt-file,
  5. make the list of references with the main-l u function
  6. generate a macro for replacing refscite(...)s in the text by numerical citations76 or citations in author year format77 with main-l m
  7. process the LATEX-document:
  8. run LATEX on the file with the replacements done

5.4  Extract reference numbers from LATEX documents

The most important command for LATEX-users who want to extract the reference numbers entered with \cite{...} in their documents is edit-main-p exc. The script called by this command issues the message

   filename.tex -> rcite.tbt

   EXCITE appended 200 reference numbers to rcite.tbt

indicating that all reference numbers have been written into rcite.tbt text file.

In order to produce a list of references you will have to convert this tbt-file into a bbt-file, remove duplicate reference numbers and sort the bbt file (cf. section 4.7). An alternative to excite script would be the extract reference numbers from a text file function of References described in section 4.10.2. The disadvantage of that function is that it can only extract one item from each \cite{...}, whereas excite can extract all reference numbers from a comma-delimited list as in \cite{label.1,label.2,...label.n} and in addition, excite can extract reference numbers form cites with optional parameter as in \cite[page n]{...}.

The command edit-main-p xex works similarly as excite, but it extends the literature-referencing commands to many of those required by the Harvard-package [4]: \cite{}, \cite[]{}, \citeasnoun{}, \citeasnoun[]{}, \possessivecite{}, \possessivecite[]{}, \citeaffixed{}{}, \citeaffixed[]{}{}, \citeyear{}, \citeyear[]{}, \citename{}, \citename[]{}.

Both edit-main p exc and edit-main p xex only require that \cite{...} and the constructs for the Harvard-package are written within one line in the LATEX-files79. The Natbib package [3] has even more referencing commands: \citet{...}, \citealt{...}, \citeauthor{...} etc., therefore, an AWK or perl-script similar to exharv.awk80 may be written by the user.

5.5  Tools for LATEX and References

If you have written a LATEX-document with reference numbers with \cite{} (sections 5.1, 5.2) and wish to process the document further with reference numbers in refscite() (cf. section 5.3), you may convert the document with the fromcite.awk script. You will find the script in the bin subdirectory of your installation. fromcite.awk works like a filter program. You may use it at the (shell) command line:

   awk -f fromcite.awk < old.tex > new.tex

It is even more practical to use the filter program from within an advanced text editor like Vim or Emacs: both editors allow to process a region through an external (“filter”) program. Details can be found in the documentation of the text editors. The reverse is done by the script tocite.awk, which is used similarly.

6  How do I …?

6.1  How do I process files (copy, rename, move)?

  1. with the options of the file manager of References main-f f or edit edit-main-f f (cf. section 4.11.1).
  2. with the explorer on win32 systems (cf. section 6.2)

6.2  How do I call the `explorer' from References on win32-systems?

From References call main-f s and enter “start .”. From the text editor shell, select edit-main-f s and enter “start .”.

6.3  How do I copy reference numbers and other short text fragments from the References screen to the text processor (and vice versa)

6.3.1  Win32-systems

Copy the text from the References into the clipboard (alt-space, process, mark)81. You may also insert text from the Win32 clipboard (alt-space, process, insert) at the References prompt.

6.3.2  Linux-systems

Linux users will run References in a console window in the KDE or Gnome desktop environment. The console programs allow comfortable interaction with the clipboard using the mouse for labelling text in the console and for inserting text in the console at the References prompt.

6.4  How do I modify lists of references?

6.4.1  How do I remove the empty lines from a list of references?

OpenOffice.org/StarOffice writer: Use “search and replace”: search “^$” and replace by an empty string, activate the “regular expression” box.

6.4.2  How do I remove <reference-number> from a list of references?

Sometimes you will generate a list of references with leading reference numbers in angular brackets (<...>). The following recipe shows how you can remove them: OpenOffice.org/StarOffice writer: Use “search and replace”: search “^<.*>_” and replace by an empty string, activate the “regular expression” box.

7  Special problems

7.1  Make lists of references formatted with different fonts

As References only produces plain text files, information on font type for certain elements of these citations as typewriter-like monospaced font, italicized, underlined or bold has to be added indirectly. A practical convention in this version of References82 proposes that you can write format definitions for lists of references like:

  ... ___open-it(text to appear in italics)close-it___ ...
  ... ___open-tt(text to appear monospaced)close-tt___ ...
  ... ___open-bf(text to appear bold)close-bf___ ...
  ... ___open-ul(text to appear undelined)close-ul___ ...
  ... ___open-sc(text to appear in small capitals)close-sc___ ...

References provides two scripts, which can convert text files with these tags either into HTML-documents or into text for LATEX-documents. The “tags” ___open-sc(...)close-sc___ are only processed for LATEX documents, they are ignored for HTML. As an example, you may study the bibliographic format definition APA-FS BFD. If you use a normal text processor, you can convert a list of references into a complete formatted HTML-file with edit-main-p htm. and import it into the manuscript. To produce a text to be included into a LATEX document, select edit-main-p ltx83. If you use “underlined” in a LATEX document, please load the soul-package.

7.2  How to create formatted citations of references in a manuscript

7.2.1  Principles

Scientific manuscripts have to provide a list of references at the end which contain all items cited in the text of the manuscript. It is therefore necessary to enter citations in a “raw” format in the text which allows automatic processing of the manuscript. These citations in the text must be converted later into either a numeric format or the author-date format (cf. section 1.1). The default method for References is to enter reference numbers in the format refscite(reference-number)84. The second step is to read the manuscript automatically to extract all reference numbers into a tbt- or bbt-file. Therefore you will have to create a copy of the manuscript with all portions containing citations in a unformatted text file. This is most easily done by copying the manuscript into the clipboard and save it as text file with the text editor85.

Citations can be formatted manually86 in a document written by a word processor. Therefore References can prepare a list of items to be searched and the corresponding items to be replaced (see section 7.2.1). Citations in a large document87 can also be processed automatically. Therefore, References can generate a macro for the text processor (things are much easier with LATEX, details are described in section 5). For all these tasks, References makes a generic macro first, which is then converted either into a list for manual search-and-replace processing in a text processing program or a macro (e. g. for a word processor). The generic macro has the format:

  ///A///refscite(i03544)///B///[8]///C///

such a macro can be generated with main-l m command using the macro format definition CITATION-NUM-1 MFD, in its converted form it is intended to replace raw citations of the type refscite(i03544) to numeric citations like “[8]”. With the macro format definition CITATION-AY-1 MFD generic macros for citations in author-date format: “(Mueller et al., 2001)”can be made.

  ///A///refscite(i03544)///B///(Mueller et al., 2001)///C///
  ///A///refscite(i03522)///B///(Grandfather and Smith, 1920)///C///

These generic macros can be converted into a list for manual search-and-replace commands for a text processor with edit-main-p msr:

   refscite(i03544)
   (Mueller et al., 2001)
   done:

   refscite(i03522)
   (Grandfather and Smith, 1920)
   done:

or into macros for text processors as described in sections 7.2.2, 7.2.3. Scripts for generation of these macros have been written following analysis of search and replace operations recorded by the macro recorder of the respective word processor.

7.2.2  Format citations automatically in an OpenOffice.org/StarOffice Writer document

The procedures described in this section work satisfactorily in the hands of the program author. However, the program author does not assume any liability for damages, resulting from the use of macros generated by References in the StarOffice/OpenOffice.org package. The user may apply these functions at her/his own risk.88

The code for the search-and-replace operations in figure 30 was derived from code descibed in [17, page 104]. It was tested using StarOffice 7.


REM  *****  BASIC  *****

Sub Main
Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim RawWords(2) As String
Dim FormattedWords(2) As String
RawWords() = Array(_
"refscite(i07160)",_
"refscite(i07161)",_
"refscite(i07162)"_
)
FormattedWords() = Array(_
"(Ahmad et al., 2004)",_
"(Shattil, 2004)",_
"(Nguyen et al., 2004)"_
)
Doc = StarDesktop.CurrentComponent
Replace = Doc.createReplaceDescriptor
For I = 0 To 2
        Replace.SearchString = RawWords(I)
        Replace.ReplaceString = FormattedWords(I)
        Doc.replaceAll(Replace)
Next I
End Sub
Figure 30: Macro to process citations in StarOffice/OpenOffice.org Writer documents, this fragment replaces refscite(i07160) by (Ahmad et al., 2004), refscite(i07161) by (Shattil, 2004) and refscite(i07162) by (Nguyen et al., 2004).


7.2.3  Format citations automatically in a Microsoft Word document

The procedures described in this section work satisfactorily in the hands of the program author. However, the program author does not assume any liability for damages, resulting from the use of macros generated by References in Microsoft Word or the Microsoft Office package. The user may apply these functions at her/his own risk.

References provides a method to create appropriate citations in a manuscript written with the Word module of the Microsoft Office package. Therefore, a Word macro can be created with References. You can use it by loading a copy of your manuscript with the raw refscite()-citations, by opening the Macro dialog, creating an empty macro for the current document as:

   Sub repl()
   '
   ' repl Makro
   ' Makro erstellt am 09.06.03 ...
   '

   End Sub

and by pasting the code of the macro generated by References between Sub macroname() and End Sub. Make the macro available to the current document and run (execute) the macro91. It is highly recommended to run the macro on a copy of the original manuscript file (to be used only for the final printing).

The following steps are necessary to create a macro for Microsoft Word generating numeric citations referring to a list with the references in the same order as they appear in the text:


   Sub repl()
   '
   ' repl Makro
   ' Makro erstellt am 09.06.03 ...
   '
    Selection.HomeKey Unit:=wdStory
    Selection.Find.ClearFormatting
    Selection.Find.Replacement.ClearFormatting
    With Selection.Find
        .Text = "refscite(i03544)"
        .Replacement.Text = "[1]"
        .Forward = True
        .Wrap = wdFindContinue
        .Format = False
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = False
        .MatchSoundsLike = False
        .MatchAllWordForms = False
    End With
    Selection.Find.Execute Replace:=wdReplaceAll
    Selection.HomeKey Unit:=wdStory
    Selection.Find.ClearFormatting
    Selection.Find.Replacement.ClearFormatting
    With Selection.Find
        .Text = "refscite(i04159)"
        .Replacement.Text = "[2]"
        .Forward = True
        .Wrap = wdFindContinue
        .Format = False
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = False
        .MatchSoundsLike = False
        .MatchAllWordForms = False
    End With
    Selection.Find.Execute Replace:=wdReplaceAll
   End Sub
Figure 31: Macro to process citations in Microsoft Word documents, this fragment replaces refscite(i03544) by [1] and refscite(i04159) by [2].

7.2.4  How to process manuscripts with citations in author-date-format with a, b, c … appended to the year of publication

If editors of scientific journals require manuscripts in author-date format it is often necessary to add `a', `b' …to the year if manuscripts (cited in the manuscript) of the same first author appeared in the same year.

7.2.4.1  Manual method
  1. To make alphabetical sorting of the bbt-file possible add autor names and years of publication with main-b ay, sort with main-b s2, convert bbt file into text format with main-b bt. Edit tbt-file with the text editor: change year to yeara …where necessary, convert this file back to a bbt file with main-b tb.
  2. Generate the list if references. In order to change the list of references automatically, use a search and replace script (section 4.10.3). Therefore enter the complete reference as text to be searched and the modified95 reference as text to be replaced.
  3. Generate the macro text file in the format:
    ///A///refscite(i06875.ua)///B///(Petz and Garratty, 2004)///C///
    ///A///refscite(i06875.tr)///B///(Petz and Garratty, 2004)///C///
    
    Change the macro appropriately, e. g.
    ///A///refscite(i06875.ua)///B///(Petz and Garratty, 2004a)///C///
    ///A///refscite(i06875.tr)///B///(Petz and Garratty, 2004b)///C///
    

    This can be done automatically with a search and replace script. The “raw” macro can then be converted to its final form (e. g. by one of the options of the edit-main-p menu).

7.2.4.2  Automatic method

Create format definitions which produce lists of references and macro text files with year numbers written “YYYY___reference-number___” instead of “YYYY”. Using search and replace either remove “___reference-number___” or replace it by “a”, “b” and following characters if appropriate.

In detail, the following steps must be taken:

  1. Write or select a format definition for the list of references which produces YYYY___reference-number___ (instead of only issuing the year of publication)
  2. Write or select a format definition for the macro which formats citations in the manuscript text with YYYY___reference-number___ (instead of the year of publication only)
  3. Write a search and replace script to replace “YYYY___reference-number___” by “a”, “b” where necessary
  4. Remove the remaining YYYY___reference-number___s. A search and replace script doing this can be found in the archive remove-refno.zip96
  5. Process the list of references and the macro which formats citations in the manuscript text with scripts 3. and 4.

7.2.5  How to generate superscripted numerical references in a manuscript

Many journals require superscripted numerical references in their manuscripts. The following procedure applies to OpenOffice.org/StarOffice writer. The procedure for Microsoft Word is described in the last paragraph of this section. It is assumed that superscripted numerical citations follow full stop or comma:

  …for a review see Miller.1, 4

To generate such superscripted references you may enter the “raw” citations as

 …for a review see Miller.///refscite(i03211), refscite(i03200)///

Then convert the refscite()s into numbers (without brackets using the CITATION-NUM-2 MFD macro format definition):

 …for a review see Miller.///1, 4///

and then change the format from normal to “superscript” using the OpenOffice.org/StarOffice writer search and replace function. Enter “///[^/]*///” into the “search for” field, and “&97 into the “replace by” field, change the format in the “replace by” from normal to superscript (or “high” position), check the box for regular expressions, and select “replace all”98. This produces:

 …for a review see Miller.///1, 4///

You may then remove the ///-delimiters with a search and replace operation (search “///” and replace it by an empty string):

 …for a review see Miller.1, 4

and obtain the desired result. Instead of “///” you may use any other string with characters which have no special meaning in OpenOffice.org/StarOffice's regular expressions and which do not appear in the normal text. The strings “///” only have the function to label those strings to be superscripted.

A similar solution can be found for Microsoft Word, regular expressions are called “Platzhalterzeichen” (“wildcards”) in the German version used by the progam author99.

7.2.6  How to generate grouped numerical references in brackets in a manuscript

Reference numbers in square brackets are quite common. The following procedure applies to OpenOffice.org/StarOffice writer (You should have read section 7.2.5 before). It is assumed that numerical citations precede full stop or comma:

  …for a review see Miller [1, 4].

To generate these references you may enter the “raw” citations as

 …for a review see Miller ///refscite(i03211), refscite(i03200)///.

Then convert the refscite()s into numbers (without brackets using the CITATION-NUM-2 MFD macro format definition):

 …for a review see Miller ///1, 4///.

and then change insert the brackets using the OpenOffice.org/StarOffice writer search and replace function. Enter “///[^/]*///” into the “search for” field, and “[&]” into the “replace by” field, check the box for regular expressions. This generates

 …for a review see Miller [///1, 4///].

You may then sort and compress the lists of numerical citations as described in section 7.2.7 and remove the “///” strings.

7.2.7  How to sort and compress lists of numerical citations in a manuscript

If references are cited within the manuscript numerically, lists of citations may occur like2, 5, 3, 1, 20, 6 or like [2, 5, 3, 1, 20, 6]. Here it is often required to sort the reference numbers in ascending order and to compress consecutive numbers as in1−3, 5−6, 20 or [1-3, 5-6, 20]100. References supports automatic conversions of unsorted lists of citations to sorted and compressed lists with the text processor in the following way:

  1. Write the raw citations numbers between pairs of three slashes:

    [///refscite(001233), refscite(25666), refscite(23699) ... ///]

    or (for superscripted lists of references without square brackets:)

    ///refscite(001233), refscite(25666), refscite(23699) ... ///

  2. Format these raw references as described in section 7.2.2 or 7.2.3 using the CITATION-NUM-2 MFD macro format definition:

    [///2, 5, 3, 1, 20, 6///]

    or

    ///2, 5, 3, 1, 20, 6///

    the latter list may be converted to superscripted text as described in section 7.2.5:

    ///2, 5, 3, 1, 20, 6///

  3. Copy the manuscript as pure text file into the text editor (using the clipboard of the operating system) and save it in the database text directory using a file name with extension “.txt”.
  4. Process this text file with edit-main-p snc. This generates a raw macro (in a file named numgr.txt as default) containing lines like

    ///A///2, 5, 3, 1, 20, 6///B///1-3, 5-6, 20///C///

    which may be converted to a macro for OpenOffice.org/StarOffice with edit-main-p osw or for Microsoft Word with edit-main-p wdm. Copy the macro code into the macro text editor in the text processor and run the macro. This will result in compressed lists of numeric citations:

    ///1−3, 5−6, 20///

    The slashes (///) can be removed with the appropriate text processor search and replace command.

7.3  Process manuscripts with reference numbers missing in the database

You may wish to include references in your manuscript, which are missing in your database. If you include them with refscite(MissingRefNo) lists of references will show them as --MissingRefNo--, macro files as ==MissingRefNo==. Before using the list of references or macro file replace --MissingRefNo--, ==MissingRefNo== by the final content using a sr-script (cf. section 4.10.3).

7.4  Make sorted lists of references

Instructions for authors often require that lists of references are sorted in alphabetical order of authors' (or editors') names. This task is most easily completed with the following sequence of actions.

  1. Extract all reference numbers from the manuscript into a bbt-file (e. g. with main-t xr)
  2. Delete all duplicate references (e. g. main-b rs)
  3. Write authors' names (and date of publication) into the text field of records in the bbt-file with main-b ay
  4. Sort the bbt-file according to the text field (main-b s2)
  5. Write the list of references (main-l ...)

A better (but a little more complicated) alternative uses the sortrefs-script:

  1. Extract all reference numbers from the manuscript into a bbt-file (e. g. with main-t xr)
  2. Delete all duplicate references (e. g. main-b rs)
  3. Compile a macro text file through main-l m with the macro format definition (MFD) MFD SORT-01. For the name of the output text file confirm macro.txt101.
  4. Make a tbt-file with sorted items with edit-main-p srt or call sortrefs at the command line, this generates the tbt-file with sorted items (sorted.tbt).
  5. Convert the tbt-file into a bbt-file (main-b tb).

Sorting order in this case (macro definition MFD SORT-01) is due to three keys:

  1. name of first author
  2. first name of first author
  3. year of publication

By writing other macro definitions you may create macros for the sortrefs script for any sorting order conceivable with three fields. Fields must be separated by a “*” as in102:

   i03784*Brunner-Bollinger*S*1997
   i03819*Santoso*S*1998
   i04082*Kroll*H*1998
   i04097*Kiefel*V*2000*

First field (no preceding *!) must contain the reference number, the following fields the 1st, 2nd and 3rd key used for sorting.

7.5  Replace references in a database

If you import data from an arr-file into a database, only those records are imported, which are not already in the database, existing records are not overwritten. If you wish to update a database with newer versions of references, then you will have to delete the records in the database first. All this is done in these steps:

  1. copy the arr-file into the database (text) directory, e. g. c:\refs42\data,
  2. extract the reference numbers from the arr-file with the exarr-script: the command at the OS-prompt
       exarr tutorial
    
    writes the reference numbers into ex_arr.tbt, alternatively you can use the command edit-main-p exa,
  3. convert the tbt-file into a bbt-file,
  4. delete the records in this file with main-f d,
  5. import the arr-file.

7.6  Backup of References databases

A backup of a References database may prepared with an archiving program, such as zip. For example, to make a backup of a the tutorial database of the standard installation, you should include directory c:\refs42\tutorial and the c:\refs42\tutorial\rdb subdirectory into the archive. The archiving program should preserve subdirectories.

For the sake of safety, you should also write all your complete databases into arr-files, details of this procedure are described in (section 4.10.1). Bibliographic format definitions and macro format definitions should be exported into an fd-file.

7.7  Eliminate duplicate or multiplicate records in a database

With a growing database, the chance that references have been entered twice at different positions in the database increase. In these cases it will be of interest, to identify all records, which appear more than once in the database.

  1. Make a bbt-file with reference numbers of all database records with menu-b ba (enter a name for bbt-file, e. g. all).
  2. Write unique record identifiers into the text field of all.bbt with menu-b ui i
  3. Convert bbt-file with menu-b ed: this makes a new file all.bbt which only contain the reference numbers of records, which appear more often than once in the database.
  4. Make a list of references from this bbt-file all.bbt (which now does no more contain all records) with main-l s [enter name for text file] [select file all.bbt], 6 (this selects a special text file format, bibliographic references from this file can directly be copied into a bbt-file).

7.8  Convert bibliographic references from Medline-format

A good alternative to manual typing in of bibliographic references is automatic conversion of data downloaded from publicly accessible databases, e. g PubMed103. The procedure is described in detail in section 4.10.4.

8  Configuration file

Some features of References are determined by variables accessible to the user in the configuration file. The configuration file (refs.cfg ) can be opened with the command main-f c. Default values of variables values may be modified by assigning new values. As an example, the default name of the text file (“form”) for entering bibliographic references is in_form.txt. If you wish enter.txt as the new name for this purpose, enter the line

INPUT_FORM=enter.txt 

into the configuration file104. A valid file name should be entered (Chapter 9.2). If you enter # the rest of the line is ignored, i. e. the line

# INPUT_FORM=enter.txt 

has no effect. The line

PROMPT=-->

changes the appearance of the command line prompt within References from default “: ” to “-->”. You may wish to use another text editor, e. g. win32pad.exe together with References. This can be done by entering the line

TEXT_EDITOR=win32pad.exe

in the configuration file, if the directory which contains win32pad.exe has been added to the PATH environment variable. If not, you may also enter an absolute path as

TEXT_EDITOR=c:\editors\win32pad.exe

A complete list of configuration file variables can be found in table 4.


VariableDescription, default values
LINES_OF_SCREENnumber of lines of screen, possible values range from 24 to 60, default 25, for Linux 24
PROMPTCommand line prompt (within References), default “”, enter a string, the string must not include a “=” or a “#
OPEN_EDITOR_YNprompt for loading text file of interest in text editor (value: 1, default) or do not prompt (value: 0), the value “1” makes References more “interactive” by calling a menu: open editor with “name-of-text-file”? [y/n], value “0” sets user interface to that of previous versions
FORM_LABELstring which introduces field names in the text file for entering text file for entering bibliographic records, default “----
INPUT_FORMname of text file for entering bibliographic records default in_form.txt
JOURN_FORMname of text file for entering journal names, default jn_form.txt
KEYW_FORMname of text file for entering keywords, default ky_form.txt
SEARCH_FORMname of text file for search commands, default sr_form.txt
TEMP_TEXTname of temporary text file for viewing bibliographic records, before saving, lists of keywords, journal data, default temp.txt
TEXT_EDITORtext editor called for editing forms and other text files, default notepad, for Linux vim
TEXTFILE_ENCODING(Linux only) encoding of text files, possible values: utf-8, latin-1, latin-9, ISO-8859 (for latin-1 or latin-2), default: utf-8
AWKlocalization of the AWK executable file (used by etext) default: c:\refs43\bin\awk.exe, default for Linux: awk
PATH_TO_SCRIPTSdirectory, where etext finds the AWK-scripts, default: c:\refs43\bin\, default for Linux: ~/refs43/bin/
PDF_VIEWERcomplete path of PDF-file viewer, default: empty string, for Linux: xpdf
USES_LESSLinux only: if you add USES_LESS=1 to the configuration file, then References uses less instead of the internal text viewing function for showing text
LESS_OPTIONSLinux only: this variable may be used to enter command line options/parameters for less, if less is uses (i .e., if the configuation file contains USES_LESS)
ENABLE_HLLinux only: 0 (default): no highlighting of menu options in square brackets, 1: bold, 2: magenta, 3: blue, 4: cyan, 5: yellow, 6: red, 7: inverted
HELP_FILEname (with complete path) of help file default ..\doc\refsdok.pdf, for Linux: ~/refs43/doc/refsdok.pdf
Table 4: Variables in configuration file refs.cfg (win32), .refscfg (Linux). Paths in a Linux installation: replace “~/” by your home directory: “/home/username/” where username is to be replaced by the appropriate string

9  Miscellaneous

9.1  Document types processed by References

Document types supported in the current References version are listed in table 5. The basic document types in scientific writing are those coded j1, b1 and b2, these documents are usually written by personal authors. Sometimes, however, publications are issued by organizations, groups of institutions, or groups of investigators [1, p. 657]. For such cases, the name of the organization may be entered (tables 5, 6). Such organizations will be referred to in this manual as institutional authors or institutional editors. Document types with institutional authors may also be used if no authors are present105.


CodeDocument type
j1article in a journal with personal author(s)
b1complete book with personal editor(s)
b2article in a book with personal editor(s) and personal author(s)
j2article in a journal with institutional author(s) or without authors
b3complete book with (or without) institutional editor(s)
m1miscellanea with personal author(s)
m2miscellanea with institutional author(s) or without author(s)
Table 5: Document types, j1, b1, b2 are basic document types for publications issued by personal authors or editors, m1, m2 may be used, if no other document types fit


Document typeAuthor(s)Editor(s)
j1p
j2i
b1p
b2pp
b3i
m1p
m2i
Table 6: Document types with personal (p), institutional (i) authors or editors

9.2  Valid file names

References makes restrictions to file names, which are more `severe' than the operating system allows. If you use References under Windows or Linux, the program will accept the letters

AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz1234567890_-.

in their filenames. References allows a filename length of 72 characters. The names `.', `..', `...', etc. are not accepted as valid file names, but a file name under Windows/Linux may contain more than one full-stop. References will not accept file names with spaces. Accented letters and `Umlaut'-characters will not be accepted. On Linux systems, small and capital letters are distinguished.

9.3  Log files

Many actions of References are written into log-files. The main log file is refs.log. As References appends new text to the file, the size of this log file will grow, you should therefore delete (parts of it) it from time to time! The functions main-t sr106 main-f v107 create their own log files (srchrepl.log and verify.log). As these functions overwrite the previous version of the log file, it is not necessary to delete them manually.

9.4  References and character sets (encoding)

9.4.1  References on win32 systems

On computers with Win32 systems, accented characters (À, Á, Â) or characters like German “Umlaut” characters (e.g. Ä) are assingned different numerical codes in the environment of a graphical Windows interface and in a text based console application. Win32 graphical user interfaces (GUIs) use latin-1 (identical with ISO/IEC 8859-1 character encoding)108 and the normal console may use codepage 850. On a win32 system, References assumes that a graphical text editor (like notepad) saves text file in latin-1 encoding and that the console shows and reads text in cp850 encoding109. Internally, text is represented and saved into database files in latin-1 encoding. This means that References has to translate text from latin-1 to cp850 when it prints text to the screen and that References converts text from cp850 to latin-1 when it reads text you type at the References prompt. No conversion is required beween text files and the database files. A thorough discussion of this issue may be found elsewhere [18].

Before you import .arr- and .fd-files from earlier versions to a v4.3 installation you have to translate encoding from cp850 to latin-1, use the program cp850-to-latin1.exe in the bin subdirectory for this task.

9.4.2  References on Linux systems

After installation on a Linux system References internally stores text in latin-1 (ISO/IEC 8859-1) encoding. It assumes that the console and the text editor uses utf-8 encoding. Thus the program converts between latin-1 and utf-8 encoding when you when it prints text to the screen and converts back from utf-8 to latin-1 encoding when it gets input from the console.110

On Linux systems with utf-8 encoding of text files, References writes text files in latin-1 encoding to disk, and converts these files to utf-8 encoding when you call the text editor with a text file from etext or refs43 (what you should always do when you use References in Linux).

On Linux systems with latin-1 encoding of text files the radmin-tool will write the line

   TEXTFILE_ENCODING=ISO-8859

into the configuration file (cf. table 4). You may enter this line also by hand into the configuration file instead of ISO-8859 you may also enter latin-1. The same line in the configuration file can be used for systems configured for latin-9 (ISO-4459-15) encoding: there are only small differences between latin-1 and latin-9 so in these Linux installations will be stored in latin-9 encoding in the References database files.

Before you import .arr- and .fd- files from earlier versions to a v4.3 installation you have to translate encoding from cp850 to latin-1, use the program bin/cp850-to-latin1 for this task. If the .arr file comes from a win32 installation of References, you will have to change newline (line break) character sequence from the win32/DOS operating system specific cr-lf (carriage return-linefeed) type to the Linux/UNIX-specific lf (linefeed). Therefore you may use the dos2unix tool of your Linux system. On a win32 system, you may use the small tofrodos package111. For more information on the newline problem see [19]. Linux comes with an extremely powerful tool to translate encoding of text files, recode.

10  Error messages and warnings

10.1  Data entry

Data entry with the input form (default name in_form.txt) should not be difficult. Sometimes, you may obtain an error message like

   [menu]: ir

   (Reading record)

   Problem: abstract not closed with `----END-OF-RECORD' in C:\refs43\in_form.txt

   (Record not stored)

if you try to import a record. One possible reason for this error message is that your abstract text contains ----... beginning in the first column (e. g. used to underline the head of a table). Solutions (1) indent the line112 containing ----, (2) if this problem happens often with your data, change the FORM_LABEL (default ----) variable in the configuration file113.

10.2  Problems with refsrun.$

After starting References, you may encounter the message

   (Warning: one copy of `References' still running
     or previous session terminated irregularly)

due to one of these reasons:

  1. You started a second instance of References while the first was still running.
  2. Your system crashed while an instance of References was running.
  3. Linux: You closed the console window without stopping References regularly

Technical background: Each time References is launched, it writes a small text file named `refsrun.$' into the database text files directory. If it already exists, References shows you the warning above. If `refsrun.$' does not yet exist, it is written and removed as soon as the program is finished regularly.114

Solution: If the file refsrun.$ remained due to an earlier crash, you may select start in the following menu. If you tried to open another instance of the software, select q.

10.3  Problems with Emacs on Linux systems

Users of References on Linux may encounter the following problem: while editing a text file in the text file directory with Emacs, References will stop irregularly if the user attempts to select a file (cf. section 3.1, file selection screen figure 3). Apparently Emacs generates irregular directory entries which cannot be handled properly by References' routine for reading directories. At present, this problem, which seems to be related to the implementation of the readdir()-function of the C-library, cannot be fixed.

10.4  Damaged database files

If, upon starting References, the program stops and the message

   At least one database file damaged

appears, this indicates, that at least one “binary” file with one of the extensions dat, ix or bbt has been damaged. Solution: the safest method is to delete the database and rebuild a new one from an arr-files, if one has been made as “backup”115.

10.5  References fails to write to database, index or bbt-files

If References issues the message

   Failure to write to binary file, for information see documentation

   Please press [ENTER] to stop References

References fails to write binary data into database files (.dat), index files (.ix) or bbt-files. One reason may be that not enough disk space is available. If this message appears, References will stop. After this critical situation, database and index files will be inconsistent, you will therefore have to rebuild a database from an .arr-file. It is strongly recommended to make regular backups (as .arr-files) (see section 4.10.1).

10.6  Problems with batch files (win32)

If you did not assign sufficient memory to the OS “environment” a call to tutorial or sortrefs or any other batch-file116 will generate117 the message:

   Kein Speicherplatz mehr im Umgebungsbereich

You may solve this by assigning more environment memory to a command prompt window.

11  Installation on Win32

References requires a text editor. For those users who do not wish to use notepad on win32-systems, alternatives are described in section 3.2. The text editor has to be installed separately.

11.1  Installation from exe-files

The program archive can be installed from the r43d.exe executable file118. The default configuration requires that References is installed in the c:\refs43-directory (folder). The following steps are required:

  1. Create the directory “c:\refs43” (e.g. using the Windows Explorer)
  2. According to the Windows version, add the item “c:\refs43;” to the PATH environment variable of the AUTOEXEC.BAT file (see description in section 11.2) or to the path entry of “environment” in the system dialog,
  3. Call the r43d.exe-installer (e. g. from the Windows explorer). Within the installer,
    1. change the target directory to c:\refs43 using the Browse-button (if necessary),
    2. extract the contents of the installer with the Extract-button and
    3. close the installer with Done
  4. You may then add links to the desktop or the start menu from the batch files tutorial.bat, e-tutorial.dat, data.bat and e-data.bat
  5. Restart the computer to make the changed PATH environment variable active.

Installation of References in another directory is described in section 11.6.

11.2  Installation from zip-files

Experienced users will be able install the program from the r43d.zip file. To begin installation of References, open a command prompt, make c the actual drive, create the directory c:\refs43 and change into this directory:

   md c:\refs43
   cd c:\refs43

Copy the file r43d.zip into this directory and unzip it119. The file refs-4.3d-src.tar.gz contains the source-code for the program and the documentation (LATEX-files) and is not required for use of this software.

   unzip r43d.zip

Make the batch files in “c:\refs43” accessible from other directories e. g. by adding this directory name to the PATH variable according to the Window version either in the AUTOEXEC.BAT configuration file or to the PATH entry of “environment” in the system dialog.

   ...;c:\refs43

After restarting the computer, opening a command line, a call to tutorial should start references as shown in figure 32, to leave References, enter q [Enter] yes [Enter].


(Checking size of database files)
(Checking size of bbt-files)

MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3 -- [e/l/b/s/d/t/f/i/q]

[menu]:
Figure 32: Screen after calling References

Transfer of data from References v3.6, v4.0, v4.0a, v4.0b, v4.0c v4.0d, v4.1 or v4.2 can be done through .arr-files and .fd-files. As the encoding of the internal representation changed from “cp850” to “latin-1” and as .arr- and .fd-files have the same encoding as the References' internal encoding you have to convert the encoding of these files with the cp850-to-latin1 command line program in the bin subdirectory.

   c:\refs43\bin\cp850-to-latin1 olddata.arr

You must not apply this command more than once on an .arr- or a .fd-file! For details on different encoding schemes in References see section 9.4.

11.3  Removal of References

If you wish to remove the References-installation, you will only have to delete the c:\refs43-directory tree (and to remove links made manually to the .bat-files).

11.4  Directory tree

The default directory structure of References is depicted in fig 33. An installation into another directory requires that all path entries in the batch (command) files are adjusted.


   c:\refs43
      |
      +--doc
      |
      +--bin
      |
      +--data
      |  |
      |  +--rdb
      |
      +--tutorial
         |
         +--rdb
Figure 33: Directory tree

The directory c:\refs43\doc contains the documentation of the software including in PDF. The refs43.exe executable file and AWK-scripts are located in the bin-directory. Databases have the general path \refs43\data and \refs43\data\rdb. The rdb subdirectory will contain the `binary' (database and index) files. The path \refs43\data will be referred to as database text files directory in this manual and \refs43\data\rdb as database binary files directory or database rdb subdirectory.

11.5  Create a new database

To create a new database, start the Radmin-tool. You will see the following screen with the main menu (figure 34):


Radmin.exe -- tool for administration of References Bibliographic Software

Current directory (folder) is:
   `C:/refs43'
Executable files directory (folder) is:
   `C:/refs43/bin'

Radmin menu -- [p/n/q] -- [Enter] shows menu options

[menu]:

[p] check/correct path entries
[n] create a new References database
[a] about Radmin
[q] quit

[menu]:
Figure 34: Radmin main menu


Select n, enter the name of the new database, e. g. mdata and press [Enter]. You will see the following message:

   Database name: mdata
   
   Please press [ENTER] to continue:
   
     `C:/refs43/mdata' created
     `C:/refs43/mdata/rdb' created
     `mdata.bat' written
     `e-mdata.bat' written
   
   To complete installation of the new database
     1. Create database and index files
     2. Import minimal database
   as described in the documentation
   
   Radmin menu -- [p/n/q] -- [Enter] shows menu options
   
   [menu]:

You may then quit Radmin with q. Radmin has created the subdirectories mdata and mdata/rdb and the starting batch/script files mdata.bat and e-mdata.bat. The following must be done to complete the installation:

  1. Start References with the command mdata.
  2. Create a set of empty database and index files with main-f r c. Go back to the main menu with q q.
  3. Import the dbase1.arr-file (copy this file from the data subdirectory to the mdata directory) with main-t im.

  4. Import a set of bibliographic format definitions from a fd-file or from fde-files

11.6  Installation of References in another than the default directory/drive

After unzipping the r43d.zip archive or the r43d.exe installer to a directory different from the default (c:\refs43)120 start the Radmin tool. Therefore, make the directory which contains Radmin.bat the current working directory121. Select p from the Radmin-menu122, at the next prompt:

   Database names:

enter the existing databases, for the default installation this should be:

   Database names: data tutorial

Database names should be separated by spaces. The following message:

   Database names: data tutorial
     `data.bat' written
     `e-data.bat' written
     `tutorial.bat' written
     `e-tutorial.bat' written

confirms that the starting batch/script files have been updated.

11.7  Building References executable files

The executable file of the References version for Windows has been compiled with the “MinGW”-Implementation of the gcc-compiler123. You will file the source code in the refs-4.3d-src.tar.gz archive, to uncompress it see section 12. For building the Windows-version with the gcc124 you may use the enclosed Makefile. First open the Makefile with your text editor and find the following two lines:

   ### -- Please select your compiling environment: uncomment the items below
   ###    according to the appropriate computing environment

In the following lines the definitions for compilation of win32 have to be uncommented and the definitions for Linux have to be commented out125:

   ### -- BEGIN: select between Linux and win32
   
   ## Linux with GCC, utf-8 encoded text
   # CFLAGS=-c -Wall -DREFS_USES_LINUXGCC
   # REFSEXE := refs43
   # ETEXTEXE := etext
   # RADMINEXE := radmin
   # CP850_TO_LATIN1EXE := cp850-to-latin1
   
   ## Win32 with MinGW compiler
   CFLAGS=-c -Wall -DREFS_USES_MINGW
   REFSEXE := refs43.exe
   ETEXTEXE := etext.exe
   RADMINEXE := radmin.exe
   CP850_TO_LATIN1EXE := cp850-to-latin1.exe
   
   ### -- END: select between Linux and win32

Save the Makefile126, close the text editor and type:

   make all 

which ensures that refs43.exe, etext.exe, cp850-to-latin1.exe and radmin.exe are built.

12  Installation on Linux systems

12.1  Installation on Linux systems of precompiled binary files (32 bit)

This section describes a “local” installation (i. e. an installation in the user's home directory) of References on a Linux system.

All required “runtime” files (including the document you are currently reading) can be found in

   refs-4.3d-rt.tar.gz

A set of binary 32 bit files for Linux systems (i386 processor architecture) is made available in the

   refs-4.3d-i386.tar.gz

archive. These two tarballs are required for the installation.

As an alternative, users are recommended to build the binary files on their target system from the sourcecode. This is also necessary, if the binary files fail to run on your system. The Linux distribution of References provides the source code of in the

  refs-4.3d-src.tar.gz

archive. Details of building/compiling the binary files are described in section 12.2.

The steps to install References on a Linux system:

  1. Please change to your home directory and unpack the refs-4.3d-rt.tar.gz tarball:
       gzip -d refs-4.3d-rt.tar.gz
       tar -xvf refs-4.3d-rt.tar
    

    This creates the ~/refs43- subdirectory tree (figure 35).


        ~/refs43
          |
          +--doc
          |
          +--bin
          |
          +--data
          |  |
          |  +--rdb
          |
          +--tutorial
             |
             +--rdb
    
    Figure 35: Directory tree on Linux systems

  2. In the home directory, unpack the tarball
       gzip -d refs-4.3d-i386.tar.gz
       tar xvf refs-4.3d-i386.tar
    
  3. Change to the refs43 directory, and run the radmin program:
       bin/radmin
    

    You will first be asked for information on the text file encoding of your Linux installation (figure 36). If you are uncertain about this issue, stop radmin and type locale from the shell. You will obtain output like

    LANG=de_DE.UTF-8
    LC_CTYPE="de_DE.UTF-8"
    LC_NUMERIC="de_DE.UTF-8"
    LC_TIME="de_DE.UTF-8"
    LC_COLLATE="de_DE.UTF-8"
    LC_MONETARY="de_DE.UTF-8"
    ...
    

    In this case, a Linux installalation uses utf-8 encoding for text files.127 You can then restart radmin and select option 1 in the menu of figure 36.


    Please enter text file encoding on your Linux system [1/2/q]
    
    [menu]:
    
    [1] utf-8
    [2] latin-1 (ISO-8859-1) or latin-9 (ISO-8859-15)
    [q] quit
    
    [menu]:
    
    Figure 36: Select text file encoding after installation of References on Linux systems

    Then, type Enter to see the main menu of this tool. Select p, this updates or creates the configuration file ~/.refscfg and inserts information on the correct text file encoding into the configuration file, then enter the names of the database directories data tutorial128, this writes new versions of the starting script files data.sh, e-data.sh, tutorial.sh, e-tutorial.sh. You may then quit radmin with q. For ease of use make these script files executable

      chmod a+x data.sh e-data.sh tutorial.sh e-tutorial.sh
    

    and copy them into a directory included in the list assigned to the PATH variable. This may require on some systems that you login as “root129. You may then start References by typing data.sh from your shell.

Now, you have completed the installation of References. References requires a text editor. On Linux systems, the default text editor is vim, this may be changed in the configuration file.

12.2  Building the binary (executable) files of References

Installation of References is described in the previous section. You may, however compile the binary files from the sourcecode in the refs-4.3d-src.tar.gz file and copy the to the ~/refs43/bin-directory. In order to compile the References binaries, tools gcc, make must be available on your system. In the Ubuntu distribution and its variants, you will first have to install the development tools with the build-essential package:

   sudo apt-get install build-essential

In a console window, uncompress the file in a temporary directory as usual, e. g.:

   gzip -d refs-4.3d-src.tar.gz
   tar -xvf refs-4.3d-src.tar

Change into the src subdirectory and open the file Makefile with your text editor and find the following two lines:

   ### -- Please select your compiling environment: uncomment the items below
   ###    according to the appropriate computing environment

In the next lines the definitions for compilation of Linux have to be uncommented and the definitions for win32 have to be commented out (normally this is the default):

   ### -- BEGIN: select between Linux and win32
   
   ## Linux with GCC, utf-8 encoded text
   CFLAGS=-c -Wall -DREFS_USES_LINUXGCC
   REFSEXE := refs43
   ETEXTEXE := etext
   RADMINEXE := radmin
   CP850_TO_LATIN1EXE := cp850-to-latin1
   
   ## Win32 with MinGW compiler
   # CFLAGS=-c -Wall -DREFS_USES_MINGW
   # REFSEXE := refs43.exe
   # ETEXTEXE := etext.exe
   # RADMINEXE := radmin.exe
   # CP850_TO_LATIN1EXE := cp850-to-latin1.exe
   
   ### -- END: select between Linux and win32

Save the Makefile130, close the text editor and type:

   make all 

The binary files can then be found in the refs43/bin/ subdirectory. Please copy them (refs43, etext, radmin, cp850-to-latin1) into the directory ~/refs43/bin/.

12.3  Building the data and tutorial databases

Please read first the description of the References user interface (section 3.1). Start the data database with data.sh at the Linux console prompt, select main-f r c. This creates an empty set of index and database files, then return to the main menu with q q. Import the data with main-t im, press [Enter] and enter the number before data.arr (this will most probably be “1”). You will then be asked, if you wish to delete the archive file, it is recommended to select n. Selection of q brings you back to the main menu.

To import the bibliographic format definitions, select main-d im y, type [Enter] and select the number before data.fd (most probably “1”). Selection of q brings you back to the main menu.

12.4  Transfer of databases from earlier (win32) versions of References

Before importing text files from win32-versions into References for Linux, the line terminators have to be changed from the DOS/Win32 format (CRLF) to LF (Unix/Linux) This can be done with the dos2unix-program available on Linux systems. A win32 version is available as part of the gnuwin32-project131 in the cygutils package132.

Transfer of text files from databases created with versions earlier than 4.3 of References requires that their enoding is changed to latin-1. Please convert the .arr- and .fd-files with the command cp850-to-latin1 in the bin-subdirectory. Please avoid the Unix/Linux recode-command for arr-files133. If you have doubt on the encoding (and if the text contains accented characters and/or Umlaut characters) you may analyse the file with the Unix/Linux command:

   file filename

The file tool also indicates if the “line terminators” are of the CRLF type (DOS, win32) or LF (Linux, UNIX). You definitely should convert text files to LF-format before the Linux version of References uses them.

12.5  Creating new databases, installation in another than the default directory

To create a new database you may use the radmin tool as described in section 11.5. To call radmin, change into the References directory and type

   bin/radmin

To create a References installation in another than the default directory134 follow the instructions in section 11.6. First change into the References directory and type bin/radmin.

12.6  A brief introduction to the nano text editor

On Linux systems, nano is perhaps the most simple text editor, which is appropriate for use with References. The help page may be accessed with Ctrl-g and left wit Ctrl-x. However documentation is not well structured, therefore, important commands may be found in table 7.


OperationCommand
Online helpCtrl-g
File operations
Finish nanoCtrl-x
Save current fileCtrl-o
Mark, copy, delete, manipulate text
Mark textCtrl-^or M-a
Copy marked text into clipboardM-^or M-6
Cut marked text and copy marked text into the clipboardCtrl-k
Paste text from clipboard into current bufferCtrl-u
Reformat pararaphCtrl-j
Reformat complete fileM-j
Toggle: wrap long linesM-l
Toggle: convert tabs into spacesM-q
Indent marked textM-}
Unindent marked textM-{
Toggle autoindent modeM-i
Navigate in/between files
Jump to the beginning of the fileM-\
Jump to the end of the fileM-/
With more than one file opened: change to next buffer/fileM->
With more than one file opened: change to previous buffer/fileM-<
Jump to corresponding bracketM-]
Search/findCtrl-w or F6
Repeat last search/findM-w
Scroll up without moving the cursorM--
Scroll down without moving the cursorM-+
Important command line options
Show a list of command line options-h (--help)
Adjust tabsize to `n' columns-T n (--tabsize=n)
Wrap lines at columns `n'-r n (--fill=n)
Do not wrap long lines at any length, overrides any value for `-r'-w (--nowrap)
Enable autoindent mode-i (--autoindent)
Convert typed tabs to spaces-E (--tabstospaces)
Enable smooth scrolling-S (--smooth)
User interface
Toggle: show line, column, character numberM-c
Toggle: intelligent “Pos 1”/“Home” keyM-h
Table 7: Important nano commands. `M' denotes the meta-key: M-q: on a PC keybord press Esc and then q or press Alt and q simultaneously.


13  Tutorial

13.1  Start and leave References, view database records

Open a command-line prompt, change into the directory c:\refs43. Enter tutorial (or tutorial.bat). The main menu appears:

   (Checking size of database files)
   (Checking size of bbt-files)

   MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3 -- [e/l/b/s/d/t/f/i/q]

   [menu]:

To view the options of the main menu, press [Enter]135:

   [e] enter, edit, view
   [l] compile lists of references etc.
   [b] process batch files
   [s] search references by keywords, authors, title etc.
   [d] bibliographic/macro format definitions
   [t] text files, export/import from/into database
   [f] file, database and system functions
   [i] information about References v4.3
   [q] quit, return to the OS

   [menu]:

To see some records of the tutorial-database select the “enter, edit, view” option with e [Enter]136:

   [menu]: e

   Menu: enter, edit, view [j1 ... m2/ir/er/fj/ij/ej/lj/fk/ik/lk/ed/c/b/s/q]
   
   [menu]:

Have a look at the menu options with an empty string or menu:

   [j1] create empty form for j1-type bibliographic record,
        more: [j2], [b1], [b2], [b3], [m1], [m2]
        [ir] import bibliographic record/reference (from form to database),
        [er] export/edit bibliographic record/reference (write to form)
   [fj] create empty form for journal data (name, short form ISSN)
        [ij] import journal data (from form to database),
        [ej] export/edit journal data (write to form),
        [lj] list journal data
   [fk] create empty form for keywords (to be transferred to the thesaurus),
        [ik] import keywords (from form to thesaurus),
        [lk] list keywords
   [ed] edit text files
   [ c] browse complete database
   [ b] browse database records by BBT-file
   [ s] browse records by BBT-file from last search
   [ q] back to main menu
   
   [menu]:

To see the complete database, select c:

   Menu: browse complete database [f/l/n/p/c/k/#/i/s/a/q]

   [000000000001] *ARTICLE IN A JOURNAL* Author1 FN, Author2 FN: Titel of an
   article in a journal. New England Journal of Medicine (ISSN: 0028-4793)
   1996; 334: 1-12. KEYWORDS: journal article.

   [menu]:

Have a look at the menu options (menu), go to the last record with l:

   [0000021] *BOOK* Daniels G: editor(s). Human blood groups. Blackwell Science:
   Oxford, 1995. KEYWORDS: blood groups, erythrocyte blood group antigens.
   (STATUS=y)

   [l]:

As you can see, the last selected option goes into the menu brackets as default, if a menu is used repeatedly. Go back one record with p:

   [0000020] *BOOK* Spriet A, Dupin-Spriet T, Simon P: editor(s). Methodology of
   clinical drug trials. (2. ed) Basel, Freiburg, Paris, London, New York, New
   Delhi, Bangkok, Singapore, Tokyo, Sydney: Karger, 1994. KEYWORDS:
   statistical methods, clinical trial, randomised controlled clinical trial,
   randomized prospective trial, methodology. (STATUS=y)

   [p]:

Quit the menu “browse complete database” with q:

   Menu: enter, edit, view [j1 ... m2/ir/er/fj/ij/ej/lj/fk/ik/lk/c/b/s/q]

   [menu]:

go back to the main menu with q:

   MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3

   [menu]:

quit References with q:

   MAIN MENU -- REFERENCES BIBLIOGRAPHIC SOFTWARE V4.3

   [menu]:

(optional): view the menu:

   [yes] yes, quit References
   [ no] no, continue to run References

   [menu]:

confirm the command to quit with yes, this brings you back to the command line of the operating system137.

13.2  Search bibliographic records

Search commands are entered into a text file with default name sr_fun.txt138. The search command itself has to be written into the first line, the name of the bbt-file, into which References shall write the reference numbers found139 may be written into the second line140. As a first example, you may wish to see all records in the References database with the item “blood” in the keywords-field.

Therefore you should load the search text file with main-t ed s into the text editor and write the following two lines into the text file141, save the file and close the text editor:

   keyw=blood
   bloodres

Then return to the main menu with q q and enter main-s c s. After the last menu selection, References will issue the message:

   (0 seconds required)
   
   (File `C:\refs43\tutorial\rdb\bloodres.bbt' with 3 records)
   
   Menu: browse database records of bbt-file [f/l/n/p/c/k/#/i/s/a/q]
   
   [0000014] *BOOK* Baldwin ML, Jefferies LC: editor(s). Irradiation of blood
   components. (1. ed) Bethesda: American Association of blood banks, 1992.
   KEYWORDS: irradiation of blood components, TA-GvHR. (STATUS=y)
   
   [menu]:

Select f to see the first record (of the three records found), if another than the first record is shown142:

   [menu]: f

   [0000014] *BOOK* Baldwin ML, Jefferies LC: editor(s). Irradiation of blood
   components. (1. ed) Bethesda: American Association of blood banks, 1992.
   KEYWORDS: irradiation of blood components, TA-GvHR. (STATUS=y)

   [f]:
   

the next two records appear with n n:

   [f]: n

   [0000019] *BOOK* Colman RW, Hirsh J, Marder VJ, Salzman EW: editor(s).
   Hemostasis and thrombosis. Basic principles and clinical practice. (2. ed)
   Philadelphia: J. B. Lippincott, 1987. KEYWORDS: hemostasis, thombosis, blood
   coagulation. (STATUS=y)

   [n]:

   [0000021] *BOOK* Daniels G: editor(s). Human blood groups. Blackwell Science:
   Oxford, 1995. KEYWORDS: blood groups, erythrocyte blood group antigens.
   (STATUS=y)

   [n]:

13.3  Make a list of references in standard format

A list based on the reference numbers in the file bloodres.bbt shall be written into a text file:

This produces the list:

   [1] Baldwin ML, Jefferies LC. Irradiation of blood components. 1. ed.
   Bethesda: American Association of blood banks, 1992.

   [2] Colman RW, Hirsh J, Marder VJ, Salzman EW. Hemostasis and thrombosis.
   Basic principles and clinical practice. 2. ed. Philadelphia: J. B.
   Lippincott, 1987.

   [3] Daniels G. Human blood groups. Blackwell Science: Oxford, 1995.

13.4  Make a list of references in user-defined format

A list based on the reference numbers in the file bloodres.bbt shall be written into a text file. The list shall have the format for the journal “Deutsche Medizinische Wochenschrift” Select main-l u [enter name for the output file, secdlis] [select number assigned to bloodres.bbt] f [look up the number assigned to the format definition for the “Deutsche Medizinische Wochenschrift” journal] q [enter the number assigned to the format definition for the “Deutsche Medizinische Wochenschrift” journal] 1 1. This produces the list:

   [1] Baldwin, M. L., L. C. Jefferies: Irradiation of blood components, 1.
   ed. (American Association of blood banks: Bethesda 1992).

   [2] Colman, R. W., J. Hirsh, V. J. Marder, E. W. Salzman: Hemostasis and
   thrombosis. Basic principles and clinical practice, 2. ed. (J. B.
   Lippincott: Philadelphia 1987).

   [3] Daniels, G.: Human blood groups (Oxford: Blackwell Science 1995).

13.5  Enter a new reference

Please enter the reference, it is of the j1 (article in a journal) document type:

   Walter RB, Hong TC, Bachli EB: Life-threatening thrombocytopenia associated
   with acute Epstein-Barr virus infection in an older adult. Annals of
   Hematology 2002; 81:672-675

First make an empty text file form for an “article in a journal” (j1) with main-e j1 enter the reference number: 0000022. References issues the message

   [menu]: j1

   New reference number (preferrably higher than 0000021): 0000022

   (Empty form for `j1' written into `in_form.txt')

   Menu: enter, edit, view [j1 ... m2/ir/er/fj/ij/ej/lj/fk/ik/lk/c/b/s/q]

   [menu]:

One of the things you will have to know for entering a j1 bibliographic reference is the code of the journal name. You can look it up from references with main-e lj enter Annals as substring (to look up Annals of Haematology) f brings you to the first page of this list, as you call see, annh is the code for this journal. Close References or change into the text editor shell-window, open this text file with the editor edit-main-r:

   ----REFERENCE-NUMBER-[width:12]
   0000022
   ----DOCUMENT-TYPE-[width:2]
   j1
   ----AUTHORS-[width:26,6]

   ----TITLE-ARTICLE-[width:255w]

   ----JOURNAL-[width:4]

   ----DATE-YEAR-[width:4;num]

   ----DATE-MONTH-[width:2;num:1..12]

   ----DATE-DAY-[width:2;num:1..31]

   ----VOLUME-[width:20]

   ----ISSUE-NUMBER-[width:8]

   ----FIRST-PAGE-[width:10]

   ----LAST-PAGE-[width:10]

   ----STATUS-[width:12]

   ----KEYWORDS-[width:75]

   ----K-NUMBER-[width:12]

   ----ABSTRACT-[width:30600w]

   ----END-OF-RECORD

Now you can enter the information about this reference

   ----REFERENCE-NUMBER-[width:12]
   0000022
   ----DOCUMENT-TYPE-[width:2]
   j1
   ----AUTHORS-[width:26,6]
   Walter,RB
   Hong,TC
   Bachli,EB
   ----TITLE-ARTICLE-[width:255w]
   Life-threatening thrombocytopenia associated with acute Epstein-Barr 
   virus infection in an older adult.
   ----JOURNAL-[width:4]
   annh
   ----DATE-YEAR-[width:4;num]
   2002
   ----DATE-MONTH-[width:2;num:1..12]

   ----DATE-DAY-[width:2;num:1..31]

   ----VOLUME-[width:20]
   81
   ----ISSUE-NUMBER-[width:8]

   ----FIRST-PAGE-[width:10]
   672
   ----LAST-PAGE-[width:10]
   675
   ----STATUS-[width:12]

   ----KEYWORDS-[width:75]
   thrombocytopenia
   Epstein-Barr-virus
   ----K-NUMBER-[width:12]

   ----ABSTRACT-[width:30600w]

   ----END-OF-RECORD

If you have completed, save the text file, go back to the References window and save this reference: main-e ir, look at the data read from the input form, go to the first page f. If everything is o.k., close the view text file function with q, confirm with y that you do wish to save this record.

13.6  Create a bibliographic format definition

First select a reference (of j1 document type) in the tutorial database for testing: open the tutorial database, browse towards the article with the key 0000005145, save the reference number with s quit with q and save the reference number under the name make-fde (References will prompt you for this name).

Create an empty fde-file with main-d mf, References prompts you for the name, enter samp, this step creates the empty format definition form samp.fde. Development of a format defintion is done in the following cycle of actions:

  1. Open the file samp.fde with main-t ed m (select the file with the assigned number)
  2. make the necessary changes with the text editor, save samp.fde
  3. produce a list of references (using samp.fde), therefore:
    1. select main-l tu
    2. confirm “reflist” as output file name
    3. select the number assigned to make-fde.bbt
    4. select the number assigned to samp.fde
    5. select 1 as reference number format
    6. confirm 1 as starting number
    7. References will then show the message (Textfile C:\refs43\tutorial\reflist.txt written)
  4. Open reflist.txt with main-t ed m. At this point only [1] has been written to reflist.txt. Now, please begin with step 1. of the cycle.

Please make yourself practically acquainted with this “cycle”. In the following explanations, progress in the samp.fde-file and the will be related to the resulting reflist.txt-file.

13.6.1  The first steps

First we will try to get the title. Change of

   --
   -- major elements (lines) for document type `journal article' (j1):
   -- sequence of list of authors (%au), title (%ti), localization (%lo)
   --
   -- width: 3
   --
   j1 string 1 ''
   j1 string 2 ''
   j1 string 3 ''

in samp.fde to

   --
   -- major elements (lines) for document type `journal article' (j1):
   -- sequence of list of authors (%au), title (%ti), localization (%lo)
   --
   -- width: 3
   --
   j1 string 1 '%ti'
   j1 string 2 ''
   j1 string 3 ''

results in

   [1] 

(reflist.txt), i. e. nothing of the title is printed, with the additional change of

   j1 title 0 ''

in samp.fde to

   j1 title 0 '%title'

you will see

   [1] The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is
   expressed by cultured endothelial cells

(reflist.txt)146.

Again change of

   j1 string 1 '%ti'
   j1 string 2 ''

in samp.fde to

   j1 string 1 '%ti'
   j1 string 2 '%au'

results in

   [1] The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is
   expressed by cultured endothelial cells

i. e. nothing of the authors line is printed into reflist.txt. Only if you complete

   j1 authors 0 ''

in samp.fde to

   j1 authors 0 '%auth'

this will append something like an unformatted list of authors:

   [1] The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is
   expressed by cultured endothelial cellsGiltayBrinkmanVlekkeKiefelvan Mourikvon
   dem Borne

(reflist.txt). To reverse the sequence of title and list of authors, change

   j1 string 1 '%ti'
   j1 string 2 '%au'

in samp.fde to

   j1 string 1 '%au'
   j1 string 2 '%ti'

This results in

   [1] GiltayBrinkmanVlekkeKiefelvan Mourikvon dem BorneThe platelet glycoprotein
   Ia-IIa-associated Br-alloantigen system is expressed by cultured endothelial
   cells

(reflist.txt). Formatting the list of authors will be done later.

13.6.2  Summary – first steps

Entries of format definition data are made in the format (between the s):

   document type field name 'contents of the field'

Format definition data may occcur in any sequence in the fde-file. Comments are usually of the form147:

   --
   -- major elements (lines) for document type `book' (b1):
   -- sequence of list of editors (%ed), book-title (%bo), localization (%lo)
   --
   -- width: 3
   --

The keywords %ti, %au and %so148 at the beginning of the format desfinition file (samp.fde)

   j1 string 1 '%ti'
   j1 string 2 '%au'
   j1 string 3 ''

do not enter anything, but they determine the sequence of the title and list of authors lines which are entered and formatted later.

13.6.3  Adding punctuation marks to title and authors lines

To append a full stop to the title line, change

   j1 title 0 '%title'
   j1 title 1 ''

in samp.fde to

   j1 title 0 '%title'
   j1 title 1 '.'

which results in

   [1] GiltayBrinkmanVlekkeKiefelvan Mourikvon dem BorneThe platelet
   glycoprotein Ia-IIa-associated Br-alloantigen system is expressed by
   cultured endothelial cells.

(reflist.txt). As you can see, a full-stop is added to the title. You may imagine that is useful that a function only adds a full-stop, if the title line does not end with a `.', `!' or `?'. In in this context it is more appropriate to write149:

   j1 title 0 '%title'
   j1 title 1 '%fullstop'

To append `: ' to the list of authors, change

   j1 authors 0 '%auth'
   j1 authors 1 ''

in samp.fde to

   j1 authors 0 '%auth'
   j1 authors 1 ': '

which results in

   [1] GiltayBrinkmanVlekkeKiefelvan Mourikvon dem Borne: The platelet
   glycoprotein Ia-IIa-associated Br-alloantigen system is expressed by
   cultured endothelial cells.

(reflist.txt).

13.6.4  Formatting the list of authors or editors (author line)

In this section, the list of authors shall be formatted like `A. B. FirstAuthor, C. SecondAuthor and Z. LastAuthor'. Therfore, change

   j1 authors string type ''

in samp.fde to

  j1 authors string type '2'

which results in

   [1] JCGiltayHJMBrinkmanAVlekkeVKiefelJAvan MourikAEGKvon dem Borne: The
   platelet glycoprotein Ia-IIa-associated Br-alloantigen system is expressed
   by cultured endothelial cells.

(reflist.txt). As you can see, first names are now inserted, but without spaces and punctuation marks150 Further formatting requires definition of delimiters and short strings described in figure 23 and its legend.

Change of

   j1 delimiter ^1 in authors string ''

in samp.fde to

   j1 delimiter ^1 in authors string ', '

results in

   [1] JCGiltay, HJMBrinkman, AVlekke, VKiefel, JAvan MourikAEGKvon dem Borne:
   The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is
   expressed by cultured endothelial cells.

(reflist.txt). To insert “ and ” between the last two names, change

   j1 delimiter ^2 in authors string ''

in samp.fde to

  j1 delimiter ^2 in authors string ' and '

which results in

   [1] JCGiltay, HJMBrinkman, AVlekke, VKiefel, JAvan Mourik and AEGKvon dem
   Borne: The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is
   expressed by cultured endothelial cells.

(reflist.txt). Now “. ” will be inserted between the first names, therefore, please change

   j1 delimiter ^3 in authors string ''

in samp.fde to

   j1 delimiter ^3 in authors string '. '

which results in

   [1] J. C.Giltay, H. J. M.Brinkman, A.Vlekke, V.Kiefel, J. A.van Mourik and
   A. E. G. K.von dem Borne: The platelet glycoprotein Ia-IIa-associated
   Br-alloantigen system is expressed by cultured endothelial cells.

(reflist.txt). As you can see, the trailing space after the last first name (the last forename) is removed, this allows you to insert a space151 between forenames and names explicitly. Therefore you will have to change

   j1 delimiter ^4 in authors string ''

in samp.fde to

   j1 delimiter ^4 in authors string ' '

which results in

   [1] J. C. Giltay, H. J. M. Brinkman, A. Vlekke, V. Kiefel, J. A. van Mourik
   and A. E. G. K. von dem Borne: The platelet glycoprotein Ia-IIa-associated
   Br-alloantigen system is expressed by cultured endothelial cells.

(reflist.txt).

13.6.5  Create the localization line

With the explanations of this section, you will finish the format definition for the article in a journal (j1) document type. The localization line for articles in a journal shall have the format: “abbreviated journal name year;volume:first page–last page”.

Therefore, change

   j1 title 0 '%title'
   j1 title 1 '%fullstop'
   j1 title 2 ''

in samp.fde to

   j1 title 0 '%title'
   j1 title 1 '%fullstop'
   j1 title 2 '%space'

which appends a space to the title line. For the localization line, change

   j1 string 3 ''

to

   j1 string 3 '%lo'

to make the following change from

   j1 localization 0 ''
   j1 localization 1 ''
   j1 localization 2 ''
   j1 localization 3 ''
   j1 localization 4 ''
   j1 localization 5 ''
   j1 localization 6 ''
   j1 localization 7 ''
   j1 localization 8 ''
   j1 localization 9 ''

in samp.fde to

   j1 localization 0 '%journsh'
   j1 localization 1 '%space'
   j1 localization 2 '%year'
   j1 localization 3 ';'
   j1 localization 4 '%volume'
   j1 localization 5 ':'
   j1 localization 6 '%pagefrom'
   j1 localization 7 '%pgs(-)'
   j1 localization 8 '%pagetosh'
   j1 localization 9 '.'

visible. This results in

   [1] J. C. Giltay, H. J. M. Brinkman, A. Vlekke, V. Kiefel, J. A. van Mourik
   and A. E. G. K. von dem Borne: The platelet glycoprotein Ia-IIa-associated
   Br-alloantigen system is expressed by cultured endothelial cells. Br J
   Haematol 1990;75:557-60.

(reflist.txt). This is a simple format definition of the j1 document type, you will then have to write similar descriptions for the other document types. To learn more about writing format definitions, you should read format definitions provided with References and you should “play” with copies of format definitions, i. e., you should modify them and study the results. For writing format definitions, it is generally recommended to write first the j1, b1 and b2 format definitions. All the other format definitions can be derived.

14  Appendix

14.1  Search command syntax

Search in a References can directed to “database fields” with field labels (table 8). The command main-s searches for a condition, in most cases, a substring contained in the text of that field. The general syntax for a search command is:

   FLBL=condition [|condition [|...]] & FLBL [|condition [|...]] & [&...]

LabelDescription
auth autor(s) of an article in a journal/periodial (j1), of an article/chapter in a book (b2)
inau institutional autor(s) (j2, m2)
edit Editor(s)/author(s) of a book
edtn edition number of a book (b1, b2, b3)
idnr identification numbers
ined institutional editor(s) of book (b3)
dtyp Document type, supported in current version: j1, j2, b1, b2, b3, m1, m2
jrnl journal name (journal code/key)
keyw keywords
plac place of publication
publ publisher (of a book)
stat status field
tita title of an article in a periodical in a journal/periodical of a chapter in a book
titb title of a book
volj volume of a journal (j1, j2)
year year of the date of publication
Table 8: Field labels for search commands. Use of field labels is case insensitive

A search command may comprise more than one condition linked with `&' (logical or `boolean' AND). Each `&'-clause may contain one or more text fragments to be searched for separated by `|' (`|' is interpreted in search commands as logical or `boolean' OR). Each `&'-clause is introduced by a field label (FLBL) which restricts the search to a database field (e.g title, keywords, date of publication). The field label is followed by a `=' and the string(s separated by `|'s) to be searched for.

A simple example for a search command is:

   keyw=anemia

it means: “find all records with the keywords anemia”, leading and trailing spaces are automatically removed, this format is also valid:

   keyw = anemia

The command

   keyw = anemia & dtyp = j1

means: “find all references with `anemia' in the keywords field, but only those which are of the article in a journal (j1) type.”

   keyw = anemia | red cell | platelets & dtyp = j1

means: “find journal articles (j1) with `anemia' or `red cell' or `platelets' in the keywords field”

   keyw = anemia | red cell | platelets & dtyp = j1 & year = 1980 - 1994

means: “find all journal articles with `anemia' or `red cell' or `platelets' in the keywords field, which appeared in the time between 1980 and 1994”.

   auth=Mueller | Keller | Mayer | Guenter & keyw = platelets & 
   dtyp=j1 | b2 & year=1973 | 1980-1994 |1996 | 1998
   &tita=platelet |rbc | granuloc | neutrophil & tita=review

This command should be written in one line, it means: “find all journal articles and all book chapters with the keyword `platelets', with authors `Mueller', `Keller', `Mayer' or `Guenter', which appeared in 1973 or between 1980 and 1994 or in 1996 or 1998. In the title of the article the text fragments `platelet' or `rbc' or `granuloc' or `neutrophil' must appear, the title must contain the string `review'.” This is not a typical example, but illustrates that complex search operations may be performed on a References database.

Some special cases have to be regarded with certain field labels: normally, References `finds' a record, if the substring entered in the search-command is found in the pertinent field of the database. For example:

   KEYW = antib

finds the references with the keywords `alloantiodies', `anti-phospholipid-antibodies' or `antibody-induced phagocytosis'. In some fields, there are exceptions:

  1. Field labels `JRNL', `EDTN' and `VOLJ': here References searches for identity of the string in the search command and the contents of the `Journal'-field:
       jrnl=n
    
    only finds `n', but not `nejm'.
  2. Field label `YEAR': References translates the text in the `year'-field into a number and tries to `understand' ranges of years:
       year = 1990-1992
    
    is equivalent to
       year = 1990 | 1991 | 1992
    
    the first format (1990-1992) however, will be processed faster.
  3. Field labels `AUTH', `EDIT': searches only for the name, initials are ignored.

If you apply search-commands on large databases, the time required for their execution will be influenced by the sequence in which the `&'-clauses appear. The following rule applies: You should insert those conditions, which reduce the size of the resulting bbt-file most, as the first `&'-clauses into the search command.

If you do not wish to search the complete database, you may restrict a search operation to a set of references defined in a bbt-file (select command b instead of c) after starting search.

14.2  Bibliographic format definitions

14.2.1  Bibliographic format definition form

    1    BIBLIOGRAPHIC STYLE FORMAT DEFINITION -- REFERENCES 4.3
    2    
    3    --
    4    -- short name (key) of format definition
    5    --
    6    -- width: 20
    7    --
    8    format definition ''
    9    
   10    --
   11    -- description of bibliographic format definition
   12    --
   13    -- width 255
   14    --
   15    description ''
   16    
   17    --
   18    -- major elements (lines) for document type `journal article' (j1):
   19    -- sequence of list of authors (%au), title (%ti), localization (%lo)
   20    --
   21    -- width: 3
   22    --
   23    j1 string 1 ''
   24    j1 string 2 ''
   25    j1 string 3 ''
   26    
   27    --
   28    -- major elements (lines) for document type `journal article' with
   29    -- institutional author (j2): sequence of author (%au), title (%ti),
   30    -- localization (%lo)
   31    --
   32    -- width: 3
   33    --
   34    j2 string 1 ''
   35    j2 string 2 ''
   36    j2 string 3 ''
   37    
   38    --
   39    -- major elements (lines) for document type `book' (b1):
   40    -- sequence of list of editors (%ed), book-title (%bo), localization (%lo)
   41    --
   42    -- width: 3
   43    --
   44    b1 string 1 ''
   45    b1 string 2 ''
   46    b1 string 3 ''
   47    
   48    --
   49    -- major elements (lines) for document type `chapter/article in a book' (b2):
   50    -- sequence of list of authors (%au), book-title (%bo), title of article (%ti)
   51    -- list of editors (%ed), localization (%lo)
   52    --
   53    -- width: 3
   54    --
   55    b2 string 1 ''
   56    b2 string 2 ''
   57    b2 string 3 ''
   58    b2 string 4 ''
   59    b2 string 5 ''
   60    
   61    --
   62    -- major elements (lines) for document type `book' with institutional
   63    -- editor (b3): sequence of editor (%ed), book-title (%bo),
   64    -- localization (%lo)
   65    --
   66    -- width: 3
   67    --
   68    b3 string 1 ''
   69    b3 string 2 ''
   70    b3 string 3 ''
   71    
   72    --
   73    -- major elements (lines) for document type `miscellanea' (m1):
   74    -- sequence of list of authors (%au), title (%ti), localization (%lo)
   75    --
   76    -- width: 3
   77    --
   78    m1 string 1 ''
   79    m1 string 2 ''
   80    m1 string 3 ''
   81    
   82    --
   83    -- major elements (lines) for document type `miscellanea' with institutional
   84    -- author (m2): sequence of list of authors (%au), title (%ti),
   85    -- localization (%lo)
   86    --
   87    -- width: 3
   88    --
   89    m2 string 1 ''
   90    m2 string 2 ''
   91    m2 string 3 ''
   92    
   93    --
   94    -- list of authors line (journal article)
   95    --
   96    -- width: 24
   97    --
   98    j1 authors 0 ''
         ...
  105    j1 authors 7 ''
  106    
  107    --
  108    -- title line (journal article)
  109    --
  110    -- width: 24
  111    --
  112    j1 title 0 ''
         ...
  121    j1 title 9 ''
  122    
  123    --
  124    -- localization line (journal article)
  125    --
  126    -- width: 24
  127    --
  128    j1 localization 0 ''
         ...
  167    j1 localization 39 ''
  168    
  169    --
  170    -- author line (journal article with institutional author)
  171    --
  172    -- width: 24
  173    --
  174    j2 authors 0 ''
         ...
  181    j2 authors 7 ''
  182    
  183    --
  184    -- title line (journal article with institutional author)
  185    --
  186    -- width: 24
  187    --
  188    j2 title 0 ''
         ...
  197    j2 title 9 ''
  198    
  199    --
  200    -- localization line (journal article with institutional author)
  201    --
  202    -- width: 24
  203    --
  204    j2 localization 0 ''
         ...
  243    j2 localization 39 ''
  244    
  245    --
  246    -- list of editors line (book)
  247    --
  248    -- width: 24
  249    --
  250    b1 editors 0 ''
         ...
  257    b1 editors 7 ''
  258    
  259    --
  260    -- title line (book)
  261    --
  262    -- width: 24
  263    --
  264    b1 book-title 0 ''
         ...
  273    b1 book-title 9 ''
  274    
  275    --
  276    -- localization line (book)
  277    --
  278    -- width: 24
  279    --
  280    b1 localization 0 ''
         ...
  319    b1 localization 39 ''
  320    
  321    --
  322    -- list of authors line (chapter/article in a book)
  323    --
  324    -- width: 24
  325    --
  326    b2 authors 0 ''
         ...
  333    b2 authors 7 ''
  334    
  335    --
  336    -- title line (chapter/article in a book)
  337    --
  338    -- width: 24
  339    --
  340    b2 title 0 ''
         ...
  349    b2 title 9 ''
  350    
  351    --
  352    -- list of editors line (chapter/article in a book)
  353    --
  354    -- width: 24
  355    --
  356    b2 editors 0 ''
         ...
  363    b2 editors 7 ''
  364    
  365    --
  366    -- book title line (chapter/article in a book)
  367    --
  368    -- width: 24
  369    --
  370    b2 book-title 0 ''
         ...
  379    b2 book-title 9 ''
  380    
  381    --
  382    -- localization line (chapter/article in a book)
  383    --
  384    -- width: 24
  385    --
  386    b2 localization 0 ''
         ...
  445    b2 localization 59 ''
  446    
  447    --
  448    -- editor line (book with institutional editor)
  449    --
  450    -- width: 24
  451    --
  452    b3 editors 0 ''
         ...
  459    b3 editors 7 ''
  460    
  461    --
  462    -- title line (book with institutional editor)
  463    --
  464    -- width: 24
  465    --
  466    b3 book-title 0 ''
         ...
  475    b3 book-title 9 ''
  476    
  477    --
  478    -- localization line (book with institutional editor)
  479    --
  480    -- width: 24
  481    --
  482    b3 localization 0 ''
         ...
  521    b3 localization 39 ''
  522    
  523    --
  524    -- list of authors line (miscellanea)
  525    --
  526    -- width: 24
  527    --
  528    m1 authors 0 ''
         ...
  535    m1 authors 7 ''
  536    
  537    --
  538    -- title line (miscellanea)
  539    --
  540    -- width: 24
  541    --
  542    m1 title 0 ''
         ...
  551    m1 title 9 ''
  552    
  553    --
  554    -- localization line (miscellanea)
  555    --
  556    -- width: 24
  557    --
  558    m1 localization 0 ''
         ...
  597    m1 localization 39 ''
  598    
  599    --
  600    -- list of authors line (miscellanea with institutional author)
  601    --
  602    -- width: 24
  603    --
  604    m2 authors 0 ''
         ...
  611    m2 authors 7 ''
  612    
  613    --
  614    -- title line (miscellanea with institutional author)
  615    --
  616    -- width: 24
  617    --
  618    m2 title 0 ''
         ...
  627    m2 title 9 ''
  628    
  629    --
  630    -- localization line (miscellanea with institutional author)
  631    --
  632    -- width: 24
  633    --
  634    m2 localization 0 ''
         ...
  673    m2 localization 39 ''
  674    
  675    --
  676    -- list of authors/editors lines (j1, b1, b2, m1)
  677    --
  678    -- sequence of first names and names type (0, 1, 2 or 3)
  679    --
  680    -- width: 1
  681    --
  682    j1 authors string type ''
  683    b1 editors string type ''
  684    b2 authors string type ''
  685    b2 editors string type ''
  686    m1 authors string type ''
  687    
  688    --
  689    -- list of authors/editors lines (j1, b1, b2, m1)
  690    --
  691    -- delimiter (1) between authors'/editors' names
  692    --
  693    -- width: 24
  694    --
  695    j1 delimiter ^1 in authors string ''
  696    b1 delimiter ^1 in editors string ''
  697    b2 delimiter ^1 in authors string ''
  698    b2 delimiter ^1 in editors string ''
  699    m1 delimiter ^1 in authors string ''
  700    
  701    --
  702    -- list of authors/editors lines (j1, b1, b2, m1)
  703    --
  704    -- delimiter (2) between last two authors'/editors' names
  705    --
  706    -- width: 24
  707    --
  708    j1 delimiter ^2 in authors string ''
  709    b1 delimiter ^2 in editors string ''
  710    b2 delimiter ^2 in authors string ''
  711    b2 delimiter ^2 in editors string ''
  712    m1 delimiter ^2 in authors string ''
  713    
  714    --
  715    -- list of authors/editors lines (j1, b1, b2, m1)
  716    --
  717    -- delimiter (3) after first name
  718    --
  719    -- width: 24
  720    --
  721    j1 delimiter ^3 in authors string ''
  722    b1 delimiter ^3 in editors string ''
  723    b2 delimiter ^3 in authors string ''
  724    b2 delimiter ^3 in editors string ''
  725    m1 delimiter ^3 in authors string ''
  726    
  727    --
  728    -- list of authors/editors lines (j1, b1, b2, m1)
  729    --
  730    -- delimiter (4) between first name (forename) and name
  731    --
  732    -- width: 24
  733    --
  734    j1 delimiter ^4 in authors string ''
  735    b1 delimiter ^4 in editors string ''
  736    b2 delimiter ^4 in authors string ''
  737    b2 delimiter ^4 in editors string ''
  738    m1 delimiter ^4 in authors string ''
  739    
  740    --
  741    -- list of authors/editors lines (j1, b1, b2, m1)
  742    --
  743    -- delimiter (5) between name and first name (forename)
  744    --
  745    -- width: 24
  746    --
  747    j1 delimiter ^5 in authors string ''
  748    b1 delimiter ^5 in editors string ''
  749    b2 delimiter ^5 in authors string ''
  750    b2 delimiter ^5 in editors string ''
  751    m1 delimiter ^5 in authors string ''
  752    
  753    --
  754    -- list of authors/editors lines (j1, b1, b2, m1)
  755    --
  756    -- delimiter (6) after last name in list
  757    --
  758    -- width: 24
  759    --
  760    j1 delimiter ^6 in authors string ''
  761    b1 delimiter ^6 in editors string ''
  762    b2 delimiter ^6 in authors string ''
  763    b2 delimiter ^6 in editors string ''
  764    m1 delimiter ^6 in authors string ''
  765    
  766    --
  767    -- list of authors/editors lines (j1, b1, b2, m1)
  768    --
  769    -- text indicating more authors/editors (e. g. `et al.')
  770    --
  771    -- width: 24
  772    --
  773    j1 delimiter more names in authors string ''
  774    b1 delimiter more names in editors string ''
  775    b2 delimiter more names in authors string ''
  776    b2 delimiter more names in editors string ''
  777    m1 delimiter more names in authors string ''
  778    
  779    --
  780    -- list of authors/editors lines (j1, b1, b2, m1)
  781    --
  782    -- maximal number of authors/editors printed (n: 1-999)
  783    --
  784    -- width: 3
  785    --
  786    j1 n in authors string ''
  787    b1 n in editors string ''
  788    b2 n in authors string ''
  789    b2 n in editors string ''
  790    m1 n in authors string ''
  791    
  792    --
  793    -- list of authors/editors lines (j1, b1, b2, m1)
  794    --
  795    -- number of authors/editors printed (m: 1-999), if number of authors/editors
  796    -- is greater than n
  797    --
  798    -- width: 3
  799    --
  800    j1 m in authors string ''
  801    b1 m in editors string ''
  802    b2 m in authors string ''
  803    b2 m in editors string ''
  804    m1 m in authors string ''
  805    
  806    END OF BIBLIOGRAPHIC STYLE FORMAT DEFINITION

14.2.2  Keywords of bibliographic format definitions


keyworddescription
 
sequence of major elements (lines)
%auindicates the position of the authors' names line (in the major elements (lines) for document type ... fields at the beginning of the format definition)
%ed editors of a book (or authors of a complete book)
%ti title of article
%bo book title
%lo `localization' data: journal name, volume, range of pages, publisher, place of publication
keywords for the remaining fields
%() inserts the delimiters (strings) of the argument in brackets into lists of authors or editors (only in the list of authors/editors lines (j1, b1, b2)-fields for delimiters)
%Auflage inserts the German word “Auflage” (edition [e. g. of a book]) if the field for the edition number is not empty
%auth controls position of authors' [personal or institutional] names (of article in journal, article/chapter in a book)
%day inserts day number (of date of publication)
%d() inserts the argument in brackets, if the field for `day' is not empty
%e() inserts the argument in brackets, if the field for edition number is not empty
%ededs inserts the word `editor', if the number of authors/editors is one, otherwise inserts `editors'
%Ededs inserts the word `Editor', if the number of authors/editors is one, otherwise inserts `Editors'
%edition inserts the text string `. edition', if the field for the edition number is not empty
%Edition inserts the text string `. Edition', if the field for the edition number is not empty
%edits indicates position of editors'/authors' [personal or institutional] names (of book)
%edno inserts edition number of a book, if this field is not empty
%endline inserts the end-of-line code (character)
%fullstop inserts the `.' character, if the previous character is not one of the following: .,?!;
%howpub inserts the contents of the howpublished-field
%hp() inserts the argument in brackets, if the howpublished-field is not empty
%i[]() inserts the argument in (round) brackets if the identifying number of the type in square brackets exists in the identifying numbers field. Example: %i[url](, ) inserts a comma and a space if a number of the type “url:http//www...” exists in the IDNR (identifying numbers) field
%ibn() inserts the argument in brackets, if the ISBN-field is not empty
%id[] inserts the identifying number of the type in square brackets (if it exists) from the IDNR (identifying numbers) field. Example: %id[doi] inserts 10.1111/j.1365-3148.2005.00578.x, if References finds doi:10.1111/j.1365-3148.2005.00578.x in the IDNR (identifying numbers) field
%idn() inserts the argument in (round) brackets if the IDNR (identifying numbers) field is not empty
%idnr inserts the contents of the IDNR (identifying numbers) field
%ina() inserts the argument in brackets if the `institutional author' field is not empty
%ine() inserts the argument in brackets if the `institutional editor' field is not empty
%inu() inserts the argument in brackets if the `issue number' field is not empty
%isbn international standard book number (ISBN)
%isn() inserts the argument in brackets, if the ISSN-field is not empty
%issn inserts the international serial standard number (ISSN)
%issuenum issue number (of a periodical or journal)
%journ inserts the full journal name
%journkey inserts the “raw” journal code (the `key' for journal records in the database file for journal data) is directly inserted
%journsh inserts the short form (abbreviated form) of the journal name, if the abbreviated form is available in the journal names database, otherwise the full name is entered
%journ4l synonym for %journkey (obsolete)
%js() inserts the short (abbreviated form) of the journal name, if the field for the abbreviated name is not empty in the database, otherwise the program enters the full name. The argument in brackets is inserted between the elements of the abbreviated form. Examples: %js(. ) with the abbreviated journal name Brit J Haematol inserts Brit. J. Haematol into the localization line; %js(-): Brit-J-Haematol
%kwds inserts the list of keywords
%m() inserts the argument in brackets if the field for `month' is not empty
%month inserts the month number (of date of publication)
%n inserts the number of a reference in a list of references
%p() inserts the argument in brackets, if at least first page (or first and last pages) field(s) is/are not empty
%pagefrom inserts the `page from' (first page of a range of pages)
%pageto inserts the `page to' (last page of a range of pages)
%pagetosh inserts significant last figures of `last page' (page to)
%pgs() places the argument in brackets between first and last page of a range of pages
%place inserts the place of publication, in case of a comma-separated list in the %place-field, selects only the first town-name
%places inserts all places of publication
%publisher inserts the name of the publisher, publishing company
%refnr inserts the reference number key
%space enters a space character
%status inserts the contents of the status field
%title inserts title of an article in a journal or title of a chapter/an article in a book
%tab inserts a tab character (→)
%titlebo inserts the book title
%v() inserts the argument in brackets, if the volume field is not empty
%volume inserts volume of a periodical, of a journal
%year inserts the year (of the date of publication)
 

14.2.3  Which keywords in which fields?

References recognizes keywords only if they appear in the appropriate fields. As an example, %auth will not insert the list of authors into the “book title line”, it will be inserted here literally. The following paragraphs list keywords recognized in format definition fields.

14.2.3.1  Major elements (lines) for document type `journal article' (j1)

%au, %ti, %so.

14.2.3.2  Major elements (lines) for document type `journal article with institutional author' (j2)

%au, %ti, %so.

14.2.3.3  Major elements (lines) for document type `book' (b1)

%ed, %bo, %lo.

14.2.3.4  Major elements (lines) for document type `chapter/article in a book' (b2)

%au, %ed, %ti, %bo, %lo.

14.2.3.5  Major elements (lines) for document type `book with institutional editor' (b3)

%ed, %bo, %lo.

14.2.3.6  Major elements (lines) for document type `miscellanea' (m1)

%au, %ti, %so.

14.2.3.7  Major elements (lines) for document type `miscellanea with institutional author' (m2)

%au, %ti, %so.

14.2.3.8  List of authors line (journal article) [j1]

%auth, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %year.

14.2.3.9  Title line (journal article) [j1]

%endline, %fullstop, %i[](), %id[], %idn(), %idnr, %refnr, %n, %tab, %title, %year, %space.

14.2.3.10  Localization line (journal article) [j1]

%d(), %day, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %inu(), %isn(), %issn, %issuenum, %journ, %journ4l, %journsh, %js(), %kwds, %m(), %month, %p(), %pagefrom, %pageto, %pagetosh, %pgs(), %space, %status, %tab, %v(), %volume, %year.

14.2.3.11  Author line (journal article with institutional author) [j2]

%auth, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %ina(), %n, %refnr, %space, %tab, %year.

14.2.3.12  Title line (journal article with institutional author) [j2]

%endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space. %tab, %title, %year,

14.2.3.13  Localization line (journal article with institutional author) [j2]

%d(), %day, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %inu(), %isn(), %issn, %issuenum, %journ, %journ4l, %journsh, %js(), %kwds, %m(), %month, %p(), %pagefrom, %pageto, %pagetosh, %pgs(), %space, %status, %tab, %v(), %volume, %year.

14.2.3.14  List of editors line (book) [b1]

%Ededs, %ededs, %edits, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %year

14.2.3.15  Title line (book) [b1]

%Auflage, %Edition, %e(), %edition, %edno, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %titlebo, %year.

14.2.3.16  Localization line (book) [b1]

%Auflage; %Edition; %e(); %edition; %edno; %endline; %fullstop; %i[](), %ibn(); %id[], %idn(), %idnr, %isbn; %kwds; %p(); %pagefrom; %pageto; %pagetosh; %place; %places; %publisher; %space; %status; %tab, %year.

14.2.3.17  List of authors line (chapter/article in a book) [b2]

%auth, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %year.

14.2.3.18  Title line (chapter/article in a book) [b2]

%endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space. %tab, %title, %year,

14.2.3.19  List of editors line (chapter/article in a book) [b2]

%Ededs, %ededs, %edits, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %year.

14.2.3.20  Book title line (chapter/article in a book) [b2]

%Auflage, %Edition, %e, %edition, %edno, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %titlebo, %year.

14.2.3.21  Localization line (chapter/article in a book) [b2]

%p(), %Auflage, %e(), %edition, %Edition, %edno, %endline, %fullstop, %i[](), %ibn(), %id[], %idn(), %idnr, %isbn, %kwds, %pagefrom, %pageto, %pagetosh, %pgs, %place, %places, %publisher, %space, %status, %tab, %year.

14.2.3.22  List of editors line (book with institutional editor) [b3]

%Ededs, %ededs, %edits, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %ine(), %n, %refnr, %space, %tab, %year.

14.2.3.23  Title line (book with institutional editor) [b3]

%Auflage, %e(), %edno, %edition, %Edition, %endline, %fullstop, %i[](), %id[], %idn(), %idnr, %refnr, %n, %space, %tab, %titlebo, %year.

14.2.3.24  Localization line (book with institutional editor) [b3]

%Auflage, %Edition, %e(), %edition, %edno, %endline, %fullstop, %i[](), %ibn(), %id[], %idn(), %idnr, %isbn, %kwds, %p(), %p(), %pagefrom, %pageto, %pagetosh, %place, %places, %publisher, %space, %status, %tab, %year.

14.2.3.25  List of authors line (miscellanea) [m1]

%auth, %endline, %fullstop, %howpub, %hp(), %i[](), %id[], %idn(), %idnr, %n, %refnr, %space, %tab, %year.

14.2.3.26  Title line (miscellanea) [m1]

%endline, %fullstop, %howpub, %hp(), %i[](), %id[], %idn(), %idnr, %n, %refnr, %space. %tab, %title, %year,

14.2.3.27  Localization line (miscellanea) [m1]

%d(), %day, %endline, %fullstop, %howpub, %hp(), %i[](), %id[], %idn(), %idnr, %kwds, %m(), %month, %p(), %pagefrom, %pageto, %pagetosh, %pgs(), %space, %status, %tab, %year.

14.2.3.28  List of authors line (miscellanea with institutional author) [m2]

%auth, %endline, %fullstop, %howpub, %hp() %i[](), %id[], %idn(), %idnr, %ina() %n, %refnr, %space, %tab, %year.

14.2.3.29  Title line (miscellanea with institutional author) [m2]

%endline, %fullstop, %howpub, %hp(), %i[](), %id[], %idn(), %idnr, %refnr, %n, %title, %year, %space, %tab.

14.2.3.30  Localization line (miscellanea with institutional author) [m2]

%d(), %day, %endline, %fullstop, %howpub, %hp(), %i[](), %id[], %idn(), %idnr, %kwds, %m(), %month, %p(), %pagefrom, %pageto, %pagetosh, %pgs(), %space, %status, %tab, %year.

14.3  Structure of archive files

Archive files contain the contents of a References database in text file format. Archive files allow to

Each archive file contains four major sections:

  1. header with version information152. Current version of References archive format is 1.1 **AV:1.1.
  2. bibliographic references are stored in the section introduced by BEGIN REFERENCES.
  3. journal names and their abbreviated forms are introduced by BEGIN JOURNALS.
  4. the keywords thesaurus is headed by BEGIN KEYWORDS THESAURUS.

The labels (four letters) at the beginning of each line (table 9) correspond to fields in the database.


Field labeldescription
ABSTabstract
AUTHlist of authors of a journal or a book-chapter
DAYPdate of publication: day
DTYPdocument type (j1, j2, b1, b2 or b3)
EDITlist of editors of a book
EDTNedition number
HOWPhowpublished
IDNRidentification numbers
INAUinstitutional author
INEDinstitutional editor
ISBNinternational standard book number
ISNUissue number
JRNLjournal code (index)
KEYWkeywords field of a bibliographic record (keywords separated by “;”s)
MONPdate of publication: month
PGFR“page from”: first page of an article, of a chapter
PGTO“page to”: last page of an article, of a chapter
PLACplace of publication (of a book)
PUBLpublisher (Herausgeber, Éditeur)
RECNrecord number, reference number
STATstatus field
TITAtitle of an article in a book
TITBtitle of a book
VOLMvolume
YEARdate of publication: year
ISSNinternational standard serial number
JCODjournal code
JNAMjournal name
JS01short form (variant 1) of journal name
KEYTitem in keywords thesaurus
Table 9: Field labels in archive files

   1 **AV:1.1
     
     ****:BEGIN ARCHIVE
     
   5 ****:BEGIN REFERENCES
     
     RECN:i05747
     DTYP:b1
     EDIT:Colman,RW;Hirsh,J;Marder,VJ;Clowes,AW;George,JN
  10 TITB:Hemostasis and thrombosis. Basic principles and clinical practice
     EDTN:4
     ISBN:0-7817-1455-9
     PLAC:Philadelphia
     IDNR:
  15 YEAR:2001
     PUBL:Lippincott Williams and Wilkins
     PGFR:
     PGTO:
     STAT:y
  20 KEYW:hemostasis, hemostatic disorders, thrombosis, textbook
     ABST:
     
     RECN:i05840
     DTYP:b2
  25 AUTH:Sebring,ES
     TITA:Fetomaternal hemorrhage -- incidence and methods of detection ...
     EDIT:Garratty,G
     TITB:Hemolytic diasease of the newborn
     EDTN:
  30 ISBN:0-915355-05-1
     PLAC:Arlington
     IDNR:
     YEAR:1984
     PUBL:American Association of Blood Banks
  35 PGFR:87
     PGTO:117
     STAT:y
     KEYW:hemolytic disease of the newborn, fetomaternal hemorrhage, ...
     ABST:
  40 
     RECN:i05862
     DTYP:j1
     AUTH:Gombotz,H;Schatz,E
     TITA:Tolerance of perisurgical anaemia
  45 JRNL:it
     IDNR:
     YEAR:2002
     MONP:6
     DAYP:
  50 VOLM:29
     ISNU:3
     PGFR:163
     PGTO:166
     STAT:y
  55 KEYW:anemia, surgery, transfusion trigger, blood loss, rbc transfusion
     ABST:
     
     ****:END REFERENCES
     
  60 ****:BEGIN JOURNALS
     
     JCOD:aa
     ISSN:
     JNAM:Anesthesia and Analgesia
  65 JS01:Anesth Analg
     
     JCOD:aas
     ISSN:
     JNAM:Acta Anaesthesiologica Scandinavica
  70 JS01:Acta Anaesthesiol Scand
     
     JCOD:ab
     ISSN:
     JNAM:Analytical Biochemistry
  75 JS01:Anal Biochem
     
     JCOD:ach
     ISSN:0001-5792
     JNAM:Acta Haematologica
  80 JS01:Acta Haematol
     
     ...
     
     JCOD:zif
  85 ISSN:
     JNAM:Zeitschrift fuer Immunitaetsforschung
     JS01:
     
     ****:END JOURNALS
  90 
     ****:BEGIN KEYWORDS THESAURUS
     
     KEYT:(111)In
     
  95 KEYT:(14)C serotonin release assay
     
     KEYT:(51)Cr
     
     KEYT:12F1
 100 
     ...
     
     KEYT:zalcitabine
     
 105 KEYT:zidovudine, (AZT)
     
     ****:END KEYWORDS THESAURUS
     
     ****:END ARCHIVE

14.4  Format of BibTEX database files

@incollection{000001,
  editor = {Colman, R. W. and Hirsh, J. and Marder, V. J. and Clowes, A. W. and George, J. N.},
  author = {Kunicki, T. J.},
  booktitle = {{Hemostasis and thrombosis. Basic principles and clinical practice}},
  title = {{Platelet immunology}},
  edition = {4},
  address = {Philadelphia, Baltimore, New York, London, Buenos Aires, Hong Kong, Sydney, Tokyo},
  publisher = {Lippincott Williams and Wilkins},
  pages = {461--477},
  year = {2001}
}


@book{000007,
  editor = {Colman, R. W. and Hirsh, J. and Marder, V. J. and Clowes, A. W. and George, J. N.},
  title = {{Hemostasis and thrombosis. Basic principles and clinical practice}},
  edition = {4},
  address = {Philadelphia},
  publisher = {Lippincott Williams and Wilkins},
  year = {2001}
}


@article{000002,
  author = {Peters, A. M. and Klonizakis, I. and Lavender, J. P. and Lewis, S. M.},
  title = {{Use (111)indium-labelled platelets to measure spleen function}},
  journal = {British Journal of Haematology},
  year = {1980},
  volume = {46},
  pages = {587--593}
}


@misc{000008,
  author = {Ihaka, R. and Gentleman, R.},
  title = {{R statistical software version 1.6.2}},
  howpublished = {Comprehensive R Archive Network. URL http://cran.at.r-project.org},
  year = {2003}
}


14.5  Names of AWK scripts called by the “process text files” menu options

Options of the menu edit-main-p mainly call AWK scripts. Names of the corresponding scripts are listed in table 10. All AWK scripts are located in the bin-subdirectory. In addition to the scripts in table 10 fromcite.awk and tocite.awk have been added to this directory. A short description is included in the commented section of these files153.


Menu option Name of script Description
edit-main-p htm txt2html.awk Converts lists of references/text files into HTML files
edit-main-p ltx txt2ltx.awk Converts lists of references/text files into LATEXfiles
edit-main-p exc excite.awk extracts reference numbers from \cite{} commands in LATEX-documents
edit-main-p xex xexcite.awk Extended excite.awk: reference numbers from \cite{} and related commands in LATEX-documents
edit-main-p srt sortrefs.awk Creates macro for sorting
edit-main-p wdm msw_sr.awk Creates MS Word macro for converting bibliographic citations in a manuscript
edit-main-p osw ooo_sr.awk Creates OpenOffice/StarOffice Writer macro for converting bibliographic citations in a manuscript
edit-main-p vi vi_sr.awk Creates Vi/Vim text editor macro for converting bibliographic citations in a manuscript
edit-main-p msr man_srl.awk Creates a search and replace list for manual change of raw bibliographic citations into formatted citations in a text processor
edit-main-p rsr refs_sr.awk Creates a References search and replace script for formatting bibliographic citations
edit-main-p exa ex_arr.awk Extracts reference numbers from an arr-file
edit-main-p snc group-num-cit.awk Converts list of numeric citations in a manuscript into a sorted, compressed list
(no menu option)fromcite.awk changes \cite{}s into refscite()s in the manuscript
(no menu option)tocite.awk changes refscite()s into \cite{}s in the manuscript
Table 10: AWK-scripts and corresponding commands in References


15  To do

Features planned for future development are listed on the References website http://references.sourceforge.net/development.html.

16  Disclaimer

This software is distributed in the hope that it will be useful for your work, but without any warranty; without even the implied warranty of merchantibility or fitness for a particular purpose. The program author therefore does not assume any liability for any alleged actual damages arising from the use of this software. References may be used under the terms of the GNU general public license, Version 2154.

References

[1]
The Chicago manual of style. Chicago, London, 14 edition, 1993.
[2]
F. Mittelbach and M. Goossens, editors. The LaTeX companion. Addison-Wesley, Boston, 2 edition, 2004.
[3]
P. W. Daly. Natural sciences citation and references. Author-year and numerical schemes. CTAN.
[4]
P. Williams and T. Schnier. The Harvard family of bibliography styles. CTAN.
[5]
H. F. Ebel and C. Bliefert, editors. Schreiben und Publizieren in den Naturwissenschaften. Wiley-VCH, Weinheim, 4 edition, 1998.
[6]
International Committe of Medical Journal Editors. Uniform requirements for manuscripts submitted to biomedical journals. New England Journal of Medicine, 336:309–315, 1997.
[7]
Wikipedia, the free encylopedia. Reference management software. http://en.wikipedia.org/wiki/Bibliographic_Software, accessed August 12, 2007, 2007.
[8]
National Library of Medicine. Recommended formats for bibliographic citation. supplement: Internet formats. http://www.nlm.nih.gov/pubs/formats/internet.pdf, July 2001.
[9]
National Library of Medicine. Entrez-PubMed. http://www.ncbi.nlm.nih.gov/entrez/query.fcgi, 2003.
[10]
References bibliographic software. http://references.sourceforge.net, 2003.
[11]
S. Oualline, editor. Vi IMproved–Vim. New Riders Publishing, Indianapolis, 2001.
[12]
D. Cameron, B. Rosenblatt, and E. Raymond, editors. Learning GNU Emacs. O'Reilly, Beijing, Cambridge, Farnham, Köln, Paris, Sebastopol, Taipei, Tokyo, 2 edition, 1996.
[13]
Vimdoc. http://vimdoc.sourceforge.net/.
[14]
GNU Emacs Manual. http://www.gnu.org/manual/emacs-21.2/emacs.html.
[15]
L. Lamport, editor. Das LaTeX-Handbuch. Addison-Wesley Publishing Company, Bonn, 1995.
[16]
M. Goossens, F. Mittelbach, and A. Samarin, editors. Der LaTeX-Begleiter. Addison-Wesley Publishing Company, Bonn, Paris, Reading, Menlo park, New York, Don Mills, Wokingham, Amsterdam, Milan, Sydney, Tokyo, Singapore, Madrid, San Juan, Seoul, Mexico City, Taipei, 1 edition, 1995.
[17]
Sun Microsystems, Inc. StarOffice™ 7 Office Suite Basic Programmierhandbuch. http://docs.sun.com/app/docs/doc/817-3924, 2003.
[18]
Wikipedia, the free encylopedia. Character encoding. http://en.wikipedia.org/wiki/Character_encoding accessed March 20, 2005, 2005.
[19]
Wikipedia, the free encylopedia. Newline, accessed april 2, 2006. http://en.wikipedia.org/wiki/Newline, 2006.

Index

  • At least one database file damaged (error message), 10.4
  • abstracts
    • write into text file, 4.6
  • archive-files, 1.2, 4.10.1
  • arr-file, 1.2, 4.10.1, 7.5, 7.6
  • article in a journal, 1.1
  • author-date citations, 1.1, 7.2.1, 7.2.4
  • authors

  • BibTEX database
    • compiling, 5.1
  • backup
  • backup of References-databases, 7.6
  • batch files, 4.7
  • batch tables, 4.7
  • bbt-file, 4.7
    • set of reference numbers/records, 4.7
  • bibliographic databases, 1.1
  • bibliographic format definitions, 4.9.2
  • bibliographic record, 1.1
  • bibliographic references
    • numerical
      • in square brackets, 7.2.6
    • superscripted, 7.2.5
  • bibliographic software, ??, 1.1
  • binary batch file (bbt), 4.7
  • browse
    • complete database, 4.1
    • references referred to in a bbt-file, 4.1


  • CRLF line terminator, 12.4
  • chapter or article in a book, 1.1
  • character encoding, 9.4.1
  • citation, 1.1
  • citations, 7.2.1
    • numerical
  • \cite{}, convert to refscite(), 5.5
  • \cite, LATEX, 5
  • clipboard, 7.2.1
    • exchange text between References and other applications, 6.3
  • codepage 850, 9.4.1
  • complete book, 1.1
  • configuration file, 8
  • cp850, 9.4.1
  • create a set of new database files, 4.11.2
  • current record, 2
  • current record number, 2

  • database
  • database binary files directory, 4.11.1, 11.4
  • database field, 1.1
  • database files
  • database rdb subdirectory, 11.4
  • database text files directory, 4.11.1, 11.4
  • delete all database files, 4.11.2
  • document type, 1.1
  • document types, 9.1
  • dos2unix, 9.4.2
  • duplicate records in a database, 7.7

  • Emacs, 3.2
  • Error messages, 10
  • editors
  • encoding, 3.3, 9.4.1
  • end of line
    • win32 and Linux systems, 12.4
  • enter new bibliographic references, 4.2
  • enter new references, 13.5
  • entry of format definition data, syntax, 13.6.2
  • etext.exe, 3.2
  • excite command, 5.4

  • Please press [ENTER] to stop References (error message), 10.5
  • fd-file, 4.9.1, 7.6, 3
  • fde-file, 4.9.1, 3
  • field, 1.1
  • file names
  • file selection, 3.1
  • fonts
    • formatting in lists of references, 7.1
  • fromcite.awk filter program, 5.5

  • Gnome desktop environment, 6.3.2
  • GVim, 3.2
  • generic macro
    • processing of citations in a word processor manuscript, 7.2.1


  • Harvard, LATEX package, 5.4
  • HTML-files
    • fonts
      • formatting in lists of references, 7.1


  • ISO/IEC 8859-1 character encoding, 9.4.1
  • in-text citations, 1.1
  • individual authors, 9.1
  • individual editors, 9.1
  • installation, 11
  • institutional authors, 9.1
  • institutional editors, 9.1

  • journal names
  • journal names data
    • enter, edit, 4.4


  • KDE desktop environment, 6.3.2
  • kewords thesaurus
    • enter edit data, 4.5
  • keywords, 1.1
    • text file, 4.6
  • keywords thesaurus
  • knowledge management, 1.1

  • LATEX, 5
  • LATEX \cite{}, 5.4, 5.4
  • LATEX \citeaffixed{}, 5.4
  • LATEX \citeasnoun{}, 5.4
  • LATEX \citename{}, 5.4
  • LATEX \citeyear{}, 5.4
  • LATEX \possessivecite{}, 5.4
  • LATEX-files, fonts, 7.1
  • LF line terminator, 12.4
  • latin-1 character encoding, 9.4.1
  • latin-1 encoding, 3.3
  • line terminator, 12.4
  • list of authors line (bibliographic format definitions), 4.9.3
  • list of references, ??, 1.1
  • lists of numerical citations
    • sort and compress, 7.2.7
  • lists of references, sorted, 7.4
  • localization line (bibliographic format definitions), 4.9.3
  • log-files, 9.3

  • MEDLINE format, 1.2, 4.10.4
  • Microsoft Word macro for creating citations in the manuscript, 7.2.3
  • macro (Microsoft Word) for creating citations in the manuscript, 7.2.3
  • macro (OpenOffice.org Writer) for creating citations in the manuscript, 7.2.2
  • macro (StarOffice Writer) for creating citations in the manuscript, 7.2.2
  • macro format definitions, 4.9.2, 7.2.1
  • main menu, 3.1
  • manuscripts references numbers missing in database, 7.3
  • menus
  • missing reference numbers
    • deliberate use in manuscripts, 7.3


  • Natbib, LATEX-package, 5.4
  • newline, 9.4.2
    • win32 and Linux systems, 12.4
  • notepad.exe, 3.2
  • numeric citations, 1.1, 7.2.1
  • numerical bibliographic references
  • numerical bibliographic references in square brackets, 7.2.6

  • OpenOffice.org Writer, 1.2
  • OpenOffice.org Writer macro for creating citations in the manuscript, 7.2.2
  • online resources
    • import into References, 1.2


  • Problem: abstract not closed with `—-END-OF-RECORD' in ... (error message), 10.1
  • PubMed MEDLINE display format, 1.2, 4.10.4
  • personal authors, 9.1
  • personal editors, 9.1

  • quit References, 11.2, 13.1

  • Radmin, 11.5, 11.6
  • References
    • part of scientific manuscript, 1.1
  • rebuild the database, 4.11.2
  • recode, 9.4.2
  • record
    • current, 2
  • record number
    • current, 2
  • references
  • refs.log, 9.3
  • refscite(), 7.2.1
  • regular expressions, 4.10.3
  • restructure the database, 4.11.2

  • StarOffice Writer macro for creating citations in the manuscript, 7.2.2
  • scientific publishing
    • bibliographic software, 1.1, 1.2
    • features implemented by References, 1.2
    • general terms, 1.1
    • personal bibliographic management software, 1.1
  • search
    • commands to process a search command, 4.8
    • syntax of search command file, 14.1
  • search pattern
    • extract reference numbers from text files, 4.10.2
  • search-and-replace script, 4.10.3
  • sets of reference numbers/records
    • bbt-files, 4.7
    • operations on, 4.7
  • sort and compress lists of numerical citations, 7.2.7
  • sorted lists of references, 7.4
  • sr-file, 4.10.3
  • sr-script, 4.10.3
  • srchrepl.log, 9.3
  • superscripted numerical bibliographic references, 7.2.5
  • syntax of format definition data, 13.6.2

  • tbt-file, 4.7
  • text batch file (tbt), 4.7
  • text editor shell, 3.2
  • text editors, 3.2
  • text file forms, 3.1
  • text files, reading from References, 3.4
  • thesaurus, 1.1
  • title line (bibliographic format definitions), 4.9.3
  • tocite.awk filter program, 5.5

  • user interface, 3
  • utf-8 encoding, 3.3

  • Vim, 3.2
  • verify.log, 9.3
  • view text file function, 3.4

  • Warning: one copy of `References' still running, 10.2
  • Warnings, 10
  • Writer (StarOffice, OpenOffice.org) macro for creating citations in the manuscript, 7.2.2

1
however, the excellent makebst package is a good alternative to writing BibTEX-styles
2
References follows most of the conventions of journals in these disciplines, so it does not handle full first names of authors or editors, only their initials, but it now allows to enter institutional authors
3
kiev AT users DOT sourceforge DOT net
4
StarOffice v8 is supported as well as OpenOffice.org v2.0.x
5
http://references.sourceforge.net
6
pl. of thesaurus
7
If support of full forenames will be added to future versions depends upon requirements of users
8
This will probably almost never be used in real life situations
9
also called corporate authors: group of authors with authorship responsibility
10
containing the example databases
11
i. e. it does not read/create binary data, e. g. documents files produced by text processors. Data of References databases, however are processed in a binary format as described in the source code, especially refs.h. The internal structures of References databases can be ignored by the normal user
12
More import or export options can be implemented upon request of users, if sufficient information on the format is available
13
database binary files directory
14
database text files directory
15
for example, under Windows versions 9x and ME, size of files that can be loaded by Notepad is limited, and column and line numbers for the current cursor position are not indicated in the status line
16
The following recommendations list text editors, which proved to be quite stable and reliable with their Win32-implementations in the hands of the program author. The selection in this chapter will therefore change with new versions of this documentation. Every user may select the text editor “her/his” is already accustomed to.
17
This editor is freely made available by its author, Gennady Feldman: http://www.gena01.com/win32pad/, however it is not an open source project
18
See http://www.scintilla.org
19
Compiled versions of Vim for Windows (gvim) may be found at ftp://ftp.vim.org/pub/editors/vim/pc/
20
A compiled version of GNU Emacs may be found at ftp://ftp.gnu.org/gnu/emacs/windows/
21
In GVim you may type :set autoread
22
The binary (program) file is ..bin/etext.exe
23
Linux: e-tutorial.sh
24
Linux: e-data.sh
25
for the windows version, this is by default notepad, another text editor (as an example win32pad), can be made available by adding TEXT_EDITOR=win32pad.exe to the configuration file refs.cfg (see section 8)
26
it may also be accessed by main-f f
27
Either command.com (Windows 9x, ME) or cmd.exe (Windows NT, XP)
28
More precisely, character encoding is ISO-8859-1, a synonym for latin-1 encoding
29
Often it will be more comfortable to view a text file with the text editor: main-e ed m
30
a text fragment with which you can restrict the resulting journal names to those which contain this text fragment
31
i. e., if you enter an empty string
32
In this situation, you may abort this function with quit
33
This is especially important, if names for these input files have been changed, cf. section 8
34
In this manual, selections at menu prompts are written in boxed in monospaced font, each menu selection (selections are separated by spaces) has to be entered with the Return-key
35
The first record is numbered 0, the last n−1
36
w for word-wrap
37
like TITLE-ARTICLE, TITLE-BOOK, PLACE-OF-PUBLICATION, PUBLISHER or ABSTRACT, an exception it the HOWPUBLISHED-field of m1, m2-document types which is also intended to be used for (sometimes rather long) URLs
38
introduced in References v4.3
39
digital object identifier, for more information, see http://www.doi.org
40
i. e. apply hexadecimal encoding, which will be fully supported for this field in later versions of References. This practice follows conventions for encoding forbidden characters in URLs
41
or main-e b or main-e s
42
but this normally remains hidden to the user. References performs certain operations on current records, e. g. it jumps again to the current record if you select a function like browse complete database: main-e c
43
“standard format” main-l s and “BibTEX main-l b database format (cf. figure 18)”
44
http://references.sourceforge.net/supplement.html
45
If you enter a file name which already exists, you will be asked to confirm overwriting with y
46
more options in figure 19
47
Normally, you will confirm 1
48
with ReferenceNo for the current reference number
49
References batch files (filename extensions bbt, tbt) have no relation to the batch files under MS-DOS or Windows (these should be better named script files for the COMMAND.COM shell of MS-DOS and have the filename extension bat)
50
in the first line
51
second line
52
the suffix .bbt will be added by the program, so enter only answ!
53
case-sensitive
54
case-insensitive
55
.fd for“format definition”
56
.fd-files may contain one or more format definitions whereas .fde-files only contain a single format definition
57
.fde for “format definition for editing”
58
the extension arr will be appended automatically
59
if new numbers shall be assigned to the records: n
60
This is most easily done by copying (the most relevant part of) the text into the clipboard. Then you will have to open the text editor, “paste” the data from the clipboard into an empty text document and save it as text file
61
i. e. you must use the same type of braces.
62
References provides a better solution for LATEX users with the edit-main-p exc and edit-main-p xex commands, see chapter 5.4 (figure 5)
63
You may enter any valid filename here!
64
Files with the extension sr will be called sr-files or sr-script
65
In the example above the delimiter was a slash (`/')
66
They are much more more flexible as they make use of regular expressions
67
National Library of Medicine
68
The filename extension for medline records must be .txt
69
j1-Format
70
this number shall be new to the database
71
References requires at least one entry in the KEYWORDS or K-NUMBER-field to store the record
72
The rename and duplicate commands preserve the filename extensions
73
e. g. all files with the extension .dat in the database binary files directory
74
either complete or selected by substring
75
This procedure is similar to that for normal text processors, cf. section 7.2
76
like “...[12]...
77
like “...(Mueller et al, 1987)...
78
this method is appropriate for documents with the text in a single file. You should make a copy either as reserve if you wish to repeat the steps described in this section
79
i. e. they must not contain a line-break!
80
the script that comes with References
81
The English names of the menu options are guessed from the designations of the author's German Win32 system. In your local Win32 distribution, the commands in the menu of the Window will differ, so please refer to the documentation. In Windows XP, the “mark” command is also available through the right mouse button
82
You may, however, introduce yout own mechanism!
83
This allows you to use or write one format definition for HTML and LATEX-documents
84
At present, only one reference number can be entered in this way
85
Therefore open start the editor with an empty file, paste the clipboard into the document and save it as text file
86
using search-and-replace function of the word processor
87
written in StarOffice Writer or Microsoft Word
88
These macros have been developed and extensively tested with StarOffice Writer v.7 including product update 1. They should, however work also in OpenOffice.org Writer. Information of users about better solutions for this problem is welcome!
89
only one reference number can be entered as one refscite()-argument
90
also: OpenOffice.org Writer
91
For detailed information of the the user is referred to the documentation of the office package
92
only one reference number can be entered as one refscite()-argument
93
after inserting msw-mak.txt into the Sub in the Word macro editor:
94
The code for the search-and-replace operations in figure 31 was derived from code generated by the macro recorder of Word
95
year with a, b … appended
96
available on the References project homepage http://references.sourceforge.net
97
the character “&” inserts the text found by the regular expression
98
the OpenOffice.org/StarOffice writer command names may be different in the English versions, the program author uses translations of commands of the German StarOffice version
99
Into the search field please enter: ///(*)///, into the replace field: \1, again format the the replace field as superscripted, here it is not necessary to remove the ///s: \1 inserts the list of citations without ///s
100
If you are using LATEX and BibTEX this cane be done automatically with the cite package
101
If you select another filename, you will have to change the name of the file to be processed in the sortrefs.bat command file
102
generated by the macro definition
103
http://www.ncbi.nlm.nih.gov/entrez/query.fcgi
104
refs.cfg (win32) or ~/.refscfg (Linux)
105
In this case fields for institutional authors or editors are left empty
106
performs search and replace operations
107
verifies database integrity
108
To be precise, win32 uses codepage 1252, similar to ISO/IEC 8859-1 character encoding
109
This is a major change from v4.2 and earlier, therefore you have to translate your archive file before you have to import it into a References v4.3 installation
110
These conversions are not done on Linux systems with latin-1 or latin-9 encoding, see below
111
http://www.thefreecountry.com/tofrodos/index.shtml
112
in the abstract text field
113
refs.cfg, for details see table 4
114
This feature was introduced to avoid that two instances of References simultaneously manipulate files of the same database
115
Which is highly recommended
116
filename extension bat
117
at least on my computer localized in Germany, a possible translation is: `Insufficient environment memory' (this is probably not the official message of an English Windows version, which is not available to me)
118
r43d.exe will be called “installer” in this section, although it is only a self-extracting archive
119
At this place, it is assumed that the unzip tool recreates the subdirectories as described in 11.4 as is the case with Info-Zip's unzip
120
The path to a References installation must not contain any spaces!
121
You may also start Radmin.bat from the Windows explorer
122
this adjusts the path entries in the configuration file
123
www.mingw.org, http://www.sf.net/projects/mingw. For the compilation process it is also recommended to have the msys package installed which is available from the same website. Msys also makes gzip and tar available
124
For the normal user, it is not necessary to compile the binary executable files again, as the r43d.zip or r43d.exe archive contain the executable files
125
In Makefiles the character “#” makes the rest of a line invisible
126
If you changed something
127
If you cannot obtain sufficient information with this command, refer to the documentation of your Linux distribution or check the “Language”-specific settings in the configuration tools
128
Details are described in the chapter on radmin
129
e. g. with the su command
130
If you changed something
131
http://gnuwin32.sourceforge.net/
132
http://gnuwin32.sourceforge.net/packages/cygutils.htm
133
with cp850-to-latin1 you will avoid that the code for new lines in abstract is destroyed
134
i. e. ~/refs43/
135
Each time you see a menu prompt “[…]:”, you can see the options by typing menu [Enter]. Everything you type at the References command line must be followed by the [Enter] ([Return])-key
136
From now on the [Enter] key required after each selection is no more mentioned
137
or to the shell from which you started References
138
This name will be different, if you changed it in the configuration file
139
A file with the filename extension .bbt (see section 4.7)
140
All further lines will be ignored by References
141
Details of References search command syntax are explained in sections 4.8 and 14.1
142
References will first present record the current reference number, if it is present in the bloodres.bbt-file, otherwise it opens the bbt-file with the first record
143
main-l s means: in the main menu enter the character l, press [Enter], enter the character [s], press [Enter]
144
this is the number assigned to the first item in the list
145
which should appear as: [0000005] *ARTICLE IN A JOURNAL* Giltay JC, Brinkman HJM, Vlekke A, Kiefel V, van Mourik JA, von dem Borne AEGK: The platelet glycoprotein Ia-IIa-associated Br-alloantigen system is expressed by cultured endothelial cells. British Journal of Haematology 1990; 75: 557-560. KEYWORDS: platelet glycoprotein Ia/IIa, Br(a), MAIPA, MAIEA, asscociation, expression.
146
In this section output in reflist.txt will be shown wrapped
147
resembling SQL or Lua-comments
148
the keyword %lo will be explained later
149
to understand how this works, please read the description of the %fullstop keyword in section 14.2.2
150
Descriptions of valid codes in this context is provided in table 1
151
or something else
152
Archive format version numbers were introduced with References version 4.3e
153
The files may be used as filters and are able to convert refscite() to LATEXs cite commands and vice versa
154
For details, see copying in the doc subdirectory

This document was translated from LATEX by HEVEA.