Config XML Encoding (#764)

* Config XML Encoding
Add a section to the main Config-Files page, and a link in each of the other pages that have XML-file details, to make sure that no matter which topic a user is reading, the manual will make it clear.

* XmlEncoding: rearrange slightly for better flow

Author: pryrt

content/docs/auto-completion.md

@@ -100,6 +100,8 @@ Notepad++ uses XML configuration files to define the per-language function and p
 
 The syntax of AutoComplete files is simple, but does have a few rules, most importantly correct syntax and proper sorting. If the syntax is incorrect, the XML file will fail to load and AutoComplete will be not be available for that file type.
 
+Auto-completion XML files need to be encoded as UTF-8 with no BOM (see [Config File Encoding](../config-files/#configuration-file-encoding)).
+
 Improper sorting (see below) can cause the AutoComplete function to behave erratic, causing it to fail on certain words.
 
 The basic character set used to recognize keywords is made of letters `a-z`, `A-Z`, digits `0-9`, and the underscore `_`.  Punctuation might work for auto-completion; however, if you want to use the parameter hints, you should not use punctuation in the keyword name.
@@ -132,6 +134,8 @@ Auto-complete files files are located in the `autoCompletion\` subfolder of the
 
 Note: Create a `normal.xml` AutoComplete file for adding custom suggestions to the default language, Normal Text \[i.e., language set to "None (Normal Text)"\].
 
+Auto-completion XML files need to be encoded as UTF-8 with no BOM (see [Config File Encoding](../config-files/#configuration-file-encoding)).
+
 Under the usual `<NotepadPlus>` tag is a `<AutoComplete>` tag. It has an optional, unused `language` attribute, which you can use for any descriptive purpose.
 
 The contents of a `<AutoComplete>` start with an autoclosing `<Environment>` tag, with the following attributes:

content/docs/config-files.md

@@ -52,6 +52,10 @@ If changes are made in the Notepad++ UI to settings which are stored in configur
 
 The `config.xml` file may be overwritten by Notepad++ on exit, even if you follow this procedure, so that sequence won't reliably work for `config.xml`. To edit `config.xml`, close all instances of Notepad++; edit `config.xml` in some "other" editor and save; reload Notepad++ and the changes should take effect. (For the "other" editor, you _could_ use something like Windows' builtin notepad.exe. But it would be better if you had another portable Notepad++ somewhere on your machine, and use that portable Notepad++ to edit your main Notepad++'s `config.xml`, thus never having to use a non-Notepad++ editor: so close your main Notepad++, run the portable Notepad++ and open your main `config.xml`, edit and save, exit the portable Notepad++, then re-run the main Notepad++, and everything should be updated.)
 
+### Configuration File Encoding
+
+The Notepad++ XML configuration files are expected to be in UTF-8 encoding (with no BOM), and so should use the prolog of `<?xml version="1.0" encoding="UTF-8" ?>`.  If you use the BOM character at the beginning of a UTF-8 encoded XML file, or if you use another encoding like UTF-16, Notepad++ will not be able to read that configuration file.
+
 ## Configuration Files during Upgrades
 
 When you use the installer to upgrade your existing copy of Notepad++ (either manually, or through the **?**-menu's **Upgrade Notepad++**, or through Notepad++'s auto-update feature), the installer will avoid overwriting configuration files that you have customized -- this is to prevent you losing your preferred settings and customizations.
@@ -64,6 +68,10 @@ For the `config.xml` (which contains the settings from the GUI's **Settings > Pr
 2. When you run Notepad++, and there is no `config.xml` (either because there isn't a `config.xml` file and/or settings file for the current user, or the `config.xml` has been deleted), so Notepad++ writes a complete `config.xml` with all default values.
 3. When your `config.xml` is missing the attribute/value pair for a given setting.
 
+<hr>
+
+# Specifics on Configuration Files
+
 ## The context menu: `contextMenu.xml`
 
 <!-- http://web.archive.org/web/20190518131311/http://docs.notepad-plus-plus.org/index.php/Context_Menu -->

content/docs/function-list.md

@@ -14,6 +14,8 @@ In order to make Function List work for your language, you should modify (or add
 
 To customize the Function List, you need to edit the XML file for the language you are defining.  This section describes the structure and requirements for each XML element.
 
+Function List XML files need to be encoded as UTF-8 with no BOM (see [Config File Encoding](../config-files/#configuration-file-encoding)).
+
 The `<parser>` node accepts the three attributes:
 
 - `id`: Unique ID for this parser.

content/docs/themes.md

@@ -23,6 +23,8 @@ The easiest way to create a new theme is to copy an existing theme file to a new
 
 (You have to exit Notepad++ and rerun the application to see a new theme that you've copied into your Themes directory, or to see any updates you've made by manually editing the XML file(s).)
 
+Theme and styler XML files need to be encoded as UTF-8 with no BOM (see [Config File Encoding](../config-files/#configuration-file-encoding)).
+
 ## Sharing Themes
 
 You may share a theme (or someone may share with you) in a similar method to creating a new theme: copy the theme file, give it an appropriate name, and put it in your `Themes\` subdirectory: it's the same whether you are sharing across multiple users on the same computer, sharing across local computers, or sharing over the internet.

content/docs/user-defined-language-system.md

@@ -164,6 +164,8 @@ This central Collection is a convenient location for UDL-users to find new UDL f
 
 It is intended that UDL are edited using the GUI dialog boxes.  However, if you are the type of user who likes to configure Notepad++ through the configuration files, it is possible.  Please see the [Configuration Files Details](https://npp-user-manual.org/docs/config-files/#editing-configuration-files) for a description of the sequence for properly editing any of the config files, including the UDL definition files.
 
+UDL definition XML files need to be encoded as UTF-8 with no BOM (see [Config File Encoding](../config-files/#configuration-file-encoding)).
+
 Most of the settings in the UDL definition files correspond directly to the names seen in the **User Defined Languages** dialog box, or the **Styler** sub-dialog.  The `<KeywordLists>` section defines the keywords or symbols for each highlighting category.  The `<Styles>` section defines the text styling (color, font, weight, and decoration) for each highlighting category.  The `<WordsStyle>` `fontStyle` attribute encodes the setting of the **Bold**, **Italic**, and **Underline** checkboxes from the **Styler** dialog, using the sum of **Italic**=1, **Bold**=2, and **Underline**=4 (so something with all three checkboxes set would have `fontStyle="7"`).  The `nesting` attribute similarly encodes the various nesting checkboxes from the **Styler** dialog with a sum of the values below, and indicate which styles will nest properly inside the active style:
 
 | Checkbox    | Value |   | Checkbox  | Value  |   | Checkbox     | Value    |