ARM Club 1/ARM_CLUB_CD.iso/contents/apps/databases/progs/citation/Docs_Manual

Text File | 1995-05-13 | 27.6 KB | 553 lines

                Citation Database Manager - The Manual
                ======================================

This package should included the following:

* !Citation (containing an editable "journals" file) - Main Application.
* Refsdata - example data, drag to the iconbar icon.
* Txtdata - example bulk import text (see "Bulk import" below).
* Archive - an example archive file (see "Archive" below).
* Docs directory - containing this Manual including some !Draw files
showing annotated windows.

What follows is a brief run down of the main features of !Citation -
don't be afraid to experiment using the supplied example data.

Input
=====
The first thing is to get some data into !Citation. Dragging a data file
(for example "Refsdata") to the iconbar !Citation icon (a big, gleaming
"C") loads any data file. To create a *new* data directory simply create
a new RISCOS directory in any RISCOS filer window (using standard RISCOS
methods) and drag the directory to !Citation's iconbar icon. Data files
are automatically created in this directory by !Citation.

Note that your data directory is just like any other RISCOS directory and
can be copied, moved, deleted and renamed (though not whilst it is being
used by !Citation..please), so keeping backups is easy. !Citation data
files within this directory are called "data" (obviously). Indexes are
called "0", "1" etc. Do not alter these files or your data will be
corrupted - but of course you will always have that back-up...?? Other
files may be stored in this directory if so wished, though I wouldn't
advise it.

If the directory is a newly created one, then the main viewer window
opens with "No file open - Waiting" and advice in the Title field to drag
a data directory to the iconbar. Dragging a data directory to the iconbar
immediately open the file and displays the data. If you have several data
directories, drag the next to the iconbar and the current file is closed
and the new one opened.

"Close file" on the iconbar menu closes the current file and !Citation
returns to its waiting mode. This option probably won't be needed often
but the pathname of the last active file is stored in a configuration
file so that !Citation always opens where you left off. If this file
moves or is deleted between running !Citation, !Citation will report an
error and open with "no file open". If you make a back up of this file
(see below) use the "close file" 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!

We will deal with manual input first and describe the actions of the
icons on the main viewer card (see also accompanying !Draw file -
"viewer")....

Icons at the top of the card are grouped from left to right:

 *Status window - shows active file name and record number. Also flags
certain activities eg Editing, Adding etc

 *Goto first record arrow
 *Goto previous record arrow
 *Goto next record arrow - note "adjust" click on forward/back arrows
jumps 10 records and "select" just one record.
 *Goto last record arrow

 *Add a record - in this mode all arrow keys are disabled (in fact all
record movements) while a new record is manually added. **NOTE: This is
also the icon to which text bulk import files must be dragged to start
the importing process**
 *Edit a record - once in this mode one can "browse edit" with arrow keys
to allow easy alteration of consecutive records. Also works with
secondary arrow icons in "Search" and "Generate set" windows. In browse
editing mode records will be automatically updated if user moves to a new
record (ie. clicks on an arrow in the main viewer window) but you must
use "Save" on the last altered record if exiting this mode, to update the
file. This also applies to the secondary arrows other windows (see
below).
 *Delete - flags the current record as deleted. Note records are not
removed until the file is "Compacted" from the icon bar menu since this
can be a time consuming process and best executed in bulk. 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-
>File->Undelete option.

 *Cancel - abort current operation and reinstate altered fields.
 *Save - update any changes to disc (note comment in Edit). Only one
record is ever held in memory so that if the system crashes data loss is
minimal.

 *Export icon allows dragging of author names directly into your paper in
the appropriate format eg. "[Radulescu et al, 1986]" or "[Smith & Jones,
1801]". (see Output for difference between select/adjust drags)

If no file is open then all icons are disabled. If it is a new, empty
data file then only add or bulk import icons function.

Now to the nitty-gritty of typing. !Citation needs to have references
entered in a specified format to provide a known starting point. This
applies really only to the author field where various output styles are
required. Authors should be entered as: SURNAME, SPACE then INITIALS with
no spaces between initials eg. Brown FG, Williams ED. Double-barreled or
complex surnames with several part MUST be hyphenated eg. Wynford-Thomas
D, Yo-Ti-Wa XF (or !Citation will interpret the unhyphenated parts as
initials). !Citation will try to correct your input by removing spaces
and altering the case where can it on bulk input but to function properly
it does needs the correct author format. Up to ten authors can be
specified and the "et al" icon can be selected at any time to add "...,
et al" to the author output. Note that this icon is automatically
selected if more than 10 authors are detected on bulk input, to flag to
the user that more authors exist than can be accommodated by !Citation.
Each maximum author length is 23 characters for surname and initials
(...technical limitations I'm afraid but should be enough for most
purposes).

