ARM Club 3/TheARMClub_PDCD3.iso/programs/fonts/citation/docs/Docs/Manual

Text File | 1998-05-28 | 105KB | 2,201 lines

             !Citation Database Manager Manual (for ver. 3.0)
             ================================================

           CONTENTS
           --------
           1 Orientation
             1.1 - Field input
             1.2 - #ID numbers
           2 Styles & Output
             2.1 Reference types
             2.2 Defining styles
                 2.2.1 Script language
                 2.2.2 Special styles
                 2.2.3 Author format
                 2.2.4 Misc options
                 2.2.5 Exclusion (LICE) brackets
                 2.2.6 Italic, bold & underline effect tags
                 2.2.7 Saving/Loading styles
             2.3 Card Export
             2.4 Generating citations for final output
                 2.4.1 Selecting references for output
                 2.4.2 Generating the output subset
           3 Searching
             3.1 First Author
             3.2 Record #ID No.
             3.3 General Search
           4 File import
             4.1 CSV Archive & Subset files
             4.2 "5"-line text file import
             4.3 Reprint (Ovid)import
             4.4 BIDS/ISI import
             4.5 Tagged (Refer) text files
             4.6 Importing & the format card
             4.7 Deleting imports & import errors
             4.8 Field Import
           5 Scanning Manuscripts
           6 Archiving
           7 Keywords, Journals & Abbreviations lists
           8 Duplicate scanning
           9 Preferences
          10 Miscellaneous (with UserKey instructions)
          11 Error Handling
          12 Acknowledgements & Copyright Notice


Note: Registered users should first insert their UserKey to gain access
to the full version. See Section 10 for instructions on how to do this.


This package should included the following:

* !Citation - Main Application.
* Docs directory - containing this Manual and related documents and some
              !Draw files showing annotated screen shots.
* Eg_data directory containing the following example files:
  !Refsdata - an example citation library, drag to the icon bar icon.
  !TestLib  - a ready created "empty" library
  Arch_v2   - v2.0 CSV archive file (see sections 4.1 & 6).
  Arch_v3   - v3.0 CSV archive file (see sections 4.1 & 6).
  fv_line   - 5 line text file (see section 4.2).
  tagged    - a Pro-Cite tagged format file (see section 4.5).
  Reprint1  - an Ovid Medline "Reprint" format file (see section 4.3).
  Reprint2  - an Ovid BIDS "Reprint" format file (see section 4.3).
  Bids_med  - BIDS embase lower case file (see section 4.4).
  Bids_phys - BIDS physics upper case file (see section 4.4).
  ManScan   - Demo files for manuscript scanning (see section 5).
  Styles    - Example style files (see section 2.2.6)

What follows is a run down of the main features of !Citation which is
intended to be read whilst experimenting with the supplied example
library and associated files.

Note: References to !Techwriter (© Icon Technology) in these documents to
also apply to their application, !Easiwriter.


1. Orientation
==============
* "Where do I start...?"
To get started, load !Citation (double click in the icon in the filer
window) and drag a library (for example "!Refsdata" supplied with this
package) to the !Citation icon on the icon bar (the coloured "C") and you
will see the main browser window display the first record in the library.
Note that !Citation's libraries are actually application directories
which can be copied, moved and *DELETED* (though not whilst it is being
used by !Citation - please!) as usual through the RISCOS filer menus...
so keeping backups is easy.

* "How do I create a *NEW* library...?"
Simply open up the icon bar menu, select "New Library", enter a name and
drag to a filer window. Data files will be automatically created in this
directory by !Citation and an empty browser window displayed ready for
data entry. The "!" prefix is automatically added to the name if you
forget. Libraries are restricted to the usual 10 letter RISCOS filenames.

* "All the fields are blank...!"
If no library is loaded then the browser window fields are blank and "No
Active Library" is displayed in the header bar. Dragging a library to the
icon bar immediately opens it and displays the first record. If you have
several libraries, when the next is dragged to the icon bar, the current
library is automatically closed, saving changes and the new one opened.

"Close library" in the icon bar menu closes the current library and its
associated windows, returning !Citation to its waiting mode. This option
is occasionally useful since the pathname of the last active library is
retained in the "settings" file so that !Citation always opens where you
left off. If this library moves or is deleted between running !Citation,
!Citation will report an error and open with "No Active Library". If you
make a back-up of the "settings" file (see section 10. for how to do
this.) use the "Close Library" option in the icon bar menu first. This
zeros the active library to "default" and prevents this error - but don't
worry it is not fatal if it does occur!

* "So what DO all these buttons do...?"
The tool bar on the left hand side contains a status window and buttons
which perform the following functions (see also accompanying !Draw file -
"browser")....

 » Status window - shows the record #ID number and flags search results

 » Goto first record browser arrow
 » Goto last record browser arrow

 » Goto previous record browser arrow - "adjust" click jumps 10 records
and "select" just one record.
 » Goto next record browser arrow - "adjust" click jumps 10 records and
"select" just one record.

 » Add record - in this mode all arrow buttons are disabled (in fact all
record movements) while a new record is manually added. When this buttons
is clicked all other windows and searches are closed and certain
operations are disabled to prevent operation clashes.

 » Edit record - this puts !Citation in the edit mode. The library can be
browsed with arrow buttons to allow easy alteration of consecutive
records but some operations are disabled to prevent operation clashes.
You can search and view subsets and call up records from the results. In
the editing mode altered records will be automatically updated if user
moves to a new record (ie. clicks on a tool bar arrow) but you must use
"Save" on the last altered record if leaving this mode to update the
library.

 » Cancel - aborts current operation and reinstates altered fields.

 » Save - updates any changes to disc (note comment in Edit above). Only
one record is ever held in memory so that if the system crashes data loss
is minimal.

 » Delete - flags the current record as deleted. Note that records are
not actually removed from the library until it is "Compacted" from the
icon bar menu ("Icon bar menu->Maintenance->Compact library") since this
can be a time consuming process and best executed in bulk. It also gives
you chance to change you mind but no attempt is made to stop the user
editing deleted records. These will be lost on the next compact but can
be reinstated BEFORE compacting using the "Main menu­>Miscellaneous­>
Undelete record" option.

 » Card export - allows dragging of author names directly into your
manuscript in the appropriate format eg. "[Radulescu et al, 1986]" or
"[Smith & Jones, 1901]". Four possible formats are available and may be
selected from "Main menu->Card export" or more rapidly by clicking menu
over this button (see section 2.3).

 » Subset designations - the references in a library may be placed in any
(or all) of 5 subsets (0 to 4). This part of the tool bar shows the
subset designation for the current reference. Designations may be simply
changed by clicking on the option button aside the number to select or
deselect. Clicking on any of the prompt *numbers* calls up the "Order
value" window (see section 2.4.1 for more information).

If no library is open then all buttons are disabled. If a new, empty
library is selected then only the "Add" button functions.

The browser window header bar shows the name of the currently active
library, the current mode (Add, Edit and Format card) and the number of
records in the library.

One other button is worthy of mention here and that is the "Abstract"
button which lies on the right in the main browser window. A click on
this brings up the abstract window. The button has two states, a raised
yellow button which indicates that the current reference has abstract
data attached or an inset button with a red cross which indicates that no
abstract data is attached. The abstract window can still be opened in
this state, by a single click, to add data.

1.1 - Field input
      -----------
!Citation needs to have authors entered in a specified format to provide
a known starting point from which the various output formats can be
derived. Authors should be entered as: SURNAME, SPACE then INITIALS or
FIRST NAMES. There should be no spaces between initials which need to be
upper case. First names should be entered as a capital then lower case
eg.

 Brown FGB, Williams ED, Flog HG
 or
 Brown Frederick George Bow, Williams Edward Dillon, Flog Henry Geld

 *IMPORTANT*
!Citation uses the following rules for working out author format.

i) For an author name, all the characters *AFTER* the FIRST space
separator are taken as the initials or first names.

 Brown FGB
      ^<-------- First space separates surn and inits
or

 Brown Frederick George Bow
      ^<-------- First space separates surn and firstname

ii) initials are in uppercase with no spaces between them.

iii) first names start with a capital followed by lowercase with spaces
between individual first names.

iv) commas separate each complete author name.

These rules allow author entry in the most readable way BUT must be
consistently used or odd formatting will result. They also allow direct
input from the computerized databases supported by !Citation.

* "What about double-barrelled, complex surnames or corporate names with
several parts?"

Double barrelled surnames present little problem since they are
concatenated with a hyphen. Applying rule i)...

 Wynford-Thomas D               ("D" is the initial)
 Jodper-Smithers Cecil          ("Cecil" is the first name)

Corporate or complex names are a special case and each element of the
"surname" needs to be concatenated with a cap (^) symbol (shift-6) rather
than a space to indicate that they are to be kept together.

 Yo^Ti^Wa XF                    ("XF" are taken as the initials)
 de^Cuevas BA                   ("BA" are taken as the initials)
 Minster^(Jean-Francois) J-F    ("J-F" are taken as the initials)
 Strang^Jr. William J           ("William J" is the first name)

!Citation then treats these "capped surnames" as one element and
automatically strips out the cap separator when the reference is output.

For corporate names without an initial/first name element...

 The FRAM Group            becomes   The^FRAM^Group
 US Dept. of Agriculture   becomes   The^US^Dept.^of^Agriculture

!Citation recognises the absence of initials/firstnames and compensates
accordingly. Obviously only some of the author formatting options
available are not applicable to these "names" and !Citation also takes
this into account.

* "How are initials leading a first name handled...?"
Some authors are reluctant to divulge their first name but appear happy
to present their second name in a citation e.g. Bennett, EB Gordon (where
"EB Gordon" is the first name component). This format doesn't really fit
in with the name and initial rules stated above but can be entered into
the author field in this form. !Citation recognises the leading
initial(s) and preserves the intervening space when punctuating the full
name form e.g.

   Bennett, E.B. Gordon
                ^<---------- space preserved

This space though, is stripped correctly if initials only are required on
output e.g. Bennett, E.B.

Up to 25 authors or 254 characters (the field length) may be entered and
each author (surname/initial) *MUST* be separated by a comma (rule iv)
eg.

 James DS, Attanoos RL, Williams GT, Neal JW

No terminating character to the author field is required and it is
recommended that extraneous spaces between elements should be avoided,
with the comma following directly after the initials. No full stops
should be used since these can be added more flexibly with style scripts
or author options. Accented characters may be used for foreign names by
using the "Alt-" key plus numberpad or !Chars utility.

