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.

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

Managing 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.0 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:

The [Imports] 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.

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): PImportRef;

Optional:

procedure Opts(AParent: HWnd);

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): 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!

Anyway, 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 the TImportRef.  Refs will copy the data, so you may dispose of it in another procedure (or next time LoadRef is called).  LoadRef is repeatedly called by Refs until you return a non-zero Result member of the TImportRef.


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

This is your optional procedure.  If this procedure is not present, Refs will display a message box to the user saying so if the Options button is chosen, otherwise Opts is called, and you are free to display an options dialog box or whatever for your DLL, using the AParent 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.


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

1	Book

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, 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 either a %J or a %B 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.


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 8,192 bytes 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

%I	Publisher

%C	City of publication

%V	Volume

%N	Number in volume

%P	Pages

%D	Date

%X	Abstract

%K	Keywords

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

%R	technical report number

%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.0

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

tjrc1@cus.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

When reporting bugs, please tell me:

a)  What you were attempting to do

b)  How much memory was free

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

d)  Program version number

Version History:

Sorry I didn't write in the MDI interface... very little time available for a project of that nature.  Maybe in version 7.0... :-) However, be thankful that the foreign file support is a lot more flexible and upgradeable than I originally intended!

Version 6.0 (22 July 1993)

1.	Expandable foreign file import DLL support added.  At last you can put your on-line database searches straight into Refs, without any tedious cut-and-paste or typing.

2.	Menu added to main editing window for mouse-based clipboard functions.  Cut/Copy/Paste/Undo are now more accessible for all field edit controls in this dialog box.  This is for the large number of users who complained that they couldn't paste into the abstract window, and who clearly didn't RTFM! :-)

Version 5.2 (not released publicly)

1.	Changed handling of Author names and Keywords to make them more flexible.  This involves some minor changes to the appearance of some dialogs.

2.	File loading and reference insertion is now much faster, at the expense of slightly more memory useage.

3.	Made considerable changes to the help file.  You can now launch notepad with REFS.INI loaded from the bibliography format syntax section.

Version 5.12 (21 June 1993)  No public release, though distributed to registered users.

RLE bitmaps are now back; the bug was in Borland's Resource Workshop, not Microsoft's display drivers.  However, the S3 drivers handle Resource Workshop's mistake correctly, whereas Microsoft's do not.  Also fixed a minor error in the behaviour of the volume number edit control.  Added internal encryption of user's name as displayed in about box.  Prevents people changing the resources and claiming they have their own registered copy. :-)

Version 5.11 (11 June 1993)

Minor bug fix... Discovered that 0.51  would not run with the standard VGA and SUPERVGA display drivers, because they can't cope with RLE compressed bitmaps (I use S3 drivers, which can, so the last version worked fine for me)

Version 5.1 (10 June 1993)

Owner drawn list box now obeys the colours specified in Control Panel, in the same way as File Manager.

Version 5.0 (29 May 1993)  Not publicly uploaded, though some copies mailed around the world.

1.	This is my first release of what I consider to be a finished program.  Consequently its status has been changed to shareware, and I have changed in version numbering policy.

2.	Abandoned Borland's data structure, and wrote my own clone of it from scratch.  This has had the added bonus that Refs now has a maximum capacity of over 4 million references, rather than 16,380!

3.	Main display changed to owner drawn list box.  As well as now having pretty icons, this also means that more entries are allowed in the list box, so larger searches can be performed.

4.	Altered and improved biliography formatting structures

Version 0.41 (not publicly released)

Small fixes to some incorrect behaviour in publisher and city edit controls, and also in multiple selections in the main window.

Version 0.4  (7 May 1993)

1.	Generic support for all  % field tags, even those not explicitly found in editing dialog boxes.

2.	Explicit support for book references added

3.	More minor list box problems fixed!

Version 0.3  (1 May 1993)

1.	Bibliography facilities

2.	Ability to make multiple selections in main display

3.	Minor bugs in list box sorting fixed

4.	Various minor cosmetic changes, and code streamlining

5.	Number in volume field support

6.	Fixed incorrect behaviour saving untitled files

Version 0.2	(21 April 1993)

Fairly major re-write, especially of file handling and internal data structure:

1.	For compatibility reasons, converted to using ASCII Unix refer file format.

2.	Improved keyboard use.

3.	Added keyword field support.

4.	Added status bar descriptions of menu commands.

5.	Expand/Narrow search added.

6.	Various bug fixes (of course!)

7.	Added display options.

Version 0.1	(October 1992)

Never publicly released, but anyway:

1.	Stored data in a proprietary binary format.

2.	Allowed searches to be made for specific references.


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 licenced 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 occuring 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 monies 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.


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 the Journal if the reference is a journal article, and the book title (%B) field if it's a book.  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.