Title and Notes fields have a 254 character limit, which should prove
enough for all but the most verbose.

The source field is limited to 75 characters, try spreading long book
references over both title and source fields. A "select" click on the
icon which sits by the Source header brings up a menu of your preferred
journals (see "Configuring" !Citation for information on how to edit this
list). If you are in adding/editing mode then clicking on an item in this
menu inserts it into the source field, otherwise the options are greyed
out.

Keywords can be upto 10 characters in length. Other fields are self
explanatory.

Clicking on the "Add" icon will clear the card ready for input. The
cursor will be initially in the First Author field but can be moved to
another field by clicking into it or using "Tab" or "Return" to step
through fields. "Tab" will step though groups of fields so that if there
is only one author to enter, "Tab" will jump on to Title whereas "Return"
steps through individual fields sequentially.

The left/right cursor keys move within a field and with shift or ctrl
effecting larger steps. Text in the longer fields will word wrap and
scroll if necessary. Shift-Tab move 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, mimicing clicking on the forward/back icons with "select".

Note the "Paper type" and "Copy?" icons which give a quick visual
reminder to the paper type or possession of a photocopy.

A default card is available, which in the adding mode allowing authors,
title, notes, papertype, copy, etal etc. to be duplicated over several
additions. This is accessed from the Main Menu "Default card->Edit
default". Remember to toggle this ON with "Default card->Use default". A
tick by this item in the menu indicates the default card is active.
Toggle off after use.

Bulk 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...!

Text input files for bulk input should dragged to the "Add" icon at the
top of the card and be formatted thus:

start of file...
au,au,au[CR]
title[CR]
source,vol,pages,yr[CR]
notes[CR]
[CR]
...end of file

ie. a new line (CR or LF not both) after each line and the last line of
the last reference. Note that the authors and source lines are treated as
comma separated variables. See the accompanying "Txtdata" file for an
example.

On bulk import, the default card (Main Menu->Default card->Edit Default)
can be used to set papertype, copy? & keywords. The keyword option in
particular, provides an easy means of grouping papers since a particular
key word can be searched for and autoadded to a set for output. Don't
forget to toggle "Main Menu->Default card->Use default" ON (ie. ticked)
and untick after use.

Note that bulk import only accepts text-type (ie. !Edit) files, other
types are ignored. Importing occurs at about 20 references/min, time for
a cuppa!. However the bulk import is multitasking so you can continue
viewing records or working on the desktop (but really the operation is so
processor intensive this feature is really only intended to allow
updating of the clock).

After checking that the user really did want to bulk import, the format
of the file is checked for missing lines or obvious errors. If found, the
error will be reported with an approx line number and import will be
aborted. If the import is accepted and the references added but form some
reason then not wanted, a "Delete import" option is available from the
Main Menu->File->Delete import. This removes all last imported references
and compacts the file. If you have other deleted records in the file,
this process also removes them - beware..

The user can also directly import to the author, title and notes fields
by drag and drop on the appropriate field. Note that this can ONLY be
done in editing/adding mode. Note that "Cancel" will usually re-instate
the previous text. Text also can be exported from these fields (see
Output) which means that !Edit can be easily used as a tool for editing
long fields, re-importing after alterations.


Output
======
Output from !Citation can be performed in 3 ways.

1) A "select" drag from the export icon (green arrow, top right of main
window) gives "[authors & yr]" only from the current reference shown in
the card. This is useful if you have !Citation running as your are
writing and want to insert the currently displayed author into the
paper's text. !Citation automatically works out the appropriate author
format and puts this into the paper with the year surrounded by squared
parentheses. This should work with any type of wordprocessor/DTP package
and uses file or direct memory transfer. Alternatively an "adjust" drag
from export icon give full citation in the defined citation style (see
below).

2) The Author, Title and Notes fields can be directly exported to file or
through direct memory transfer by dragging from the small green arrow
adjacent to their header icons (see the!Draw file "viewer"). Note that
text can be dragged directly back into those fields ONLY when !Citation
is in the editing/adding mode.

3) Generating citations for final output to a technical paper. This
comprises three parts a) defining the style of the output references, b)
selecting which references within the database are for output and c)
generating the output set.

a) Defining the Style
   ------------------
The essence of !Citation is the ability to output references in any
desired format. Styles are set up in the the Citation style window (Main
Menu->Citation style, see also the !Draw file "style") and allow any
style of output using certain command words. These are (note lower case
and exact spelling):

  author  title  source  vol  pages

  * = tab
  / = new line