The possible author formatting options are explained fully in section
2.2.3. Note that entries into the Editors field should be in the same
format as that described for the authors (ie. Surname Init, Surname Init)
and the output follows the same style as that set for authors. !Citation
works optimally if *ALL* the authors and editors on a paper are entered
into the author field since in many cases it needs to know the exact
number of authors to calculate its output - tedious I know, but
advisable.

* "Are there any other input requirements..."
If the user wishes to use the page number abbreviation option, the page
number field requires a standard hyphen (ASCII decimal 95) as a separator
with the full start/end page numbers i.e.

   1234-1244         *NOT* 1234-44

!Citation uses the hyphen character to distinguish between start and end
numbers and the full numbering is required for the page number
abbreviation option to work correctly.

It is also recommended (but not obligatory) that the user refrains from
ending title entries with a full stop. This can easily be added in the
style format and computerized databases do not appear to include it in
their output. Thus for consistency, the full stop is better omitted from
manually entered references particularly if you intend to mix them with
database derived entries. However, !Citation does checks author, editor,
book and title ending punctuation on output to remove extraneous, style
script added, full stops or full stops following "?!" characters in, say,
a title field.

* "What about the other fields on the browser card?"
Other fields are essentially self explanatory and have a free format so
that dates can be "1967" or "1973a" or "13th Sept 1956". Similarly, pages
and volumes can contain letters to allow, for example, supplement page
numbers "s11-s45". This flexibility essentially means that there can be
no validation check on these fields for, say, numerical input only.

Field limits are:
     Authors            - 254 chars or 25 authors
     Item Title         - 254 chars
     Journal/Book title - 150 chars
     Editors            - 150 chars
     Publisher          - 70 chars
     Place              - 60 chars
     Volume             - 25 chars
     Pages              - 25 chars
     Date               - 15 chars
     Edition            - 60 chars
     ISBN               - 25 chars
     Keywords           - 254 chars
     Field A            - 254 chars
     Field B            - 254 chars
     Abstract           - unlimited

A select click on the menu button which sits at the end of the Source
field (labelled as Journal or Book (Series) Title) brings up a list of
your preferred journals (see section 7, for information on how to edit
this list). In adding/editing mode, clicking on an item in this list
inserts it into the Journal/Book title field. In browse mode the list can
be accessed but items are unselectable (greyed out).

The Keyword field can be upto 254 characters in length and can be used in
any manner you wish, with or without separators between words. A menu
list of keywords can be called up by an adjust click on the menu button
to the right of the field (see section 7, for information on how to edit
this list). Clicking on an entry, when in the edit/add mode, inserts the
selected entry into this field. As many keywords as the field can hold
may be added from the list. An "adjust" click inserts the item and holds
the menu open for another selection. Using this list aids in consistency
of keyword use and saves a bit of typing.

* "How do I start adding references...?"
Clicking on the "Add" button will clear the card ready for input. The
cursor will be initially in the Author field but can be moved to another
field by clicking into it or using "Tab" or "Return" to step through
fields sequentially.

The left/right cursor keys move within a field with shift or ctrl
effecting larger steps. Text in the longer fields will word wrap and
scroll as necessary. Shift-Tab moves to the previous field. Ctrl-U clears
a field and other standard RISCOS protocols apply.

"Page up/down" or shift up/down arrows will allow browsing through
records, mimicking clicking on the forward/back buttons with "select".

* "How can I enter several papers which have the same author...?"
A default format card is available, which in the add mode (click on add
record button), allows authors, title, notes, reference type, copy,
keywords etc. *AS WELL AS* the subset assignments (see defining subsets
in section 2.4.1), to be duplicated over several additions. This is
accessed from the "Main Menu­>Format card­>Edit format" and like the "Add
mode" it clears !Citation windows and closes searches when it is
selected. Remember to toggle this option ON with "Format card­>Use
format". A tick by this item in the menu indicates the format card is
active. *Toggle OFF after use*. !Citation remembers this setting between
sessions.

There is also an option in the format card menu to transfer the current
reference in the browser window, into the format card (shortcut is ctrl-
T). This is useful if you have data within a reference already entered,
that you wish to duplicate over several entries.

1.2 - #ID Numbers
      -----------
Each reference in !Citation is allocated a unique identity number (#ID)
which is indicated in the status window as "No. #xxxx". To ensure that
the #ID numbers are indeed unique they are assigned sequentially as
records are added. Thus for a group of records in which there have been
no deletions, these #ID numbers will run sequentially but as records are
deleted, gaps in the sequence appear, however this will be of little
consequence to the user.

Two options are provided to manage record #ID numbers. "Main Menu­>
Miscellaneous­>Reset next #ID" leads to field showing the #ID number to
be assigned to the next reference added and allows the user to change
this "seed" value. This must be done with EXTREME caution since you may
well end up generating duplicate #ID numbers and there is little error
checking in this routine - alterations require confirmation through a
warning box. Altering this "seed" value may be of use if you need to add
a group of records originating from another application (de-archive or
file import) which require specific #ID numbers, though I am sure other
occasions may present themselves.

The other option, "Main Menu­>Miscellaneous­>Alter record #ID", allows
the user to alter the #ID number of the record currently shown in browser
window. Again caution is advised but this routine checks for invalid or
duplicate number or warns the user that the #ID lies outside the current
range and may be duplicated later.


2. Styles & Output
==================
Output from !Citation can be performed in 2 ways, a) direct export of
data from the currently shown entry and b) output of a group (subset) of
selected citations from the library. The way in which the output from
either of these operations is formatted is dictated by *REFERENCE TYPES*
and *CITATION STYLES*.

2.1 - Reference types
      ---------------
The essence of !Citation is the ability to output references in any
desired format. This is achieved by allocating each entry one of 11
reference types and assigning each reference type a separate definable
style (see section 2.2). There are 11 reference types namely:

 Journal Article
 Review Article
 Book
 Book Section
 Edited Book
 Periodical Article
 Conference Proceedings
 Thesis
 Personal Communication
 Generic 1
 Generic 2

When !Citation outputs a record it looks at its reference type and uses
the corresponding user defined style. This process therefore
automatically takes into account the different output required for
journal and book styles which use different fields to derive information
and have different text prompts within the final reference.

Reference types are allocated when a reference is added to a library by
using the menu attached to the reference type button in the main browser.
The default is "Journal article". Note that the fields (and prompts)
which are presented in the browser window change according to the type of
reference selected. Non-relevant fields are hidden but their contents are
preserved (and will not be used unless the style script accesses them) in
case the user reassigns the type. Most of the types are self explanatory
however some need expansion.

"Book" is for non-edited books with just an author and title or which are
part of a series.

"Book section" is for citing sections within edited books with author of
the section first, followed by item title, book editors and book title.

"Edited book" is for citing edited books which are part of a series of
books. The book author is first, followed by book title, series editors
and series title.

(The correct use of these above types is explained in more detail in the
document "BookType".)

"Periodical article" is for citing and newspaper or magazine articles.

The "Generic" reference types show all fields in the main browser window
and may be used for any reference types which are not covered. They are
obviously associated with the corresponding "Generic" styles.

2.2 - Defining Styles
      ---------------
