FAQ: v8.5.3 (and newer) Macros and Run-Menu Commands

[PeterJones]

Hello, and welcome to the FAQ Desk. You have likely come looking for information or have been directed here to find out more about the v8.5.3 changes to Macros and Run-Menu commands.

Notepad++ v8.5.3 changed how it interprets the Macros and Run-Menu commands in shortcuts.xml (found in the <Macros> and <UserDefinedCommands> sections).

Differences in shortcuts.xml

In Notepad++ v8.5.2 and earlier, if you had a “special character” in your macro or run-menu command – whether it was in the name of the macro/command or in text that it uses – then inside the XML, it would be stored as an XML entity. For example, ☺ would be stored as ☺ or π as π .

In Notepad++ v8.5.3, it changed to storing those characters as actual UTF-8 encoded characters, and it treats entities as raw text. Thus, π is interpreted by v8.5.3 (and newer) as 8 characters, not an entity-representation of the underlying character.

This change in interpretation may make it so your old macros or run-menu commands don’t work as expected.

Good News

2023-July-05 update: There are still a small number of entities that will be recognized inside macros, even in v8.5.3 and newer:

• The 5 predefined XML named-entities: & < > ' "
• Any of the hexadecimal entities that only include two hex digits, like 
 and 
 for CR and LF, and " for double-quotes. This notation works for all ASCII codepoints from 1 ( for the SOH character) through 127 ( for the DEL character)

Updating shortcuts.xml from earlier versions to v8.5.3 (or newer)

When Notepad++ v8.5.3 (or newer) reads a shortcuts.xml that was created with v8.5.2 (or earlier) when it first loads, it will interpret those entities as literal characters, so you may notice that your Macros or Run Menu commands don’t work as they used to. Notepad++ will actually warn you about this if you exit Notepad++ after having done anything that triggers a write to shortcuts.xml (for example, if you recorded a new macro, or added a new Run-menu command, or changed a shortcut using Shortcut Mapper): it will pop up a dialog , telling you that it is backing up your old-style shortcuts.xml as shortcuts.xml.v8.5.2.backup, and encouraging you to check your macros and run-menu commands for functionality, and to edit them if they don’t work. It does not update the entities to characters for you, because the developers could not find a way to match the edge cases for that conversion, and instead left it up to you to manually change all your old macros and run-menu commands.

To edit your macros and run-menu commands, follow the User Manual’s advice on Editing Configuration Files, and open %AppData%\Notepad++\shortcuts.xml (assuming a standard Config Files Location) and also look at %AppData%\Notepad++\shortcuts.xml.v8.5.2.backup for comparing to the old version of your macros. Anyplace there is an π-style entity in the shortcuts.xml, you will want to replace it with the actual character it refers to.

For doing the translation, there are multiple choices for entering characters that aren’t easily typed on your keyboard, or characters that are special to XML:

• Inside Notepad++, you can select the specific entity – in this example, π – then use Ctrl+H or Search > Replace to bring up the replacement dialog; the π will normally now be populated in the Find what: expression; set Replace with: to \x{03C0}, make sure Search mode is set to Regular Expression, and run Replace All. (Unfortunately, you have to do that manually for every entity; you cannot put a capture group in the Find what and then refer to that group-number inside the \x{...} in the Replace with, as convenient as that would be.) Alternately, you can search the internet for entity-to-character tables; the author of this FAQ frequently uses fileformat.info’s unicode search, where you can just paste in the entity and it will link you to the actual character.
  • For macros where you recorded typing a newline (hitting ENTER on your keyboard), it would have been recorded as an individual 
 and 
. The following regular-expression replacements below will convert those to two-digit hex entities (per July 5 update): individual CR and LF characters to make up the newline:
    • FIND WHAT = &#x0+0D; and REPLACE WITH = 
 with Search mode set to Regular Expression
    • FIND WHAT = &#x0+0A; and REPLACE WITH = 
 with Search mode set to Regular Expression
  • For macros where you recorded typing a double-quote mark ", it would have been recorded as an ". The following regular-expression replacements are two different ways to update the macros to use allowed entities for the double-quote:
    • FIND WHAT = &#x0+22; and REPLACE WITH = " with Search mode set to Regular Expression
    • FIND WHAT = &#x0+22; and REPLACE WITH = " with Search mode set to Regular Expression
• When in Windows (CR LF) line ending mode, you cannot easily type a single CR or a single LF; to get those individual characters, if you don’t want to use the search-and-replace , you can use the Windows-standard Alt+numeric-keypad sequence: holding down Alt key while typing 0 then 1 then 3 on your numeric keypad, then letting go of Alt, will insert a lone CR (regardless of your file’s line-ending) and holding down Alt and typing 0 then 1 then 0 on your numeric keypad, then letting go of Alt, will insert the lone LF.
• Notepad++'s Edit-menu Character Panel feature will allow you to insert characters – whether the lone CR or LF, or one of the others from the ANSI character list shown in the Character Panel
• You can also run Windows’ Character Map app using Notepad++'s Run > Run… with a command of charmap.exe , which will allow you to put one or more character into the clipboard, then paste them into the appropriate attribute in your shortcuts.xml

Example

If you had a macro called πΣσ whose purpose was to input those three characters, the v8.5.2 shortcuts.xml would look like:

        <Macro name="&#x03C0;&#x03A3;&#x03C3;" Ctrl="no" Alt="no" Shift="no" Key="0">
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&#x03C0;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&#x03A3;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&#x03C3;" />
        </Macro>

To make that same macro work right in v8.5.3, you would have to edit it to be

        <Macro name="πΣσ" Ctrl="no" Alt="no" Shift="no" Key="0">
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="π" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="Σ" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="σ" />
        </Macro>

The following macro shows the named entities that still work in macro sParam values with v8.5.3 and newer, as well as showing how to get a CRLF newline sequence using the two-hex-digit entities. You can use this as an example for when you are manually editing your macros to work for v8.5.3 and newer:

        <Macro name="XML Named Entities" Ctrl="no" Alt="no" Shift="no" Key="0">
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&amp;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&lt;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&gt;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&apos;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&quot;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&#x0D;" />
            <Action type="1" message="2170" wParam="0" lParam="0" sParam="&#x0A;" />
        </Macro>

I need help fixing my macro despite the example

If you still need help on how to fix your existing macros after reading this FAQ, you can post in the “HELP: Having trouble with Macros in v8.5.3 or later” topic. Please make sure you have at least tried to follow the advice here, and explain what you tried, and why you think it didn’t work. If discussions there show that this FAQ is inadequate, we will try to improve the FAQ.