alikaz3mi / MendeleyMacros

New functionalities for Mendeley's plugin: hyperlinks for citations pointing to bibliography, hyperlinks for URLs in bibliography, and fix to maintain Microsoft Word style of bibliography.

Mendeley macros

Macros used with Microsoft Word to add new functionalities to Mendeley's plugin.

Functionalities:

• The GAUG_* macros generate hyperlinks for citations pointing to the corresponding entry in the bibliography, as well as hyperlinks for the URLs in the bibliography generated by Mendeley's plugin. They support IEEE and APA CSL citation styles.
• The modified refreshDocument macro maintains Microsoft Word style of the bibliography generated by Mendeley's plugin when refreshing it.

Author

José Luis González García

Overview

You need the GAUG_* macros to create or remove the hyperlinks. Just add them to Microsoft Word, activate the RegExp object and execute any of the GAUG_* macros. The default custom configuration allows you to use the macros without any further modification. See the detailed instructions bellow on how to install them.

If you are annoyed that Mendeley's plugin changes the font style of the bibliography every time you refresh it, then you need to modify the refreshDocument macro installed by Mendeley's plugin to correct the problem. If you are happy with your bibliography, just forget about refreshDocument. See the detailed instructions bellow on how to modify the original macro.

Macros

GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Removes all hyperlinks generated for the citations from the document and leaves all fields as originally inserted by Mendeley's plugin. It also removes all bookmarks and hyperlinks generated in the bibliography.

The parameter strTypeOfExecution can have one of three different values:

• "RemoveHyperlinks": Removes the bookmarks and hyperlinks from the document. Manual modifications to citations and bibliography will remain intact. This value CANNOT be used if the square brackets are part of the hyperlinks in the IEEE CSL citation style. WARNING: UNEXPECTED RESULTS IF MANUAL MODIFICATIONS EXIST, BUT VERY FAST.
• "CleanEnvironment": Removes the bookmarks and hyperlinks from the document. Manual modifications to citations and bibliography will also be removed to have a clean environment. WARNING: STILL EXPERIMENTAL, BUT FAST.
• "CleanFullEnvironment": Removes the bookmarks and hyperlinks from the document. Manual modifications to citations and bibliography will also be removed to have a clean environment. WARNING: SAFE, BUT VERY SLOW IN LONG DOCUMENTS.

Custom configuration:

• strStyleForTitleOfBibliography: Specifies the Microsoft Word style used for the title of the bibliography. It helps to improve speed when locating the bibliography by narrowing the search to only the sections of the document with this style. It is only used when the flag blnMabEntwickeltSich is set to True. The document MUST follow a particular structure; see the description of the flag blnMabEntwickeltSich. The default value is a custom style called “Titre de dernière section” that you may need to create or change.
• blnMabEntwickeltSich: The default value False will force the macro to check every section of the document for the bibliography; IT IS THE WAY TO GO. If the flag is set to True, the speed may improve in long documents, but you need a particular structure in your document. First, the style specified by strStyleForTitleOfBibliography MUST exist otherwise the macro will throw an error. In addition to the style, the bibliography MUST also be placed in a section with a title in that style or the macro will not find it.

Important: It works ONLY with the IEEE and APA CSL citation styles installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or both IEEE and APA CSL citation styles.

NOTE: strTypeOfExecution="RemoveHyperlinks" is the way to go; it is reliable and fast. In case of manual modifications to the citations or bibliography, the hyperlinks may not be created or linked correctly. If previous approach did not work, use strTypeOfExecution="CleanEnvironment"; also fast but still considered as EXPERIMENTAL. It executes a very light weight version of Mendeley's function Mendeley.undoEdit to remove the hyperlinks and manual modifications from the citations. If you want to be in the safe side, use strTypeOfExecution="CleanFullEnvironment" which calls Mendeley's functions to do the job. The execution with the last option may take several minutes; use it with caution. Mendeley is slow when undoing changes to citation fields. This function is also called when creating hyperlinks for IEEE and APA citation styles.

GAUG_removeHyperlinks()

Wrapper for GAUG_removeHyperlinksForCitations("RemoveHyperlinks").

GAUG_cleanEnvironment()

Wrapper for GAUG_removeHyperlinksForCitations("cleanEnvironment").

GAUG_cleanFullEnvironment()

Wrapper for GAUG_removeHyperlinksForCitations("cleanFullEnvironment").

GAUG_createHyperlinksForCitationsAPA()

Creates the bookmarks in the bibliography and the hyperlinks for the citations in the document. It also creates the hyperlinks for the URLs in the bibliography. The citations must follow the APA CSL citation style.

Custom configuration:

