Reordered searching section so preferred SCI_SEARCHINTARGET API is shown first

to discourage use of other APIs.
Fixed some HTML bugs.

1 files changed, 94 insertions, 99 deletions

diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html
index 648615821..e21be5e6a 100644
--- a/doc/ScintillaDoc.html
+++ b/doc/ScintillaDoc.html
@@ -82,7 +82,7 @@
 
     <h1>Scintilla Documentation</h1>
 
-    <p>Last edited 2 October 2014 NH</p>
+    <p>Last edited 16 October 2014 NH</p>
 
     <p>There is <a class="jump" href="Design.html">an overview of the internal design of
     Scintilla</a>.<br />
@@ -606,7 +606,14 @@ struct Sci_TextRange {
 
     <h2 id="Searching">Searching</h2>
     <p>
-    There are methods to search for text and for regular expressions. The base regular expression support
+    There are methods to search for text and for regular expressions.
+    Most applications should use
+    <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET</a>
+    as the basis for their search implementations.
+    Other calls augment this or were implemented before <code>SCI_SEARCHINTARGET</code>.
+    </p>
+    <p>
+    The base regular expression support
     is limited and should only be used for simple cases and initial development.
     <span class="provisional">When using a C++11 compliant compiler and runtime, it may be possible to use the
     runtime's implementation of &lt;regex&gt; by compiling Scintilla with <code>CXX11_REGEX</code> defined.</span>
@@ -615,17 +622,81 @@ struct Sci_TextRange {
     or can be called from the container using direct access to the buffer contents through
     <a class="message" href="#SCI_GETCHARACTERPOINTER">SCI_GETCHARACTERPOINTER</a>.
     </p>
-    <code><a class="message" href="#SCI_FINDTEXT">SCI_FINDTEXT(int flags, Sci_TextToFind
-    *ttf)</a><br />
-     <a class="message" href="#SCI_SEARCHANCHOR">SCI_SEARCHANCHOR</a><br />
-     <a class="message" href="#SCI_SEARCHNEXT">SCI_SEARCHNEXT(int searchFlags, const char
+
+    <h3 id="SearchAndReplaceUsingTheTarget">Search and replace using the target</h3>
+
+    <p>Searching can be performed within the target range with <code>SCI_SEARCHINTARGET</code>,
+    which uses a counted string to allow searching for null characters. It returns the
+    position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by
+    <code>SCI_SEARCHINTARGET</code> such as <code>SCFIND_MATCHCASE</code>,
+    <code>SCFIND_WHOLEWORD</code>, <code>SCFIND_WORDSTART</code>, and <code>SCFIND_REGEXP</code>
+    can be set with <code>SCI_SETSEARCHFLAGS</code>.</p>
+    <code><a class="message" href="#SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</a><br />
+     <a class="message" href="#SCI_GETTARGETSTART">SCI_GETTARGETSTART</a><br />
+     <a class="message" href="#SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</a><br />
+     <a class="message" href="#SCI_GETTARGETEND">SCI_GETTARGETEND</a><br />
+     <a class="message" href="#SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</a><br />
+     <a class="message" href="#SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</a><br />
+     <a class="message" href="#SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</a><br />
+     <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char
     *text)</a><br />
-     <a class="message" href="#SCI_SEARCHPREV">SCI_SEARCHPREV(int searchFlags, const char
+     <a class="message" href="#SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char
     *text)</a><br />
-     <a class="jump" href="#SearchAndReplaceUsingTheTarget">Search and replace using the
-    target</a><br />
+     <a class="message" href="#SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char
+    *text)</a><br />
+     <a class="message" href="#SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</a><br />
     </code>
 
+    <p><b id="SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</b><br />
+     <b id="SCI_GETTARGETSTART">SCI_GETTARGETSTART</b><br />
+     <b id="SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</b><br />
+     <b id="SCI_GETTARGETEND">SCI_GETTARGETEND</b><br />
+     These functions set and return the start and end of the target. When searching
+     you can set start greater than end to find the last matching text in the
+    target rather than the first matching text. The target is also set by a successful
+    <code>SCI_SEARCHINTARGET</code>.</p>
+
+     <p><b id="SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</b><br />
+     Set the target start and end to the start and end positions of the selection.</p>
+
+    <p><b id="SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</b><br />
+     <b id="SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</b><br />
+     These get and set the <a class="jump" href="#searchFlags"><code>searchFlags</code></a> used by
+    <code>SCI_SEARCHINTARGET</code>. There are several option flags including a simple regular
+    expression search.</p>
+
+    <p><b id="SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char *text)</b><br />
+     This searches for the first occurrence of a text string in the target defined by
+    <code>SCI_SETTARGETSTART</code> and <code>SCI_SETTARGETEND</code>. The text string is not zero
+    terminated; the size is set by <code>length</code>. The search is modified by the search flags
+    set by <code>SCI_SETSEARCHFLAGS</code>. If the search succeeds, the target is set to the found
+    text and the return value is the position of the start of the matching text. If the search
+    fails, the result is -1.</p>
+
+    <p><b id="SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char *text)</b><br />
+     If <code>length</code> is -1, <code>text</code> is a zero terminated string, otherwise
+    <code>length</code> sets the number of character to replace the target with.
+           After replacement, the target range refers to the replacement text.
+           The return value
+    is the length of the replacement string.<br />
+    Note that the recommended way to delete text in the document is to set the target to the text to be removed,
+    and to perform a replace target with an empty string.</p>
+
+    <p><b id="SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char *text)</b><br />
+     This replaces the target using regular expressions. If <code>length</code> is -1,
+    <code>text</code> is a zero terminated string, otherwise <code>length</code> is the number of
+    characters to use. The replacement string is formed from the text string with any sequences of
+    <code>\1</code> through <code>\9</code> replaced by tagged matches from the most recent regular
+    expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
+           After replacement, the target range refers to the replacement text.
+           The return value is the length of the replacement string.</p>
+
+    <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</b><br />
+     Discover what text was matched by tagged expressions in a regular expression search.
+     This is useful if the application wants to interpret the replacement string itself.</p>
+
+    <p>See also: <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p>
+
     <p><b id="searchFlags"><code>searchFlags</code></b><br />
      Several of the search routines use flag options, which include a simple regular expression
     search. Combine the flag options by adding them:</p>
@@ -675,10 +746,6 @@ struct Sci_TextRange {
       </tbody>
     </table>
 
-    <p>You can
-    search backwards to find the previous occurrence of a search string by setting the end of the
-    search range before the start.</p>
-
     <p>In a regular expression, special characters interpreted are:</p>
 
     <table border="0" summary="Regular expression synopsis">
@@ -774,12 +841,25 @@ struct Sci_TextRange {
 
     <p>Regular expressions will only match ranges within a single line, never matching over multiple lines.</p>
 
+    <code><a class="message" href="#SCI_FINDTEXT">SCI_FINDTEXT(int flags, Sci_TextToFind
+    *ttf)</a><br />
+     <a class="message" href="#SCI_SEARCHANCHOR">SCI_SEARCHANCHOR</a><br />
+     <a class="message" href="#SCI_SEARCHNEXT">SCI_SEARCHNEXT(int searchFlags, const char
+    *text)</a><br />
+     <a class="message" href="#SCI_SEARCHPREV">SCI_SEARCHPREV(int searchFlags, const char
+    *text)</a><br />
+    </code>
+
     <p><b id="SCI_FINDTEXT">SCI_FINDTEXT(int searchFlags, <a class="jump"
     href="#Sci_TextToFind">Sci_TextToFind</a> *ttf)</b><br />
      This message searches for text in the document. It does not use or move the current selection.
     The <a class="jump" href="#searchFlags"><code>searchFlags</code></a> argument controls the
     search type, which includes regular expression searches.</p>
 
+    <p>You can
+    search backwards to find the previous occurrence of a search string by setting the end of the
+    search range before the start.</p>
+
     <p>The <code>Sci_TextToFind</code> structure is defined in <code>Scintilla.h</code>; set
     <code>chrg.cpMin</code> and <code>chrg.cpMax</code> with the range of positions in the document
     to search. You can search backwards by
@@ -832,89 +912,6 @@ struct Sci_TextToFind {
     <p>See also: <a class="message" href="#SCI_SEARCHINTARGET"><code>SCI_SEARCHINTARGET</code></a>,
     <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p>
 
-    <h3 id="SearchAndReplaceUsingTheTarget">Search and replace using the target</h3>
-
-    <p>Using <a class="message" href="#SCI_REPLACESEL"><code>SCI_REPLACESEL</code></a>,
-    modifications cause scrolling and other visible changes, which may take some time and cause
-    unwanted display updates. If performing many changes, such as a replace all command, the target
-    can be used instead. First, set the target, ie. the range to be replaced. Then call
-    <code>SCI_REPLACETARGET</code> or <code>SCI_REPLACETARGETRE</code>.</p>
-
-    <p>Searching can be performed within the target range with <code>SCI_SEARCHINTARGET</code>,
-    which uses a counted string to allow searching for null characters. It returns the
-    position of the start of the matching text range or -1 for failure, in which case the target is not moved. The flags used by
-    <code>SCI_SEARCHINTARGET</code> such as <code>SCFIND_MATCHCASE</code>,
-    <code>SCFIND_WHOLEWORD</code>, <code>SCFIND_WORDSTART</code>, and <code>SCFIND_REGEXP</code>
-    can be set with <code>SCI_SETSEARCHFLAGS</code>. <code>SCI_SEARCHINTARGET</code> may be simpler
-    for some clients to use than <a class="message"
-    href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a>, as that requires using a pointer to a
-    structure.</p>
-    <code><a class="message" href="#SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</a><br />
-     <a class="message" href="#SCI_GETTARGETSTART">SCI_GETTARGETSTART</a><br />
-     <a class="message" href="#SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</a><br />
-     <a class="message" href="#SCI_GETTARGETEND">SCI_GETTARGETEND</a><br />
-     <a class="message" href="#SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</a><br />
-     <a class="message" href="#SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</a><br />
-     <a class="message" href="#SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</a><br />
-     <a class="message" href="#SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char
-    *text)</a><br />
-     <a class="message" href="#SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char
-    *text)</a><br />
-     <a class="message" href="#SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char
-    *text)</a><br />
-     <a class="message" href="#SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</a><br />
-    </code>
-
-    <p><b id="SCI_SETTARGETSTART">SCI_SETTARGETSTART(int pos)</b><br />
-     <b id="SCI_GETTARGETSTART">SCI_GETTARGETSTART</b><br />
-     <b id="SCI_SETTARGETEND">SCI_SETTARGETEND(int pos)</b><br />
-     <b id="SCI_GETTARGETEND">SCI_GETTARGETEND</b><br />
-     These functions set and return the start and end of the target. When searching in non-regular
-    expression mode, you can set start greater than end to find the last matching text in the
-    target rather than the first matching text. The target is also set by a successful
-    <code>SCI_SEARCHINTARGET</code>.</p>
-
-     <p><b id="SCI_TARGETFROMSELECTION">SCI_TARGETFROMSELECTION</b><br />
-     Set the target start and end to the start and end positions of the selection.</p>
-
-    <p><b id="SCI_SETSEARCHFLAGS">SCI_SETSEARCHFLAGS(int searchFlags)</b><br />
-     <b id="SCI_GETSEARCHFLAGS">SCI_GETSEARCHFLAGS</b><br />
-     These get and set the <a class="jump" href="#searchFlags"><code>searchFlags</code></a> used by
-    <code>SCI_SEARCHINTARGET</code>. There are several option flags including a simple regular
-    expression search.</p>
-
-    <p><b id="SCI_SEARCHINTARGET">SCI_SEARCHINTARGET(int length, const char *text)</b><br />
-     This searches for the first occurrence of a text string in the target defined by
-    <code>SCI_SETTARGETSTART</code> and <code>SCI_SETTARGETEND</code>. The text string is not zero
-    terminated; the size is set by <code>length</code>. The search is modified by the search flags
-    set by <code>SCI_SETSEARCHFLAGS</code>. If the search succeeds, the target is set to the found
-    text and the return value is the position of the start of the matching text. If the search
-    fails, the result is -1.</p>
-
-    <p><b id="SCI_REPLACETARGET">SCI_REPLACETARGET(int length, const char *text)</b><br />
-     If <code>length</code> is -1, <code>text</code> is a zero terminated string, otherwise
-    <code>length</code> sets the number of character to replace the target with.
-           After replacement, the target range refers to the replacement text.
-           The return value
-    is the length of the replacement string.<br />
-    Note that the recommended way to delete text in the document is to set the target to the text to be removed,
-    and to perform a replace target with an empty string.</p>
-
-    <p><b id="SCI_REPLACETARGETRE">SCI_REPLACETARGETRE(int length, const char *text)</b><br />
-     This replaces the target using regular expressions. If <code>length</code> is -1,
-    <code>text</code> is a zero terminated string, otherwise <code>length</code> is the number of
-    characters to use. The replacement string is formed from the text string with any sequences of
-    <code>\1</code> through <code>\9</code> replaced by tagged matches from the most recent regular
-    expression search. <code>\0</code> is replaced with all the matched text from the most recent search.
-           After replacement, the target range refers to the replacement text.
-           The return value is the length of the replacement string.</p>
-
-    <p><b id="SCI_GETTAG">SCI_GETTAG(int tagNumber, char *tagValue)</b><br />
-     Discover what text was matched by tagged expressions in a regular expression search.
-     This is useful if the application wants to interpret the replacement string itself.</p>
-
-    <p>See also: <a class="message" href="#SCI_FINDTEXT"><code>SCI_FINDTEXT</code></a></p>
-
     <h2 id="Overtype">Overtype</h2>
 
     <p><b id="SCI_SETOVERTYPE">SCI_SETOVERTYPE(bool overType)</b><br />
@@ -3181,6 +3178,7 @@ struct Sci_TextToFind {
     </p>
 
     <h2 id="OtherSettings">Other settings</h2>
+    <code>
      <a class="message" href="#SCI_SETBUFFEREDDRAW">SCI_SETBUFFEREDDRAW(bool isBuffered)</a><br />
      <a class="message" href="#SCI_GETBUFFEREDDRAW">SCI_GETBUFFEREDDRAW</a><br />
      <a class="message" href="#SCI_SETPHASESDRAW">SCI_SETPHASESDRAW(int phases)</a><br />
@@ -5539,7 +5537,6 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){
 
       </tbody>
     </table>
-     <p></p>
 
     <p><b id="SCI_EXPANDCHILDREN">SCI_EXPANDCHILDREN(int line, int level)</b><br />
     This is used to respond to a change to a line causing its fold level or whether it is a header to change,
@@ -7536,8 +7533,6 @@ EM_FORMATRANGE
      Any use of these symbols should be removed and replaced with <a href="#Indicators">standard indicators</a>.
     <code>SCI_GETSTYLEBITS</code> and <code>SCI_GETSTYLEBITSNEEDED</code> always return 8,
     indicating that 8 bits are used for styling and there are 256 styles.</p>
-     </p>
-
 
     <h2 id="EditMessagesNeverSupportedByScintilla">Edit messages never supported by Scintilla</h2>
 <pre>