Styles are defined in the the !Citation style window ("Main
Menu­>Citation style", see also the !Draw file "style"). Here you will
see all the styles which correspond to the reference types mentioned
above plus three additional styles which will be explained later. Any
format desired (until someone proves otherwise) can be defined using a
simple script language. Each style set is saveable and can be given a
name.

2.2.1 - Script language
        ---------------
!Citation uses a simple script language to define each style and access
the appropriate field. The commands are (note lower case and exact
spelling):

     Command          Output (mnemonics in capitals)
     -------          -----------------------------
     abs              ABStract field
     title            item TITLE
     idn              unique ID No. as #xxxx
     cdau             CarD AUthor field direct from entry (unformatted)
     auth             AUTHors formatted according to author style options
     itau             In-Text AUthor format
     joti             JOurnal TItle
     bkti             BooK (series) TItle
     coti             COnference TItle
     cform            Communication FORM
     degr             DEGRee type
     supv             degree SUPerVisor
     univ             UNIVersity
     edr              EDitoRs field
     volm             VOLuMe field
     pgs              PaGeS field (affected by page no. abbrev options)
     stpg             STart PaGe only (overrides page abbrev. options)
     date             Obvious really!
     edtn             EDiTioN field
     pub              PUBlisher field
     place            PLACE field
     isbn             ISBN/location field
     keys             KEYwordS field
     flda             FieLD A
     fldb             FieLD B

     *                Tab char [09]
     ¶                New line Alt-R [inserts LF]

They are mostly self explanatory and there is little restriction in the
way commands can be be entered as long as they are lower case and bounded
on either side by a space character, brackets or punctuation (which
includes * and ¶). The commands can be used in any order and may also be
combined with text prompts (e.g. "Editors:", "Edition:", "In:" or
"From:") which are required in the final reference output. Where the such
a text prompt is similar to a command word (e.g. "Pgs" as an abbreviation
for "Pages" versus "pgs", the command to access the page number field),
!Citation only recognises the lower case form as a command word so that
the form, ".. Pgs: pgs, .." is perfectly acceptable in a style script.

To explain the process further, consider the style script:

           auth (date).¶title¶{italic on}joti{italic}¶volm;pgs

This would output the formatted authors followed by a space, date in
parentheses followed by a full-stop, new-line, title field, new-line,
curly brackets containing the words "italic on" followed directly by the
journal field and "{italic}" again. A new-line is inserted before volume
number which is followed by a semi-colon and page numbers.

Anything which !Citation encounters in the script which is not a command
word or "*¶" is simply included in the output at the appropriate place
i.e. all punctuation (including spaces), text prompts and strings like,
{italic}.

Note that the expressions in {curly brackets} are text formatting
commands (or "effect tags") recognised by Computer Concept's Impression
package as part of a Document Description Format (DDF) which allow
automatic conversion of the enclosed text into the specified style (see
CC's Impression/Style manual - "Advanced Search and Replace" or set up
some styles and export the text story with "Styles Set". The exported
text will indicate the correct format). Thus in this case, the "journal"
field will be italicized - a requirement of some journals (see also the
DDF directory in the accompanying "Docs dir" for a slightly "off-beat"
explanation of how to get the best out of Impression).

One could equally use Rich Text Format (RTF) or HTML effect tags in the
same way which would be recognised by other packages such as Techwriter,
Word for Windows or Web browsers for Web publishing. An explanation of
these tags however is beyond the scope of this manual and the user is
referred to appropriate texts. !Citation in fact offers an easy way of
automatically inserting the appropriate italic, bold and underline effect
tags for DDF, RTF and HTML - see section 2.2.6.

The In-text author (itau) command needs slight elaboration. This works
out how many authors there are in a reference (hence the need for
entering all the authors) and then presents the surnames *ONLY*, in an
appropriate format for an in-text citation. If there is only one author
it returns the single surname. For a two author reference it concatenates
the surnames with "and" (or "&" as defined by the option "In-text author
separator", below the main style list) and for more than two authors it
returns the first author surname appended with the selected "et al" flag
eg.

 1 author    -  Bloggs
 2 authors   -  Bloggs and Jones
 2+ authors  -  Bloggs et al

Thus if the "In-text" style definition for a 1986 paper is:

 [itau, date]

 Bloggs JA                                 ->  [Bloggs, 1986]
 Bloggs JA, Jones FC                       ->  [Bloggs and Jones, 1986]
 Bloggs JA, Jones FC, Wilber DF, Henry JK  ->  [Bloggs et al, 1986]

Default styles are written into !Citation and may be recalled at anytime
using "Icon bar menu->Citation styles->default". To restore the last used
styles to the current style window (from the settings file) use the "Icon
bar Menu­>Citation styles­>Restore".

To get an idea of how styles are scripted look at the !Citation default
styles. For each reference type there are appropriate mnemonic script
commands to access fields specific to that type e.g. "univ" accesses the
University field in the Thesis reference type and "cform" accesses the
"Communication form" field in the Personal Communication reference type.
Other fields, such as the "date" and "pgs" commands for the date and page
number fields, are universal. The only slight variants to this theme
are...

 "Book Series Title" is accessed using "bkti" (BooK TItle)
 "Author Editor(s)" uses the general author (auth, cdau, itau) commands
 "Series Editors" is accessed using "edr" (EDitoRs)
 "Periodical" is accessed using "joti" (JOurnal TItle)

The "Generic" reference types in the browser window offer all the
available fields with a generic prompt. Use whichever fields are
appropriate for your non-standard citation and reference them accordingly
in the appropriate Generic style script. The generic field "Source Title"
may be referenced in the script with the command "joti" (JOurnal TItle).

Two facilities are available to make script entry easier. Clicking menu
over the Style window brings up a list of the script commands and
selecting a command by a click enters this command at the cursor.
Remember that an adjust click keeps the menu up for another entry.

Script lines may be duplicated from field to field by putting the cursor
in the "from" field, clicking the "copy" button at the bottom of the
window, moving the cursor to the "to" field and clicking the "paste"
button. This can vastly speed up the construction of a style set.

2.2.2 Special styles
      --------------
Below the main reference type styles are three special styles:

 Card format 1
 Card format 2
 In-text citation

These styles override the reference type attached to each entry and are
useful in certain circumstances. They are active from the card export
button (middle tool pane - see Card Export section 2.3) and the View &
Output subset window (see section 2.4.2).

The Card format styles are for outputting data in a fixed style ignoring
the reference type, for instance generating a reading list and the
default style gives an example of fields prepended by "AU-", "TI-" etc.

The In-text citation style is for dragging author names into your
manuscript as you are writing and the default style is formatted as
[itau, date] though of course may be defined in any manner appropriate
using the script language. Options relating to the "itau" command can be
set from the "In-text author (itau)" option box immediately below style
scripts.

2.2.3 Author format
      -------------
Underneath the "In-text author (itau)" options you will see the author
format option box which affects the output of the "auth" command word.
Author names are a major problem in citations and journals require a wide
range of arrangements with subtle variations. The options here allow for
most of the possible variations encountered though it might require a bit
of experimentation to get the right form. Note that Editor names
automatically follow this Author format as well.

Moving through the options from top to bottom... the first stage is to
decide is the whether to use full first names (provided these have been
entered in the library) or initials. !Citation will convert first names
to initials if the initial option is selected. Use the menu button to
make the selection and note the contents of the adjacent "punctuation"
field alters accordingly. Now select the type of punctuation required
from the menu list provided by clicking on the menu button.

Next select the "Name order" required from the next menu:

 Surname inits
 SURNAME inits    (capitalize surname)
 Inits Surname
 etc.

(note that "inits" also means "first names" if this is selected).

This menu also allows selection of surname capitalization and whether a
comma will be inserted after the surname if the surname comes before the
initials; choose from the menu list. We will call this name order the
*MAJOR* order. Sometimes it is required that the first or last name in a
series of authors is reversed from the major order eg.

 Blogg FG, Williams GT, DS James (major order surn/inits, reverse last)

or

 FG Blogg, Williams GT, James DS (major order surn/inits, reverse first)

In these cases select the MAJOR order and use the adjacent SUBORDER
option to switch the first or last author names as needed (or "OFF" for
no suborder change is required).

In cases where the MAJOR order is inits/surname and the SUBORDER is set
(first or last author reversed order) a comma is occasionally required
after the REVERSED surname. The two options, below the separator, in the
"Name order" menu allow for this...

 Inits (Surname,)
 Inits (SURNAME,)

eg.  Williams, J, KH Bloggs, GF Clopp
or   J Williams, KH Bloggs and Clopp, GF

The brackets indicate that in the MAJOR order, no comma will be inserted
but if the SUBORDER dictates a reversal a comma will be inserted after
the reversed surname.

The "Separator.." option allows definition of the separator character
between complete author names. The menu allows a range of common
possibilities...

  A, B, C  (comma separator)       eg. Jones G, Bloggs F, Flog H
  A; B; C  (semi-colon separator)  eg. Jones G; Bloggs F; Flog H
  A, B & C (comma with last "&")   eg. Jones G, Bloggs F & Flog H
  ... etc.

The letters (A, B or C) refer to a complete author name (Inits/Firstname
plus Surname) which will be in the format defined by the preceding
Initials, Punctuation, Name order and Suborder options. The menu options
containing an "&" or "and" before "C" (e.g. A, B and C) indicate that
this concatenator will be inserted before the LAST author instead of a
comma or semi-colon.

In the case of...

  A, B, C  (comma separator)       eg. Jones G, Bloggs F, Flog H
  A; B; C  (semi-colon separator)  eg. Jones G; Bloggs F; Flog H

... there is occasionally a need to specify a slightly different format
for entries which have ONLY two authors. This usually involves
concatenating the two author form with an "and" of some sort.

For example, 3 authors...

  Jones G, Bloggs F, Flog H

but 2 authors needs to be...

  Jones G and Bloggs F

To instruct !Citation to do this, move to the "Only 2 author" submenu
aside either "A, B, C" or "A; B; C" which presents a list of two author
concatenation options...

  A & B
  A, & B
  A and B
  A, and B

... and select the appropriate format. The yellow "Separator.." menu
field will then show the multi-author separator character "A, B, C"
followed by the chosen two author separator in brackets e.g.

  A, B, C (, and)

or

  A; B; C (&)

This special treatment is only necessary for these first two, comma or
semi-colon separated options, since the remainder all have a last "&"
component which is obviously used where there are only two authors
anyway.

The options below the dash line in the "Separator" menu offer formats for
specialized situations where, for example, individual authors need to be
placed on separate lines or for generating tagged format files.

  A¶B¶C - inserts newline commands as separators between each author so
that they are output as a list..

  A
  B
  C

To complete the listing though, the "auth" command in the style format
will also require a following newline marker to generate a newline after
the last author, C as, auth¶

  A//B//C - inserts a double forward slash between the authors, which
again is useful in some situations where it is necessary to export data
to another application.

  A¶%A B¶%A C - inserts the "Tagged (Refer) format" author tag (%A)
before authors B & C (see section 4.5 for further details on this
format). To complete the effect though, the "auth" command in the style
format will also requires a preceding "%A " and following newline marker,
thus:

  %A auth¶....<rest of tag style>

...to generate:

  %A A
  %A B
  %A C

For references without an author entry the user can select a blank output
(Anon flag - "OFF") or flag the absence with "Anonymous" or "Anon.". This
only affects the author commands (cdau, itau and auth) and not the editor
command which is left blank if no editors are present in the field.

Occasionally journals stipulate a maximum number of authors to be cited
and if this number is exceeded, then how many authors should be shown
before the "et al" terminator. The "More than.. ..then show.." option
allows these values to be set. For example, to conform with the Vancouver
protocol, set the "More than.." field to 7 authors and the "..then
show.." to 3 authors using the adjacent bump arrows.

The truncated author ending can be selected from the adjacent menu
("End truncated authors with...") which allows a choice of "et al" (with
or without full stop), "and/& others" and "and/& x others", etc.
According to the selection these can be can be in italic, underlined
("uline") or plain (no effects applied, except for those which are acting
on the auth command as a whole). !Citation automatically inserts the
appropriate effect tags for the type of output set in the "Style Effects
tags" option in the Preferences window (see section 2.2.6). The "x" in
"and x others" is replaced by the number of remaining authors not cited:

e.g.   J Williams, KH Bloggs, GF Clopp

...with the limit set to 1 and the ending to "and x others", becomes:

       J Williams and 2 others

Note that if the "More than.." option is "OFF" then the truncated author
option is not selectable.

2.2.4 Misc Options
      ------------
Below the author option box is the Misc option box which allows various
other style attributes to be set.

Page number abbreviations offers the options of:

  As Field (OFF)
  Simple 1
  Simple 2
  MLA
  Chicago
  Turabian
  Start only

* Simple 1: end number comprises changed digit(s) only:
   1-8; 12-7; 34-7; 200-4; 210-8; 301-8; 331-9; 445-64
   555-657; 2356-433

* Simple 2: as Simple 1 but numbers ending in teens take 2 digits:
   1-8; 12-17; 34-7; 200-4; 210-18; 301-8; 331-9; 445-64
        ^^^^^               ^^^^^^
   555-657; 2356-433

* MLA: Start numbers in range 1-99 have end numbers quoted in full. 100+,
all end numbers are 2 digits or more, with a leading zero if required.
   1-8; 12-17; 34-37; 200-04; 210-18; 301-08; 331-39; 445-64;
                      ^^^^^^          ^^^^^^
   555-657; 2356-433

* Chicago: Complex with many variants! The 1995 version of the Chicago
style manual states:
Start numbers in range 1-99 have end numbers quoted in full.
Start numbers on the hundreds boundary have end numbers quoted in full.
101-109 (in hundreds) use simple abbreviation.
All other end numbers are 2 digits or more as necessary.
   1-8; 12-17; 34-37; 200-204; 210-18; 301-8; 331-39; 445-64
   555-657; 2356-433

* Turabian: a Chicago variant that uses full end number for start numbers
4+ digits long which have more than 2 changed digits!
   1-8; 12-17; 34-37; 200-204; 210-18; 301-8; 331-39; 445-64
   555-657; 2356-2433
            ^^^^^^^^^
* Start only: inserts the start page number only.
   1; 12; 34; 200; 301; 331; 445; 555; 2356

Note there is also a "start only" script command for awkward journals
that insist on mixing page numbering styles.

For the abbreviation options (Simple1/2, MLA, Chicago, Turbanian and
Start) to function correctly the FULL page reference needs to be entered
in the page field as two complete page numbers separated by a standard
hyphen (ASCII decimal 95) with no intervening spaces. !Citation validates
the field before attempting to abbreviate the page numbers. Invalid
fields are rejected and "*PGN ERROR*" appears in the output to flag the
offending entry for correction. The following cases will generate such an
error:

  * a blank field (unless enclosed in LICE brackets, see section 2.2.5)
  * a hyphen only
  * a missing start number e.g. -453
  * a missing end number e.g. 329-
  * start number less than end number e.g. 329-53

Exceptions to this standard pgn-pgn format which do not generate an error
are:

  * start and end numbers which are identical e.g. 345-345
    (but only one number is output, as in 345)
  * fields containing only one page reference e.g. 675
  * mixed alphanumeric fields with NO hyphen e.g. 233 pages
  * Roman numerals are not abbreviated e.g. iii-v
  * mixed alpha-leading-numeric ARE abbreviated e.g. S223-34
  * mixed numeric-leading-alpha are NOT abbreviated e.g. 183a-194a

If the adjacent option "En-dash" is selected, then the standard hyphen in
page numbers is automatically converted to an en-dash character (ASCII
decimal 151) which is more appropriate, typographically, for number
ranges.

The numbering style option used for generating a numbered reference list
e.g.

 1. Bloggs FG, Jones JK etc.
 2. Williams GH, Jenkins DF etc.
 3. Dillon CB, Watson J etc.

Various numbering styles are catered for which should cover most needs.
Note that numbering only operates for citations generated from the "View
& Output subsets" window and has no effect on the output from the
"Export" icon in the tool pane.

The adjacent "Start at.." allows the user to give an offset start number
in case references are exported in blocks. Clicking on the bump arrows
increments or decrements the value. The mouse "Select" button does this
by a value of one and the "Adjust" button by a value of 10. Setting the
numbering style to "OFF", resets the start offset back to "1". The start
offset is NOT saved in the settings or style files and is always reset
back to "1" on load-up.

The "Strip (issue) nos." option is particularly useful for database
imported files which add issue numbers in parentheses to the volume
reference.

eg. volm(issue)

The issue number is often not required in a reference list and selecting
this option will strip them from the volume reference in the final
output.

Source output... !Citation has an editable list of source/journals which
can be selected from a menu whilst adding or editing an entry. The
"journals" file contains the full source name and two user abbreviated
forms (see section 7). The "Source output" option allows the user to
select which form will be included in the final output. It is recommended
that the abbreviated forms include any full stop punctuation required
because these can easily be stripped out, if required, by selecting the
adjacent "Strip full stops" option (see section 7. for more details).


2.2.5 Exclusion brackets
      ------------------
Exclusion brackets are a way of instructing !Citation not to output a
defined section of the style script if one of the fields within that
section contains no data. For example, you might find it necessary to
create a script, particularly for books, which contains a translator
name. You use the spare Field A for the translator name and formulate a
book style as...

 auth (date). title. In: bkti Series Eds: edr. pub place Trans: flda

Now any book cited in your reference list which does not have a
translator will have "Trans:" at the end followed by a blank entry.
Annoying eh... well this is where you can use LICE brackets (Linked
Internal Concurrent Exclusion brackets). Putting the "Trans: flda" in
exclusion brackets forces !Citation to look at the field and if it is
empty, it skips everything between the brackets and strips the brackets
from the output. Exclusion brackets are Alt-Z («) and Alt-X (») or may be
selected from the citation style window command menu. The style script
would be altered thus:

  auth (date). title. In: bkti Series Eds: edr. pub place «Trans: flda»

To summarize LICE brackets:

*   «Text: flda, »
If the nominated field is empty then everything within the brackets is
ignored (as in the above example).

*   «Text1: bkti. Text2, fldb »
If either one of the nominated fields (bkti, fldb) is empty then
EVERYTHING within the brackets is ignored, even if the other field
contains data. They are 'mutually reliant'; you either get the both of
them or neither, hence the term "Linked Internal Concurrent". This can be
extended for any number of nominated fields contained within the span of
the brackets , i.e.

     «auth , title., (Place: pub, date) isbn»

In this example, if the 'isbn' field is empty then everything (including
the punctuation) will be ignored. There is no limit to the number of
paired of exclusion brackets entered into in a style script:

     «auth» , title., («Place: pub, »date) «isbn»

However NESTING brackets is not allowed and may give unexpected results.

i.e.     «Text1: joti ,«Text2, fldb »»  *NOT ALLOWED*

If you do nest or miss a bracket !Citation will flag a warning before you
leave the style window.

2.2.6 Italic, bold & underline effect tags
      ------------------------------------
The inclusion of effect tags in a style script has already been mentioned
in section 2.2.1 where the example script:

           auth (date).¶title¶{italic on}joti{italic}¶volm;pgs

... contains DDF effect tags to italicize the journal name.

A similar process can be used for entering effect tags in RTF and HTML
formats which allows !Citation output to be used in DOS/Windows programs
and material intended for Web browsers as well as Icon Technology's
!Techwriter. This however requires some knowledge of the effect tags used
by these formats as well as the correct file typing so that the receiving
application can interpret the data correctly.

!Citation offers a facility to handle these tags automatically once they
are entered into a style script and ensures that the output is of the
correct file type to be understood.

* "OK so how does it work...?"
Effect tags are an extension of the standard script commands and are
entered into the style script on either side of the item to which the
effect is to be applied. There are 3 pairs of commands which are enclosed
in curly brackets:

 {bti}  Begin Tag Italic
 {eti}  End Tag Italic

 {btb}  Begin Tag Bold
 {etb}  End Tag Bold

 {btu}  Begin Tag Underline
 {etu}  End Tag Underline

The "Begin Tag" command is placed where the effect should start and the
"End Tag" command is placed where the effect finishes. Thus in the
example script:

    auth (date).¶{btb}title{etb}¶{bti}joti{eti}¶{btu}volm;pgs{etu}
                  ^^^       ^^^   ^^^      ^^^   ^^^         ^^^

... the title output will be *bold*, the journal output *italic* and the
volume and page numbers *underlined*. Note that the tags are placed
immediately before or after the commands they pertain to, spaces are not
necessary but may be inserted if the output format demands it. Text
prompts enclosed within the tags will also be affected:

    auth, title., {bti}(Place: pub, date){eti} isbn
                   ^^^                    ^^^
In this example the word "Place" as well as the publisher and date will
be italicized.

Once the style scripts have been set up it is necessary to tell !Citation
what type of output your receiving application can handle so that the
!Citation's tags can be replaced with by the appropriate tags for that
format. Access the "Preferences" window from the icon bar menu and select
a format from the "Style Effect Tag" list, either DDF, HTML or RTF (the
"Text" option ignores any !Citation tags in the scripts, effectively
switching-off all effects in the output).

With DDF, HTML or RTF selected, any output from the "Card Export" button
or the "View & Output Subsets" window will have the necessary style tags
inserted and the file set to the appropriate file type. The "Finds"
output from the General Search window always ignores effect tags and
produces a standard text file.

Options are also available in the Citation style window to use italicized
"et al" output to indicate author truncation. This process also uses
effect tags and requires an appropriate "Style Effect Tag" setting in the
"Preferences" window to be operational.

It should be stressed that !Citation only inserts effect tags in the
output and it depends on the receiving application to apply the
appropriate effects. If your receiving application does not support the
file type it will probably ignore the input or it may receive the data
but fail to interpret it correctly showing your reference containing odd
bracketed text commands.

Note: If a DDF/RTF/HTML effect tag occurs at the end of a reference,
whether inserted directly by the user or translated from a !Citation tag
e.g.

    auth, title., {italic on}(Place: pub, date){italic}
                                                ^^^^^^
... !Citation automatically adds a trailing space to the output. This
ensures that the effect in Impression or !Techwriter is terminated
otherwise the effect is carried over onto the following text.


2.2.7 Saving/Loading styles
      ---------------------
Once a set of styles have been created they can be saved from the "Icon
bar menu->Citation styles->Save style" so the user can build up a set of
frequently used styles. To import saved style files, drop them onto the
load icon in the Citation style window. The current styles are also saved
in the settings file on shut down and may be restored at any time in the
next session with "Icon bar Menu­>Citation styles­>Restore".

2.3 - Card Export
      -----------
Dragging from the Card Export Button (green arrow, mid-tool pane) exports
data from from the current entry. This is useful if you have !Citation
running as you are are writing and want to insert the currently displayed
entry into a manuscript or add to a reference list.

Four style options are available for this output:

  In-text citation
  Card format 1
  Card format 2
  As type

These are selected from the "Main menu->Card export" and these styles are
defined in the Citation style window (see section 2.2). The "Card Export"
menu may also be called up by clicking menu on the Card Export Button
which allows a quick change of type before dragging.

"In-text", "Card format 1" and "Card format 2", are special styles since
they override the reference type style. "As type" uses the reference type
style as defined in the Citation style window.

The use of "In-text" has already be explained but what of the other two?
Well, it may be that you wish to quickly export all the data on a card or
just one field for a quick visit to the library or for some one
requesting a particular reference. The Card format styles can be defined
to any sort of output without interfering with any of the reference type
styles... use as you will but I thought it was a good idea!

Incidentally, "Adjust" dragging (3rd button on the mouse) will *ALWAYS*
export the current reference "As type" so that you can easily add the
full current reference into the bibliography without having to alter the
"Select" drag option each time.

An option is also available for the direct export of "Abstract" data to
allow easy editing. Open the Abstract window by clicking on the Abstract
button in the main browser card and click menu (this only works in the
Browse mode and is disabled in the Add/Edit mode). This brings up a save
window for dragging the data out to file or directly into an editor. Data
can be saved back into the abstract window in Add/Edit mode by dragging
selected text directly from and editor or by dropping a file into the
window.

In fact data can be entered/added to any field in the browser window by
dragging a file or data into the appropriate field. However, this only
works if !Citation is in the Add/Edit mode. Field import is ignored in
the Browse mode.

Data imported in this way replaces the existing contents of the field
unless the "Add on field import" option is selected in the "Preferences"
window in which case it is appended to the end of existing data.

2.4 - Generating citations for final output to a technical paper
      ----------------------------------------------------------
This comprises three parts a) defining styles for the output references
(see above), b) selecting which references within the database are for
output and c) generating the output set.

