Reference Database Help Contents
Contents

Introduction

How to do it

Technical notes

Licence

About


Using bibliographies
Creating and using a bibliography

The contents of the bibliography are maintained by the program regardless of closing, opening and creating new files.  Thus you can compile a bibliography from several source databases.

Select the reference(s) you wish to add to the bibliography and choose Reference, Add to bibliography.

References currently in the bibliography are shown a different colour from the others.

To remove references from the bibliography, you need to be viewing the bibliography (in the main window, not the bibliography window), make sure that View, Bibliography is checked, selecting it if it is not.  This displays the bibliography rather than the current search results.  You may now use Reference, Delete as usual to remove the references.  However, in this case the references are not removed from memory unless they are from a different file to the current open file.

To save a bibliography as a database, make sure its contents are displayed in the main window, as above.  Then select File, Save displayed references.  Saving a bibliography as a formatted text file is dealt with below.

To empty the bibliography, select Bibliography, Clear in the main window.

To view the complete bibliography in a readable format of your choice, choose Options, Bibliography format, and then Bibliography, Display formatted.  This creates the Bibliography window, which is a simple text editor where you can touch up the formatted references.  You can still carry on working in the main window, although any changes you make to the bibliography itself in the main window will cause changes you type in the bibliography window to be lost as it will be automatically updated.

From the bibliography window you can save the formatted text in the window to a file (Save...) or copy it to the clipboard.

New bibliography formats can be created and entered in REFS.INI using Notepad.  See bibliography format syntax for details.


How To Do It

How to...

Add a new reference

Edit a reference

Delete a reference

Search for references

Create and manage a bibliography

Print a reference

Transfer information to other applications

Import references from a foreign file format

Add or remove import libraries

Customise Displays


Adding/removing import DLLs

The Import feature of Refs 6.x is designed to be easily expandable with new formats.  I will release these DLLs as they become available.  So far I have covered Medline (for our American friends) and BIDS for us Brits.  Medline is more or less untested, so I would be pleased to hear if it works or not.  This help file also contains information for programmers wishing to write their own import DLLs.  See Import DLL Interface  for details.

Letting Refs know about new DLLs is easily accomplished.  Edit REFS.INI.  Click the notepad icon below to do this now: (this will only work if REFS.INI is located in a directory called C:\WINDOWS)

The [Import] section should look similar to:

[Import]

Filters=2

1=IMPBIDS.DLL

2=IMPMED.DLL

So to add/remove an import DLL, add or remove its name to or from the list, and adjust the Filters value appropriately.

Please note:

a) 'Filters' should always return the number of entries that follow.  Any more and there will be errors.

b) The order of DLLs in the INI file is the order in which they will appear in the list box of choices.

c)  The numbered list must run from 1 up to the number of DLLs - numbers must not be missed out.


Importing other format databases
Importing other database formats

Refs can theoretically import references from any text-based reference file format.  Each format needs to have an import DLL written for it (such as IMPBIDS.DLL), to deal with the foreign format.  These DLLs should be listed in the [Import] section of REFS.INI.  Refs can deal with up to 65,535 foreign formats.  At present, I have written such DLLs only for ISI (BIDS) and Medline.

1.	Select File, Import...and a dialog will appear listing the available formats known by Refs.  Select a format, and choose OK.

2.	Some DLLs may have an options function.  Choosing the Options button will allow you to call this function if it exists.

3.	Choose OK

Double-clicking the desired format will also close the dialog box, as if you'd selected it and then clicked OK.

4.	Select the file to import in the next dialog box.

5.	Refs will then import the file as well as the DLL can manage.  Imports may well lose some information, depending on the capabilities of the format being imported.

Programmers wishing to write their own import DLLs are referred to the Import DLL Interface section.


Import DLL structure
Import DLL Structure and interface

Import DLLs consist of four exported functions.  Three are compulsory, one is optional.  These are as follows:

function WhoAmI: PChar;

function GetSpecs: PChar;

function LoadRef(AParent: HWnd; F: PText;INIPath: PChar): PImportRef;

Optional:

procedure Opts(AParent: HWnd; INIPath: PChar);

Please upload any import DLLs you write... others might find them useful!  Or send them to me, and I will include them in the next official release of Refs.


