Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/448a.lha/Citation_Base_v1.1/Citation_Base.doc

Text File | 1990-09-15 | 26.9 KB | 601 lines

Citation_Base  Copyright 1989, 1990 by Michael J. Arrowood

INTRODUCTION:

     What is Citation_Base?  Basically, Citation_Base is a
collection of utilities designed for writers who maintain a
sizeable database(s) of bibliographic citations that must be
included in the LITERATURE CITED or BIBLIOGRAPHY section of their
published papers.  A common problem with most "homebrew" citation
databases is that the citation format chosen as "standard"
usually does not conform to the citation format required by the
journal to which the writer submits his/her article(s).  A writer
in such a position must retype the citations in the correct
format before submitting the paper.  If your bibliography is
large, this can seem like a terrible waste of time (and usually
is).

     The files in this directory make scientific or professional
writing easier on the Amiga by automating the creation and
maintenance of a database of published citations or references.
There are actually two ways to accomplish this task.  The first
employs Software Visions Incorporated's excellent database
program entitled "MicroFiche Filer Plus" (hereafter referred as
MFF+).  The second employs any word processor or text editor.
ARexx macros included in this package rearrange stock citations
to conform to any given bibliographic or journal style.  Put
simply, the macros automatically format ("lay out") the stock
citations so you don't have to.  You get to spend more time
composing your masterpiece (and less time retyping your
bibliography).  The ARexx macros are named LAYOUT.mffm and
LAYOUT.rexx respectively and can be customized to reformat stock
citations into nearly any journal style through the creation of
journal (bibliographic) TEMPLATE files.  The macros use the
TEMPLATE files as guides in formatting citations.

     LAYOUT.mffm reads selected citation records (from within
MFF+) one at a time, reformats the citation (as directed by the
TEMPLATE file) and writes the modified citation to an output text
file in one of two forms.  The first output file form can be
RETRIEVED directly into WordPerfect (Amiga version 4.1) for
immediated use in your manuscript.  The second output file form
is in the Rich Text Format (RTF) which enables the file to be
imported into a variety of software programs that run on the IBM
PC, the MacIntosh, and XENIX/UNIX computers.  As a bonus, if the
journal style requires underlining, italics, or boldface in the
citation, the LAYOUT.mffm macro embeds the formatting codes
necessary to turn these features on and off.  If you do not use
WordPerfect or any of the other above mentioned software, it may
still be possible to customize the LAYOUT.mffm macro to embed the
appropriate codes necessary to turn on/off these features for
your word processor (see below).

     LAYOUT.rexx reads citations from a text file and reformats
them (the same way that LAYOUT.mffm does, but without the need
for the MFF+ database program).  LAYOUT.rexx is functionally
identical to the MFF+ based LAYOUT.mffm with the exception that
LAYOUT.mffm works within the flexible MFF+ database environment
while LAYOUT.rexx works on text files of citations created with a
word processor or text editor.  The latter allows a user to
create citation databases which can later be imported into MFF+
(the cost effective way of creating databases until MFF+ may be
purchased).  Don't underestimate the utility of LAYOUT.rexx.  I
started out by creating my citation databases as text files using
a word processor.  The users of such text file based citation
databases must perform all numeric or alphabetic sorting and
selection of citation subsets using a word processor or text
editor.  Once the subset of citations has been saved as a text
file, LAYOUT.rexx can be used to "lay out" or format the
citations as directed by the journal TEMPLATE file (see below).

FILES FOUND IN THE CITATION_BASE DIRECTORY:

  ReadMe                 {shareware disclaimer}
  Citation_Base.doc      {doc file about Citation_Base}
  CB_v1.1_update.doc     {version 1.1 update doc file}
  MFF+_Files <dir>       {MFF+ database example and ARexx macros}
  LAYOUT.templates <dir> {directory of Citation_Base journal
                          templates used by ARexx LAYOUT macros}
  REXX <dir>             {directory of ARexx macros and example
                          text file citation database}
  QView                  {shareware text file viewer}

FILES FOUND IN THE MFF+_FILES DIRECTORY:

  Example_Base.mff        {example database file}
  Example_Base.mff.info   {corresponding info file}
  macros <dir>            {ARexx macros for use within MFF+}
  MFF.project.info        {info file makes setting up new MFF+
                          databases easier}

