References Development Documentation v1.0

From Diversity Workbench
Jump to: navigation, search

The following information was present in DiversityReferences version 1.0, documenting some development steps. With the development of DiversityReferences 2.0 this information has been wiped in the database and migrated to the Wiki. It refers both to development of the information model and sometimes to the MS Access prototype client.

User Topic Text Date
gh Subsystem Prefix “ Introduction: Each database subsystem (Nomenclature, Taxonomy, Literature, References, Geography, Descriptions, Host-Parasite-Relations, TaggedImportFiles) should have a name of its own to identify the module as an exchangable application, and a name-prefix to identify the objects that belong to a certains subsystem when used in an integrated application.
“Reference” alone seems to be too general, different types of “references” between database subsystems seem to be possible, e.g. you can also reference a collection specimen as voucher for information.
Therefore, “Lit” has been used as prefix of tables etc. “LitRef” would have been another possibility; or always LitReference. The latter, however, is too long for my taste.”
10/08/2000 18:34:01
gh Subsystem Name “ Tentatively, I have used the name _ReferenceAccess_ for this subsystem. I consider this not yet fixed -> new name: DiversityReferences” 10/08/2000 18:40:14
gh Replication and primary key “Jet fügt zusätzliche Felder hinzu, darunter ein s_GUID als GUID Autonumber (16 Byte lang). Um dieses Feld zum Primärschlüssel zu machen, genügt es nicht bereits ein Feld mit GUID Autonumber definiert zu haben. Es wird dennoch ein weiteres GUID hinzugefügt, was die Datenbank entsprechend aufbläht. Folgende Methode funktioniert jedoch: Kopiere aus einer beliebigen Replizierten Tabelle das Feld s_GUID in die noch nicht replizierten Tabellen der Datenbank. Die Description kann bereits frei gewählt werden. s_GUID kann bereits durch ref. Integrität als Foreign key in Untertabellen definiert werden. Nun ändere Status der Datenbank zu replizierbar. Anschliessend kann s_GUID umbenannt werden, die Replikation funktioniert trotzdem weiter (zumindest in meinem Test!)” 10/08/2000 20:32:11
gh Data model ver. 0.1 “Introduction:
-------------
The following text documents some changes of the datamodel relative to the first draft model. It contains some documentation fragments, but is mostly intended for internal communication among the developers

General:
--------
Description text for entities added.
Description text for attributes updated. General scheme:
- Everything changed to explanation phrasing, not prompt like “Enter...” or “Use this field to”
- RefMan annotation at the end, after a long list of blanks to separate from the rest. Contains Ref.Man. field number and RIS import tags.

Text fields either changed to Memo to conform with the Ref. Manager Specifications, or at least set to 255 char. Text (many fields in the first draft were left at the default of 50). Note: Memo fields can not be sorted; text 255, if empty, only takes the minimum space of 1 Byte if empty (in Jet databases). SeriesTitle has been purposely set to Text (max. 255 char.) and not to Memo. This allows generation of pick list (index added for this purpose, with IgnoreNulls).

Unicode compression turned on in all cases. In the draft version many attributes had it turned off, esp. those imported from MINOS.

Entity “Signature” changed to “LitAvailability”

Replication: Row level tracking has been turned on for the subtables.

Specifics:
----------
TypeOfReference -> ReferenceType
Entity LitRefType added
Lookup added

ReferenceID
Primary key gemacht, required,
LitKey (Autonumber, Probleme wenn repliziert) deleted
Validationrule/Text added
Input Mask added

Author now independent of Person, s. tel. discussion with Tom. There is a high danger of having to guess about the identity of a name with a person, e.g. “J.Smith”. Errors introduced by false guesses (and perhaps by later “corrections”, e.g. when a person changes his or her name through marriage) are very difficult to find and correct. The added knowledge that the identity of name and person MAY be known is not very valuable in the case of literature references. - Author required, 255 char. Lookup set to self (grouped and sorted query).
LitSequence -> AuthorSequence
AuthorAddress in LitAuthor: OK, added during import to the first primary author (although this may be wrong, if the address of the article belongs in fact to another author).
AuthorFunction -> AuthorType: I find “function” slightly irritating, misleading, although on second thought it is well thought of. To avoid such irritation, however, I propose the more neutral “AuthorType”. Lookup added.

