curl_easy_escape: elaborate a little on encoding a URL

Closes #14069

diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md
index 272d607171d0bff8bf539b1711ffebb70a183587..e153f3ca908f662c73b1e61c581f77dbb1e23aec 100644 (file)
--- a/docs/libcurl/curl_easy_escape.md
+++ b/docs/libcurl/curl_easy_escape.md
@@ -6,7 +6,8 @@ Section: 3
 Source: libcurl
 See-also:
   - curl_easy_unescape (3)
-  - curl_free (3)
+  - curl_url_set (3)
+  - curl_url_get (3)
 Protocol:
   - All
 ---
@@ -51,6 +52,17 @@ uses.
 The caller of curl_easy_escape(3) must make sure that the data passed in
 to the function is encoded correctly.
 
+# URLs
+
+URLs are by definition *URL encoded*. To create a proper URL from a set of
+components that may not be URL encoded already, you cannot just URL encode the
+entire URL string with curl_easy_escape(3), because it then also converts
+colons, slashes and other symbols that you probably want untouched.
+
+To create a proper URL from strings that are not already URL encoded, we
+recommend using libcurl's URL API: set the pieces with curl_url_set(3) and get
+the final correct URL with curl_url_get(3).
+
 # EXAMPLE
 
 ~~~c

diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md
index a99b4e30f6e2f4975f476a8191bcee6bb559ee88..5e507ad8b4423c9fd60362dca7beb94f8d9eee5a 100644 (file)
--- a/docs/libcurl/curl_easy_unescape.md
+++ b/docs/libcurl/curl_easy_unescape.md
@@ -6,7 +6,7 @@ Section: 3
 Source: libcurl
 See-also:
   - curl_easy_escape (3)
-  - curl_free (3)
+  - curl_url_get (3)
 Protocol:
   - All
 ---