From: Daniel Stenberg <daniel@haxx.se>
Date: Mon, 1 Jul 2024 08:11:39 +0000 (+0200)
Subject: curl_easy_escape: elaborate a little on encoding a URL
X-Git-Tag: curl-8_9_0~146
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ecd654e12ef2d984d986c8acd69adf45cc623e15;p=thirdparty%2Fcurl.git

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 272d607171..e153f3ca90 100644
--- 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 a99b4e30f6..5e507ad8b4 100644
--- 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
 ---