2.4.1 - Selecting references for output
        -------------------------------
!Citation uses the idea of "Subsets" to select which references are for
output, such that any record in the library can be included in a "Subset"
of references. This simply means that each record holds a flag (actually
5 flags) which indicates whether that record is a member of a particular
Subset.

There are up to 5 Subsets (hence 5 flags, numbered 0 to 4) and any record
can be a member of any one or more of these Subsets or have no subset
designation. The Subset status for any entry is shown in the tool pane
and is updated as the user browses the library. A reference is included
in a Subset if the button by the Subset number (0 to 4) is ticked.

To select a Subset of references for output, browse through the library
to find the desired references and click on a Subset button to include
that reference in the chosen subset. With 5 Subsets, the user can have
say, 5 papers on the go at any one time each defining a discrete Subset,
though of course any one record may be a member of several Subsets. This
method, particularly in combination with the various search options (see
below), allows references to be easily added or removed from a Subset.
The "Clear subset" option (Main Menu­>Citation subsets­>Clear subset(s))
will clear any selected subset of ALL designations - use wisely.

It is thus essentially very easy to build up a Subset but what about the
output order? In most cases journals require references to be arranged in
alphabetical order which can be performed automatically by !Citation but
what about those that require references to be arranged in a particular
order - usually the order in which the references occur in the text? This
is where the "Order value" comes into play. The Order value window is
called up through "Main Menu->Subsets->Order value" or using the hot key
"ctrl-O" or clicking "select" on the *subset numbers* adjacent to  the
subset designation buttons.