WhoAmI import DLL function
function WhoAmI: PChar; export;

This returns a PChar (LPSTR for you C fans) pointing to a null-terminated string describing the DLL.  This is the string that gets inserted in the choices list box.


GetSpecs import DLL function
function GetSpecs: PChar; export;

This returns a pointer to a special string that will be referred to in the lpstrFilter member of a TOPENFILENAME structure that will be passed to GetOpenFileName.  See  your compiler documentation for details.  IMPBIDS.DLL has the following code for this function:

function GetSpecs: PChar; export;

begin

  GetSpecs := 'ISI text file (*.isi)'+

    #0+'*.ISI'+#0+'All files (*.*)'+#0+'*.*'+#0#0;

end;


LoadRef import DLL function
function LoadRef(AParent: HWnd; F: PText; INIPath: PChar): PImportRef; export;

PText is a far pointer to a Pascal variable of type text.  Sorry, C programmers.  You'll have to find out exactly what the structure of this beast is.  Besides, if you're not writing DLLs in Pascal, you're missing out - it's a piece of cake!

The file F^ will be open, and LoadRef must load a single reference at this point, and fill a TImportRef structure with the new reference.  You then return a pointer to this structure.  REFS.EXE will copy the data, so you may dispose of it in another procedure (or next time LoadRef is called, which is the way both IMPBIDS and IMPMED do it).  LoadRef is repeatedly called by Refs until you return a non-zero Result member of the TImportRef.

If you need to load any options, INIPath gives the path to REFS.INI


Opts import DLL procedure
procedure Opts(AParent: HWnd; INIPath: PChar); export;

This is your optional procedure.  If this procedure is not present, Refs will display a message box to the user saying so when the Options button is chosen, otherwise Opts is called, and you are free to display an options dialog box for your DLL, using AParent which is the REFS.EXE main window handle.  Bear in mind that your DLL will be freed before being used again to import a reference, so any options should be saved to an INI file.  You may use REFS.INI for this purpose.  The path to REFS.INI is given by INIPath.

Please note that this has changed since Refs 6.2 and 6.3.  Old DLLs will not work with Refs 6.31, and new DLLs will not with Refs 6.3 or before.


TImportRef import DLL structure
TImportRef

This is declared by Refs as follows

type

  PImportRef = ^TImportRef;

  TImportRef = record

    Result: Byte;

    RefType: Byte;

    Authors: PChar;

    Date: PChar;

    Title: PChar;

    Journal: PChar; {Or book title, depending on RefType}

    Vol: PChar;

    VolNo: PChar;

    Pages: PChar;

    Text: PChar; {Abstract}

    Keywords: PChar;

    Publisher: PChar;

    City: PChar;

    SortStr: PChar;

  end;

Result should be filled as follows:

0	Reference read, file not yet exhausted, carry on reading

1	Reference read, end of file reached, stop reading

>1	Other error, stop reading, do not create a reference from this TImportRef.

RefType:

0	Journal (%J)

1	Book (%B)

2	Report (%R)

Other values will result in problems.

The other entries should contain pointers to null-terminated strings, or a value of 'nil' (or NULL in C-speak).  There are some rules:

Keywords and Authors fields:

The individual items should be separated by CRLF, otherwise Refs will make errors saving and displaying the references.

SortStr is ignored, at present.  Refs will fill this itself, on copying the structure.


Introduction

Welcome to Refs, a program for creating, maintaining and searching academic reference databases.

In this help file, paragraphs preceded by [image] concern keyboard use only.  Paragraphs preceded by [image] concern the mouse only.

Refs provides a user-friendly interface for handling Unix-style reference databases.  It provides the following features:

1.	Merge database files non-destructively.

2.	Import databases from other sources

3.	Save searches to separate database files.

4.	Create bibliographies which can be saved as text files, refer files, or pasted into other applications

5.	Store data in the following fields:  Author(s), Title, Date, Journal, Book Title, Report, Issuer, City, Volume, Number, Pages, Keywords and Abstract

6.	Single or multi-column display options.

7.	Easy Cardfile-like keyboard operation.

There are four main windows in Refs:

The Main Display:

This is where results of searches are displayed, and where you give commands to the database for adding, editing and deleting references,