....any or all of the command words can be combined in any order with any
punctuation or special characters (*/) as indicated above eg.

  author (yr)./title/{italic on}source{italic}/vol;pages

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

Anything which !Citation encounters in the style format which is not a
command word or */ is simply included in the output at the appropriate
place eg. all punctuation (including spaces) and strings like {italics}.
Note the "{strings}" shown here are text foramatting commands used in
Impression. On import these will automatically convert 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 show the correct format.). Thus in
this case the "source" field will be italicized - a requirement of some
journals.

Upto 5 styles are stored in !Citation (a to e) and these are saved in a
configuration file (see Configuration). Select which style you wish to
use with the radio buttons by each style. To return to the default
settings use the Iconbar Menu->Citation styles->Default styles (note this
will replace your currently stored styles on exit). To restore the last
saved styles to the current style window use the Iconbar Menu->Citation
styles->Restore styles.

The Author options in citation style window allows surname and initials
to be reversed (from that shown in the viewer window), surname to be
capitalized, and initials to be punctuated with ".", " " or "#". The
latter is sufficiently unusual to allow later search and replace in !Edit
to convert to more esoteric separators if desired.

b) Selecting references for output
   -------------------------------
!Citation uses the idea of "Sets" to select which references are for
output, such that any record in the file can be included in a "Set" 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
Set.

There are up to 5 Sets (hence 5 flags, numbered 0 to 4) and any record
can be a member of any one or more of these Sets or none. The Set status
for any record is shown in the "Define set" window (Main Menu->Citation
sets->Define sets, see !Draw file "sets"). This window is an extension of
the information seen in the main viewer and changes as the user browses
the file. A reference is included in a Set if the button by the Set
number (0 to 4) is ticked. The field next to this button, which contains
a number will turn yellow if the corresponding set is selected - this is
the "Ordering value" (we will return to this below).

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

It is thus essentially very easy to build up a Set but what about the
output order? In most cases journal 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 "Ordering value" comes into play. This 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 simply
determines the order in which references are organised in the final
output. Thus the Ordering 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 icons on this card can increment in steps of 1 or 10
depending on whether the are "select" or "adjust" clicked and I would
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 Ordering value is an extension of selecting
the record as a Set member. Once the Set button is ticked the ordering
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 icons to increment/decrement the value (0 to 999) or enter a
value manually. One only needs to click on the "Save" icon (bottom right
of the card) if manually inputting a number into Ordering value. Clicking
on the bump icons updates the record automatically. Once the Ordering
value is given move on to the next record...and so on. Note that if the
user only requires an alphabetical output the Ordering value can be
ignored.

The Set selection buttons or Ordering values for a record can be changed
at anytime and is stored with the record until the Set is cleared.

c) Generating the output set
   -------------------------
We now have a citation output style and a Set (or more) defined and we
can output the Set to the paper. Opening the Main Menu->Citation sets-
>Generate set window shows the 5 possible sets, the Order options, Go,
Clear and Arrow icons (see !Draw file "sets"). First select the Set for
output using the "Set" radio buttons and then the desired output order.
This is "plain Alphabetical", "Numbered alphabetical" and "Ordered" ie.
according to the Ordering values. Click on the "Go" icon and !Citation
searches the database to collect together all records which are members
of that set. The arrow keys can now be used to browse through the set to
check the order and membership. The status window in this card indicates
the browse position in the Set.

Note that once !Citation has calculated this group, altering the
membership of the Set with the "Define set" window has no effect until
the process is "Clear"ed and started again. The final step is to click on
the Generate set icon (blue icon by the status window) and a save box is
shown for the user to drag the set to file or directly into the paper.
This option is disabled in the "demo" version of !Citation. Registered
users will be sent a full working version.


Searching
=========
Three forms of searching are supported a) first author, b) card by number
and c) general search (see !Draw file "search").

a) First author
   ------------
!Citation maintains an index of First authors 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 file 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 main card status window. The arrow keys on the search card allow
alphabetical browsing of the file either around your found surname or if
the field is empty, through the whole file. The user can, in this way,
search for an author and once found browse round related papers.

If there appears to be a problem with the alphabetical ordering it may be
because the indexing has become outdated. This shouldn't happen often but
may occur after multiple bulk imports. In this case re-index the file
using the "Re-index" option on the iconbar menu - this doesn't take long.
An out-of-date index does not affect the "Generation set" option since
this creates its own new index each time.

b) Card by No.
   -----------
