URL-SYNTAX: add IMAP UID SEARCH example

- Explain the difference between IMAP search via URL (which returns
  message sequence numbers) and IMAP search via custom request (which
  can return UID numbers if prefixed with UID, eg "UID SEARCH ...").

Bug: https://github.com/curl/curl/issues/7626
Reported-by: orycho@users.noreply.github.com
Ref: https://github.com/curl/curl/issues/2789

Closes https://github.com/curl/curl/pull/7881

diff --git a/docs/URL-SYNTAX.md b/docs/URL-SYNTAX.md
index a97eb0d9ffad4d354420b3b4ba80a81268b47008..4921f81fcb40401ffba38d63c86f6eb7215f8805 100644 (file)
--- a/docs/URL-SYNTAX.md
+++ b/docs/URL-SYNTAX.md
@@ -5,7 +5,8 @@
 The official "URL syntax" is primarily defined in these two different
 specifications:
 
- - [RFC 3986](https://tools.ietf.org/html/rfc3986) (although URL is called "URI" in there)
+ - [RFC 3986](https://tools.ietf.org/html/rfc3986) (although URL is called
+   "URI" in there)
  - [The WHATWG URL Specification](https://url.spec.whatwg.org/)
 
 RFC 3986 is the earlier one, and curl has always tried to adhere to that one
@@ -41,8 +42,8 @@ security concerns:
 
 1. If you have an application that runs as or in a server application, getting
    an unfiltered URL can trick your application to access a local resource
-   instead of a remote resource. Protecting yourself against localhost accesses is very
-   hard when accepting user provided URLs.
+   instead of a remote resource. Protecting yourself against localhost accesses
+   is very hard when accepting user provided URLs.
 
 2. Such custom URLs can access other ports than you planned as port numbers
    are part of the regular URL format. The combination of a local host and a
@@ -285,8 +286,26 @@ subject line:
 
     imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows
 
-For more information about the individual components of an IMAP URL please see
-RFC 5092.
+Searching via the query part of the URL `?` is a search request for the results
+to be returned as message sequence numbers (MAILINDEX). It is possible to make
+a search request for results to be returned as unique ID numbers (UID) by using
+a custom curl request via `-X`. UID numbers are unique per session (and
+multiple sessions when UIDVALIDITY is the same). For example, if you are
+searching for `"foo bar"` in header+body (TEXT) and you want the matching
+MAILINDEX numbers returned then you could search via URL:
+
+    imap://user:password@mail.example.com/INBOX?TEXT%20%22foo%20bar%22
+
+.. but if you wanted matching UID numbers you'd have to use a custom request:
+
+    imap://user:password@mail.example.com/INBOX -X "UID SEARCH TEXT \"foo bar\""
+
+For more information about IMAP commands please see RFC 9051. For more
+information about the individual components of an IMAP URL please see RFC 5092.
+
+* Note old curl versions would FETCH by message sequence number when UID was
+specified in the URL. That was a bug fixed in 7.62.0, which added MAILINDEX to
+FETCH by mail sequence number.
 
 ## LDAP