Bibliography window:

This is where the bibliography is displayed in a readable format, and from where it can be saved to disk or copied to the clipboard.

Reference form:

This appears when you ask to view or edit a reference.  It displays the authors and date of the reference in the title bar, and contains edit fields for the various fields of the reference.

See Editing references

Author form:

This is used to edit the author or date fields of the reference that make up its title in the reference form, and also to specify the reference type (book or journal).


Finding a reference
How to find a reference:

 1.	Select New search... from the View menu, or press F3.

2.	From the Search By combo box choose the type of search you wish to perform.

3.	In the Search For box type the string you wish to search for.

4.	Choose OK.  The main window will then show all references matching your criteria.

The status bar will show how many references were found and the criterion used.

5.	You're not content with the results?  Too many references?  You can restrict the search, by now selecting  View, Narrow search...  This will repeat steps 2-4, but this time will perform the search only on those references you found last time (i.e., those which are currently displayed).

Too few results?  What if you want those references with either DNA or RNA in the title?  You could search for NA, but this would turn up all sorts of junk.  Instead, search for DNA, then select View, Expand search...  Again, this repeats steps 2-4, but this time search for RNA.  The existing search is kept and any new references found which are not already in the list are added to it.


Adding a new reference
How to add a new reference:

1.	Choose Reference, New... or press F7.

2.	A dialog box will appear for you to enter author and date for the reference. The Author field must be filled.  The Unix refer format does not require this, but since the program sorts by Author name before sorting by year and then title, it's fairly important!  Besides, somebody must have written it!

3.	Select one of the option buttons for the document type.  Journal is the default (although this can be changed).  The only difference this makes is to save a %J, %B or %R field.  See technical notes for more information on Unix refer file field identifiers.

4.	Choose OK

5.	A second dialog box will appear for you to enter the title, journal or book title as decided in Step 3, and notes for the current reference, as for editing a reference.


Editing or Viewing a reference
How to edit or view a reference:

1.	Select the reference you are interested in and then select Reference, Edit...

 	Double-click on the reference you are interested in the main list.

Press F6.