DatePrimary: Split into DateYr, DateMo, DateDay, DateSuppl, to make entry control and data retrieval easier. The year part must absolutely be separated, to allow efficient retrieval by year.

Editor (from Minos) deleted, Authors were this flag is set must be mapped to secondary author! Source (from Minos) deleted, must be expanded/denormalized!

Start/EndingPageNumber: ‘Number’ removed, not necessary, may be misleading if page reference contains “figure” etc.
EndingPage -> EndPage, see RefMan fieldname Start Page, End Page (Ref.Man. documentation)
Type changed from Numeric to Text, may contain punctuation and letters, see Ref. Man. docu!
Later model changed again, simplified and both attributes joined to “Pages”, just like in EndNote and in the Minos model. Too many cases don’t fit the start/end page model sufficiently well (333 pp., non-consecutive pages // in ref. man in StartPage alone!) and it is very easy to change from a single to two attributes during import/export.

TitleSecondary -> SourceTitle. Except for “Case” only used as book title (but primary title may contain the book title if whole book is entered, therefore BookTitle attribute name would be confusing.

VolumeNumber -> Volume

Edition: Validation rule added

Volume: Index added (with IgnoreNulls)

ISSN/ISBN -> ISSN_ISBN. “/” may cause problems in SQL, if interpretated as division.

Supplement (from MINOS) deleted, muss bei Import der MINOS-Daten auf die entsprechenden Felder verteilt werden!
(in most cases this maps to SeriesTitle, T3!) -> Somebody needs to start working through existing Minos (Access 97) fields!

CityOfPublication -> PublPlace
Lookup added to this attribute and to “Publisher”.
Indices added to speed up generation of pick lists (with IgnoreNull set!).

PeriodicalName -> Periodical. Lookup added, entry only form lookup.

Reprint Status in 2 Felder geteilt, da nur 3 Werte zugelassen sind. Ein Textfeld muesste m.E. aufwendig kontrolliert werden, um Fehleinträge zu vermeiden. Lookuplist und Validation rules hinzugefügt.

URLs may be several, must be semicolon separated! -> could introduce another relation for it! Shall we do this?

DuplicateCheck/DuplicateOverride separated from RefDescription. The latter can be redefined by user and is not used for duplicate checks.

UserDefinable1..5 to UserDef1..5; Used this was in Ref. Manager; also Definable is temporarily fixed to before it has been defined.”
10/08/2000 22:10:28
gh Export to Ref.Manager “The RefID (tag: ID) and importing to Reference Manager Version 9:
================================================
In older versions, the ReferenceID was exported and reimported from the RIS format as defined in the import file.
However, in Ref. Manager Version 9 the default behaviour was changed to that the ID tag is now ignored during import. The Version 9 RIS Tagged format documentation says explicitly: “Reference ID. (Note that any information in this field is not imported.)”

Consequences: Data from Reference Manager Databases can be imported to ReferenceAccess, and export back to Reference Manager. However, the following scenarios do not work any more:
- A reference Manager database is used to produce references for publications (this uses the ID numbers). The data are imported to ReferenceAccess, changed, and later re-exported to ReferenceManager. Now the link to the publications (in Word etc.) is broken.
- A subset of references in ReferenceAccess is loaded into ReferenceManager, updated and improved there, and then the references in ReferenceAccess are overwritten with the temporarily off-line edited. The exported references in ReferenceAccess now must be immediately deleted, the gaps can the later be filled by reimporting.

This is only true for the default RIS import format. It is possible to create a modified RIS-withID-RM9.cap (this file is supplied with the database) format that does import the RIS.

Internal Note: When automatic ID creation is turned on for a database, and some IDs are missing, the following ID are incremented from the last ID that was imported, e.g. if consecutive records have the following IDs: “1,2,100,missing,200” this results in “1,2,100,101,200”.”
10/08/2000 23:02:41
gh User manual, attribute notes “Signatures, Availability, and reprint status:

In contrast to reference manager, which basically assumes that only a single person is working with a collection of references, ReferenceAccess is designed to be used concurrently by multiple researchers. This necessitates some changes in regard to markers about the availability

During import of a reference manager file, you are asked with which user signature (usually the name of user) the imported reprint markers shall be associated. The information will then be imported into the Availability table together with the signature field set to this value. Similarly, during export to reference manager, one specific signature can be reexported into the Reprint status field of reference manager.

The reprint status “On request” has been further differentiated into 3 categories: reprint requests directly from the corresponding author, references requested for a reprint by marking them for internal order (e.g. copying them from journals that are available in an in-house library) and marking articles for interlibrary loan.

The markers can be used to first mark multiple articles with the intend to perform an actual request or order (leave the associated RequestDate field empty) and having actually performed that request (enter the date on which the request was sent out or submitted in the RequestDate field).”
10/08/2000 23:11:33
gh User manual, attribute notes “Dates:
------
The secondary date is redefined in some cases, e.g. as copyright date. However, the field is enabled with just a “date” label in many reference types, and no information could be found in the Reference Manager Help or User’s Manual as to the differentiation between primary and secondary date in these types.”
10/08/2000 23:25:33
gh User manual, attribute notes “Page numbers: A hyphen (“-”) is used between the start page and the end page of an article. The end page is always the last page on which material of the article appears, for example the last page may contain a figure or table.
Special cases: complex, non-consecutive page numbers are entered using commas to separate page numbers. Example: (“3, 5-9, Tafel 10, Figs. 3-6”).
If the page count for books is desired, enter it with a “pp.” after the number. That is, use “342 pp.” instead of “1-342” (The first definitions are in accordance with reference manager. However, the last definition regarding page counts in books has been defined freely, since neither Ref. Manager help nor the PDF user manual contains any relevant information.
Do not enter only the first page number of an article that appears on more than one page. Some articles may actually appear only on a single page, and entering a single number for multipage articles is therefore ambiguous. If you do not know the ending page or if it is questionable, you should enter it like in the following examples: “20-??”, “20-45?”
***NOTE: EndNote does have “Num of Pages” for books, RM maps this to “Start Page & End Page” -> what does this mean? Needs to be tested to understand where or how Ref.Man stores this!”
10/08/2000 23:31:32
gh User manual, attribute notes “Language:
Reference Manager has no provision to indicate the language of an article (or the secondary language in which a second abstract is available). This database has added such functionality, which can, however, not be exported to reference manager. (Note: User manual checked, no information)”
10/08/2000 23:46:10
gh User manual, attribute notes “Translator:
There is no provision for a “translator” of a book in the data structure. If you wish to record such information, please use the Notes attribute for this purpose (Ref. Manager itself would also import the EndNote “Translator” into this field).”
10/08/2000 23:50:43
gh Import from Ref.Manager “Author Address, Import: The address should be added to the first author, although this is not necessarily correct. The corresponding author, whose address is given in the paper, may in fact be another than the first author. However, in most cases there will be an association between the address and the first author, even if the first author is no longer at the named institution. Alternatively, the address could be associated with the article. However, in manual entries, it is possible to associate the address with the correct author (if different from the first) and the author specific address retrieval may be very helpful. I am uncertain, what is the best solution...” 11/08/2000 10:51:27
gh Import from Ref.Manager “Periodicals, Import: Description for “Source” contains notes about the Markers that should be used. Both for User Syn 1 and 2 the marker “RefMan imported synonym” should be used.” 11/08/2000 10:51:31
gh Import from Ref.Manager “Reprint Status, Import: Reprint Status has been integrated with Availability. The respective attribute note is: “During import of a reference manager file, you are asked with which user signature (usually the name of user) the imported reprint markers shall be associated. The information will then be imported into the Availability table together with the signature field set to this value. Similarly, during export to reference manager, one specific signature can be reexported into the Reprint status field of reference manager.” Similarly, it should be possible to add a “Responsible” person to the Keywords, see there.” 11/08/2000 10:52:40
gh Import from Ref.Manager “Keywords, Import: It should be possible to add 1-5 additional keywords to all imported records. Reference manager has a similar functionality. Similarly, it should be possible to add a “Responsible” person to all imported Keywords. “Responsible” and the similar signature question during import need to be separate: they may contain the same string for a person, but may be different.” 11/08/2000 10:52:59
gh Export to Ref.Manager “Keywords, Export: It should be possible to restrict the exported keywords to those from a specific “responsible” person.” 11/08/2000 10:53:20
gh Import from Ref.Manager “Pages, Import: If StartPage and EndPage are present, they are combined with a hyphen (“23-44”). Else either attribute is directly imported into Pages as it is.” 11/08/2000 10:53:25
gh Export to Ref.Manager Pages, Export: If only a single hyphen is present and the rest consists only of digits or blanks, then the attribute is split at the position of the hyphen and exported as StartPage/EndPage. In all other cases, esp. if the Pages attributes contains letters in addition to digits, or non-consecutive page numbering (‘23,25-41,44’), the entire attribute is exported as StartPage. 11/08/2000 10:53:57
gh Import from Ref.Manager SeriesTitle, Import: It is possible that an imported SeriesTitle is longer than 255 characters. In this case the string should be truncated and a warning issued. 11/08/2000 10:54:02
gh Import from Ref.Manager “RefString, DuplicateCheck:
@@@ These are calculated strings, must be added. Please reuse and modify the existing functions in MINOS with a similar functionality!
Note: Use ANON (abbreviation for anonymous) if no author is available. It is probably better to finish import without duplicate checks and then run a duplicate check for ALL records for which the DuplicateCheck string has not yet been calculated. This should be implemented as a separate process, and the import process should ask whether to run this process. In cases where multiple imports are done, it may be desirable to skip duplicate checks until the very end.”
11/08/2000 10:54:16
gh Export to Ref.Manager Language: A thought: Language and other attributes not supported in reference manager could be exported to UserDef5 (and later reimported from there) as long as UserDef has not yet been used. Thus, with the exception of importing data were UserDef5 had already been used, a 100% export/reimport compatibility with Ref.Manager could be achieved. 11/08/2000 10:54:39
gh Import from Ref.Manager “Reference Types, Import: ReferenceAccess now basically supports all Reference Manager reference types. Only the checkbox in table Reference Types restricts which ref. types are visible. Provisions must be made for the case the Reference Manager users have added their own, user defined reference types! Thus additional type coded must be recognized in import and added to the Reference Types table (referential integrity is turned on, else impossible to import with this type!). The forms will treat user defined types as “General” with all attributes visible and the default label captions.” 11/08/2000 10:54:54
mw Subsystem Prefix, name würde Lit als Prefix und Literature als Name bevorzugen. Wie von GH schon angemerkt ist reference etwas sehr allgemein 21/09/2000 16:55:47
gh Subsystem Prefix, name “Answer to MW: Lit or Biblio are in a way to restrictive to the future. I do not think we want to restrict ourselves to printed reference items, and URL, but also graphic objects may be a source for references, i.e. they will be used as voucher references for information obtained from them, in the same places in the modular component model where currently we reference almost exclusively printed “literatur” items. See also the ReferenceType table for the list of supported ref. types, many of which do not fit the “LIT” prefix.” 14/10/2000 20:35:18
gh reference subforms “The subforms for authors, keywords etc. are designed to work without a module. Forms without a module load considerably faster than those with a module. Instead, the events are passed through to the parent form, using functions directly in event properties. Information is hidden whereever possible, e.g. the author address in authors. However, the layout had to be somewhat complicated to get away with the continuous form: Making the control locked & disabled means that double-click event does not occur any longer. Thus it is possible to put the cursor into the text, which is somewhat unexpected. -- However, this is necessary. Althouth putting a transparent label with a double-click on top of the text prevents the cursor behaviour and allows the double-click, it also means that double-clicking on a row other than the current record will open the address of the current record, NOT the address clicked upon. There seems to be no event/method in access to figure out in a continuous form, which row has received a mouse-move or click event. -- Finally, the label had to stay nevertheless, since the desirable control-tip telling the user about the meaning of the symbol DOES NOT display properly for text style control. It pops up very shortly and immediately vanishes. I could not figure out a method to prevent this.” 14/10/2000 20:35:26
gh Style guide “Labels: Tahoma, 8pt. Avoid bold, esp. on buttons (that was Win 3.0 style guide, changed since Win 95!). Use only few large buttons with large icons. Icons should generally not be larger than the toolbar buttons, set on small size. Exception are OK for are a single “logo” type icon. Simple continuous subforms should look like a table and use flat, not sunken style. The entire subform control can then be sunken. Editable text comes in two sizes: Small uses Tahoma 8 as well, to fit with the Windows/Office menu and dialogs. Larger text, for improved readability can be either Tahoma or Verdana, we still have to settle on this.” 14/10/2000 22:50:09
gh Word indexing: Currently the Title and Source title are combined in one calculated word index, Abstracts in a second. Stopwords, single letter words are excluded, words > 50 char. truncated to 49+*. Like for other simple dependent table, row level tracking has been chosen for these tables. 28/10/2000 21:48:38
gh Differences to RefManager “Some specifications have been changed relative to Reference Manager:

1. All 5 User defined fields are supported Import/Export only, but not recommended to use inside the database. In a collaborative environment, userdefined fields must be user specific, and invisibile to other users. Undefined open fields are of little value.

2. Title/Source title: omit period at end not really important and not enforced by triggers

3. Negative years (Before Christ) no longer supported, prohibited by validation rule to improve data quality.

4. URL: several URLs are imported, but the open-definition of what the URL actually is (just interesting cross reference, or the actual source for the reference???) is given up. It should now be the source, multiple interesting URLs are not actively supported by the user interface.

5. The secondary date is recommended to use for the true puplication date”
31/10/2000 18:48:12
gh linking tables “The advantage of using linked tables are:
- Less chances for corruption of data
- The application mdb does not have to be replicated, allowing for smaller development files that can be updated instead of replicated. Also, since public stand-alone versions shall be distributed, creating these versions from the replicated development base would be difficult
- Data can be compacted/repaired from within the application! Note: When linking with a mapped network drive, the UNC Servername/Share naming convention is used instead!”
09/11/2000 09:47:09
gh user specific pick list lookup “For Availability.Signature and UserMarker.Marker both during data entry and retrieval, the pick list is restricted to values where the current operator or responsible user is entered as “Responsible”. During querying, the returned values are restricted to those entered by these users as well.” 21/11/2000 22:18:17
gh user specific editing Abstracts and Availability records can be viewed by all users (optionally the view can be restricted to records entered by the user), but can be edited or deleted only where the current users (operator/Responsible) are compatible with the users originally creating the record. 21/11/2000 22:18:24
mw Error in import Klassenvariable in der alle auflaufenden Fehler gespeichert werden und am Schluss ausgegeben werden 18/12/2000 11:51:02
mw Periodical Abbreviation muss vorhanden sein, Fullname kann 18/12/2000 11:51:23
mw Import Alle Abfragen bzw. Recordsets auf einen nicht vorhandene ID beschränken (RefidDummy) um zu vermeiden, dass die gesammte Tabelle in das Recordset beladen wird. 18/12/2000 11:52:29
gh Author form “The double-click to zoom authors has been removed because of an artifact that occurred ONLY in New References entry, only when going into the authors subform the first time. Since entering data in zoomed mode circumvents the AuthorChecks (“,”, “;”, etc.), this is highly undesirable.” 03/05/2001 12:00:21
gh Periodicals There should be NO referential intergrity b/w Title.Periodical and Periodical entity, otherwise to many errors are introduced with imports! 03/05/2001 12:00:24