Readme.1st Table of Contents: INTRODUCTION REQUIREMENTS BEFORE YOU START CONTENTS OF DISTRIBUTION INSTALLATION RUNNING THE PROGRAM INTRODUCTION Mrc2xml.pl is a perl program that converts a file of MARC records to XML. The resulting XML markup will reflect the MARC tags and subfields that occur in the input file of MARC records. The output file will be well-formed XML but not necessarily valid XML (i.e valid when parsed against the DTD mrcbfile.dtd). The DTD reflects only the tags present in MARC 21 (including obsolete tags). So, for instance, any 9XX local fields will cause validation to fail. This means that, in order to produce valid XML data, the user will need to either, 1) delete the local fields (before or after conversion), or, 2) edit the DTD to allow the presence of the local fields. The program optionally provides for conversion of special characters and diacritics to Unicode character entities (see RUNNING THE PROGRAM below). REQUIREMENTS BEFORE YOU START The conversion software requires Perl v5.003 or later and version 1.2 or later of the free nsgmls parsers. Ports of Perl are available from http://www.perl.com, and nsgmls is available from http://www.jclark.com/sp. NOTE: Both perl and nsgmls need to be installed on your path. You need to know three things before you install the software: 1. The location of your Perl executable, which will be "perl.exe" on DOS and Windows systems and "perl" on Unix systems; 2. The location of Perl's "lib" directory; and 3. The directory in which you want the mrc2xml.pl file installed. This should be in a directory on your path. CONTENTS OF DISTRIBUTION: INSTALL.ME Perl script to install mrc2xml.pl MANIFEST File listing used by install.me README.1ST The file you are reading. bin/ Directory containing program files lib/ Directory containing Perl libraries and modules INSTALLATION To install the conversion software, go to the directory where you unpacked the distribution, then type the following at your shell prompt and follow the instructions: perl install.me SAMPLE INSTALLATION C:> perl install.me Pathname of perl executable: \perl\bin\perl.exe Directory to install executables: ("") \local\bin Directory to install library files: ("") \perl\lib You have specified the following: Perl path: \local\bin Bin directory: \local\bin Lib directory: \perl\lib Is this correct? ['y'] y (\perl\bin\perl.exe) Installing programs to "\local\bin": bin/mrc2xml.pl => \local\bin\mrc2xml.pl Installing lib files to "\perl\lib": lib/SGMLS => \perl\lib\SGMLS lib/SGMLS.pm => \perl\lib\SGMLS.pm lib/sgmlspl.pl => \perl\lib\sgmlspl.pl lib/sgmlspl.pm => \perl\lib\sgmlspl.pm lib/Marcconv => \perl\lib\Marcconv NOTES ON INSTALLATION PROGRAM o You must be in the same directory as the install.me program. o The programs require Perl 5.003 and nsgml 1.2 or later to be installed. o The '#!' line in the installed programs is set to point to the Perl executable specified in the installation process. o Programs are updated to include the path location of the installed library files. Hence, you can install the library files in any location, and the program will still work. Manual Installation o Copy library (*.pl) files in the "lib" directory to the library location you desire. o Copy the program files to the location you want them installed. After copying, you must edit each file as follows: - Edit the "#!/..." line (the first line of each file) to be the complete pathname of your perl interpreter. Note, this step is unnecessary for Windows/MSDOS users. - Add a new line right after the "#!/..." line to contain the following: unshift(@INC, "/path/to/lib/files"); where "/path/to/lib/files/" is the path to where you copied the library files. Note, for Windows/MSDOS user, you will have to use "\\" (w/o the quotes) as the directory separator if using double quotes to delimit the path. For example: unshift(@INC, "C:\\path\\to\\lib\\files"); Note, if the location you copied the libraries are already part of Perl's standard library search path, you do not need to add the unshift () statement. RUNNING THE PROGRAM To run the program on DOS and Windows systems, the program is run from the DOS prompt. The program command line must be preceded by "perl -S", as in the following examples, so that the program is run by the PERL interpreter. On Unix systems, the "perl -S" is not necessary since Unix systems are able to automatically start the PERL interpreter to execute the program. Examples The following examples illustrate the use of the mrc2xml.pl program in the DOS and Windows command format. The complete program options are listed below (see Complete Command Options below). The user will type (or place in a batch file) the following commands and parameter settings: C:\perl -S mrc2xml.pl file.mrc The file of MARC records, "file.mrc", will be converted to XML. Since no options were given, the default minimal conversion of significant XML characters will be performed, the output will be written to "stdout.xml", and the log file written to "mrc2xml.log" C:\perl -S mrc2xml.pl -charconv file.mrc This is the same as the previous example except that " -charconv" specifies that that non-ASCII characters will be converted to Unicode entities using the character conversion table referenced by the program. perl -S mrc2xml.pl -command mycmd.cmd file.mrc The program is executed using the options contained in the command file "mycmd.cmd". C:\perl -S mrc2xml.pl -command mycmd.cmd -log mylog.log file.mrc The program is executed using the options contained in the command file "mycmd.cmd", except that the command line option" -log mylog.log" overrides both the default log file name and any " -log" log file name assignment in the command file. Complete Command Options Following is the complete list of command options used to invoke the MARC-to-XML conversion utility. The command can be followed by a variety of parameter settings, each of which follows the command, separated by a space, as follows. mrc2xml.pl [ -command file] [ -charconv | -userconv file] [-log file] [-o file] [-marcdesc file] [-help] input-file Remember, parts of these parameter settings highlighted above are determined by the user. Not all parameter setting must be used. When a parameter setting is not provided by the user, system defaults are applied by the conversion utility. Descriptions of each parameter setting are as follows: -command file Read program command options from "file" -xmlconv Perform minimal, "XML sanity" character conversion using the built-in conversion table. This is the default character conversion. -charconv Convert characters to entities using the built-in conversion table. The minimal XML conversion will also be performed. -userconv file Perform character conversion using the user -supplied Conversion specification in "file". An error will be signaled if "file" is not specified or if "file" cannot be opened, or if "file" is not a file of the correct format. The minimal XML conversion will also be performed. -log file Write the output log to "file". If this option is not specified, the log will be written to " mrc2xml.log" in the current directory. -o file Write the unvalidated XML output to "file" instead of to the default file "stdout.xml". -marcdesc file Read the MARC Description File named "file" instead of the default MARC Description File that the program automatically reads on initialization. -help Print help information then quit. input -file The name of the input MARC record file