The Order value is simply a value which indicates to !Citation the order
which the user would like the references to be arranged on output - note
it is *NOT* the number which is printed by the reference on the final
output but a value which determines the order in which references are
organised in the final output. Thus the Order values do not need to be
consecutive eg. if ref1=(10), ref2=(20), ref3=(15) the output will be...

 1. ref1
 2. ref3
 3. ref2

In fact the bump buttons in this window can increment in steps of 1 or 10
depending on whether the are "select" or "adjust" clicked and it is
recommend that the user uses large steps so that is is easy to go back an
insert or reorder the references as the paper evolves.

The process of setting the Order value is an extension of selecting the
record as a Subset member. Once the Subset button is ticked the order
field becomes available (ie. goes yellow). You should see the cursor in
this field, if not click in it to put the cursor there, then either use
the bump buttons to increment/decrement the value (0 to 999) or enter a
value manually. The user only needs to click on the "Save" button (in the
tool pane) to update the entry if manually entering a number into Order
value. Clicking on the bump buttons updates the record automatically.
Once the Order value is given move on to the next record...and so on.

The Order value can more easily be set by using the "Scan manuscript"
option which can scan a text file of the manuscript to put references
into a specified subset and set the order value in order of occurrence
(see section 5).

Note that if the user only requires an alphabetical output the Order
value can be ignored. The Subset selection buttons and Order values for
an entry can be changed at anytime and are stored with the entry until
the Subset is cleared.

2.4.2 - Generating the output subset
        ----------------------------
We now have a citation output style and a Subset (or more) defined and we
can output the Subset to the paper. Opening the "Main Menu­>Citation
Subsets­>View & Output" window (or hot key ctrl-V) shows a blank selector
window headed by the menu options "Range?" and "Order?" (see also !Draw
file "sets"). Use the range menu to select a Subset and the Order menu to
select an output order (#ID number, Alphabetical, Order value or Date).
Alphabetical ordering is based on the author's surnames/initials in turn
and then on the date. Once selections are finished, hit the "Go" button
(or the Return key).

!Citation will search the library and present all the matching records in
the selected order in the selector window. This may be browsed using the
scroll bar and clicking on a line brings the corresponding entry into the
main browser window where it may be viewed or edited. There is also an
option in the "Range?" menu to select all the records in the library
which is useful if you need to view the whole library in list form.

The subset is now ready for generating an output file but first the user
must select the desired output format. There are four options in the
"Output subset as..." menu:

 As type
 Card format 1
 Card format 2
 CSV subset

The "As type" output looks at the reference type of each entry and uses
the corresponding style in the same way as the Card export Button does
when set to "As type". For a numbered reference list ensure that the
"Numbering style" option in the Citation style window is selected.

The "Card format" output overrides the reference types attached to each
entry and applies the selected card format style to all entries. This may
be useful for generating say, a reading list in which all the references
must conform to a one particular style, irrespective of whether they are
a book or journal type.

Note that the Author and Misc options set in the Citation style window
will be active on appropriate fields in both of the above options.

The "CSV subset" output creates an archive file from the chosen subset
and is useful for pulling selected references out of one library for
inclusion into another or for sorting out references from a temporary
library created by importing on-line data.

The final step is to click on the Generate subset button (yellow icon to
the right of "Output subset as..." box) and a save box is shown for the
user to drag the set to file or directly into the manuscript.

Note that once !Citation has gathered a Subset into the selector window,
altering the Subset designation of a record to include/exclude it from
the list will have no effect until the "Go" button is clicked again.
Changing the Subset or Order options in the window with a subset active
has the effect of clearing the Subset and clicking "Go" re-initializes
the subset.


3. Searching
============
Three forms of searching are supported a) First Author, b) Record #ID
number and c) General Search (see also !Draw file "search").

3.1 - First Author
      ------------
!Citation maintains an index of First author names as they are entered
which allows very rapid searching. Opening the search window (Main
Menu­>Search­>1st author) shows a yellow string entry field. Click in
this field and begin entering the surname. Each letter is grabbed by
!Citation as it is entered and the library updated to the nearest match.
If the sequence of letters thusfar entered (which need not necessarily be
the whole name) is not found then !Citation bleeps and flags "Not found"
in the status window. The arrow buttons on the search card ("A to Z
browse") allow alphabetical browsing of the library either around your
found surname or if the search field is empty, through the whole library.
The user can, in this way, search for an author and once found browse
round papers by the same author.

If there appears to be a problem with the alphabetical ordering it may be
because the author index has become outdated. This may occur after
multiple file imports or entry deletes. In this case re-index the library
using the "Re-index" option on the "Icon bar->Maintenance" menu - this
doesn't take long. An out-of-date index does not affect subset generation
since this creates its own new index each time.

If this fails, check that your author fields do not contain leading
spaces by entering a space into the search field. If this finds an entry
then the author field has a leading space. Switch into edit mode and
remove the space and then use the alpha browse keys to find any others.

3.2 - Record #ID No.
      --------------
This simply accesses any record by its unique #ID number so that the user
can go directly to any reference. The card number is entered into the
entry field and pressing <Return> activates the find.

3.3 - General Search
      --------------
For more extensive searches, including all Authors, Keywords, Sources and
Subject (ie. Title, Keyword, Field A and Field B fields combined) use the
general search option (Main Menu­>Search­>General Search) or hot key
ctrl-S.

The "Range?" menu on the general search card is self evident. "Authors"
searches ALL authors (unlike the first author search) and "AuthorCS"
performs a case sensitive search. "Subject" searches Title, Keywords,
Field A and Field B for the search string. "Keywords" searches keywords
only - useful for defining a Subset. The search string is case
independent (except for AuthorCS) and the search performs a simple but
flexible - "does the field specified in the search range *CONTAIN* the
search string".

This window bears some similarities to the "View & Output subsets" window
in that, after selecting a range, a search string is entered and "Go"
clicked (or <Rtn> pressed). The finds appear in the selector window which
can be scrolled. Clicking on a line brings the corresponding entry into
the main browser window.

Like the "View & Output subsets" window clicking on the "Range?" option
with an active search, clears the window and you must use "Go" to
reinstate it or enter a new search string.

The find list can be exported to file by clicking on the "Save finds"
button at the bottom of the window. Note that the style of output is
dictated by the "Card Export" setting, so you can choose "In-text", "Card
1", "Card 2" or "as type" which are defined in the Citation style window.

The "Add to subset..." option, adds all finds to a specified Subset but
does not provide an Order value. This is useful if the user has a group
of records characterized by a specific term in the subject or keywords
fields. These can be searched out and added to a Subset ready for output.
An order value can be added by selecting the Subset using the "View &
Output subsets" option with alphabetical ordering and stepping though the
Subset updating the Order values as necessary.


4. - File import
================
The file import window is accessed from the "Main Menu->File import".
This window is used for importing several "foreign" file types, namely:

 1) !Citation archive/subset CSV files
 2) 5-line text files
 3) Reprint/Medlars format files
 4) BIDS/ISI files (with and without case conversion)
 5) Tagged text files

The specifics of the different import types will be addressed below but
here are some general principles. Dragging a file to the load icon within
the window activates the import process. CSV type files are automatically
detected and assumed to be a !Citation archive or subset files. The
window also accepts DOS type and TEXT type files but the form of import
desired has to be specified using the "Import type" menu. The import
routine automatically handles the extra [CR] in DOS files so you do *NOT*
need to strip out these extra characters. If a valid file is dropped then
the status window responds with the file name and the current type of
import and waits for a click on "Go".

Importing is multi-tasking with progress shown in the status window.
Clicking on "Cancel" during the import aborts the operation at the next
appropriate place in the import loop and thus might take a second or two
to show a response. The menu option and close the window button are
disabled until import is complete or aborted and similarly some !Citation
functions are unselectable to prevent operation clashes. Line lengths
over 254 characters, in all cases, will cause the import to abort but it
will be most unusual to encounter such long lines, even for on-line
citation database derived material.

It is strongly recommended that you don't edit your on-line database
derived file manually in a text editor before importing. These files are
quite complex and the import routine is tailored to find specific start
and end markers which may be lost during editing. !Citation automatically
sorts through Email headers etc. if present. If you wish to sort through
a bulk of references it is suggested that you create a temporary library
for the initial import and browse this temporary library putting the
selected references into a subset. Once you have all the references you
need, use the "Main menu­>Subsets->View & Output subset" window to
generate a CSV subset of the these references and *THEN* import them into
your main library.

