<commit_before>EPUBCFI
=======

# The EPUB 3.0 CFI library

This library provides support, in javascript, for parsing and interpreting EPUB 3.0 Canonical Fragment Identifiers (CFIs). jQuery is the only dependency. 

The purpose of this library is to allow reading systems to do useful things with EPUB CFIs. At the moment, this involves injecting HTML elements into EPUB documents at locations referenced by CFIs. The intent is that the injected HTML elements can then be used by reading systems to navigate to, or display something at, those CFI locations. 

The library may be extended to include other sorts of behaviour as the use cases for CFIs become clearer. 

# How to use the CFI library

Note: Steps 3. and 4. will change soon. The requirement to retrieve a package document, parse a CFI, and pass the result to
the Interpreter, will be removed. The intention is to create an API that only requries the URL of an EPUB's package document and the HTML element to inject .

1. Get a copy of the library. Currently, a development version of the (library)[https://github.com/justinHume/EPUBCFI/blob/master/epub_cfi.js] is available in the Github repository. When the library becomes more stable, a minified version will also be made available as a separate download. 

2. Add the CFI library to your code using a script tag, and make sure you have included jQuery:

    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    <script src="epub_cfi.js"></script>

3. Set the package document URL and retrieve a package document object:

    EPUBcfi.Config.packageDocumentURL = "http://something/something";
    EPUBcfi.Config.cfiMarkerElements.textPointMarker = '<span class="cfi_marker"></span>';

    $packageDocument = do_some_stuff_to_get_a_jQueryed_package_document_object;

4. Parse a CFI and inject an element for that CFI:

    cfi = 'epubcfi(/6/18!/4/2/4:2)';

    try {
    
        ast = EPUBcfi.Parser.parse(cfi);
        $resultWithInjection = EPUBcfi.Interpreter.injectCFIReferenceElements(ast, $packageDocument, pathToPackageDoc);
    }
    catch (err) {

        // Do something with the error
    }

The result of this will be to inject the '<span class="cfi_marker"></span>' HTML element into a position in the EPUB pointed to by the CFI.

# Setting up the development environment

There are a number of dependencies for this project: 

* Ruby
* Rake
* The ERB template gem
* Git
* (jasmine)[http://pivotal.github.com/jasmine/]
* (PEG.js)[http://pegjs.majda.cz/]. PEG.js is both a library and a command-line tool. The project assumes that the PEG.js command line tool can be found on your path. You can change this in the Rake file. 

Once all that is good to go, clone the (Github)[https://github.com/justinHume/EPUBCFI] repository. 
<commit_msg>Changes to readme<commit_after>EPUBCFI
=======

# The EPUB 3.0 CFI library

This library provides support, in javascript, for parsing and interpreting EPUB 3.0 Canonical Fragment Identifiers (CFIs). jQuery is the only dependency. 

The purpose of this library is to allow reading systems to do useful things with EPUB CFIs. At the moment, this involves injecting HTML elements into EPUB documents at locations referenced by CFIs. The intent is that the injected HTML elements can then be used by reading systems to navigate to, or display something at, those CFI locations. 

The library may be extended to include other sorts of behaviour as the use cases for CFIs become clearer. 

# How to use the CFI library

Note: Steps 3. and 4. will change soon. The requirement to retrieve a package document, parse a CFI, and pass the result to
the Interpreter, will be removed. The intention is to create an API that only requries the URL of an EPUB's package document and the HTML element to inject .

1. Get a copy of the library. Currently, a development version of the [library](https://github.com/justinHume/EPUBCFI/blob/master/epub_cfi.js) is available in the Github repository. When the library becomes more stable, a minified version will also be made available as a separate download. 

2. Add the CFI library to your code using a script tag, and make sure you have included jQuery:

    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    <script src="epub_cfi.js"></script>

3. Set the package document URL and retrieve a package document object:

    EPUBcfi.Config.packageDocumentURL = "http://something/something";
    EPUBcfi.Config.cfiMarkerElements.textPointMarker = '<span class="cfi_marker"></span>';

    $packageDocument = do_some_stuff_to_get_a_jQueryed_package_document_object;

4. Parse a CFI and inject an element for that CFI:

    cfi = 'epubcfi(/6/18!/4/2/4:2)';

    try {
    
        ast = EPUBcfi.Parser.parse(cfi);
        $resultWithInjection = EPUBcfi.Interpreter.injectCFIReferenceElements(ast, $packageDocument, pathToPackageDoc);
    }
    catch (err) {

        // Do something with the error
    }

The result of this will be to inject the '<span class="cfi_marker"></span>' HTML element into a position in the EPUB pointed to by the CFI.

# Setting up the development environment

There are a number of dependencies for this project: 

* Ruby
* Rake
* The ERB template gem
* Git
* [jasmine](http://pivotal.github.com/jasmine/)
* [PEG.js](http://pegjs.majda.cz/). PEG.js is both a library and a command-line tool. The project assumes that the PEG.js command line tool can be found on your path. You can change this in the Rake file. 

Once all that is good to go, clone the [Github](https://github.com/justinHume/EPUBCFI) repository. 

{'fraction_non_alphanumeric': 0.07915194346289753, 'fraction_numerical': 0.007067137809187279, 'mean_word_length': 3.94410480349345, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '999283', 'n_tokens_mistral': 1665, 'n_tokens_neox': 1611, 'n_words': 720}