2.	Choose Cancel to go back to the main list, or OK if you want the reference to be updated to its current displayed contents (i.e. if you've just edited it).

NB:  You cannot edit or view a reference if more than one is selected in the main list.

If you wish to change the author, year or document type (book or journal) you cannot do this from the standard reference form you have just called up.  To do this, close the reference form:

Hold down Ctrl and double-click the reference.

Select Reference, Edit author...  or press F2.

Please note:

(a)	Windows multi-line edit controls all allow carriage returns to be entered using Ctrl+Enter.  Do not do this!  If the field accepts carriage returns (without using Ctrl+Enter), then you may insert them.  In other fields, using Ctrl+Enter will cause confusion when saving the file, and text following the carriage return will be reloaded as part of the abstract!

(b)	If you wish to insert tab characters in your abstract field (or any other field), you must use Ctrl+Tab, since Tab alone moves the input focus to the next control in the dialog.

(b)	To enter unsupported fields such as %E (editor) just type them on a new line in the abstract field.  For instance if the abstract edit box when viewing the reference contains:

This is your abstract.¶

%E editor

This will produce the correct refer file of:

%X This is your abstract.

%E editor

Be careful of duplicating entries this way.  If you put a %T field in here, and your title field has something in it, both will be saved as %T lines.  When this is next loaded by Refs, the second %T entry (the one in the abstract) will be ignored and subsequently lost!  I don't know how other programs would behave.  This is the case for all duplicated fields, except %A (Author), which is duplicated for each author anyway.

(c)	The Keyword field should have your keywords on separate lines, without blank lines between them.  The same applies to the author field.  Each author should occupy a separate line with no blank lines.


Deleting references
How to delete a reference

 Select the reference(s) you wish to delete.

Then press Del(ete) or select Reference, Delete


Printing a reference
How to print references

This is not yet possible directly.  However, an interim solution is to paste a bibliography into Notepad and print that, or print a .REF file using Notepad.  It's plain text, and is a fairly readable format.  Refs also saves it in a reasonably logical order; Authors and Title followed by the other fields, and the Abstract last.  Refs also saves the file in alphabetical order of primary author.


Technical notes

This program was written in Turbo Pascal for Windows 1.5, and requires Windows 3.1 or higher to run.

The central database structure has a maximum capacity, in the registered version, of 262,140 references in Standard mode, and something over 4.1 million references in 386 Enhanced mode.  You will certainly run out of memory before reaching this limit!  The About box in the program tells you how much memory is free.

There are restrictions, unfortunately, that are imposed by Windows 3.x.  You are only allowed 8,192 entries in a List Box, so searches going over that will stop being displayed when the list box is full, though they will still be in the search results.  I do not know whether this restriction applies if the program is run under Windows NT.

Huge data files will be slow to search by the current program, and this is probably better done with a program such as WinRefer which maintains indexes to make this faster.

At present I have arbitrarily imposed a maximum length of 8K to each field.  This should be enough for most purposes, I hope!

Files are saved in the common Unix refer format.  This means that databases created by this program can be used with Unix refer, and bibliography programs such as WinRefer.  The order of fields is not important.

Fields currently supported explicitly by Refs are:

%A	Author

%T	Title

%J	Journal

%B	Book title

%R	report (used for unpublished documents)

%I	Publisher

%C	City of publication

%V	Volume

%N	Number in volume

%P	Pages

%D	Date

%X	Abstract

%K	Keywords

The above meanings are as described in SunOS 4.1 manpage refer(1)

Fields not included in the above list can still be entered in the database;  see editing references.

The major fields not covered explicitly are:

%E	editor

%O	other (appended)

%Z	ignored

Such fields, when encountered in files, will appear in the abstract field, but will be saved correctly.  If anyone knows of other less common fields (those listed here are all the ones I know about), I would be glad to learn about them.

Import DLLs are loaded at run-time.  The DLL interface structure is included in this help file for any programmers wishing to write one.


Transferring information
Transferring information to/from other applications

Transferring information to word-processors is best done as follows:

1.	Add the references you want transferred to the bibliography

2.	Choose a format for display

3.	Display the formatted bibliography

4.	Edit it if you wish

5.	Select as much as you wish to copy,  in the bibliography window

6.	Choose Edit, Copy to place the selected information in the clipboard

7.	Now you can paste it into any application that supports text pasting from the clipboard

You can also cut and paste directly to any edit box:

Select the text you wish to copy, or place the insertion point where you wish to paste.

Use standard Windows Cut/Copy/Paste keys.  These are:

Cut:	Ctrl+X

Copy:	Ctrl+C

Paste:	Ctrl+V

In the main editing window, there is also a menu for this purpose.


About Reference Database
About Refs 6.32

Please send any bug reports, registrations or suggestions to any of the following addresses:

tjrc1@mbfs.bio.cam.ac.uk

or by snail mail:

T. J. R. Cutts

CRC Mammalian Cell DNA Repair Research Group

Dept. of Zoology

Downing St.

Cambridge

CB2 3EJ

UK

(please note that my e-mail address has changed... the old tjrc1@cus.cam.ac.uk still works, but will redirect to mbfs.bio).

You may also phone me at home on (+44) 223 411292, though please make it a sensible hour of the evening.  I won't be very polite if Bloggs calls from LA at 4am...

When reporting a bug, please tell me the following:

a)  What you were attempting to do; if the bug is not reproducible I won't be able to find it!

b)  How much memory was free

c)  What the error was (Runtime error numbers and/or address at which the error occurred)

d)  Program version number

e)  Anything else that might be even remotely relevant

Changes since Refs 6.31

Fixed bug in progress dialog which was preventing saving files with <5 references.

Changes since Refs 6.3

More modification of DLL interface fixing bug that prevented IMPBIDS from seeing its saved options.

Changes since Refs 6.0

1.	Database routines rewritten to increase cleanup speed, which was unacceptably low with large files.  Some routines are now written in assembler.

2.	Bug in deletion of references and bibliography behaviour fixed.

3.	Progress dialogs for file loading, saving, searching and memory cleanup.

4.	Colour coding of references in bibliography, and ability to choose this colour

5.	REFS.INI may now be stored in the same directory as REFS.EXE.  Refs searches for it first in your windows directory and then in the same directory as REFS.EXE.

