cmdline-opts/interface.md: expand the documentation

Explain the syntax it supports.

Closes #13882

.github/scripts/spellcheck.words

@@ -119,10 +119,10 @@ CMake
 cmake
 CMake's
 cmake's
-CNAME
-CNAMEs
 CMakeLists
 CNA
+CNAME
+CNAMEs
 CodeQL
 codeql
 CODESET
@@ -209,9 +209,9 @@ EBCDIC
 ECC
 ECDHE
 ECH
-ecl
 ECHConfig
 ECHConfigList
+ecl
 ECONNREFUSED
 eCOS
 EFnet
@@ -358,6 +358,7 @@ ifdef
 ifdefed
 Ifdefs
 ifdefs
+ifhost
 IIS
 ILE
 Illumos

docs/cmdline-opts/interface.md

@@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: interface
 Arg: <name>
-Help: Use network INTERFACE (or address)
+Help: Use network interface
 Category: connection
 Added: 7.3
 Multi: single
@@ -11,15 +11,41 @@ See-also:
   - dns-interface
 Example:
   - --interface eth0 $URL
+  - --interface "host!10.0.0.1" $URL
+  - --interface "if!enp3s0" $URL
 ---
 
 # `--interface`
 
-Perform an operation using a specified interface. You can enter interface
-name, IP address or hostname. An example could look like:
+Perform the operation using a specified interface. You can enter interface
+name, IP address or hostname. If you prefer to be specific, you can use the
+following special syntax:
 
-    curl --interface eth0:1 https://www.example.com/
+## if!<name>
 
-On Linux it can be used to specify a **VRF**, but the binary needs to either
-have **CAP_NET_RAW** or to be run as root. More information about Linux
-**VRF**: https://www.kernel.org/doc/Documentation/networking/vrf.txt
+Interface name. If the provided name does not match an existing interface,
+curl returns with error 45.
+
+## host!<name>
+
+IP address or hostname.
+
+## ifhost!<interface>!<host>
+
+Interface name and IP address or hostname. This syntax requires libcurl 8.9.0
+or later.
+
+If the provided name does not match an existing interface, curl returns with
+error 45.
+
+##
+
+curl does not support using network interface names for this option on
+Windows.
+
+That name resolve operation if a hostname is provided does **not** use
+DNS-over-HTTPS even if --doh-url is set.
+
+On Linux this option can be used to specify a **VRF** (Virtual Routing and
+Forwarding) device, but the binary then needs to either have the
+**CAP_NET_RAW** capability set or to be run as root.

src/tool_listhelp.c

@@ -304,7 +304,7 @@ const struct helptxt helptext[] = {
    "Allow insecure server connections",
    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP},
   {"    --interface <name>",
-   "Use network INTERFACE (or address)",
+   "Use network interface",
    CURLHELP_CONNECTION},
   {"    --ipfs-gateway <URL>",
    "Gateway for IPFS",