Now to the specifics....

4.1 CSV Archive and Subset files
    ----------------------------
Archive files are generated from the "Icon bar menu->Archive Library"
option and essentially output the whole of the active library to a CSV
file with a !Citation header (see section 6). This is useful for
combining libraries or upgrading to a later version of !Citation which
may have a different data structure. Similarly, subset CSV files are
generated from the "Main menu->Subsets->View & Output" window and allow
the export of a subset of the active library to a CSV file. This is
useful for sorting out references from a temporary library before final
import into your main library. CSV files are automatically assumed to be
!Citation generated and the header is checked for type (archive/subset)
and the user notified through the import window before import is
accepted. The import type setting is ignored once !Citation has detected
a CSV type file and import proceeds once the user has clicked on "Go".

4.2 "5"-line text file import
    -----------------------
This is a useful option, as described in the introduction. Personally I
keep a list of my current references in a text file on my Psion/Pocket
book as a plain text file, adding to this list as I come across new
references. This saves long typing sessions and keeps me organized...!

The entry format of the 5-line files is simple. Open your text editor and
on the first line type in the authors in the standard format (see section
1.1). At the end of the line press <return>. On the next line enter the
Item title followed by a <return>. The next line should be the
journal title, volm, pages, yr; each separated by a comma with no
intervening space followed by a <return>. The final line of the entry is
optional and can be a short note up to 254 characters again followed by a
<return>. To indicate the end of a data block enter a hash character (#)
and <return>. The author line of the next reference now can be entered on
the next line... and so on. The last reference of a list should be
followed by a single hash character and <return>.

Thus a 5-line file has the following format:

...start of file
au,au,au[LF]
title[LF]
journal,volm,pages,yr[LF]
notes[LF]
#
au,au,au[LF]
title[LF]
journal,volm,pages,yr[LF]
notes[LF]
#
[last data block etc]
#
...end of file

Note the "return" character (CR/LF for DOS files) after each line and
hash character after the last line of the last reference. The authors and
source lines are formatted as *COMMA SEPARATED VARIABLES* and the order
of the source line *IS* important (journal,volm,pages,yr). The "notes"
line is optional and !Citation will accept a 3 line entry as author,
title and journal (see the accompanying "fv_line" file for an example).
The 5-line format however doesn't cater for the extra book fields in the
database which will have to be entered directly into !Citation or use the
"Tagged text" file format (see below).

* "How do I import my 5-line text file...?"
Open the "File import" window, ensure the 5-line text import option is
selected and drag your text file onto the load icon. You will be informed
that the file format will be checked first and given the option to
continue or cancel. I have found, from experience, that despite this
simple file structure it is easy to put an extra CR/LF in by mistake or
forget to put a hash character between references which would cause the
fields to be entered out-of-step. The other common mistake is to put
spaces after the separator hash and the problem is you cannot see them on
most text editors.

To prevent this !Citation checks that each entry comprises 3 or 4 lines
followed by a hash. If variation from this format is detected, an error
is flagged with an indication of roughly (+/- 1) in which entry (data
block) the error lies. Check the file at the indicated place, correct the
error and begin the process again.

If the format is correct then the user is asked whether to continue with
the import. The error checking routine is fairly rudimentary and aborts
on the first error encountered. It might require several runs to debug a
file that contains multiple errors but this is better than having all the
fields out-of-synch. Importing occurs at about 40 references/min on an
ARM3 (time for a cuppa!) but should be faster on newer models.

4.3 Reprint/Medlars import
    ----------------------
The "Reprint" format is a "standard" used by some computerized journal
databases specifically for importing into bibliography managers, in
particular those using "Ovid" software. Medline and BIDS both use an Ovid
interface and you should ensure that the "Reprint/Medlars" output option
is selected when you save search data. If you cannot find the correct
option, get your IT co-ordinator to show you how to set it.

You can select all sorts of data to output to a "Reprint" file but as
long as it is in the "Reprint" format and contains a "Unique Identifier"
field, !Citation will sort through it and extract only the fields needed.
Like all "standards" it has variations and the Medline Reprint/Medlars
version outputs the article source data in a slightly different format to
that of BIDS Reprint/Medlars but !Citation will recognise both from the
"Reprint" import setting. Example files are included with this package.
Sometime the source output really is uninterpretable in which case this
is flagged in the source field.

Starting the import is the same as for the "5-line text" files but select
the "Reprint" import type BEFORE dragging the file to the load icon. DOS
file types are also accepted so there is no need to reset the type or
remove [CR] characters. Confirmation for import is requested and then the
whole file is directly imported on the assumption that, being machine
created, there is no need to pre-check.

The start of data block marker is "UI  -",  which stands for Unique
Identifier and should be present as the first line in all Reprint
formatted records. If there is an option in your computerized database to
select which data is output, ensure the Unique Identifier field is
included or !Citation will not be able to find the start of a reference.
The end of data block marker is the blank line which follows the last
line of the reference.

4.4 BIDS/ISI "DownLoad" import
    --------------------------
The Bath Information Database (BIDS.ac.uk) is a multi-disciplinary on-
line database. This section refers to the original ("clunky" - users will
know what I mean!) telnet BIDS interface which offers a "DownLoad" format
option. They now also offer slicker, Ovid telnet and Ovid Web-browser
search interfaces - for these use the "Reprint" import option. Example
BIDS output files are included with this package and the document,
"BIDS_info" explains acceptable file formats. Data is usually received
via screen capture or E-mail and !Citation will accept both file types
unmodified.

The reference (data block) start marker is "Record -" and the blank line
following a reference, indicates the end. The medical database (embase)
outputs data in appropriate lower case format but other databases seem to
use upper case fields only. This is rather inconvenient so there are two
options for import. The "BIDS/DownLoad" import type just extracts the
fields and enters them directly into !Citation but the "BIDS/DL +Case"
option attempts to convert the fields to lower case before they are
entered into !Citation. Obviously there are limitations to what !Citation
can do in this respect and whilst authors surnames/initials can be
converted reasonably accurately and even Journal names are mostly
formatted appropriately the Title fields are all lower-cased bar the
first character. This means that chemical symbols and proper names in the
title are also converted and may need changing after import.

The import process is similar to that described above. Select either
"BIDS/DownLoad" for direct (unconverted) import or "BIDS/DL +Case" for
lower case conversion and drop the file onto the load icon. Check that
the details are correct in the import status window and click "Go" to
begin the import (or "Cancel" to abort).

There are quite a lot of fields in the full BIDS output and all those
which tally with !Citation fields are directly inserted. Extra fields
which have no direct !Citation equivalent are placed into "Field A" or
appended to the abstract. See the BIDS_info document for more information
about the file format and translation.

4.5 Tagged (Refer) text files
    -------------------------
The tagged text files are simple text, extending the facilities of the
5­line format by allowing the entry of book references as well as journal
type articles. They can be generated in any text editor to hand and are
based on the "Refer format" used in other bibliography managers. Each
line begins with a field tag, which is a percent sign (%) followed by a
single letter identifying what kind of information is held in the
following text. eg.

...start file
%A Eustace S
%A Suojanen J
%A Buff B
%A McEniff N
%A Januario J
%A Norris C
%T Pre-operative imaging of esthesioneuroblastoma
%J Clinical Radiology
%V 50(9)
%P 639-43
%D 1995
%@ 1234-5677
%K MRI, PNET, surgery
%1 too many long words... avoid at all costs
#
%A Gotsis ED, Fountas K, Kapsalaki E, Toulas P, Peristeris G, Papadakis N
%T In vivo proton MR spectroscopy: The diagnostic possibilities of lipid
resonances in brain tumors
%J Anticancer Research
%V 16(3B)
%P 200-208
%D 1984
%@ 3252 345 2345 245
%K proton nuclear magnetic resonance, lipid, brain tumor/diagnosis,
Alzheimer's
#
... end file

Each entry line is ended by a return character and each complete
reference is separated by a hash (with no following spaces). Note that
the author line (%A) may be spread over several lines or concatenated
into just one line with comma separators in the usual entry format (see
section 1.1).

The tags, with mnemonic keys in capitals, are:

 %A Author(s)
 %T item Title
 %J Journal title
 %I Issuer/publisher
 %C City of publisher (place)
 %E Editors
 %B Book (series) title
 %V Volume
 %P Pages
 %D Date
 %N editioN
 %K Keywords
 %@ ISBN/location
 %1 Field A
 %2 Field B

!Citation makes a best guess at the reference type from the fields
present within an entry. The default is "Journal Article" but if the
Editors (%E) tag is present, the reference type is set to "Book Section".
If there is no "Editor" tag but the "Issue/publisher" (%I) tag is present
then the type is set to "Book".

There is a 254 character limit on all these fields. An example tagged
file is included in the example data directory. Abstract fields are not,
at present, supported in this format.

To import a tagged file, set the import option accordingly and drop the
file on the import icon. If the status window report is satisfactory,
click "Go".

4.6 Importing & the Format card
    ---------------------------
With all types of file import except CSV, the Format card (Main
Menu­>Format card­>Edit Format) can be used to set the "Copy?",
"Keywords" and "Field B" fields as well as the subset designations of the
imported references to pre-determined values.

Access the format card and set the fields or subsets appropriately and
save the entry. To use these setting during an import, select the "Use
format card settings" option in the file import window and continue with
the import. It should, however, be noted that Reprint and BIDS files
often includes keyword data which will override the format card setting.

4.7 Deleting imports & import errors
    --------------------------------
* "I have imported the wrong file. What can I do...?"
Have a cuppa and calm down... If you import the wrong batch of references
or an error occurs and the file is half imported you can use the "Delete
import" option from the "Main Menu­>Miscellaneous­>Delete import" to
remove all of the last imported references and compact the library. If
you have other deleted records in the library, this process also removes
them - beware... Note this only works within a session. If you quit and
restart !Citation the import pointers are lost.

* "BIDS/Reprint/5-line/Tagged import hasn't worked...!"
If !Citation has accepted and read the file but nothing has been
imported, check that you have the correct import type selected. !Citation
searches for data block markers and 5-line, tagged, BIDS and Reprint
formats all use different markers. With the wrong type set !Citation will
scan the file but will not find anything to import. Next check that your
file is actually in BIDS "download" format or in "Reprint" format and
that the "Unique Identifier" is present in "Reprint" files. There are
usually several download options but one usually indicates its use for
import into bibliography managers. Compare your file against the example
files provided.

4.8 Field Import
    ------------
The user can also directly import text files into the Author, Title,
Notes, Abstract, Date etc. fields of the displayed record by drag'n'drop
on the appropriate field (drops onto the mask between fields will be
ignored). Note that this can *ONLY* be done in edit/add modes. Authors
should be comma separated and in the usual format. If a mistake is made
"Cancel" will reinstate the previous text. Dragged data normally
overwrites the existing field contents but if the "Add on field import"
option in the preferences window is selected (see section 9), dragged
text will be appended to the existing contents.

Note that text can also be *EXPORTED* from selected fields using the
"Card Export" button and one of the Card Format styles containing the
appropriate field (see section 2.2.2). This means that a text editor can
be easily used as a tool for editing long fields, re-importing after
alterations.


5. Scanning Manuscripts
=======================
!Citation can scan a manuscript for in-text references which are then
searched for in the current library, flagged to a specified subset and if
required, given an order value. However, !Citation does not (yet!) alter
the manuscript to insert reference numbers.

The manuscript file must be of Text, DDF, HTML or RTF type, WP or DTP
package files cannot be used directly but as most offer a text or Rich
Text Format output option this presents little problem.

In-text references must be inserted in the form:

 [#0123 - Flogit & Runn, 1986]

... which is the default "in-text" style script, viz. [idn - itau, date],
where "#0123" represents the unique identity number (IDN) for that entry.
To find in-text references !Citation searches the manuscript for an open
square bracket followed by a hash i.e. [#. It then extracts the 4 digit
IDN and searches the current library for that number, flagging the subset
and updating the order value of the appropriate entry accordingly. Thus,
the in-text references *MUST* start with a "[#xxxx" for this operation to
work. The reference text following the IDN can be in any format.

* "OK, so take me through this... slowly."
1) Set the in-text style script in the Citation style window to an
acceptable format e.g. [idn - itau, date]

2) As you write, use the card export function, set to "In-text", to drop
each reference into your manuscript which should look something like
this...

"The rarity of extraneural metastasis from oligodendrogliomas may be
appreciated from the work of Smith et al [#0042 - Smith et al., 1969] who
reviewed 8000 primary CNS tumours in the AFIP files and only found one
truly metastasizing lesion. The first substantiated case of
oligodendroglioma extraneural metastasis was reported by James & Pagel
[#0033 - James & Pagel, 1951] and concerned a 25 yr old woman who
presented in 1945 with a right-sided cystic parietal tumour."

3) Export the finished manuscript to a temporary text/DDF/RTF/HTML file.

4) Ensure the appropriate library is loaded into !Citation and call up
the "Scan manuscript" window (Main menu->Scan manuscript).

5) Select which subset you wish to add the references to by using the
"Add to..." menu in the Scan window.

