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
 ---