• strStyleForTitleOfBibliography: Specifies the Microsoft Word style used for the title of the bibliography. It helps to improve speed when locating the bibliography by narrowing the search to only the sections of the document with this style. It is only used when the flag blnMabEntwickeltSich is set to True. The document MUST follow a particular structure; see the description of the flag blnMabEntwickeltSich. The default value is a custom style called “Titre de dernière section” that you may need to create or change.
• blnMabEntwickeltSich: The default value False will force the macro to check every section of the document for the bibliography; IT IS THE WAY TO GO. If the flag is set to True, the speed may improve in long documents, but you need a particular structure in your document. First, the style specified by strStyleForTitleOfBibliography MUST exist otherwise the macro will throw an error. In addition to the style, the bibliography MUST also be placed in a section with a title in that style or the macro will not find it.
• blnGenerateHyperlinksForURLs: The default value True will generate the hyperlinks for the URLs in the bibliography. The regular expression used to detect the URLs may not find them all; in such case you need to manually specify those that were not detected or fully detected. If the flag is set to False, the macro will not generate the hyperlinks for the URLs in the bibliography.
• arrNonDetectedURLs: Specifies the URLs that were not detected, or fully detected, by the regular expression in the bibliography. The macro will use these URLs to generate the corresponding hyperlinks. The list is only used when the flag blnGenerateHyperlinksForURLs is set to True.
• strTypeOfExecution: The default value "RemoveHyperlinks" is the fastest and THE WAY TO GO. See more details in the description of the GAUG_removeHyperlinksForCitations(strTypeOfExecution As String) macro about the type of execution.

Requires: GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Important: It works ONLY with the APA CSL citation style installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or APA CSL citation style.

GAUG_createHyperlinksForCitationsIEEE()

Creates the bookmarks in the bibliography and the hyperlinks for the citations in the document. It also creates the hyperlinks for the URLs in the bibliography. The citations must follow the IEEE CSL citation style.

Custom configuration:

• strStyleForTitleOfBibliography: Specifies the Microsoft Word style used for the title of the bibliography. It helps to improve speed when locating the bibliography by narrowing the search to only the sections of the document with this style. It is only used when the flag blnMabEntwickeltSich is set to True. The document MUST follow a particular structure; see the description of the flag blnMabEntwickeltSich. The default value is a custom style called “Titre de dernière section” that you may need to create or change.
• blnMabEntwickeltSich: The default value False will force the macro to check every section of the document for the bibliography; IT IS THE WAY TO GO. If the flag is set to True, the speed may improve in long documents, but you need a particular structure in your document. First, the style specified by strStyleForTitleOfBibliography MUST exist otherwise the macro will throw an error. In addition to the style, the bibliography MUST also be placed in a section with a title in that style or the macro will not find it.
• blnGenerateHyperlinksForURLs: The default value True will generate the hyperlinks for the URLs in the bibliography. The regular expression used to detect the URLs may not find them all; in such case you need to manually specify those that were not detected or fully detected. If the flag is set to False, the macro will not generate the hyperlinks for the URLs in the bibliography.
• arrNonDetectedURLs: Specifies the URLs that were not detected, or fully detected, by the regular expression in the bibliography. The macro will use these URLs to generate the corresponding hyperlinks. The list is only used when the flag blnGenerateHyperlinksForURLs is set to True.
• blnIncludeSquareBracketsInHyperlinks: The default value False will exclude the square brackets from the hyperlinks. If the flag is set to True, the macro will include the square brackets as part of the hyperlinks. BE AWARE that Microsoft Word DOES NOT handle this kind of hyperlinks very well and it is not possible to remove them with the argument "RemoveHyperlinks" or the wrapper GAUG_removeHyperlinks when the square brackets are part of them.
• strTypeOfExecution: The default value "RemoveHyperlinks" is the fastest and THE WAY TO GO. However, this value cannot be use if blnIncludeSquareBracketsInHyperlinks is set to True. See more details in the description of the GAUG_removeHyperlinksForCitations(strTypeOfExecution As String) macro about the type of execution.

Requires: GAUG_removeHyperlinksForCitations(strTypeOfExecution As String)

Important: It works ONLY with the IEEE CSL citation style installed with Mendeley. It MAY not work if you make manual modifications to the citation fields, bibliography or IEEE CSL citation style.

refreshDocument

This is a copy of the original macro installed by Mendeley and located in Mendeley-1.16.1.dotm (file name depends on the version of Mendeley). It has been modified in order to keep the Microsoft Word style of the bibliography generated by Mendeley's plugin when refreshing it. Have a look at the three lines with the comment 'MabEntwickeltSich, you need to add them to the macro of your installation of Mendeley. Follow the installation instructions below.

Keep in mind that this will only work if you used a Microsoft Word style for the bibliography. You can use a build-in style or create your own. If you made manual modifications to the format (font and paragraph) directly to the bibliography and then refresh it, it will go back to the original Microsoft Word style settings.