6) Decide whether you simply want to add the references in the manuscript
to already existing subset designations ("Add to current subset") or
whether you want to clear the subset before adding, so it will contain
only those references cited in the manuscript. This option also sets the
order value of added references to the order in which they first occur in
the manuscript.

7) Drop the manuscript text file on the load icon and click "Go".
"Cancel" will abort the scanning operation. The progress is shown in the
status window.

8) To view the results, access the "View & Output subsets" window and
select the destination subset. All the references cited in the manuscript
will be included and if the order value order is selected they will be
shown in the order in which they first occur in the manuscript ready for
output.

If a reference IDN is found in the manuscript which is not in the current
library, a warning is flagged in the Scan manuscript status window.
Ensure you have the correct library loaded!

A worked example may be found in the eg_data directory, called "ManScan"
with a couple of deliberate missing references. Load the library !glioma
and use the manuscript in the file "TextStory" to try out the process.


6. Archiving
============
Selecting "Archive" from the icon bar menu allows archiving of the
*ENTIRE* current library into a CSV format file (ie. Author, Title,
Source, Date... Abstract). It is also possible to include the identity
number for each reference by setting the "Include #IDN in archives" in
the "Icon Bar Menu -> Preferences" window, though this should be done
with care in case the numbers may be duplicated in the receiving library.

In contravention to the CSV standard, the archive file carries a one line
header which provides general information on the creation date etc. but
more importantly for !Citation, specifies the presence of identity
numbers in the file so that these can be imported correctly. This header
will be transparent in general use and can be deleted if the archive is
not intended for use with !Citation. The default state excludes identity
numbers to err on the safe side.

The first major use of archiving is for the combining libraries. Simply
load and archive each of the libraries you wish transfer, then open the
receiving library and drag the CSV archive files to the file import
window (Main Menu->File import). !Citation will detect that this is a CSV
archive file (rather than a 5-line text or Reprint file) and a warning
will be flagged asking for confirmation of de­archiving. If accepted the
archived data will be added to the end of the receiving library data with
new ID numbers allocated.

The second major use is for "future-proofing" !Citation. Should a later
version of !Citation require a change in the structure of the data file
then data can simply be archived out of the old version and imported into
the new version. If it is necessary to preserve the unique identity
numbers of your old library, select the Preferences option - "Include
#IDN in archives".

Other possible uses include, of course, importing of the whole file into
any application that accepts CSV format files and importing CSV data into
!Citation. In the former case, remember to delete the one line header or
substitute it for a CSV description header before importing into your
alternative application.

Importing a generic CSV file into !Citation, is not recommended.
!Citation expects the file to be machine created and so minimal error
checking is employed on de-archiving. As you can see from the example
Archive files (load it into !Edit), it is quite complex and easy to make
errors if manually created. If you do attempt CSV import, make a backup
of the receiving library first!

Archives also allow global changes to be made to a library - for example
a text editor could be used to remove extraneous full stops from the end
of title fields or spelling could be checked in a word processor.


7. Keywords, Journals & Abbreviations lists
===========================================
The Journal and Keyword files are automatically loaded by !Citation each
time the application is run. The Journal file can contain a list of your
"favourite" journals and can be accessed in !Citation by clicking select
over the menu button at the far end of the Source/Journal/Book field (see
!Draw file "Browser"). Select the Journal name and click to insert the
name into the Source/Journal field.

!Citation also supports abbreviations of the source names for output eg.
"Proceedings of the National Academy of Sciences USA" is often
abbreviated to "P.N.A.S.(U.S.A.)". To achieve this, each entry in the
"journal" file comprises three parts. First the full name (as appears in
the selection menu), followed by abbreviation 1 and abbreviation 2,
separated by ">" all on *ONE* line and terminated by a <Return> eg.

Proceeding of the National Academy of Sciences> Proc. Natl. Acad. Sci.
USA> P.N.A.S(U.S.A.)

(this is all on one line)

The recommended arrangement is to have abbreviation 1 as the "longer"
abbreviation with abbreviation 2 as the minimal abbreviation. This
arrangement is important since *ONLY* one abbreviation type can be
selected for output and journals tend to stick to the full, medium or
short format. The user *CANNOT* shuttle between abbreviations on output.
Include full stops in the abbreviations wherever appropriate as there is
an option for stripping these out if they are not required in the final
output. Up to 150 journals can be accommodated in the list.

* "How do I add to, or alter this journals file...?"
Clicking on "Icon bar menu->Journal & Keys->Edit journals" loads the
journal file into your default editor (usually !Edit - see the RISCOS
manual for how to use this program). After editing the file use the
editor's "Save" option and *RELOAD* the journals file using "Icon bar
menu->Journals & Keys->Reload journals" to see the changes in the
!Citation journals/source selector window.

* "What about journals that don't need abbreviations or only have one
reasonable abbreviation...?"
Well in fact, the abbreviations are optional and if !Citation doesn't
find any it automatically copies over the full name to the abbreviation
fields eg. "Nature" only requires a single line entry with no
abbreviations and both abbreviation fields are automatically set to
"Nature". If there is only one abbreviation then this is also
automatically copied to the remaining abbreviation field and thus only
requires two source names on the single line eg.

 Journal of Endocrinology> J. Endocrinol.

"J. Endocrinol." is automatically copied over to the remaining
abbreviation field.

* "How do I implement these abbreviations in my output...?"
Look at the !Citation styles window (Main menu->Citation style) and note
the "Source output..." option in the "Misc" section. Simply select which
type of abbreviation (if any) is appropriate for your output and whether
the full stops should be stripped out. These options then become part of
your output style.

* "Problems...?"
During the output of a reference !Citation takes the source field and
scans the journal list for an exact match and derives the appropriate
abbreviation from this match. The journal field should contain the *FULL*
name and if entered using the journal menu will provide an *EXACT* match.
However if these have been entered manually there may be minor variations
(extra space or typo mistake) and the search will fail. If no match is
found then the contents of the source field are output unaltered.

* "What if my journal is not in the journals file...?"
If !Citation doesn't find the source name in the journal list it just
outputs the contents of the source field unaltered.

* "What about the keyword list...?"
The keyword list follows essentially the same format as the journals
list. Enter a keyword or series of "slash" separated keywords on each
line of the list as you wish them to appear in the keyword menu (do not
put commas in this file, they mess up the menu structure). Up to 200
lines (or keywords) are available.

Journals and keywords can be selected to appear in their menu in the same
order as they are entered in the list or sorted in alphabetical order
according to the option settings in the preferences window.

The example Journal & Keywords file included with the application
provides a template for editing. Lines beginning with a hash (for
comments) are ignored and in the example journal file a hash has been
inserted between lines for clarity. It is rcommended to leave the...

 # ----> End <----

marker in place.

* "How do I make a backup of these files...?"
Access the "Resources" directory which holds these files by selecting
"Icon bar menu->Journal & Keys->Open directory". Drag the files out to
your backup directory.

Note: Do not rename or move the "keywords" or "journals" files. !Citation
expects to find files of these names in the Resources directory and will
flag an error if they are not there!


8 - Duplicate scanning
======================
* "How do I check a library for possible duplicates...?"
In a large library it is possible to accidentally enter duplicates of
some records. The "Duplicates" option (Main menu->Miscellaneous-
>Duplicates) provides for an automatic scan of the current library to
pick out potential duplicates and report them to a text file. To initiate
the scan call up the "Duplicate scan" window and click on "Go". Progress
is reported in the scan window and if any potential duplicates are found
a save box pops up with a text report which can be dragged to a RISCOS
filer window or directly to a text editor.

