From 17351b8f5910feb8250e4608f204fca503e19dfb Mon Sep 17 00:00:00 2001 From: PeterCJ Date: Wed, 12 Feb 2025 08:49:57 -0800 Subject: [PATCH 1/2] 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. --- content/docs/auto-completion.md | 2 ++ content/docs/config-files.md | 6 ++++++ content/docs/function-list.md | 2 ++ content/docs/themes.md | 2 ++ content/docs/user-defined-language-system.md | 2 ++ 5 files changed, 14 insertions(+) diff --git a/content/docs/auto-completion.md b/content/docs/auto-completion.md index f23d8a36..c4632b07 100644 --- a/content/docs/auto-completion.md +++ b/content/docs/auto-completion.md @@ -132,6 +132,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 `` tag is a `` tag. It has an optional, unused `language` attribute, which you can use for any descriptive purpose. The contents of a `` start with an autoclosing `` tag, with the following attributes: diff --git a/content/docs/config-files.md b/content/docs/config-files.md index 5a4c6f87..92840275 100644 --- a/content/docs/config-files.md +++ b/content/docs/config-files.md @@ -64,6 +64,12 @@ 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. +## 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 ``. 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. + +# Specifics on Configuration Files + ## The context menu: `contextMenu.xml` diff --git a/content/docs/function-list.md b/content/docs/function-list.md index 5564dbd7..8667f25f 100644 --- a/content/docs/function-list.md +++ b/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 `` node accepts the three attributes: - `id`: Unique ID for this parser. diff --git a/content/docs/themes.md b/content/docs/themes.md index fd2f5c5e..6c83b2b9 100644 --- a/content/docs/themes.md +++ b/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. diff --git a/content/docs/user-defined-language-system.md b/content/docs/user-defined-language-system.md index efc4c3c6..06f6f8f4 100644 --- a/content/docs/user-defined-language-system.md +++ b/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 `` section defines the keywords or symbols for each highlighting category. The `` section defines the text styling (color, font, weight, and decoration) for each highlighting category. The `` `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 | From 1978d8065daba4009fb57fd237f603e042df5d7a Mon Sep 17 00:00:00 2001 From: PeterCJ Date: Wed, 12 Feb 2025 08:57:55 -0800 Subject: [PATCH 2/2] XmlEncoding: rearrange slightly for better flow --- content/docs/auto-completion.md | 2 ++ content/docs/config-files.md | 8 +++++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/content/docs/auto-completion.md b/content/docs/auto-completion.md index c4632b07..f7cf22ad 100644 --- a/content/docs/auto-completion.md +++ b/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. diff --git a/content/docs/config-files.md b/content/docs/config-files.md index 92840275..72eecae6 100644 --- a/content/docs/config-files.md +++ b/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 ``. 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,9 +68,7 @@ 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. -## 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 ``. 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. +
# Specifics on Configuration Files