Merge pull request #17 from pryrt/autocomp-fixes

auto-completion fixes

Author: pryrt

content/auto-completion/index.md

@@ -67,7 +67,7 @@ The syntax of AutoComplete files is simple, but does have a few rules, most impo
 
 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 recognise keywords is made of letters a-z, A-Z, 0-9 digits and the underscore.  Using [Settings -> Preferences -> Delimiter](../preferences/#delimiter), you may add more characters by specifying the additionalWordChars parameter in the environment. The value will be a string with all the extra parameters without any separators.
+The basic character set used to recognize keywords is made of letters a-z, A-Z, 0-9 digits and the underscore.  Punctuation may work for auto-completion; however, if you want to use the parameter hints, you should not use punctuation in the keyword name.
 
 Syntax:
 
@@ -87,18 +87,10 @@ A small example of how the XML file is built is given above. NotepadPlus, AutoCo
 
 For keywords that are not functions, the Keyword tag is autoclosing and only has the "name" attribute. To indicate a keyword can be displayed in a calltip, add the attribute 'func' with the value "yes". In this case, the Keyword tag is a node and contains other tags.
 
-Then, for each overload of the function, an Overload element should be added ,which specifies the behavior and the parameters of the function. A function must have at least one Overload or it will not be displayed as a calltip. The 'retVal' attribute must be present and specifies the type of the return value, but the 'descr' attribute is optional and describes the functions behavior, like a comment. You can add newlines in the description if you wish to do so. For each parameter the function takes, a 'Param' element can be added. The 'name' attribute must be present and specifies the type of the parameters and/or any name of the parameter.
+Then, for each overload of the function, an Overload element should be added, which specifies the behavior and the parameters of the function. A function must have at least one Overload or it will not be displayed as a calltip.  Multiple Overload elements allow there to be different sets of parameters for a given function.  The 'retVal' attribute must be present and specifies the type of the return value, but the 'descr' attribute is optional and describes the functions behavior, like a comment. You can add newlines in the description if you wish to do so. For each parameter the function takes, a 'Param' element can be added. The 'name' attribute must be present and specifies the type of the parameters and/or any name of the parameter.
 
 In the 'AutoComplete' element you can add the 'language' attribute but it is not used by Notepad++, you can add it for completeness if you wish and can take any string you want.
 
-### Sorting
-
-Depending on the value of the 'ignoreCase' attribute in the 'Environment' element, the XML file has to be sorted case sensitive or case insensitive (if the attribute is absent it will default to case sensitive).
-
-The simples approach, when building an autocompletion file, may be to first define a plain text, one word a line file of words to be recognized, then sort it, then turn lines int Keyword tags, then add all Overload information as needed. The following will focus on the sorting part. A tool will be made available which will read any given XML API file and sort it properly - not released as of v6.6.6.
-
-For case sensitive sorting you can use any generic ASCII/ANSI sorter that sorts on the byte value of the characters. Simply put this means underscore is between uppercase and lowercase letters. When you have to sort case insensitive, treat lowercase letters as uppercase, that is, subtract 32 from each one. This means the underscore comes both after uppercase and lowercase letters. The default strcmpi() function in the standard C library does not seem to work correctly, but the TextFX plugin does, which is installed by default with Notepad++.
-
 ### Auto-completion File Format
 
 <!-- in the old NppWiki++, this was a section of the "Editing Configuration Files" page, but I [pryrt] don't see an equivalent page in the new npp-usermanual, so I'm putting it here for now -->
@@ -147,6 +139,7 @@ Remember that the call tip shows up when you type the opening parenthesis after
 For both call tips and autocompletion to work, keywords must be words, ie identifiers most languages would readily accept. This means that only the 26 Latin alphabet letters in either lower or upper case (no diacritics), digits and the underscore are safe to use. Additional allowed characters will work if they are not whitespace. Autocompletion may cope with spaces or blanks, call tips won't. This is a Scintilla limitation.
 
 #### Sorting
+
 The `<KeyWord>` tag list must be sorted by "name" in ascending order. **Failure to do so will result in a non working file, without a warning.**
 
 Now which sorting, case sensitive or insensitive? It depends on the value of the ignoreCase `<Environment>` attribute. If set to "yes", use case insensitive sorting, which considers all letters to be in upper case. Otherwise, use case sensitive sorting.
@@ -162,3 +155,7 @@ The simplest way to build a new file might be this:
 7. Now manually add text and extra overloads. Re-indent as applicable;
 8. Save and test your file;
 9. Sloppy work, test again (recursive, beware of infinite loops).
+
+For case sensitive sorting, you can use Notepad++'s **Edit > Line Operations > Sort Lexicographically Ascending**, or any generic ASCII/ANSI sorter that sorts on the byte value of the characters. Simply put, this means the underscore character is between uppercase and lowercase letters.
+
+For case insensitive sorting, treat lowercase letters as uppercase, that is, subtract 32 from each lowercase byte value; this means the underscore must come both after uppercase and lowercase letters.  Unfortunately, Notepad++'s **Edit > Line Operations > Sort Lexicographically Ascending** does case-sensitive sorting, and will not work for this purpose.

content/preferences/index.md

@@ -234,11 +234,16 @@ Determines whether multiple instances of Notepad++ can be run simultaneously.
 
 ### Delimiter
 
-Sets the characters that are considered part of a "word" for quick selections using double-click and similar.  It is also used for [auto-completion](../auto-completion/#create-auto-completion-definition-files).
+Sets the characters that are considered part of a "word" for quick selections using double-click, [Smart Highlighting](#highlighting), or the "match whole word only" in a normal search expression.  It is also used for [auto-completion](../auto-completion/#create-auto-completion-definition-files).  This setting does _not_ affect a [regular expression](../searching/#regular-expressions)'s interpretation of a word character or word boundary.
 
 * **Word character list**
-    * `☐ Use default Word character list as it is`: for Smart Highlighting (see above) or the Find dialog, will use the normal alphanumeric rules for determining what constitutes a word for "Match Whole Word Only"
-    * `☐ Add yuor character as part of word`: sometimes, the default "word character list" isn't sufficient for you; if you want other characters to be considered in "whole word only", add them here
+    * `☐ Use default Word character list as it is`: for Smart Highlighting (see above) or the Normal search mode in the Find and Replace dialogs, will use the normal alphanumeric rules for determining what constitutes a word for "Match Whole Word Only"
+        * The default "word characters" inlcude anything that Unicode considers alphanumeric, plus the underscore "_" character.
+            * Includes: standard Latin characters, accented characters, letterlike symbols, superscript digits, and enclosed (circled) digits
+            * Excludes: punctuation, mathematical operators, box drawing, arrows, emoji, or other such sybols.
+    * `☐ Add your character as part of word`: sometimes, the default "word character list" isn't sufficient for you; if you want other characters to be considered in "whole word only", add them here
+        * The value should be a string consisting of all the additional characters you would like to be included as a "word character".
+        * Spaces are liable to cause problems, and are not recommended to be present in this entry.  If you try to add a space, the dialog box will show a warning message.
 * **Delimiter selection settings**
     * If you define open and close characters, Ctrl + MouseDoubleClick will select everything inside that delimiter pair
     * `☐ Allow on several lines`: Ctrl + MouseDoubleClick will work across multiple lines, instead of just on a single line