This simply accesses any card by its record number so that the user can
go directly to any reference. The card number is entered into the entry
field and pressing <Rtn> activates the find. It will not allow numbers
outside the record range.

c) General Search
   --------------
For more extensive searches, including all Authors, Keywords, Sources and
Subject (ie. Title, Keyword and Note fields combined) use the general
search option (Main Menu->Search->General Search).

The "Search range" on the general search card is self evident. "Authors"
searches ALL authors (unlike the first author search). "Subject" searches
Title, Keywords and Notes for the search string. "Keywords" searches
keywords only - useful for defining Sets. The search string is case
independent and the search performs a simple - "does the field specified
in the search range *contain* the search string".

This window bears some similarities in function to the "Generate set"
window in that a search string is entered and "Go" clicked (pressing
<Rtn> after typing the search string mimics clicking on "Go"). The number
of finds is flagged in the status window and the arrow icons allow
browsing (and editing) through the found records with the status window
indicating the position of the record in the found group. Before entering
another search string the current search needs to be cleared with the
"Clear" icon.

Searching with an empty search string selects all records. This could be
useful if you wish to output all references in a file, perhaps to import
to another application (though why you would want to do this when this on
is so good defeats me..!) but the option is there. Defining the citation
style with commas or tabs separating fields allows a CSV or TSV formatted
output.

The "Autoadd" option adds all finds to a specified Set but does not
provide an Ordering 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 Set ready for output. An
ordering value can be added by selecting the Set using the "Generate set"
option with alphabetical ordering and stepping though the Set updating
the Ordering value as necessary.


Archiving
=========
An "Archive" option is available from the iconbar menu. This archives the
entire data file into a CSV format, converting the button values, "etal",
"papertype" and "Copy?" to text values (ie. etal_on/off, copy_on/off and
research/review/book - see example Archive file). This option has two
major uses and two minor uses.

The first major use is for combining libraries (data files). Simply load
and archive each of the libraries you wish transfer, then open the
receiving library and drag the CSV archive files to the *ICONBAR ICON*.
!Citation will detect that this is a CSV archive file (rather than a data
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.

The second major use is for "future-proofing" !Citation. Should a new
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.

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 that the command words available
in defining citation styles (see above) allow CSV and TSV formatting for
export of the main fields and the archive option is only of use if the
"button" fields and keywords are also required.

Importing a CSV file into !Citation, could be problematic. !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 file
(load it into !Edit), it is quite complex and easy to make errors if
manually input. The only advantage of this type of import over the "Bulk
text" type (see Bulk Import above) is again the ability to include
"button" fields and keywords in the data. If you do attempt CSV import,
make a backup of the receiving library first!


Configuration
=============
The "Journals" file in !Citation application directory (Shift- double
click on !Citation) can be edited to contain your most used journals but
heed overall 255 character restriction in length (including commas) and
do make a back up !!

A configuration file ("settings") in the !Citation application directory
is read on start up. This contains your preferred citation styles and a
new file is written on closing the application. Do not alter this. If it
is corrupted or lost !Citation will report an error on startup and then
use defaults. A new one will be created on exit but your styles will be
lost. You may like to keep a back up. The last active file is also stored
here so if this moves or is deleted between running !Citation, !Citation
will report an error on next start-up and open with "no file open". If
you make a back up of this file use the "close file" 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!

The "Citation styles->Default styles" option on the icon bar menu deletes
all your preferred styles and returns to the defaults. Your preferred
styles will be lost - beware (but may be restored with "Restore defaults"
before exiting).


Misc
====
* Note that "Compact"ing the file (icon bar menu) closes any active
Search or Set queries first since these may contain references which are
flagged deleted and therefore removed from the file. Use this option
cautiously.

* The "Clear all data" option in the icon bar menu does just that...do
keep regular backups of your data.

* There are some hot keys which work ONLY when the main card has the
input focus:
ctrl-D, open define set card
ctrl-S, open general search card
ctrl-A, open first author search card
ctrl-N, open card by no. card
ctrl-G, open generate set card

* Clicking on the close cross - top left of the main viewer window, hides
this window as well as any other window related to !Citation. The file is
NOT closed and "select" clicking on the iconbar icon reopens the main
viewer window and any related windows (search, define sets 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.

* Most database files (including this one) use fixed length fields. A
record uses about 1kb so a fair sized reference file can be stored on a
1.6 Mb floppy for backup (say, over a 1500). However, since most records
contain numerous redundant spaces a compression utility (!Spark,
!Compression etc) will achieve significant a space saving.


Errors
======

I have tried to prevent most errors occurring by design but those obvious
ones which escape 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"
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. 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.