====== MODS: a command-line tool for searching and editing MODS records ======

The MODS command-line tool is a simple way to search and edit MODS records from the command-line.  The examples below show some basic uses of the tool.  Use the editing features of this tool with some caution, however.  It is powerful and not particularly user-friendly.

===== Documentation =====

==== Installation ====

To install, copy all the contents of R:\aaron\dubois_digitization\mods into your C:\WINDOWS folder.  Open up a Command Prompt by going to Programs -> Accessories -> Command Prompt or by clicking on Run in the Start menu and entering "cmd" into the window.  To test if mods is installed correctly, enter:
<code>mods --help</code>
and hit enter.  You should see a list of options and an explanation of what they do.

==== Examples ====

In these examples, ">" represents the command-line prompt. 

The most common and practical use of the tool is to search within an entire directory of MODS records.  The "-S" option allows you to do this.  All commands are case sensitive so make sure you use a capital "S".  The basic method of searching looks like this:

<code>>mods -S "Text you want to search for" *.xml</code>

Every mods command requires an argument at the end.  Generally, that argument should be *.xml, which will apply the command to every .xml file in your current directory.  By default, the command above will search all the text in the <abstract> element.  If you would like to search for text in another element(s), you can specify an xpath expression using the "-x" option to indicate what you would like to search:

<code>>mods -S "Allison" -x "//mods:name/mods:namePart[@type='family']" *.xml</code>

The above command will search every <namePart> element where the attribute type="family" for the text "Allison".  Make sure to include the namespace for each element, i.e. <mods:name> instead of <name>.  For more on xpath expressions, check out this tutorial: [[http://www.w3schools.com/XPath/default.asp|http://www.w3schools.com/XPath/default.asp]].  If your text string is found, the file name of the record where the text was found will be printed out to the screen.

==== Options summary ====

<code>Usage: mods.py [options] arg1

Options:
  -h, --help            show this help message and exit
  
  -v, --validate        Validate record to Schema
  
  -s SCHEMA_PATH, --set-schema=SCHEMA_PATH
                        Set path to MODS schema
 
  -c, --check-text      Check for missing text

  -e TEXT, --edit-text=TEXT
                        Set the text you want add.  Must use with --xpath
                        option to identify element text to edit.

  -I, --add-identifier  Add local identifier to records

  -o OUTFILE, --outfile=OUTFILE
                        Save edited records to a single outfile.  Default
                        prints to STDOUT.

  -w, --write-changes   Write changes to files.  WARNING, this will overwrite
                        the original files.

  -x XPATH, --xpath=XPATH
                        Use xpath expression to identify elements to edit.

  -a ELEM_XML, --add-element=ELEM_XML
                        XML element to add.

  -i INDEX, --index=INDEX
                        Tree index where element should be inserted.

  -f, --find-element    Find if an element is present in the tree.  Use with
                        --xpath option.

  -S STRING, --find-string=STRING
                        If specified with --xpath, find string in returned
                        element.  Default finds string in abstract  

 </code> 

==== Command-line tips ====
   
To change drives, enter the drive letter at the prompt and press enter:

<code>>y:</code>

To change directories, use the cd command followed by the path to the directory you want to change into:

<code>y:>cd scans/dubois_scanning/dubois_digitization/staging/box001</code>

To see what files are in your current directory, use the dir command:

<code>y:/scans>dir</code>