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 {MFF+ database example and ARexx macros} LAYOUT.templates {directory of Citation_Base journal templates used by ARexx LAYOUT macros} REXX {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 {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 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