FILES FOUND IN THE MACROS DIRECTORY:

  LAYOUT.mffm              {MFF+ ARexx macro #1}
  IMPORT.mffm              {MFF+ ARexx macro #2}
  EXPORT.mffm              {MFF+ ARexx macro #3}
  FULL_JOURNAL.mffm        {MFF+ ARexx macro #4}
  ABBR_JOURNAL.mffm        {MFF+ ARexx macro} ***external***
  AGRICOLA_IMP.mffm        {MFF+ ARexx macro #5}
  PRO-CITE_IMPORT.mffm     {MFF+ ARexx macro #6}
  PRO-CITE_EXPORT.mffm     {MFF+ ARexx macro #7}
  REFER-BibIX_IMPORT.mffm  {MFF+ ARexx macro #8}
  REFER-BibIX_EXPORT.mffm  {MFF+ ARexx macro #9}

FILES FOUND IN THE TEMPLATES DIRECTORY:
(LAYOUT.mffm and LAYOUT.rexx journal style templates identified
by name.  Here are two examples.  Please read or print the
directory for a full listing...)

  J_Clin_Microbiol.template    {representative template file}
  ALL_TEMPLATES                {file listing all CB templates}

FILES FOUND IN THE REXX DIRECTORY:

     Example_Base.txt          {citation database, text format}
     AGRICOLA_example.txt      {example AGRICOLA citation file}
     PRO-CITE_example.txt      {example PRO-CITE citation file}
     REFER-BibIX_example.txt   {example REFER-BibIX citation file}
     LAYOUT.rexx               {ARexx macro}
     FULL_JOURNAL.rexx         {ARexx macro}
     ABBR_JOURNAL.rexx         {ARexx macro}
     AGRICOLA_IMPORT.rexx      {ARexx macro}
     PRO-CITE_IMPORT.rexx      {ARexx macro}
     PRO-CITE_EXPORT.rexx      {ARexx macro}
     REFER-BibIX_EXPORT.rexx   {ARexx macro}
     REFER-BibIX_EXPORT.rexx   {ARexx macro}

     SORTING_UTILITIES DIRECTORY  {ARexx/Xicon macros for sorting
                                   Citation_Base text databases}

WHAT DO YOU NEED TO USE THIS PACKAGE OF MACROS AND FILES?

     You will have to modify (upgrade) your WORKBENCH disk by
first installing William Hawes' ARexx and secondly installing ARP
version 1.3 (AmigaDOS Resource Project version 1.3, available in
the public domain).  If you have WorkBench 2.0, you will already
have ARexx!  The RexxArpLibrary must also be installed
(as instructed on William Hawes' ARexx disk).  A copy of
MicroFiche Filer Plus (MFF+) must be supplied in order to use the
example citation database file (Example_Base.mffm) and the MFF+
specific ARexx macros.  Alternatively, you may choose to create
text file-based citation databases using a word processor or text
editor.

     You will also need to create (format) a working disk named
CITATION_BASE, onto which the entire CITATION_BASE directory must
be copied.  The reason for this is to allow the existing macros
to work without modifying the disk names and directory
assignments.  That is, the macros look for a disk named
CITATION_BASE, and directories named CITATION_BASE, REXX,
MFF+_FILES, MACROS, and TEMPLATES.  If you do not like these

names, the macros can be modified to use any disk or directory
names you prefer.  The most important disk/directory path
assignments are made in the MFF+ macro menu selections one
through eight (where, for example, LAYOUT.mffm is executed by
running macro #1).  Should you change the disk and directory
names, be sure to edit the macro menu selections in MFF+ before
trying to run them, or else they will simply abort without
execution.  The best way to understand the preceding section is
to start up MFF+ (from a CLI or SHELL), load Example_Base.mff and
look at the selections available in the MACROS menu.


CITATION_BASE OPERATION WITH MICROFICHE FILER PLUS:

     There are two ways to create and maintain a citation
database using Micro Fiche Filer Plus (MFF+).  The first way is
to make a backup copy of Example_Base.mff, rename it, open this
example database file and enter new citation records directly.
There is an alternative or complementary approach available as
well.  Citations can be created in a word processor, saved as a
plain text file (as instructed below) and imported into the
database file using the MFF+ ARexx macro "IMPORT.mffm" included
in this package.  I wrote this simple macro because I must use
IBM and MacIntosh computers at work.  I certainly don't want to
enter the citations I need for work related writing at home, on
my own time.  To get around this problem, I create (save) TEXT
files of citations using word processors at work.

     If the files originated on an IBM, I use one of the
following means to transfer the file to an AmigaDos disk:  1)
Central Coast Software's commercial software DOS-2-DOS, 2)
PCUtils720--Werner Gunter's public domain patch to the PCUtil
programs found on the Amiga EXTRAS disk, 3) Consultron's
commercial software CrossDos, or Olaf Seibert's public domain
program entitled MSH (MessyDos File System).  If the file was
created on a MacIntosh, I use the file transfer software supplied
with ReadySoft's A-Max MacIntosh emulator to transfer the text
files to an AmigaDos disk.  Alternatively, the files could have
been transfered using a modem or Central Coast Software's
MAC-2-DOS.  Once copied to the AmigaDos disk, the citations can
be imported into the MFF+ citation database using MFF+ ARexx
macro #2 (IMPORT.mffm).  Please note, however, that if the
citations in the text file do not conform to the standard format
described below, they will become garbled during the import
process, or may even cause the macro to end prematurely.  You
should always import such files to a backup copy of your parent
(primary) MFF+ citation base file.


     Three additional macros allow for the importation of
citations from other databases.  You must first move the citation
file from the disk of origin (MAC or IBM) to an AmigaDos disk
(see above).  The first macro, AGRICOLA.IMP.mffm imports
citations that originate on the AGRICOLA database (accessed via
online services or CD ROM-based computer station.  Be careful
when importing these citations, since not all of the citations on
the AGRICOLA CD ROM are entirely accurate.  "Odd" citations are
excluded during the importation process and saved in a "BAD"
citation file.  You can edit these citations by hand and try to
import again, or simply enter them into the database by hand.

     The PRO-CITE_IMPORT.mffm and PRO-CITE_EXPORT.mffm macros and
the REFER-BibIX_IMPORT.mffm and REFER-BibIX_EXPORT.mffm macros import
citations that originate from ISI's Current Contents software
(IBM or MAC).  As long as you exclude book citations, these
macros import just fine.  You can also export using these macros
which will allow you to share databases with individual using
bibliographic software including:  PRO-CITE, EndNote, REFER and
BibIX.  (Each copyright their respective parent companies).

     The macro EXPORT.mffm allows the user to export the
citations contained in the MFF+ database as a text file of
stock citations.  This feature allows you to share databases with
other Citation_Base users who do not have a copy of MFF+.

     There are two ways to enter the citation database using
MFF+.  Firstly, the citation database file icon (e.g.
Cite_Base.mff.info) can be double clicked, whereupon you will be
prompted to insert your MFF+ disk (MFF+ and the database file are
loaded automatically).  The MFF+ ARexx macros will work fine this
way, but there are advantages to using the second method.  The
second method requires that you open a new CLI or SHELL, load
MFF+ from the CLI or SHELL and finally load the citation database
file from within MFF+.  The CLI/SHELL used to launch MFF+ is then
used as a destination for MFF+ error messages (hopefully zero in
number) and for screen output generated by the ARexx macros.  The
screen output generated by the macros allows the user to monitor
the progress of the macros.

     LAYOUT.mffm is executed by using the mouse to select macro
#1 in the macro menu in MFF+ (after SELECTING some citation
records).  Upon execution, the macro displays a requester
requiring the user to select the output file format for the laid
out citations (WordPerfect or Microsoft Word [Rich Text Format]).
A second requester will appear requiring the user to select or
enter the name of the destination file into which the "laid out"
citations will be saved.  Drive ID's, disk names, directory names
and file names may be "clicked on" in the requester to enter the
path and file name required.  Next, a requester appears requiring

the user to select or enter the name of a TEMPLATE file to be
used in "laying out" the citations.  The macro will then proceed
to lay out the citations, echoing the results to the appropriate
CLI/SHELL.  I recommend saving the text file of "laid out"
citations to RAM: or to VD0: to speed up output and reduce the
time your disk drive is tied up.  After LAYOUT.mffm is finished,
remember to copy the file to your floppy or hard disk before
proceeding.  The text file of laid out citations can be RETRIEVED
into WordPerfect or software capable of importing RTF files.
LAYOUT.mffm is no speed demon, it lays out citations at a rate of
approximately 900 per hour (i.e. 1 citation every 4 seconds).
While that may seem slow, the alternative (retyping and
proofreading citations) is usually even more time consuming.

     Two additional ARexx macros enable the user to export lists
of full journal names or abbreviated journal names from MFF+
citation databases.  Again, these macros may be executed by
selecting the appropriate macro menu item in MFF+
(FULL_JOURNAL.mffm or ABBR_JOURNAL.mffm).  I use the macros to
maintain lists of the names of journals from which the citations
originated and to allow a quick visual cross check for
misspellings.  The exported lists will not be sorted
alphabetically unless you first move the SORT BY ABBR_JOURNAL
form to the SORT FORM slot.


CITATION_BASE OPERATION WITH A WORD OR TEXT PROCESSOR:

     Citation databases may be created with a word processor or
text editor by following the standard citation format described
below.  Since most word processors and text editors do not sort
groups of text lines, you will have to manually enter (insert)
"new" citations in the correct position within existing citation
database files if you wish the citations to be alphabetized or
numerically ordered.  When the citations must be "laid out" for
use in a manuscript, entire citation files may be used or a
subset may be selected and exported as a text file.  I usually
use "block and move" operations in the word processor to move the
necessary citations to the front of the file, delete the
unnecessary citations and save the subset as a separate text
file.  At this point the ARexx macros may be executed.

     The LAYOUT.rexx macro may be executed  (launched) by double
clicking on the LAYOUT.rexx icon or by typing "rx LAYOUT" from a
CLI or SHELL.  LAYOUT.rexx functions the same way as LAYOUT.mffm
(see above for details) with the following exception:  the first
requester requires the user to identify a text file of stock
citations to be laid out.


     Two additional ARexx macros enable the user to export lists
of full journal names or abbreviated journal names from the
citation database text files.  Again, these macros may be
executed by double clicking their icons or by entering
"rx FULL_JOURNAL" or "rx ABBR_JOURNAL" at a CLI/SHELL prompt.  I
use the macros to maintain lists of the names of journals from
which the citations originated and to allow a quick visual cross
check for misspellings.  The exported lists will not be sorted
alphabetically, but this is easily accomplished using the
AmigaDos (ARP version) command SORT.  Enter the following at a
CLI/SHELL prompt:

   sort <unsorted file name> <sorted file name>

including any relevant directory paths and the file of unsorted
journal names will be sorted and saved into the sorted file.

     Additional macros include AGRICOLA IMPORT, PRO-CITE and
REFER-BibIX IMPORT and EXPORT ARexx macros.  As described above,
these macros import or export citations from other databases,
altering the formats to closely resemble the CITATION_BASE format.
All require minor editing of the imported citations to completely
match the standard format.  Remember, you must create the
citation lists as text files on the originating computer and move
the files to an AmigaDos disk before these macros can be used.


CITATION_BASE STANDARD FEATURES:

STOCK CITATION FORMAT:

     LAYOUT.mffm and LAYOUT.rexx require that the stock
(standard) citations (records in MFF+) conform to the following
format:

LINE 1:  surname, initials, surname, initials...
LINE 2:  year of publication
LINE 3:  title
LINE 4:  abbreviated journal name, volume number, first page,
         last page, and keywords separated by commas
LINE 5:  full journal name preceded by an asterix









THREE EXAMPLES OF STOCK CITATIONS:

     Zakowski, P, Fligiel, S, Berlin, G W, Johnson, B L Jr
     1982
     Disseminated &Mycobacterium$ &avium$-&intracellulare$
     infection in homosexual men dying of acquired
     immunodeficiency
     J. Am. Med. Assoc., 248, 2980, 2982, case report, AIDS,
     *Journal of the American Medical Association

     Gordon, MJ, Huang, X, Pentoney, SLJr, Zare, RN
     1988
     Capillary electrophoresis
     Science, 242, 224, 228, review,
     *Science

     Weisman, B L
     1979
     Urticaria and &Giardia$ &lamblia$ infection
     Ann. Allergy, 42, 91,, brief report, protozoan,
     *Annals of Allergy

Please note these important features:

Line 1)  The authors' surnames and initials are separated by
         commas, and there can be spaces in between each author's
         initials.  The authors' initials are all in capitals
         with the exception of the lowercase 'r' in the
         abbreviation of 'junior' (Jr).  The last set of initials
         in the author list is not followed by any punctuation.
         If the citation contains no author(s) you should
         probably use 'Anonymous' as the surname and leave the
         initials blank.
         For example:  Anonymous, [RETURN]

Line 2)  Use the full year designation (e.g. 1988, not '88).

Line 3)  The title is entered in full, but do not end it with
         a period (punctuation is added by the LAYOUT macros).
         Also note that words requiring special formatting (e.g.
         italics) can be accomodated by adding an '&' in front of
         the word to turn ON the formatting and by adding a '$'
         after the word to turn OFF the formatting.  The
         desired format is controlled by a subcode in the
         TEMPLATE string (more on this later).

Line 4)  The abbreviated journal name (using periods after each
         abbreviated word) is followed by a comma and a space.
         Next is the journal volume number followed by a comma

         and a space.  Next in line is the first page number.
         The second page number follows the first.  Please note
         that if the article is only one page long you should
         enter no character (null) for the last page number, but
         do add a comma to separate the 'null' last page number
         from the first keyword (see above).  Keywords are
         separated by commas.

Line 5)  The last line begins with an asterix (*) and is followed
         by the full journal name.

         If you are not sure of the appropriate abbreviation for
         a given journal name, verify your abbreviation by
         consulting one of the following:  Bibliographic Guide
         for Editors and Authors, Serial Sources for the BIOSIS
         Data Base, American National Standard for Abbreviation
         of Titles of Periodicals, or Chemical Abstracts Service
         Source Index.  If you cannot find an "accepted" abbrevi-
         ation for the journal name, it is probably best to use
         the full journal name in LINE 4.


Here is the "first" citation (shown above) "laid out" in two
different journal formats.  Please note that special printing
characters are not shown (i.e. italics and boldface).

"JOURNAL OF PARASITOLOGY" format:

ZAKOWSKI, P., S. FLIEGAL, G. W. BERLIN AND B. L. JR. JOHNSON.
1982. Disseminated Mycobacterium avium-intracellulare infection
in homosexual men dying of acquired immunodeficiency. Journal of
the American Medical Association 248:2980-2982.

"PARASITOLOGY RESEARCH" format:

Zakowski, P, Fliegal, S, Berlin, GW, Johnson, BLJr (1982)
Disseminated Mycobacterium avium-intracellulare infection in
homosexual men dying of acquired immunodeficiency. J Am Med Assoc
248:2980-2982











CREATING YOUR OWN LAYOUT TEMPLATE FILES:

     The TEMPLATE file actually contains a single string broken
up into seven substrings, each with a particular function.  Each
substring is separated by a slash ("/") character.  For example,
the TEMPLATE file "Infect_Immun.template" represents the format
required by the journal INFECTION AND IMMUNITY:

{a.} y. t. j {v:}f-l./ i./ @i s/i s,/i s,/s,i,/i/

     The first substring represents the structural format of the
entire citation.  In the example above, the curly bracket ("{")
turns ON boldface type.  Next, the "a" indicates that all of the
author names follow, with a period added to the end of the last
author's name.  The closing curly bracket ("}") turns OFF the
boldface type.  A space is then printed followed by the year, a
period and a space.  The title is printed followed by a period
and a space.  The abbreviated journal name is printed next
followed by a space.  Boldface type is again turned ON and the
volume number is printed followed by a colon.  Boldface type is
turned OFF, the first page number is printed followed by a dash,
the last page number and finally a period.  That's it!

     The second substring defines the format around each author's
initial(s).  In the above example, each initial is preceded by a
space and followed by a period.

     The third substring defines the format around the last
author in the author list.  In the above example, a space
precedes the word "and" (here denoted by the symbol "@"),
followed by the author's initial(s) (see substring 2 for the
initials format).  A space is printed after the author's initials
and finally the author's surname is printed.  REMEMBER, substring
1 indicated that a period follows the list of author names, so no
period is included at the end of substring 3.

     The fourth substring defines the format around the next-to-
the-last author in the author list.  In the above example, the
author's initial(s) are printed followed by a space, the author's
surname and finally a comma.

     The fifth substring defines the format around an author in
the middle of a long author list (more than three authors).  In
the above example, the author's initial(s) are printed followed
by a space, the author's surname and finally a comma.  (Same as
substring 4).




     The sixth substring defines the format around the first
author in the author list.  In the above example, the author's
surname is printed followed by a comma, the author's initials
(again, as defined by substring 2) and finally a comma.  So what
happens if the citation only has one author?  Do you get a comma
and a period after the author's name?  No.  LAYOUT.mffm and
LAYOUT.rexx check for improper character combinations (like ",.")
and remove the unnecessary character(s).

     The seventh substring defines the type of embedded
formatting codes to substitute for the toggle characters ("&" and
"$") used in the title string (in the stock citation).  The five
possible embedded code pairs are identified by the following
characters:

  "i" replaces "&" and "$" with italics ON and OFF codes
  "u" replaces "&" and "$" with underline ON and OFF codes
  "b" replaces "&" and "$" with boldface ON and OFF codes
  "S" replaces "&" and "$" with the same characters ("&" and "$")
  "n" replaces "&" and "$" with null values ("")

     The TEMPLATE string contains other reserved or special
characters that are decoded into the format used by LAYOUT.mffm.
The following lists these characters and their meanings for
substring 1:

  "a" represents the author list
  "y" represents the year
  "t" represents the title
  "f" represents the first page number
  "l" represents the last page number
  "n" represents the citation number (printed in order of output)
  "J" represents the full journal name (capitol "J")
  "j" represents the abbreviated journal name (lowercase "j")
  "k" represents the abbreviated journal name (without periods
      after the abbreviations)
  "{" turns ON boldface type
  "}" turns OFF boldface type
  "[" turns ON italics
  "]" turns OFF italics
  "<" turns ON underline
  ">" turns OFF underline








     The following lists the special characters and their
meanings for substrings two through six (initials and author
formats):

  "i" represents initials
  "s" represents normal surname (lowercase "s")
  "S" represents surname printed in uppercase (uppercase "S")
  "@" represents the word "and" (it will be printed in either
      upper or lowercase depending on the surname character case)

     All other characters present in the TEMPLATE string are
printed directly to the output citation file.  For example,
characters like spaces, periods, commas, colons, semicolons, and
the ampersand ("&") are printed directly as part of the citation.


     The best way to master the creation of TEMPLATE strings
(files) is to make a printout of all of the TEMPLATE file strings
supplied with this package (see 'ALL_TEMPLATES' file).  Lay out
the citations in the example database file using each of these
TEMPLATES, retrieve them into WordPerfect or RTF file compatible
software and print the laid-out citations.  Compare the TEMPLATE
strings with their corresponding laid-out citations and use them
as a guide in creating your own TEMPLATES.

     Some journals employ unusual formats that cannot be
completely accommodated by the current versions of LAYOUT.mffm
and LAYOUT.rexx.  Journal templates can usually be devised to
carry out most of the necessary formatting, with the user
supplying additional modification.  For example,
"!J_Am_Vet_Med_Assoc.template" lays out citations in a standard
manner, but the journal requires that citations with more than
three authors follow a special format:  authors number four and
higher in the author list are truncated and replaced with "et
al."  TEMPLATES with unusual formatting conditions are identified
be an exclamation point preceding the TEMPLATE filename.


SUMMARY:

     While I have made every attempt to create a useful package,
the user may find it necessary to customize the macros or
accessory files for his/her own purpose.  If you find a defect or
deficiency in the package or improve it in some way, please let
me know about it so that I can update the files or advertise your
version in future releases of the text file you are now reading.

Michael J. Arrowood
September 15, 1990