6.	DLL interface modified in view of (5).  Old DLLs will run with the new REFS, but versions 6.0 - 6.2 of REFS will crash if attempting to run the new IMPBIDS Options procedure (import function will still work).

7.	IMPBIDS.DLL has a new option allowing saving of DT (document type) fields as keywords.

8.	Explicit support for the %R field tag added.


Licence
Licence and Registration Information

This piece of software is shareware.  It is not public domain, or freeware.  Versions up to and including 0.4 were freeware beta releases.

The demonstration version of Refs is fully functional, except for a limit on its capacity of 100 references.  Refs will load and display files larger than this, but you will not be able to add new entries to such files.  This should give you some time to evaluate its usefulness for you before you run out of entries.

You are licensed to copy and distribute the demonstration version freely as long as you distribute the following files together:

REFS.EXE

REFS.HLP

REFS.INI

IMPBIDS.DLL

IMPMED.DLL

TEST.REF

BWCC.DLL

README.TXT

and make no charge other than reasonable duplication costs.

Important:

This software comes under no warranty whatsoever, expressed or implied.  The author cannot be held responsible for any loss occurring during the use of this program, directly or indirectly.

Registration:

The registration fee is £30 sterling, by cheque drawn on a UK bank, or International Money Order.  My apologies; I cannot accept VISA or MasterCard registrations.  Registration gets you:

i)	The full version of Refs with the 100 reference limit removed.

ii)	Internet/CompuServe users will be mailed any minor bug fix releases to their registered version.  Other users requiring these will need to send me sufficient moneys to cover postage.

iii)	One free upgrade to a major release.  If you are registering an old version, this will be to the current version.  If you are registering the current version your update will be to the next major release, when that occurs.  Subsequent upgrades will carry a small additional fee.

iv)	Your registration fee covers a single-user copy of the program.  You may not distribute the registered version to any other persons.  Network administrators wishing to register Refs for multi-user use should write to me for details.

My address can be found in the about section, as can information about the current state of development and plans for future versions.


Customising the displays

Options, Main list...

Options, Input... Allows you to specify the default date used when creating a new reference, and the default source for references (book or journal).

Options, Bibliography format... Choose how references will be formatted in the bibliography window.  See bibliography format syntax for details.

Options, Bibliography colour... When a reference has been added to the bibliography, it changes colour in the main list.  Use this dialog box to choose what that colour should be.


Bibliography format syntax

These formats are stored in REFS.INI.  To create a new format, or change an existing one, edit REFS.INI with Notepad.  Click the notepad icon below to do this now:

In the [Formats] section add a line like:

Journal=<A@, ><T@, >< J@, ><V@><N/@ ><P@ ><D(@)>

'Journal' is the name that will appear in the Bibliography format... dialog combo box.

Fields begin with a <.  The next character must be a valid field identifier character.  If this field exists in the reference, the other characters in the field will be printed until a > is encountered, otherwise parsing continues after the next >, so the field is missed out.  The symbol @ indicates where in the field to insert the field text itself.  To insert a literal @, < or > without using their special function, precede them with a \.  \\ will produce a single \ in the formatted text.

The uppercase letters ATJICVNPD have the same meanings as they do as field tags in the Refer file format, except J which returns %J, %R or %B fields depending on the reference source.  See Technical notes for an explanation of the tag meanings.  They are fairly self evident.  K and X are not supported.  Other characters are literally copied, so if your reference has Date field of '1992', <D(@)> will produce '(1992)' when formatted, and nothing if the date field is empty.

There is no way to create bold or italic type, since Refs formats ANSI text, as used in Notepad.  However, if you are creating bibliography files for TeX, it is possible since TeX uses plain text source files, and I have included an example TeX format line in REFS.INI.


Main display options
List Options Dialog

There are two panels to this dialog.  The left hand panel governs how the references are displayed in the main list; how wide the column for author names is, how many author names to display, and whether to also display the title of the reference.

The right hand panel governs the behaviour of the main list box, rather than its appearance.  There are three radio buttons giving progressively higher levels of warnings when deleting references.  Such warnings never appear when deleting references from the bibliography, only when deleting references from the currently loaded file.

The Select new items check box controls whether a newly created reference is automatically selected afterwards.