README
======

Table of Contents
-----------------

  I. Introduction
 II. Installation Instructions
III. Usage Instructions
 IV. License
  V. Funding and Acknowledgements
 VI. Contact


I. Introduction
---------------
Mendeley Desktop's Microsoft (MS) Office Word Plugin is difficult to work with
when compared with Endnote's Cite-While-You-Write (CWYW) Plugin. However, many
feel that Mendeley Desktop provides a more preferential user experience than
Endnote does for citation management and PDF annotation. I assume that you wish
to continue using Mendeley to manage your references and PDFs, but use Endnote's
CYWY Plugin in MS Word. This repository enables anyone running macOS to
accomplish this task. Similar principles would apply for other operating
systems, but such are not documented here. Please note that the script that
removes links to the PDFs in the the exported XML file from Mendeley should
work on virtually any Linux machine. In effect, this repository exists to help
others complete two relatively common, but potentially difficult tasks:

	1. Sending one or more Mendeley references to Endnote
	2. Converting in-text citations (and bibliography) in a MS Office Word
	   document generated with the Mendeley Plug-in to Endnote's CYWY format


II. Installation Instructions
-----------------------------
MendeleyEndnoteTools is implemented in bash and has some additional supporting
files (e.g., a macOS workflow, Mendeley CSL (Citation Style Language) file,
etc.). To install on a machine running macOS, please see the `INSTALL' file.

To install on a Linux machine, simply type `make'. The binary will be in the
`bin' directory. To install a binary outside this package, type `make' followed
by `make install'.  The binary will be in both the `bin' and `/usr/local/bin'
directories (to change this, please read the `INSTALL' file). To uninstall, type
`make clean'.

See the `INSTALL' file for further instructions.


III. Usage Instructions
-----------------------
1. Sending one or more Mendeley references to Endnote

Gratefully, Mendeley has provided an export
feature to Endnote. Simply select the records that need to go to Endnote and
select "Export" or command-E (macOS). Then ensure "Endnote" is the selected
export format (as opposed to .bib or RIS format). A common problem with
importing this output into Endnote is that the links to the PDFs are broken.
For those who do not even need/want the PDFs in Endnote anyway, this problem is
easily resolved by deleting the copies of the PDFs and removing the "links" to
them in the XML file. This script automates that process. Exporting and
importing must stil be done by hand.

For directions on how to run this software, simply run with the -h flag. Note
that the default file name for the XML file is "~/Desktop/My Collection.xml" and
the default directory for PDFs is "~/Desktop/My Collection.Data". Thus, if you
do not specify, -x and/or -d, the default values will be assumed.


Please run the software with the `-h' option for complete usage instructions
(i.e., type `geneSynthesizer -h' or `geneSynthesizer --help'). The format of the
input and output files is described below; followed by usage examples.

Input File Format:

    Description:

        The input file must be in Fasta format. The sequences may be on a single
        line or multiple lines. The header and sequence lines must not contain
        any leading or trailing whitespace. The header line must not contain any
        tabs. The sequence lines must not contain whitespace between
        nucleotides. Mixed-case nucleotides are acceptable; they will be
        replaced with uppercase nucleotides for primer design.

    Good Example:

        >sequence 1
        AGCGTGTCGTGTACACGTGTACGTACGTACGATCGATGCTACGTAGCATCGATCGACGTATCGTATCGATC
        CACGTGTACGTACGTACGATCGATGCTACGTAGCATCGATCGACGTATCGTATCGATCAGCGTGTCGTGTA
        .
        .
        .
        >sequence 2
        cgtacgatcgatgctacgtagcatcgatcgacgtatcgtatcgatcagcgtgtcgtgtacacgtgtacgta
        gatcgacgtatcgtatcgatcagcgtgtcgtgtacacgtgtacgtacgtacgatcgatgctacgtagcatc
        .
        .
        .
        >sequence 3
        taTCgATCAGCGtGTCGTGTAcACGTGTACGTAcgtaCGAtCgATGCTACGTagcatCGATCGACGTATCG
        cgtacgtacgATCGATGCTACGTaGCATCGaTCGaCGTAtCGTAtcgatcaGCGTGTCGTGTAcacgtgta
        .
        .
        .

Output File Format:

    Description:

        The output file has one record per header/sequence pair in the input
        fasta file. Each record has 2 sections (with an optional third section
        between the other two). The first section has three lines with
        name-value pairs, separated by a colon and a space (": "). These names
        are "ID", "Length", and "Overlap". The "ID" is the fasta header. The
        "Length" is the number of nucleotides in the fasta sequence. The
        "Overlap" is the number of nucleotides that overlap between primers.

        Given an overlap of 20, the "example/GFP.fasta" (which has only one
        sequence) will look like this:

                ID: Green Fluorescent Protein (GFP)
                Length: 717
                Overlap: 20
        
        The optional section contains a title line ("Overlap-View:"), followed
        by one line per primer. Each primer is padded with spaces to show the
        overlapping sections.

        The final section is tab-delimited. The first line is a title line and
        can easily be identified (for parsing purposes) because it begins with
        a "#". Remember, in a tab-delimited file, the columns may not align
        when viewed with a simple text editor. The columns (in order) are:

                Primer-Number
                For./Rev.
                Sequence(5'->3')
                Length

        Each of the columns are described below:

        Primer-Number: The primer number, counted left-to-right, starting with
                       the number one.

            For./Rev.: Each primer is identified as "F" (Forward) or "R"
                       (Reverse). It is also given a number, counted
                       left-to-right, starting with the number one. The count
                       is separate for the forward and reverse primers. As an
                       example, if there are 4 primers, the "Primer-Number"
		       will be 1, 2, 3, and 4. The "For./Rev." will be F-1,
		       F-2, R-1, and R-2, respectively.

     Sequence(5'->3'): The actual primer sequence, writen 5' to 3'.

               Length: The number of nucleotides in the primer.

        As a simple illustration of this section of the  output file, consider
        the following example with a primer length of 10, an overlap length of
	3, and sequence length of 41 (formatted here for readability):

                #Primer-Number   For./Rev.   Sequence(5'->3')   Length
                1                F-1         ACGTACGTAC         10
                2                F-2         TACGTACGTA         10
                3                R-1         GTACGTACGT         10
                4                R-2         CGTACGTACGT        11


IV. License
-----------
Please see the `LICENSE' file.


V. Funding and Acknowledgements
-------------------------------
The production of this software received no funding. Thanks to Alyssa Evans for
providing the motivation for this project. Further thanks to the Thomson Reuters
community for suggesting the method by which in-text citations can be
"converted" from Mendeley format to Endnote format; see the following forum:
http://community.thomsonreuters.com/t5/EndNote-How-To/Convert-an-citations-in-an-existing-document-to-be-EndNote-X7/td-p/55047


VI. Contact
-----------
For questions, comments, concerns, feature requests, suggestions, etc., please
contact:

Brandon Pickett -- [email protected]

Note: For usage questions, please consult section `III. Usage Instructions'
first.