The word "potential" here is important. !Citation intentionally does a
"fuzzy" scan of the author and date fields of each record to allow for
spelling mistakes and so may report entries by the same author in the
same year but which are in fact genuinely different entries. It is
recommended that the user manually check the duplicates reported, using
the "First Author" search window (see section 3.1) and "A-Z" browse
arrows, before deleting them. Entries can be flagged deleted using the
"Delete" button on the toolbar and removed permanently by "Compact"ing
the library using the icon bar menu option.


9 - Preferences
===============
A preference window can be called up from the icon bar menu which allows
the setting of several application-wide options whilst !Citation is
running. There is no "OK" button in this window since all options are
immediately effective and it is closed by clicking outside the window.

"Include #IDN in archives" - by default when an archive is created
identity numbers are *NOT* included in the file. On importing into the
receiving library new numbers are allocated. If the user requires to
transport the ID numbers with the archive then set this option "on". The
danger of this is that numbers might be duplicated and therefore are no
longer "unique". Beware.

"Add on field import" - by default data dragged directly to a field in
the main browser window (in add/edit mode only) is imported overwriting
the existing data. With this option selected the data is appended to the
end of the existing data (see section 4.8).

The sort journals and keywords options, arrange the respective lists into
alphabetical order for presentation in the appropriate menu (see section
7). Some people may prefer to have these unsorted (in the order in which
they occur in the file) so that commonly used entries can be kept at the
top of the list.

"Style Effect Tags" - !Citation offers the option to type exported files
as text, DDF, HTML or Rich Text Format (RTF) in conjunction with effect
tags as explained in section 2.2.6. Techwriter supports both HTML and RTF
(but RTF is probably the better of the two) so that by using the
appropriate commands in the script style, references may be directly
imported into TW and the necessary styles automatically applied. HTML
output can be directly incorporated into files intended for viewing with
a Web browser.

This option affects file output from the "Card export" button and "View &
Output subsets" but not the search finds or abstract export which are
always text type files with no effect tags.


10. Miscellaneous
=================
* "What is this UserKey file?"
When you register for a licence to use !Citation you will be supplied
with a UserKey file which "unlocks" the application from its demo mode
and inserts your name and registration number into the "Info" window. To
insert the key, run the application and you will see a "This is a
demo..." warning. Click "OK" and the main browser window will open. Go to
the "Iconbar menu->Journals & Keys->Open directory" menu option to open
the "resources" directory. Drag your personal key into the filer window,
alongside the "settings", "journals" and "keywords" files. Quit the
application and re-run it. It will now be in the full version mode and
your name with serial number will appear in the "Info" window. Leave the
UserKey in this directory at all times.

DO NOT change the UserKey file in ANY way or it will be corrupted and
!Citation will default to the demo mode only. You may like to make a
backup of this key but DO NOT allow anyone else to use it - this breaks
the terms of the licence and the Net Police will be after you!

* "An upgrade... that's nice but what about my existing files...?"
Check in the "History" document to see what changes have been made and
what files are not compatible with the new version.

Libraries are always upgradeable through archives. Archive each library
to a CSV file using the OLD version of !Citation with the icon bar menu
option, "Archive". Quit the old version and load the NEW version. Create
a new library using the "New Library" option on the icon bar menu and
open the file import window from the main menu. Drag an archived library
to the import arrow and click "Go". Repeat the process for each library
as necessary.

Your old "settings" file in the "Resource" directory will not be
compatible and should NOT be transferred. Style files may well have their
internal variables changed and are unlikely to be directly compatible but
the style scripts will be imported after a warning had been issued. You
should then check the scripts for any changes in the command words and
alter accordingly. You will also need to reset the In-text, Author and
Misc options and re-save the file from the new version.

Remember to transfer your UserKey across to the "resources" directory of
the new version of !Citation to unlock the full version.

* "What about renaming the library...?"
You can't simply use the RISCOS rename option on a library because the
sprite files inside the library also need renaming. Instead !Citation has
a "Rename library" option from the "Icon bar menu->Maintenance" menu.
Enter the new name and press <Rtn>. The current library is automatically
closed, the library application directory and associated sprites are
renamed and then the newly named library is reopened. Note that the
closing of the old library removes all search data and windows in the
process. Make sure that any searches that are in progress are complete or
the results (but not data!) will be lost.

* "Where is the library that !Citation is using...?"
If you have several libraries with the same name but in different
directories, you may want to check the pathname of the current library
use the "Pathname" option from the "Icon bar menu->Maintenance" menu.

* Note that "Compact"ing the library ("Icon bar->Maintenance" menu)
closes any active Search or Subset queries first since these may contain
references which are flagged deleted and therefore removed from the
library. Use this option cautiously.

* The "Delete all records" option in the "Icon bar->Maintenance" menu
does just that for the entire library... do keep regular backups of your
data.

* There are some hot keys which work ONLY when the main browser card has
the input focus:

 ctrl-O, open subset Order value window
 ctrl-S, open general Search window
 ctrl-A, open first Author search window
 ctrl-N, open search record by #id Number
 ctrl-V, open View subset window
 ctrl-T, Transfers current record to the default format record
 ctrl-], for serial entries when in "Adding" mode. This automatically
         saves current record and opens a new "Add" window by
         mimicking "Save" then "Add" button clicks
 Page Up or shift-up arrow, moves one record on
 Page Down or shift-down arrow, moves one record back

* Clicking on the close cross - top left of the main browser window,
hides this window as well as any other window related to !Citation. The
library is *NOT* closed and "select" clicking on the icon bar icon
reopens the browser window and any related windows (search, view subsets
etc). This is useful for maintaining an uncluttered desktop whilst
working on your WP and you can easily flick back and forth to insert
citations.

* Closing the library (Icon bar menu->Close library) shuts down all
searches and other windows and closes the browser window. !Citation
though is still running and dropping a new library on the icon bar icon
opens the browser window.

* !Citation should be run from harddisc only - due to speed and space
considerations. It has been checked on a 4MB A5000/A4, RISCOS 3.1 and
requires just over 1MB RAM so it is just possible to run a WP package at
the same time. A library of circa 2500 references (each with several
hundred words of Abstract data), un-compressed, is in the order of 8MB.
The ease of loading and transferring data between libraries however means
that such large libraries are not really necessary and the user is
recommended to partition references into smaller sub-1000 record
libraries for speed of operation.

For backup purposes - most database files (including this one) use many
fixed length fields. A record uses about 1.4Kb (with no abstract data) so
a fair sized abstractless library can be stored on a 1.6 Mb floppy for
backup (say, over a 1000). However, since most records contain numerous
redundant spaces a compression utility (!Spark, !Compression etc) will
achieve significant a space saving for back-up files. Libraries can be
run from !Compression to save space.

* "I'm curious - what's inside a library directory...?"
Normally you need not concern yourself with file contents of a library
but for the curious; Shift-double clicking on a library (application
directory) opens it to show the data files, one not surprisingly called
"data" and others called "0", "1" etc. which are indexes. Do not alter
these files in any way or your data will be corrupted. You will also see
the !Run and !Sprite files which are needed to define the resource as an
application directory and hold information on which version of !Citation
created the library.

* Application structure and some important files.
For the curious the following may be of interest. Shift­double click on
!Citation opens the application directory. It is worthwhile pointing out
that you should *NOT* alter/move any file or the application may
irrevocably crash and may take your data with it... you have been warned!

"!Citation.config" is a config file used by the SBase exec program which
runs !Citation (which is in intermediate code).

"!Citation.data" is the default (empty) file that is loaded in the "No
active library" state.

"!Citation.Resources.settings" is read by !Citation on start up and is
updated on closing the application. It holds the last set of citation
styles (amongst other things) and if this file is corrupted or lost
!Citation will report an error on startup and use defaults. A new
"settings" file will be created on exit but your previous styles will be
lost. The last active library is also stored here. If this library moves
or is deleted between running !Citation, !Citation will report an error
on next start-up and open with "No active library". If you make a back up
of the "settings" file use, the "Close library" option in the icon bar
menu first, which zeros the active file to default and prevents this
error - don't worry it is not a fatal error if it does occur!

"!Citation.newlib" is the new library template.

"!Citation.Resources.journals" is the journal and abbreviations file and
may be accessed easily from "Icon bar menu->Journals & Keys->Edit
journals" option. You may like to back-up this file or to restore a back-
up, delete the old file and drop the back-up into this directory ensuring
that the name is also restored to "journals" (use the "Icon bar menu-
>Journals & Keys->Open Directory" to directly open the directory).

"!Citation.Resources.keywords" is the keywords file and can be accessed
in a similar way to the journals.

* "What's this banner "S-Exec" that appears on start-up...?"
!Citation is written in S-code as part of the S-Base programmable
database system by Simon Glass. This is an excellent suite which allows
coding in a Pascal-like language and offers many database specific
features which ease handling of data. !Citation contains an S-Exec engine
which interprets the compiled S-code at run-time and handles most of the
WIMP features. The version number on the banner is that of S-Exec not
!Citation. This can be found in the program information window.


11. Error Handling
==================
Most errors are covered by appropriate error handlers (usually where data
is imported or exported and the media may be faulty/not present). Error
reports are mostly informative but S-base exec does not support many
error messages so you might get something like "Error 107" (which is
"File not found") or similar. A click on "OK" will abort most errors and
!Citation will fail-safe.

A global error handler, however, is provided to capture unforeseen errors
and flags, "!Citation has encountered a fatal error and must exit
immediately. No data should be lost (see manual)." After exiting,
!Citation then writes an error code to the "settings" file (see section
10). Immediately after experiencing such an error (preferably before
running !Citation again), make a copy of your "settings" file and send it
to me for diagnosis.

If !Citation does behave in an unexpected manner, check the "Problems"
file which documents currently known problems and might provide some sort
of explanation.


12. Acknowledgements
    ================
My thanks go to all those people who have taken the time to report bugs
and engage in constructive criticism. Without them !Citation would not
have reached this stage. I am particularly grateful to Stewart Brookes
(who always kept me smiling), Peter Killworth (bug finder par
excellence), Nick Kaijaks and John Pettigrew and for their feedback,
suggestions, testing and general encouragement.

I wish you happy and successful writing....


           - - - C O P Y R I G H T   N O T I C E - - -
The bibliography program, !Citation, its manual, associated documents and
files are the sole copyright of the author - Dr TP Dawson. Licence is
given to the registered user for one active copy of the program. It may
not be given to any third party, as gift or for payment and a single copy
only, may be made for back-up purposes by the registered user.