Important: This macro will NOT work out if its context. DO NOT COPY THE MACRO TO MICROSOFT WORD. This is just to illustrate what modifications have to be done to the original macro installed by Mendeley's plugin.

Installation

GAUG_*

1. Copy the code to your Microsoft Word macros to install any of the GAUG_* macros. See note below if using a Mac! For more information about macros, check Microsoft Office support: https://support.office.com/en-us/article/Create-or-run-a-macro-C6B99036-905C-49A6-818A-DFB98B7C3C9C

2. The GAUG_* macros make use of regular expressions; hence you need to enable the RegExp object in Microsoft Visual Basic for Applications. Open the menu “Tools” | “References” and check the box next to “Microsoft VBScript Regular Expressions 5.5”. For more information on how to activate the RegExp object search online for “Activate Microsoft VBScript Regular Expressions 5.5 in Word”.

refreshDocument

To “install” refreshDocument you need to modify the original macro by inserting the three extra lines with the comment 'MabEntwickeltSich:

1. Open the file Mendeley-1.16.1.dotm (or Mendeley-word201x-1.16.1.dot on a Mac) located in C:\Program Files\Mendeley Desktop\wordPlugin (or /Applications/Mendeley Desktop.app/Contents/Resources/macWordPlugin/word201x on a Mac). Check your own installation, your version of Mendeley may be different. You may have to enable macros for the document when you open it.

2. Open Microsoft Visual Basic for Applications from the “Developer” tab in Microsoft Word. You may have to enable the “Developer” tab if you do not see it. For more information on how to show the “Developer” tab, check Microsoft Office support: https://support.office.com/en-us/article/Show-the-Developer-tab-E1192344-5E56-4D45-931B-E5FD9BEA2D45

3. Modify the macro: Function refreshDocument(Optional openingDocument As Boolean = False) As Boolean which is located in the module MendeleyLib.

4. Once you finish the modifications save the changes, close Microsoft Visual Basic for Applications and Microsoft Word.

5. Open Mendeley Desktop, uninstall the Microsoft Word plugin and reinstall it again for the changes to take effect.

A sad note for Mac users The current versions of GAUG_createHyperlinksForCitationsAPA() and GAUG_createHyperlinksForCitationsIEEE() make use of regular expressions which are not available on Mac OS X (or macOS). HOWEVER, there is hope if you need the hyperlinks for the IEEE CSL citation style. Commit 6289273 has an old version of GAUG_createHyperlinksForCitationsIEEE() without regular expressions which you can still use. Follow the standard installation.

Usage

ALWAYS have a BACKUP COPY of your document BEFORE using these macros. GAUG_removeHyperlinksForCitations(strTypeOfExecution As String) is still considered as experimental.

Execute the desired macro. See also Extending/modifying the code.

My recommendation for a typical usage is to keep your document free of any manual modification to the bibliography or to the citations inserted by Mendeley, but you can merge the citations with the standard way provided by Mendeley: [1][2][3][4] becomes [1]-[4]. This also applies for the APA CSL citation style.

Also, keep your document without the bookmarks and hyperlinks generated by these macros while editing. Generate them ONLY when you want to create the PDF file or when you are done with the edition. If you want to further edit the document, remove all bookmarks and hyperlinks generated by these macros to prevent any conflict with Mendeley's plugin; the citation numbers in IEEE or text in APA may change.

It is important to note that GAUG_removeHyperlinksForCitations(strTypeOfExecution As String) is very slow when strTypeOfExecution="CleanFullEnvironment". It uses Mendeley's code to restore the original citation fields and bibliography. It is also called from GAUG_createHyperlinksForCitationsAPA() and GAUG_createHyperlinksForCitationsIEEE() to have a clean environment before creating the bookmarks and hyperlinks.

Extending/modifying the code

There is no need to do any changes to the code to start using the macros. The default custom configuration, at the beginning of every macro, fits most scenarios. The flag blnMabEntwickeltSich activates part of the code to improve speed in long documents, but a particular document structure is required or errors will appear during the execution.

In this moment the code is adapted to my own needs and to the structure of my document. Nevertheless, changing the code to fit other requirements is straight forward when you stick to the IEEE or APA CSL citation styles. Much more effort may be required to support a different CLS citation style; and I can confirm that great effort was done to include APA.

My document is divided in sections (Microsoft Word sections) for the chapters and other parts that are included in the thesis. The bibliography is located in a section with the title “Bibliography” using the style “Titre de dernière section” (custom Microsoft Word style for the title). The macros to remove or create the hyperlinks will try to find the bibliography in a section with this description when the flag blnMabEntwickeltSich is set to True. I did it this way to increase speed in long documents. If you want to remove this restriction and locate the bibliography in any section, simply set the flag to False (the default value) to force the macros to check every section for the bibliography.

Comments and suggestions are welcome.