docs/cmdline: change to .md for cmdline docs

 - switch all invidual files documenting command line options into .md,
   as the documentation is now markdown-looking.

 - made the parser treat 4-space indents as quotes

 - switch to building the curl.1 manpage using the "mainpage.idx" file,
   which lists the files to include to generate it, instead of using the
   previous page-footer/headers. Also, those files are now also .md
   ones, using the same format. I gave them underscore prefixes to make
   them sort separately:
   _NAME.md, _SYNOPSIS.md, _DESCRIPTION.md, _URL.md, _GLOBBING.md,
   _VARIABLES.md, _OUTPUT.md, _PROTOCOLS.md, _PROGRESS.md, _VERSION.md,
   _OPTIONS.md, _FILES.md, _ENVIRONMENT.md, _PROXYPREFIX.md,
   _EXITCODES.md, _BUGS.md, _AUTHORS.md, _WWW.md, _SEEALSO.md

 - updated test cases accordingly

Closes #12751

.github/scripts/cleancmd.pl

@@ -0,0 +1,52 @@
+#!/usr/bin/perl
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# SPDX-License-Identifier: curl
+#
+# Input: a cmdline docs markdown, it gets modfied *in place*
+#
+# The main purpose is to strip off the leading meta-data part, but also to
+# clean up whatever else the spell checker might have a problem with that we
+# still deem is fine.
+
+my $header = 1;
+while(1) {
+    # set this if the markdown has no meta-data header to skip
+    if($ARGV[0] eq "--no-header") {
+        shift @ARGV;
+        $header = 0;
+    }
+    else {
+        last;
+    }
+}
+
+my $f = $ARGV[0];
+
+open(F, "<$f") or die;
+
+my $ignore = $header;
+my $sepcount = 0;
+my @out;
+while(<F>) {
+    if(/^---/ && $header) {
+        if(++$sepcount == 2) {
+            $ignore = 0;
+        }
+        next;
+    }
+    next if($ignore);
+
+    # strip out all long command line options
+    $_ =~ s/--[a-z0-9-]+//g;
+
+    # strip out https URLs, we don't want them spellchecked
+    $_ =~ s!https://[a-z0-9\#_/.-]+!!gi;
+
+    push @out, $_;
+}
+close(F);
+
+open(O, ">$f") or die;
+print O @out;
+close(O);

.github/scripts/spellcheck.words

@@ -50,6 +50,7 @@ backend
 backends
 backoff
 backticks
+balancers
 Baratov
 basename
 bashrc
@@ -445,6 +446,7 @@ Makefile
 makefiles
 malloc
 mallocs
+manpage
 maprintf
 Marek
 Mavrogiannopoulos

.github/workflows/linkcheck.yml

@@ -31,6 +31,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        name: checkout
+
+      - name: trim the cmdline docs markdown files
+        run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md | xargs -n1 ./.github/scripts/cleancmd.pl
+
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
           use-quiet-mode: 'yes'

.github/workflows/spellcheck.yml

@@ -57,6 +57,12 @@ jobs:
           perl -pi -e 's/\-\-[\a-z0-9-]*//ig' docs/curl.md
           perl -pi -e 's!https://[a-z0-9%/.-]*!!ig' docs/curl.md
 
+      - name: trim the cmdline docs markdown files
+        run: find docs/cmdline-opts -name "*.md" ! -name "_*" ! -name MANPAGE.md | xargs -n1 ./.github/scripts/cleancmd.pl
+
+      - name: trim the cmdline docs markdown _*.md files
+        run: find docs/cmdline-opts -name "_*.md" | xargs -n1 ./.github/scripts/cleancmd.pl --no-header
+
       - name: setup the custom wordlist
         run: grep -v '^#' .github/scripts/spellcheck.words >  wordlist.txt
 

docs/cmdline-opts/MANPAGE.md

@@ -9,24 +9,38 @@
 This is the curl man page generator. It generates a single nroff man page
 output from the set of sources files in this directory.
 
-There is one source file for each supported command line option. The output
-gets `page-header` prepended and `page-footer` appended. The format is
-described below.
+The `mainpage.idx` file lists all files that are rendered in that order to
+produce the output. The magic `%options` keyword inserts all command line
+options documented.
+
+The `%options` documentation is created with one source file for each
+supported command line option.
+
+The documentation file format is described below. It is meant to look similar
+to markdown which is why it uses `.md` file extensions.
 
 ## Option files
 
 Each command line option is described in a file named `<long name>.d`, where
 option name is written without any prefixing dashes. Like the file name for
-the -v, --verbose option is named `verbose.d`.
+the `-v, --verbose` option is named `verbose.d`.
+
+Each file has a set of meta-data in the top of the file, followed by a body of
+text.
 
-Each file has a set of meta-data and a body of text.
+The documentation files that do not document options have no meta-data part.
+
+A line that starts with `<!--` is a comment. It should also end with `-->`.
 
 ### Meta-data
 
+    --- (start of meta-data)
     Added: (version number in which this was added)
     Arg: (the argument the option takes)
     c: (copyright line)
-    Example: (example command line, without "curl" and can use `$URL`)
+    Example:
+      - (an example command line, without "curl" and can use `$URL`)
+      - (another example)
     Experimental: yes (if so)
     Help: (short text for the --help output for this option)
     Long: (long form name, without dashes)
@@ -36,7 +50,9 @@ Each file has a set of meta-data and a body of text.
     Protocols: (space separated list for which protocols this option works)
     Requires: (space separated list of features this requires, no dashes)
     Scope: global (if the option is global)
-    See-also: (space separated list of related options, no dashes)
+    See-also:
+      - (a related option, no dashes)
+      - (another related option, no dashes)
     Short: (single letter, without dash)
     SPDX-License-Identifier: curl
     Tags: (space separated list)
@@ -54,7 +70,7 @@ Text written within `*asterisks*` is shown using italics. Text within two
 Text that is prefixed with a space is treated like an "example" and gets
 output in monospace.
 
-Within the body, describe a lite of items like this:
+Within the body, describe a list of items like this:
 
     ## item 1
     description
@@ -67,12 +83,20 @@ explicitly with an empty "header":
 
     ##
 
-## Header and footer
+### Headers
+
+The `#` header can be used by non-option files and it produces produces a
+`.SH` output.
+
+If the `#` header is used for a command line option file, that header is
+simply ignored in the generated output. It can still serve a purpose in the
+source file as it helps the user identify what option the file is for.
 
-`page-header` is the file that is output before the generated options output
-for the master man page.
+### Variables
 
-`page-footer` is appended after all the individual options.
+There are three different "variables" that can be used when creating the
+output. They need to be written within backticks in the source file (to escape
+getting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`.
 
 ## Generate
 

docs/cmdline-opts/Makefile.am

@@ -28,7 +28,7 @@ MANPAGE = $(top_builddir)/docs/curl.1
 
 include Makefile.inc
 
-EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(OTHERPAGES) CMakeLists.txt
+EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(SUPPORT) CMakeLists.txt mainpage.idx
 
 GEN = $(GN_$(V))
 GN_0 = @echo "  GENERATE" $@;
@@ -37,5 +37,5 @@ GN_ = $(GN_0)
 
 all: $(MANPAGE)
 
-$(MANPAGE): $(DPAGES) $(OTHERPAGES) Makefile.inc gen.pl
+$(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl
 	$(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp && mv $(builddir)/manpage.tmp $(MANPAGE))

docs/cmdline-opts/Makefile.inc

@@ -23,264 +23,283 @@
 ###########################################################################
 # Shared between Makefile.am and CMakeLists.txt
 
-DPAGES = \
-  abstract-unix-socket.d \
-  alt-svc.d \
-  anyauth.d \
-  append.d \
-  aws-sigv4.d \
-  basic.d \
-  ca-native.d \
-  cacert.d \
-  capath.d \
-  cert-status.d \
-  cert-type.d \
-  cert.d \
-  ciphers.d \
-  compressed-ssh.d \
-  compressed.d \
-  config.d \
-  connect-timeout.d \
-  connect-to.d \
-  continue-at.d \
-  cookie-jar.d \
-  cookie.d \
-  create-dirs.d \
-  create-file-mode.d \
-  crlf.d \
-  crlfile.d \
-  curves.d \
-  data-ascii.d \
-  data-binary.d \
-  data-raw.d \
-  data-urlencode.d \
-  data.d \
-  delegation.d \
-  digest.d \
-  disable-eprt.d \
-  disable-epsv.d \
-  disable.d \
-  disallow-username-in-url.d \
-  dns-interface.d \
-  dns-ipv4-addr.d \
-  dns-ipv6-addr.d \
-  dns-servers.d \
-  doh-cert-status.d \
-  doh-insecure.d \
-  doh-url.d \
-  dump-header.d \
-  egd-file.d \
-  engine.d \
-  etag-compare.d \
-  etag-save.d \
-  expect100-timeout.d \
-  fail-early.d \
-  fail-with-body.d \
-  fail.d \
-  false-start.d \
-  form-escape.d \
-  form-string.d \
-  form.d \
-  ftp-account.d \
-  ftp-alternative-to-user.d \
-  ftp-create-dirs.d \
-  ftp-method.d \
-  ftp-pasv.d \
-  ftp-port.d \
-  ftp-pret.d \
-  ftp-skip-pasv-ip.d \
-  ftp-ssl-ccc-mode.d \
-  ftp-ssl-ccc.d \
-  ftp-ssl-control.d \
-  get.d \
-  globoff.d \
-  happy-eyeballs-timeout-ms.d \
-  haproxy-protocol.d \
-  haproxy-clientip.d \
-  head.d \
-  header.d \
-  help.d \
-  hostpubmd5.d \
-  hostpubsha256.d \
-  hsts.d \
-  http0.9.d \
-  http1.0.d \
-  http1.1.d \
-  http2-prior-knowledge.d \
-  http2.d \
-  http3.d \
-  http3-only.d \
-  ignore-content-length.d \
-  include.d \
-  insecure.d \
-  interface.d \
-  ipfs-gateway.d \
-  ipv4.d \
-  ipv6.d \
-  json.d \
-  junk-session-cookies.d \
-  keepalive-time.d \
-  key-type.d \
-  key.d \
-  krb.d \
-  libcurl.d \
-  limit-rate.d \
-  list-only.d \
-  local-port.d \
-  location-trusted.d \
-  location.d \
-  login-options.d \
-  mail-auth.d \
-  mail-from.d \
-  mail-rcpt-allowfails.d \
-  mail-rcpt.d \
-  manual.d \
-  max-filesize.d \
-  max-redirs.d \
-  max-time.d \
-  metalink.d \
-  negotiate.d \
-  netrc-file.d \
-  netrc-optional.d \
-  netrc.d \
-  next.d \
-  no-alpn.d \
-  no-buffer.d \
-  no-clobber.d \
-  no-keepalive.d \
-  no-npn.d \
-  no-progress-meter.d \
-  no-sessionid.d \
-  noproxy.d \
-  ntlm-wb.d \
-  ntlm.d \
-  oauth2-bearer.d \
-  output-dir.d \
-  output.d \
-  parallel-immediate.d \
-  parallel-max.d \
-  parallel.d \
-  pass.d \
-  path-as-is.d \
-  pinnedpubkey.d \
-  post301.d \
-  post302.d \
-  post303.d \
-  preproxy.d \
-  progress-bar.d \
-  proto-default.d \
-  proto-redir.d \
-  proto.d \
-  proxy-anyauth.d \
-  proxy-basic.d \
-  proxy-ca-native.d \
-  proxy-cacert.d \
-  proxy-capath.d \
-  proxy-cert-type.d \
-  proxy-cert.d \
-  proxy-ciphers.d \
-  proxy-crlfile.d \
-  proxy-digest.d \
-  proxy-header.d \
-  proxy-http2.d \
-  proxy-insecure.d \
-  proxy-key-type.d \
-  proxy-key.d \
-  proxy-negotiate.d \
-  proxy-ntlm.d \
-  proxy-pass.d \
-  proxy-pinnedpubkey.d \
-  proxy-service-name.d \
-  proxy-ssl-allow-beast.d \
-  proxy-ssl-auto-client-cert.d \
-  proxy-tls13-ciphers.d \
-  proxy-tlsauthtype.d \
-  proxy-tlspassword.d \
-  proxy-tlsuser.d \
-  proxy-tlsv1.d \
-  proxy-user.d \
-  proxy.d \
-  proxy1.0.d \
-  proxytunnel.d \
-  pubkey.d \
-  quote.d \
-  random-file.d \
-  range.d \
-  rate.d \
-  raw.d \
-  referer.d \
-  remote-header-name.d \
-  remote-name-all.d \
-  remote-name.d \
-  remote-time.d \
-  remove-on-error.d \
-  request-target.d \
-  request.d \
-  resolve.d \
-  retry-all-errors.d \
-  retry-connrefused.d \
-  retry-delay.d \
-  retry-max-time.d \
-  retry.d \
-  sasl-authzid.d \
-  sasl-ir.d \
-  service-name.d \
-  show-error.d \
-  silent.d \
-  socks4.d \
-  socks4a.d \
-  socks5-basic.d \
-  socks5-gssapi-nec.d \
-  socks5-gssapi-service.d \
-  socks5-gssapi.d \
-  socks5-hostname.d \
-  socks5.d \
-  speed-limit.d \
-  speed-time.d \
-  ssl-allow-beast.d \
-  ssl-auto-client-cert.d \
-  ssl-no-revoke.d \
-  ssl-reqd.d \
-  ssl-revoke-best-effort.d \
-  ssl.d \
-  sslv2.d \
-  sslv3.d \
-  stderr.d \
-  styled-output.d \
-  suppress-connect-headers.d \
-  tcp-fastopen.d \
-  tcp-nodelay.d \
-  telnet-option.d \
-  tftp-blksize.d \
-  tftp-no-options.d \
-  time-cond.d \
-  tls-max.d \
-  tls13-ciphers.d \
-  tlsauthtype.d \
-  tlspassword.d \
-  tlsuser.d \
-  tlsv1.0.d \
-  tlsv1.1.d \
-  tlsv1.2.d \
-  tlsv1.3.d \
-  tlsv1.d \
-  tr-encoding.d \
-  trace-ascii.d \
-  trace-config.d \
-  trace-ids.d \
-  trace-time.d \
-  trace.d \
-  unix-socket.d \
-  upload-file.d \
-  url.d \
-  url-query.d \
-  use-ascii.d \
-  user-agent.d \
-  user.d \
-  variable.d \
-  verbose.d \
-  version.d \
-  write-out.d \
-  xattr.d
+SUPPORT = \
+  _AUTHORS.md \
+  _BUGS.md \
+  _DESCRIPTION.md \
+  _ENVIRONMENT.md \
+  _EXITCODES.md \
+  _FILES.md \
+  _GLOBBING.md \
+  _NAME.md \
+  _OPTIONS.md \
+  _OUTPUT.md \
+  _PROGRESS.md \
+  _PROTOCOLS.md \
+  _PROXYPREFIX.md \
+  _SEEALSO.md \
+  _SYNOPSIS.md \
+  _URL.md \
+  _VARIABLES.md \
+  _VERSION.md \
+  _WWW.md
 
-OTHERPAGES = page-footer page-header
+DPAGES = \
+  abstract-unix-socket.md \
+  alt-svc.md \
+  anyauth.md \
+  append.md \
+  aws-sigv4.md \
+  basic.md \
+  ca-native.md \
+  cacert.md \
+  capath.md \
+  cert-status.md \
+  cert-type.md \
+  cert.md \
+  ciphers.md \
+  compressed-ssh.md \
+  compressed.md \
+  config.md \
+  connect-timeout.md \
+  connect-to.md \
+  continue-at.md \
+  cookie-jar.md \
+  cookie.md \
+  create-dirs.md \
+  create-file-mode.md \
+  crlf.md \
+  crlfile.md \
+  curves.md \
+  data-ascii.md \
+  data-binary.md \
+  data-raw.md \
+  data-urlencode.md \
+  data.md \
+  delegation.md \
+  digest.md \
+  disable-eprt.md \
+  disable-epsv.md \
+  disable.md \
+  disallow-username-in-url.md \
+  dns-interface.md \
+  dns-ipv4-addr.md \
+  dns-ipv6-addr.md \
+  dns-servers.md \
+  doh-cert-status.md \
+  doh-insecure.md \
+  doh-url.md \
+  dump-header.md \
+  egd-file.md \
+  engine.md \
+  etag-compare.md \
+  etag-save.md \
+  expect100-timeout.md \
+  fail-early.md \
+  fail-with-body.md \
+  fail.md \
+  false-start.md \
+  form-escape.md \
+  form-string.md \
+  form.md \
+  ftp-account.md \
+  ftp-alternative-to-user.md \
+  ftp-create-dirs.md \
+  ftp-method.md \
+  ftp-pasv.md \
+  ftp-port.md \
+  ftp-pret.md \
+  ftp-skip-pasv-ip.md \
+  ftp-ssl-ccc-mode.md \
+  ftp-ssl-ccc.md \
+  ftp-ssl-control.md \
+  get.md \
+  globoff.md \
+  happy-eyeballs-timeout-ms.md \
+  haproxy-protocol.md \
+  haproxy-clientip.md \
+  head.md \
+  header.md \
+  help.md \
+  hostpubmd5.md \
+  hostpubsha256.md \
+  hsts.md \
+  http0.9.md \
+  http1.0.md \
+  http1.1.md \
+  http2-prior-knowledge.md \
+  http2.md \
+  http3.md \
+  http3-only.md \
+  ignore-content-length.md \
+  include.md \
+  insecure.md \
+  interface.md \
+  ipfs-gateway.md \
+  ipv4.md \
+  ipv6.md \
+  json.md \
+  junk-session-cookies.md \
+  keepalive-time.md \
+  key-type.md \
+  key.md \
+  krb.md \
+  libcurl.md \
+  limit-rate.md \
+  list-only.md \
+  local-port.md \
+  location-trusted.md \
+  location.md \
+  login-options.md \
+  mail-auth.md \
+  mail-from.md \
+  mail-rcpt-allowfails.md \
+  mail-rcpt.md \
+  manual.md \
+  max-filesize.md \
+  max-redirs.md \
+  max-time.md \
+  metalink.md \
+  negotiate.md \
+  netrc-file.md \
+  netrc-optional.md \
+  netrc.md \
+  next.md \
+  no-alpn.md \
+  no-buffer.md \
+  no-clobber.md \
+  no-keepalive.md \
+  no-npn.md \
+  no-progress-meter.md \
+  no-sessionid.md \
+  noproxy.md \
+  ntlm-wb.md \
+  ntlm.md \
+  oauth2-bearer.md \
+  output-dir.md \
+  output.md \
+  parallel-immediate.md \
+  parallel-max.md \
+  parallel.md \
+  pass.md \
+  path-as-is.md \
+  pinnedpubkey.md \
+  post301.md \
+  post302.md \
+  post303.md \
+  preproxy.md \
+  progress-bar.md \
+  proto-default.md \
+  proto-redir.md \
+  proto.md \
+  proxy-anyauth.md \
+  proxy-basic.md \
+  proxy-ca-native.md \
+  proxy-cacert.md \
+  proxy-capath.md \
+  proxy-cert-type.md \
+  proxy-cert.md \
+  proxy-ciphers.md \
+  proxy-crlfile.md \
+  proxy-digest.md \
+  proxy-header.md \
+  proxy-http2.md \
+  proxy-insecure.md \
+  proxy-key-type.md \
+  proxy-key.md \
+  proxy-negotiate.md \
+  proxy-ntlm.md \
+  proxy-pass.md \
+  proxy-pinnedpubkey.md \
+  proxy-service-name.md \
+  proxy-ssl-allow-beast.md \
+  proxy-ssl-auto-client-cert.md \
+  proxy-tls13-ciphers.md \
+  proxy-tlsauthtype.md \
+  proxy-tlspassword.md \
+  proxy-tlsuser.md \
+  proxy-tlsv1.md \
+  proxy-user.md \
+  proxy.md \
+  proxy1.0.md \
+  proxytunnel.md \
+  pubkey.md \
+  quote.md \
+  random-file.md \
+  range.md \
+  rate.md \
+  raw.md \
+  referer.md \
+  remote-header-name.md \
+  remote-name-all.md \
+  remote-name.md \
+  remote-time.md \
+  remove-on-error.md \
+  request-target.md \
+  request.md \
+  resolve.md \
+  retry-all-errors.md \
+  retry-connrefused.md \
+  retry-delay.md \
+  retry-max-time.md \
+  retry.md \
+  sasl-authzid.md \
+  sasl-ir.md \
+  service-name.md \
+  show-error.md \
+  silent.md \
+  socks4.md \
+  socks4a.md \
+  socks5-basic.md \
+  socks5-gssapi-nec.md \
+  socks5-gssapi-service.md \
+  socks5-gssapi.md \
+  socks5-hostname.md \
+  socks5.md \
+  speed-limit.md \
+  speed-time.md \
+  ssl-allow-beast.md \
+  ssl-auto-client-cert.md \
+  ssl-no-revoke.md \
+  ssl-reqd.md \
+  ssl-revoke-best-effort.md \
+  ssl.md \
+  sslv2.md \
+  sslv3.md \
+  stderr.md \
+  styled-output.md \
+  suppress-connect-headers.md \
+  tcp-fastopen.md \
+  tcp-nodelay.md \
+  telnet-option.md \
+  tftp-blksize.md \
+  tftp-no-options.md \
+  time-cond.md \
+  tls-max.md \
+  tls13-ciphers.md \
+  tlsauthtype.md \
+  tlspassword.md \
+  tlsuser.md \
+  tlsv1.0.md \
+  tlsv1.1.md \
+  tlsv1.2.md \
+  tlsv1.3.md \
+  tlsv1.md \
+  tr-encoding.md \
+  trace-ascii.md \
+  trace-config.md \
+  trace-ids.md \
+  trace-time.md \
+  trace.md \
+  unix-socket.md \
+  upload-file.md \
+  url.md \
+  url-query.md \
+  use-ascii.md \
+  user-agent.md \
+  user.md \
+  variable.md \
+  verbose.md \
+  version.md \
+  write-out.md \
+  xattr.md

docs/cmdline-opts/_AUTHORS.md

@@ -0,0 +1,5 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# AUTHORS
+Daniel Stenberg is the main author, but the whole list of contributors is
+found in the separate THANKS file.

docs/cmdline-opts/_BUGS.md

@@ -0,0 +1,5 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# BUGS
+If you experience any problems with curl, submit an issue in the project's bug
+tracker on GitHub: https://github.com/curl/curl/issues

docs/cmdline-opts/_DESCRIPTION.md

@@ -0,0 +1,11 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# DESCRIPTION
+
+**curl** is a tool for transferring data from or to a server using URLs. It
+supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS,
+IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP,
+SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS.
+
+curl is powered by libcurl for all transfer-related features. See
+*libcurl(3)* for details.

docs/cmdline-opts/_ENVIRONMENT.md

@@ -0,0 +1,114 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# ENVIRONMENT
+The environment variables can be specified in lower case or upper case. The
+lower case version has precedence. `http_proxy` is an exception as it is only
+available in lower case.
+
+Using an environment variable to set the proxy has the same effect as using
+the --proxy option.
+
+## `http_proxy` [protocol://]<host>[:port]
+Sets the proxy server to use for HTTP.
+
+## `HTTPS_PROXY` [protocol://]<host>[:port]
+Sets the proxy server to use for HTTPS.
+
+## `[url-protocol]_PROXY` [protocol://]<host>[:port]
+Sets the proxy server to use for [url-protocol], where the protocol is a
+protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP,
+SMTP, LDAP, etc.
+
+## `ALL_PROXY` [protocol://]<host>[:port]
+Sets the proxy server to use if no protocol-specific proxy is set.
+
+## `NO_PROXY` <comma-separated list of hosts/domains>
+list of host names that should not go through any proxy. If set to an asterisk
+'*' only, it matches all hosts. Each name in this list is matched as either
+a domain name which contains the hostname, or the hostname itself.
+
+This environment variable disables use of the proxy even when specified with
+the --proxy option. That is
+
+    NO_PROXY=direct.example.com curl -x http://proxy.example.com
+    http://direct.example.com
+
+accesses the target URL directly, and
+
+    NO_PROXY=direct.example.com curl -x http://proxy.example.com
+    http://somewhere.example.com
+
+accesses the target URL through the proxy.
+
+The list of host names can also be include numerical IP addresses, and IPv6
+versions should then be given without enclosing brackets.
+
+IP addresses can be specified using CIDR notation: an appended slash and
+number specifies the number of "network bits" out of the address to use in the
+comparison (added in 7.86.0). For example "192.168.0.0/16" would match all
+addresses starting with "192.168".
+
+## `APPDATA` <dir>
+On Windows, this variable is used when trying to find the home directory. If
+the primary home variable are all unset.
+
+## `COLUMNS` <terminal width>
+If set, the specified number of characters is used as the terminal width when
+the alternative progress-bar is shown. If not set, curl tries to figure it out
+using other ways.
+
+## `CURL_CA_BUNDLE` <file>
+If set, it is used as the --cacert value. This environment variable is ignored
+if Schannel is used as the TLS backend.
+
+## `CURL_HOME` <dir>
+If set, is the first variable curl checks when trying to find its home
+directory. If not set, it continues to check *XDG_CONFIG_HOME*
+
+## `CURL_SSL_BACKEND` <TLS backend>
+If curl was built with support for "MultiSSL", meaning that it has built-in
+support for more than one TLS backend, this environment variable can be set to
+the case insensitive name of the particular backend to use when curl is
+invoked. Setting a name that is not a built-in alternative makes curl stay
+with the default.
+
+SSL backend names (case-insensitive): **bearssl**, **gnutls**, **mbedtls**,
+**openssl**, **rustls**, **schannel**, **secure-transport**, **wolfssl**
+
+## `HOME` <dir>
+If set, this is used to find the home directory when that is needed. Like when
+looking for the default .curlrc. *CURL_HOME* and *XDG_CONFIG_HOME*
+have preference.
+
+## `QLOGDIR` <directory name>
+If curl was built with HTTP/3 support, setting this environment variable to a
+local directory makes curl produce **qlogs** in that directory, using file
+names named after the destination connection id (in hex). Do note that these
+files can become rather large. Works with the ngtcp2 and quiche QUIC backends.
+
+## `SHELL`
+Used on VMS when trying to detect if using a **DCL** or a **unix** shell.
+
+## `SSL_CERT_DIR` <dir>
+If set, it is used as the --capath value. This environment variable is ignored
+if Schannel is used as the TLS backend.
+
+## `SSL_CERT_FILE` <path>
+If set, it is used as the --cacert value. This environment variable is ignored
+if Schannel is used as the TLS backend.
+
+## `SSLKEYLOGFILE` <file name>
+If you set this environment variable to a file name, curl stores TLS secrets
+from its connections in that file when invoked to enable you to analyze the
+TLS traffic in real time using network analyzing tools such as Wireshark. This
+works with the following TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS
+and wolfSSL.
+
+## `USERPROFILE` <dir>
+On Windows, this variable is used when trying to find the home directory. If
+the other, primary, variable are all unset. If set, curl uses the path
+**"$USERPROFILE\Application Data"**.
+
+## `XDG_CONFIG_HOME` <dir>
+If *CURL_HOME* is not set, this variable is checked when looking for a
+default .curlrc file.

docs/cmdline-opts/_EXITCODES.md

@@ -0,0 +1,201 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# EXIT CODES
+There are a bunch of different error codes and their corresponding error
+messages that may appear under error conditions. At the time of this writing,
+the exit codes are:
+## 0
+Success. The operation completed successfully according to the instructions.
+## 1
+Unsupported protocol. This build of curl has no support for this protocol.
+## 2
+Failed to initialize.
+## 3
+URL malformed. The syntax was not correct.
+## 4
+A feature or option that was needed to perform the desired request was not
+enabled or was explicitly disabled at build-time. To make curl able to do
+this, you probably need another build of libcurl.
+## 5
+Could not resolve proxy. The given proxy host could not be resolved.
+## 6
+Could not resolve host. The given remote host could not be resolved.
+## 7
+Failed to connect to host.
+## 8
+Weird server reply. The server sent data curl could not parse.
+## 9
+FTP access denied. The server denied login or denied access to the particular
+resource or directory you wanted to reach. Most often you tried to change to a
+directory that does not exist on the server.
+## 10
+FTP accept failed. While waiting for the server to connect back when an active
+FTP session is used, an error code was sent over the control connection or
+similar.
+## 11
+FTP weird PASS reply. Curl could not parse the reply sent to the PASS request.
+## 12
+During an active FTP session while waiting for the server to connect back to
+curl, the timeout expired.
+## 13
+FTP weird PASV reply, Curl could not parse the reply sent to the PASV request.
+## 14
+FTP weird 227 format. Curl could not parse the 227-line the server sent.
+## 15
+FTP cannot use host. Could not resolve the host IP we got in the 227-line.
+## 16
+HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is
+somewhat generic and can be one out of several problems, see the error message
+for details.
+## 17
+FTP could not set binary. Could not change transfer method to binary.
+## 18
+Partial file. Only a part of the file was transferred.
+## 19
+FTP could not download/access the given file, the RETR (or similar) command
+failed.
+## 21
+FTP quote error. A quote command returned error from the server.
+## 22
+HTTP page not retrieved. The requested URL was not found or returned another
+error with the HTTP error code being 400 or above. This return code only
+appears if --fail is used.
+## 23
+Write error. Curl could not write data to a local filesystem or similar.
+## 25
+Failed starting the upload. For FTP, the server typically denied the STOR
+command.
+## 26
+Read error. Various reading problems.
+## 27
+Out of memory. A memory allocation request failed.
+## 28
+Operation timeout. The specified time-out period was reached according to the
+conditions.
+## 30
+FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT
+command, try doing a transfer using PASV instead.
+## 31
+FTP could not use REST. The REST command failed. This command is used for
+resumed FTP transfers.
+## 33
+HTTP range error. The range "command" did not work.
+## 34
+HTTP post error. Internal post-request generation error.
+## 35
+SSL connect error. The SSL handshaking failed.
+## 36
+Bad download resume. Could not continue an earlier aborted download.
+## 37
+FILE could not read file. Failed to open the file. Permissions?
+## 38
+LDAP cannot bind. LDAP bind operation failed.
+## 39
+LDAP search failed.
+## 41
+Function not found. A required LDAP function was not found.
+## 42
+Aborted by callback. An application told curl to abort the operation.
+## 43
+Internal error. A function was called with a bad parameter.
+## 45
+Interface error. A specified outgoing interface could not be used.
+## 47
+Too many redirects. When following redirects, curl hit the maximum amount.
+## 48
+Unknown option specified to libcurl. This indicates that you passed a weird
+option to curl that was passed on to libcurl and rejected. Read up in the
+manual!
+## 49
+Malformed telnet option.
+## 52
+The server did not reply anything, which here is considered an error.
+## 53
+SSL crypto engine not found.
+## 54
+Cannot set SSL crypto engine as default.
+## 55
+Failed sending network data.
+## 56
+Failure in receiving network data.
+## 58
+Problem with the local certificate.
+## 59
+Could not use specified SSL cipher.
+## 60
+Peer certificate cannot be authenticated with known CA certificates.
+## 61
+Unrecognized transfer encoding.
+## 63
+Maximum file size exceeded.
+## 64
+Requested FTP SSL level failed.
+## 65
+Sending the data requires a rewind that failed.
+## 66
+Failed to initialize SSL Engine.
+## 67
+The user name, password, or similar was not accepted and curl failed to log in.
+## 68
+File not found on TFTP server.
+## 69
+Permission problem on TFTP server.
+## 70
+Out of disk space on TFTP server.
+## 71
+Illegal TFTP operation.
+## 72
+Unknown TFTP transfer ID.
+## 73
+File already exists (TFTP).
+## 74
+No such user (TFTP).
+## 77
+Problem reading the SSL CA cert (path? access rights?).
+## 78
+The resource referenced in the URL does not exist.
+## 79
+An unspecified error occurred during the SSH session.
+## 80
+Failed to shut down the SSL connection.
+## 82
+Could not load CRL file, missing or wrong format (added in 7.19.0).
+## 83
+Issuer check failed (added in 7.19.0).
+## 84
+The FTP PRET command failed.
+## 85
+Mismatch of RTSP CSeq numbers.
+## 86
+Mismatch of RTSP Session Identifiers.
+## 87
+Unable to parse FTP file list.
+## 88
+FTP chunk callback reported error.
+## 89
+No connection available, the session is queued.
+## 90
+SSL public key does not matched pinned public key.
+## 91
+Invalid SSL certificate status.
+## 92
+Stream error in HTTP/2 framing layer.
+## 93
+An API function was called from inside a callback.
+## 94
+An authentication function returned an error.
+## 95
+A problem was detected in the HTTP/3 layer. This is somewhat generic and can
+be one out of several problems, see the error message for details.
+## 96
+QUIC connection error. This error may be caused by an SSL library error. QUIC
+is the protocol used for HTTP/3 transfers.
+## 97
+Proxy handshake error.
+## 98
+A client-side certificate is required to complete the TLS handshake.
+## 99
+Poll or select returned fatal error.
+## XX
+More error codes might appear here in future releases. The existing ones are
+meant to never change.

docs/cmdline-opts/_FILES.md

@@ -0,0 +1,6 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# FILES
+*~/.curlrc*
+
+Default config file, see --config for details.

docs/cmdline-opts/_GLOBBING.md

@@ -0,0 +1,40 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# GLOBBING
+You can specify multiple URLs or parts of URLs by writing lists within braces
+or ranges within brackets. We call this "globbing".
+
+Provide a list with three different names like this:
+
+    "http://site.{one,two,three}.com"
+
+or you can get sequences of alphanumeric series by using [] as in:
+
+    "ftp://ftp.example.com/file[1-100].txt"
+
+And with leading zeroes:
+
+    "ftp://ftp.example.com/file[001-100].txt"
+
+Or with letters through the alphabet:
+
+    "ftp://ftp.example.com/file[a-z].txt"
+
+Nested sequences are not supported, but you can use several ones next to each
+other:
+
+    "http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
+
+You can specify a step counter for the ranges to get every Nth number or
+letter:
+
+    "http://example.com/file[1-100:10].txt"
+
+    "http://example.com/file[a-z:2].txt"
+
+When using [] or {} sequences when invoked from a command line prompt, you
+probably have to put the full URL within double quotes to avoid the shell from
+interfering with it. This also goes for other characters treated special, like
+for example '&', '?' and '*'.
+
+Switch off globbing with --globoff.

docs/cmdline-opts/_NAME.md

@@ -0,0 +1,4 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# NAME
+curl - transfer a URL

docs/cmdline-opts/_OPTIONS.md

@@ -0,0 +1,26 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# OPTIONS
+Options start with one or two dashes. Many of the options require an
+additional value next to them. If provided text does not start with a dash, it
+is presumed to be and treated as a URL.
+
+The short "single-dash" form of the options, -d for example, may be used with
+or without a space between it and its value, although a space is a recommended
+separator. The long "double-dash" form, --data for example, requires a space
+between it and its value.
+
+Short version options that do not need any additional values can be used
+immediately next to each other, like for example you can specify all the
+options *-O*, *-L* and *-v* at once as *-OLv*.
+
+In general, all boolean options are enabled with --**option** and yet again
+disabled with --**no-**option. That is, you use the same option name but
+prefix it with "no-". However, in this list we mostly only list and show the
+*--option* version of them.
+
+When --next is used, it resets the parser state and you start again with a
+clean option state, except for the options that are "global". Global options
+retain their values and meaning even after --next.
+
+The following options are global: `%GLOBALS`.

docs/cmdline-opts/_OUTPUT.md

@@ -0,0 +1,11 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# OUTPUT
+If not told otherwise, curl writes the received data to stdout. It can be
+instructed to instead save that data into a local file, using the --output or
+--remote-name options. If curl is given multiple URLs to transfer on the
+command line, it similarly needs multiple options for where to save them.
+
+curl does not parse or otherwise "understand" the content it gets or writes as
+output. It does no encoding or decoding, unless explicitly asked to with
+dedicated command line options.

docs/cmdline-opts/_PROGRESS.md

@@ -0,0 +1,25 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# "PROGRESS METER"
+
+curl normally displays a progress meter during operations, indicating the
+amount of transferred data, transfer speeds and estimated time left, etc. The
+progress meter displays the transfer rate in bytes per second. The suffixes
+(k, M, G, T, P) are 1024 based. For example 1k is 1024 bytes. 1M is 1048576
+bytes.
+
+curl displays this data to the terminal by default, so if you invoke curl to
+do an operation and it is about to write data to the terminal, it *disables*
+the progress meter as otherwise it would mess up the output mixing progress
+meter and response data.
+
+If you want a progress meter for HTTP POST or PUT requests, you need to
+redirect the response output to a file, using shell redirect (>), --output or
+similar.
+
+This does not apply to FTP upload as that operation does not spit out any
+response data to the terminal.
+
+If you prefer a progress "bar" instead of the regular meter, --progress-bar is
+your friend. You can also disable the progress meter completely with the
+--silent option.

docs/cmdline-opts/_PROTOCOLS.md

@@ -0,0 +1,51 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# PROTOCOLS
+curl supports numerous protocols, or put in URL terms: schemes. Your
+particular build may not support them all.
+## DICT
+Lets you lookup words using online dictionaries.
+## FILE
+Read or write local files. curl does not support accessing file:// URL
+remotely, but when running on Microsoft Windows using the native UNC approach
+works.
+## FTP(S)
+curl supports the File Transfer Protocol with a lot of tweaks and levers. With
+or without using TLS.
+## GOPHER(S)
+Retrieve files.
+## HTTP(S)
+curl supports HTTP with numerous options and variations. It can speak HTTP
+version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
+command line options.
+## IMAP(S)
+Using the mail reading protocol, curl can "download" emails for you. With or
+without using TLS.
+## LDAP(S)
+curl can do directory lookups for you, with or without TLS.
+## MQTT
+curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
+topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
+not supported (yet).
+## POP3(S)
+Downloading from a pop3 server means getting a mail. With or without using
+TLS.
+## RTMP(S)
+The **Realtime Messaging Protocol** is primarily used to serve streaming media
+and curl can download it.
+## RTSP
+curl supports RTSP 1.0 downloads.
+## SCP
+curl supports SSH version 2 scp transfers.
+## SFTP
+curl supports SFTP (draft 5) done over SSH version 2.
+## SMB(S)
+curl supports SMB version 1 for upload and download.
+## SMTP(S)
+Uploading contents to an SMTP server means sending an email. With or without
+TLS.
+## TELNET
+Telling curl to fetch a telnet URL starts an interactive session where it
+sends what it reads on stdin and outputs what the server sends it.
+## TFTP
+curl can do TFTP downloads and uploads.

docs/cmdline-opts/_PROXYPREFIX.md

@@ -0,0 +1,22 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# PROXY PROTOCOL PREFIXES
+The proxy string may be specified with a protocol:// prefix to specify
+alternative proxy protocols. (Added in 7.21.7)
+
+If no protocol is specified in the proxy string or if the string does not
+match a supported one, the proxy is treated as an HTTP proxy.
+
+The supported proxy protocol prefixes are as follows:
+## http://
+Makes it use it as an HTTP proxy. The default if no scheme prefix is used.
+## https://
+Makes it treated as an **HTTPS** proxy.
+## socks4://
+Makes it the equivalent of --socks4
+## socks4a://
+Makes it the equivalent of --socks4a
+## socks5://
+Makes it the equivalent of --socks5
+## socks5h://
+Makes it the equivalent of --socks5-hostname

docs/cmdline-opts/_SEEALSO.md

@@ -0,0 +1,5 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# SEE ALSO
+
+**ftp (1)**, **wget (1)**

docs/cmdline-opts/_SYNOPSIS.md

@@ -0,0 +1,5 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# SYNOPSIS
+
+**curl [options / URLs]**

docs/cmdline-opts/_URL.md

@@ -0,0 +1,28 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# URL
+The URL syntax is protocol-dependent. You find a detailed description in
+RFC 3986.
+
+If you provide a URL without a leading **protocol://** scheme, curl guesses
+what protocol you want. It then defaults to HTTP but assumes others based on
+often-used host name prefixes. For example, for host names starting with
+"ftp." curl assumes you want FTP.
+
+You can specify any amount of URLs on the command line. They are fetched in a
+sequential manner in the specified order unless you use --parallel. You can
+specify command line options and URLs mixed and in any order on the command
+line.
+
+curl attempts to reuse connections when doing multiple transfers, so that
+getting many files from the same server do not use multiple connects and setup
+handshakes. This improves speed. Connection reuse can only be done for URLs
+specified for a single command line invocation and cannot be performed between
+separate curl runs.
+
+Provide an IPv6 zone id in the URL with an escaped percentage sign. Like in
+
+    "http://[fe80::3%25eth0]/"
+
+Everything provided on the command line that is not a command line option or
+its argument, curl assumes is a URL and treats it as such.

docs/cmdline-opts/_VARIABLES.md

@@ -0,0 +1,44 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# VARIABLES
+curl supports command line variables (added in 8.3.0). Set variables with
+--variable name=content or --variable name@file (where "file" can be stdin if
+set to a single dash (-)).
+
+Variable contents can expanded in option parameters using "{{name}}" (without
+the quotes) if the option name is prefixed with "--expand-". This gets the
+contents of the variable "name" inserted, or a blank if the name does not
+exist as a variable. Insert "{{" verbatim in the string by prefixing it with a
+backslash, like "\{{".
+
+You an access and expand environment variables by first importing them. You
+can select to either require the environment variable to be set or you can
+provide a default value in case it is not already set. Plain --variable %name
+imports the variable called 'name' but exits with an error if that environment
+variable is not already set. To provide a default value if it is not set, use
+--variable %name=content or --variable %name@content.
+
+Example. Get the USER environment variable into the URL, fail if USER is not
+set:
+
+    --variable '%USER'
+    --expand-url = "https://example.com/api/{{USER}}/method"
+
+When expanding variables, curl supports a set of functions that can make the
+variable contents more convenient to use. It can trim leading and trailing
+white space with *trim*, it can output the contents as a JSON quoted string
+with *json*, URL encode the string with *url* or base64 encode it with
+*b64*. You apply function to a variable expansion, add them colon separated to
+the right side of the variable. Variable content holding null bytes that are
+not encoded when expanded cause error.
+
+Example: get the contents of a file called $HOME/.secret into a variable
+called "fix". Make sure that the content is trimmed and percent-encoded sent
+as POST data:
+
+    --variable %HOME
+    --expand-variable fix@{{HOME}}/.secret
+    --expand-data "{{fix:trim:url}}"
+    https://example.com/
+
+Command line variables and expansions were added in in 8.3.0.

docs/cmdline-opts/_VERSION.md

@@ -0,0 +1,15 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# VERSION
+
+This man page describes curl %VERSION. If you use a later version, chances are
+this man page does not fully document it. If you use an earlier version, this
+document tries to include version information about which specific version
+that introduced changes.
+
+You can always learn which the latest curl version is by running
+
+    curl https://curl.se/info
+
+The online version of this man page is always showing the latest incarnation:
+https://curl.se/docs/manpage.html

docs/cmdline-opts/_WWW.md

@@ -0,0 +1,4 @@
+<!-- Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -->
+<!-- SPDX-License-Identifier: curl -->
+# WWW
+https://curl.se

docs/cmdline-opts/abstract-unix-socket.d → docs/cmdline-opts/abstract-unix-socket.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: abstract-unix-socket
@@ -6,10 +7,15 @@ Help: Connect via abstract Unix domain socket
 Added: 7.53.0
 Protocols: HTTP
 Category: connection
-See-also: unix-socket
-Example: --abstract-unix-socket socketpath $URL
 Multi: single
+See-also:
+  - unix-socket
+Example:
+  - --abstract-unix-socket socketpath $URL
 ---
+
+# `--abstract-unix-socket`
+
 Connect through an abstract Unix domain socket, instead of using the network.
 Note: netstat shows the path of an abstract socket prefixed with '@', however
 the <path> argument should not have this leading character.

docs/cmdline-opts/alt-svc.d → docs/cmdline-opts/alt-svc.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: alt-svc
@@ -6,10 +7,16 @@ Protocols: HTTPS
 Help: Enable alt-svc with this cache file
 Added: 7.64.1
 Category: http
-See-also: resolve connect-to
-Example: --alt-svc svc.txt $URL
 Multi: append
+See-also:
+  - resolve
+  - connect-to
+Example:
+  - --alt-svc svc.txt $URL
 ---
+
+# `--alt-svc`
+
 This option enables the alt-svc parser in curl. If the file name points to an
 existing alt-svc cache file, that gets used. After a completed transfer, the
 cache is saved to the file name again if it has been modified.

docs/cmdline-opts/anyauth.d → docs/cmdline-opts/anyauth.md

@@ -1,14 +1,22 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: anyauth
 Help: Pick any authentication method
 Protocols: HTTP
-See-also: proxy-anyauth basic digest
 Category: http proxy auth
-Example: --anyauth --user me:pwd $URL
 Added: 7.10.6
 Multi: mutex
+See-also:
+  - proxy-anyauth
+  - basic
+  - digest
+Example:
+  - --anyauth --user me:pwd $URL
 ---
+
+# `--anyauth`
+
 Tells curl to figure out authentication method by itself, and use the most
 secure one the remote site claims to support. This is done by first doing a
 request and checking the response-headers, thus possibly inducing an extra

docs/cmdline-opts/append.d → docs/cmdline-opts/append.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Short: a
@@ -5,11 +6,17 @@ Long: append
 Help: Append to target file when uploading
 Protocols: FTP SFTP
 Category: ftp sftp
-See-also: range continue-at
-Example: --upload-file local --append ftp://example.com/
 Added: 4.8
 Multi: boolean
+See-also:
+  - range
+  - continue-at
+Example:
+  - --upload-file local --append ftp://example.com/
 ---
+
+# `--append`
+
 When used in an upload, this option makes curl append to the target file
 instead of overwriting it. If the remote file does not exist, it is
 created. Note that this flag is ignored by some SFTP servers (including

docs/cmdline-opts/aws-sigv4.d → docs/cmdline-opts/aws-sigv4.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: aws-sigv4
@@ -6,10 +7,16 @@ Arg: <provider1[:provider2[:region[:service]]]>
 Help: Use AWS V4 signature authentication
 Category: auth http
 Added: 7.75.0
-See-also: basic user
-Example: --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" $URL
 Multi: single
+See-also:
+  - basic
+  - user
+Example:
+  - --aws-sigv4 "aws:amz:us-east-2:es" --user "key:secret" $URL
 ---
+
+# `--aws-sigv4`
+
 Use AWS V4 signature authentication in the transfer.
 
 The provider argument is a string that is used by the algorithm when creating

docs/cmdline-opts/basic.d → docs/cmdline-opts/basic.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: basic
 Help: Use HTTP Basic Authentication
-See-also: proxy-basic
 Protocols: HTTP
 Category: auth
-Example: -u name:password --basic $URL
 Added: 7.10.6
 Multi: mutex
+See-also:
+  - proxy-basic
+Example:
+  - -u name:password --basic $URL
 ---
+
+# `--basic`
+
 Tells curl to use HTTP Basic authentication with the remote host. This is the
 default and this option is usually pointless, unless you use it to override a
 previously set option that sets a different authentication method (such as

docs/cmdline-opts/ca-native.d → docs/cmdline-opts/ca-native.md

@@ -1,14 +1,22 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ca-native
 Help: Use CA certificates from the native OS
 Protocols: TLS
 Category: tls
-See-also: cacert capath insecure
-Example: --ca-native $URL
 Added: 8.2.0
 Multi: boolean
+See-also:
+  - cacert
+  - capath
+  - insecure
+Example:
+  - --ca-native $URL
 ---
+
+# `--ca-native`
+
 Tells curl to use the CA store from the native operating system to verify the
 peer. By default, curl otherwise uses a CA store provided in a single file or
 directory, but when using this option it interfaces the operating system's

docs/cmdline-opts/cacert.d → docs/cmdline-opts/cacert.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: cacert
@@ -5,11 +6,17 @@ Arg: <file>
 Help: CA certificate to verify peer against
 Protocols: TLS
 Category: tls
-See-also: capath insecure
-Example: --cacert CA-file.txt $URL
 Added: 7.5
 Multi: single
+See-also:
+  - capath
+  - insecure
+Example:
+  - --cacert CA-file.txt $URL
 ---
+
+# `--cacert`
+
 Tells curl to use the specified certificate file to verify the peer. The file
 may contain multiple CA certificates. The certificate(s) must be in PEM
 format. Normally curl is built to use a default file for this, so this option

docs/cmdline-opts/capath.d → docs/cmdline-opts/capath.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: capath
@@ -5,11 +6,17 @@ Arg: <dir>
 Help: CA directory to verify peer against
 Protocols: TLS
 Category: tls
-See-also: cacert insecure
-Example: --capath /local/directory $URL
 Added: 7.9.8
 Multi: single
+See-also:
+  - cacert
+  - insecure
+Example:
+  - --capath /local/directory $URL
 ---
+
+# `--capath`
+
 Tells curl to use the specified certificate directory to verify the
 peer. Multiple paths can be provided by separating them with ":" (e.g.
 "path1:path2:path3"). The certificates must be in PEM format, and if curl is

docs/cmdline-opts/cert-status.d → docs/cmdline-opts/cert-status.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: cert-status
@@ -5,10 +6,15 @@ Protocols: TLS
 Added: 7.41.0
 Help: Verify the status of the server cert via OCSP-staple
 Category: tls
-See-also: pinnedpubkey
-Example: --cert-status $URL
 Multi: boolean
+See-also:
+  - pinnedpubkey
+Example:
+  - --cert-status $URL
 ---
+
+# `--cert-status`
+
 Tells curl to verify the status of the server certificate by using the
 Certificate Status Request (aka. OCSP stapling) TLS extension.
 

docs/cmdline-opts/cert-type.d → docs/cmdline-opts/cert-type.md

@@ -1,15 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: cert-type
 Protocols: TLS
 Arg: <type>
 Help: Certificate type (DER/PEM/ENG/P12)
-See-also: cert key key-type
 Category: tls
-Example: --cert-type PEM --cert file $URL
 Added: 7.9.3
 Multi: single
+See-also:
+  - cert
+  - key
+  - key-type
+Example:
+  - --cert-type PEM --cert file $URL
 ---
+
+# `--cert-type`
+
 Tells curl what type the provided client certificate is using. PEM, DER, ENG
 and P12 are recognized types.
 

docs/cmdline-opts/cert.d → docs/cmdline-opts/cert.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Short: E
@@ -5,12 +6,19 @@ Long: cert
 Arg: <certificate[:password]>
 Help: Client certificate file and password
 Protocols: TLS
-See-also: cert-type key key-type
 Category: tls
-Example: --cert certfile --key keyfile $URL
 Added: 5.0
 Multi: single
+See-also:
+  - cert-type
+  - key
+  - key-type
+Example:
+  - --cert certfile --key keyfile $URL
 ---
+
+# `--cert`
+
 Tells curl to use the specified client certificate file when getting a file
 with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
 PKCS#12 format if using Secure Transport, or PEM format if using any other
@@ -19,10 +27,10 @@ the terminal. Note that this option assumes a certificate file that is the
 private key and the client certificate concatenated. See --cert and --key to
 specify them independently.
 
-In the <certificate> portion of the argument, you must escape the character ":"
-as "\\:" so that it is not recognized as the password delimiter. Similarly, you
-must escape the character "\\" as "\\\\" so that it is not recognized as an
-escape character.
+In the <certificate> portion of the argument, you must escape the character
+":" as "\:" so that it is not recognized as the password delimiter. Similarly,
+you must escape the double quote character as \" so that it is not recognized
+as an escape character.
 
 If curl is built against OpenSSL library, and the engine pkcs11 is available,
 then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
@@ -37,13 +45,12 @@ system or user keychain, or the path to a PKCS#12-encoded certificate and
 private key. If you want to use a file from the current directory, please
 precede it with "./" prefix, in order to avoid confusion with a nickname.
 
-(Schannel only) Client certificates must be specified by a path
-expression to a certificate store. (Loading *PFX* is not supported; you can
-import it to a store first). You can use
-"<store location>\\<store name>\\<thumbprint>" to refer to a certificate
-in the system certificates store, for example,
-*"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is
+(Schannel only) Client certificates must be specified by a path expression to
+a certificate store. (Loading *PFX* is not supported; you can import it to a
+store first). You can use "<store location>\<store name>\<thumbprint>" to
+refer to a certificate in the system certificates store, for example,
+*"CurrentUser\MY\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a"*. Thumbprint is
 usually a SHA-1 hex string which you can see in certificate details. Following
-store locations are supported: *CurrentUser*, *LocalMachine*, *CurrentService*,
-*Services*, *CurrentUserGroupPolicy*, *LocalMachineGroupPolicy* and
-*LocalMachineEnterprise*.
+store locations are supported: *CurrentUser*, *LocalMachine*,
+*CurrentService*, *Services*, *CurrentUserGroupPolicy*,
+*LocalMachineGroupPolicy* and *LocalMachineEnterprise*.

docs/cmdline-opts/ciphers.d → docs/cmdline-opts/ciphers.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ciphers
@@ -5,11 +6,18 @@ Arg: <list of ciphers>
 Help: SSL ciphers to use
 Protocols: TLS
 Category: tls
-See-also: tlsv1.3 tls13-ciphers proxy-ciphers
-Example: --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
 Added: 7.9
 Multi: single
+See-also:
+  - tlsv1.3
+  - tls13-ciphers
+  - proxy-ciphers
+Example:
+  - --ciphers ECDHE-ECDSA-AES256-CCM8 $URL
 ---
+
+# `--ciphers`
+
 Specifies which ciphers to use in the connection. The list of ciphers must
 specify valid ciphers. Read up on SSL cipher list details on this URL:
 

docs/cmdline-opts/compressed-ssh.d → docs/cmdline-opts/compressed-ssh.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: compressed-ssh
@@ -5,9 +6,14 @@ Help: Enable SSH compression
 Protocols: SCP SFTP
 Added: 7.56.0
 Category: scp ssh
-See-also: compressed
-Example: --compressed-ssh sftp://example.com/
 Multi: boolean
+See-also:
+  - compressed
+Example:
+  - --compressed-ssh sftp://example.com/
 ---
+
+# `--compressed-ssh`
+
 Enables built-in SSH compression.
 This is a request, not an order; the server may or may not do it.

docs/cmdline-opts/compressed.d → docs/cmdline-opts/compressed.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: compressed
 Help: Request compressed response
 Protocols: HTTP
 Category: http
-Example: --compressed $URL
-See-also: compressed-ssh
 Added: 7.10
 Multi: boolean
+See-also:
+  - compressed-ssh
+Example:
+  - --compressed $URL
 ---
+
+# `--compressed`
+
 Request a compressed response using one of the algorithms curl supports, and
 automatically decompress the content.
 

docs/cmdline-opts/config.d → docs/cmdline-opts/config.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: config
@@ -5,11 +6,16 @@ Arg: <file>
 Help: Read config from a file
 Short: K
 Category: curl
-Example: --config file.txt $URL
 Added: 4.10
-See-also: disable
 Multi: append
+See-also:
+  - disable
+Example:
+  - --config file.txt $URL
 ---
+
+# `--config`
+
 Specify a text file to read curl arguments from. The command line arguments
 found in the text file are used as if they were provided on the command
 line.
@@ -22,9 +28,9 @@ is specified with one or two dashes, there can be no colon or equals character
 between the option and its parameter.
 
 If the parameter contains whitespace or starts with a colon (:) or equals sign
-(=), it must be specified enclosed within double quotes (\&"). Within double
-quotes the following escape sequences are available: \\\\, \\", \\t, \\n, \\r
-and \\v. A backslash preceding any other letter is ignored.
+(=), it must be specified enclosed within double quotes ("). Within double
+quotes the following escape sequences are available: \\, \", \t, \n, \r and
+\v. A backslash preceding any other letter is ignored.
 
 If the first non-blank column of a config line is a '#' character, that line
 is treated as a comment.
@@ -38,19 +44,19 @@ Note that to be able to specify a URL in the config file, you need to specify
 it using the --url option, and not by simply writing the URL on its own
 line. So, it could look similar to this:
 
-url = "https://curl.se/docs/"
+    url = "https://curl.se/docs/"
 
- # --- Example file ---
- # this is a comment
- url = "example.com"
- output = "curlhere.html"
- user-agent = "superagent/1.0"
+    # --- Example file ---
+    # this is a comment
+    url = "example.com"
+    output = "curlhere.html"
+    user-agent = "superagent/1.0"
 
- # and fetch another URL too
- url = "example.com/docs/manpage.html"
- -O
- referer = "http://nowhereatall.example.com/"
- # --- End of example file ---
+    # and fetch another URL too
+    url = "example.com/docs/manpage.html"
+    -O
+    referer = "http://nowhereatall.example.com/"
+    # --- End of example file ---
 
 When curl is invoked, it (unless --disable is used) checks for a default
 config file and uses it if found, even when --config is used. The default
@@ -62,11 +68,11 @@ config file is checked for in the following places in this order:
 
 3) **"$HOME/.curlrc"**
 
-4) Windows: **"%USERPROFILE%\\.curlrc"**
+4) Windows: **"%USERPROFILE%\.curlrc"**
 
-5) Windows: **"%APPDATA%\\.curlrc"**
+5) Windows: **"%APPDATA%\.curlrc"**
 
-6) Windows: **"%USERPROFILE%\\Application Data\\.curlrc"**
+6) Windows: **"%USERPROFILE%\Application Data\.curlrc"**
 
 7) Non-Windows: use getpwuid to find the home directory
 

docs/cmdline-opts/connect-timeout.d → docs/cmdline-opts/connect-timeout.md

@@ -1,16 +1,22 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: connect-timeout
 Arg: <fractional seconds>
 Help: Maximum time allowed for connection
-See-also: max-time
 Category: connection
-Example: --connect-timeout 20 $URL
-Example: --connect-timeout 3.14 $URL
 Added: 7.7
 Multi: single
+See-also:
+  - max-time
+Example:
+  - --connect-timeout 20 $URL
+  - --connect-timeout 3.14 $URL
 ---
-Maximum time in seconds that you allow curl's connection to take.  This only
+
+# `--connect-timeout`
+
+Maximum time in seconds that you allow curl's connection to take. This only
 limits the connection phase, so if curl connects within the given period it
 continues - if not it exits.
 

docs/cmdline-opts/connect-to.d

@@ -1,23 +0,0 @@
-c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
-SPDX-License-Identifier: curl
-Long: connect-to
-Arg: <HOST1:PORT1:HOST2:PORT2>
-Help: Connect to host
-Added: 7.49.0
-See-also: resolve header
-Category: connection
-Example: --connect-to example.com:443:example.net:8443 $URL
-Multi: append
----
-For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
-This option is suitable to direct requests at a specific server, e.g. at a
-specific cluster node in a cluster of servers. This option is only used to
-establish the network connection. It does NOT affect the hostname/port that is
-used for TLS/SSL (e.g. SNI, certificate verification) or for the application
-protocols. "HOST1" and "PORT1" may be the empty string, meaning "any
-host/port". "HOST2" and "PORT2" may also be the empty string, meaning "use the
-request's original host/port".
-
-A "host" specified to this option is compared as a string, so it needs to
-match the name used in request URL. It can be either numerical such as
-"127.0.0.1" or the full host name such as "example.org".

docs/cmdline-opts/connect-to.md

@@ -0,0 +1,30 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+SPDX-License-Identifier: curl
+Long: connect-to
+Arg: <HOST1:PORT1:HOST2:PORT2>
+Help: Connect to host
+Added: 7.49.0
+Category: connection
+Multi: append
+See-also:
+  - resolve
+  - header
+Example:
+  - --connect-to example.com:443:example.net:8443 $URL
+---
+
+# `--connect-to`
+
+For a request to the given `HOST1:PORT1` pair, connect to `HOST2:PORT2`
+instead. This option is suitable to direct requests at a specific server,
+e.g. at a specific cluster node in a cluster of servers. This option is only
+used to establish the network connection. It does NOT affect the hostname/port
+that is used for TLS/SSL (e.g. SNI, certificate verification) or for the
+application protocols. `HOST1` and `PORT1` may be the empty string, meaning
+"any host/port". `HOST2` and `PORT2` may also be the empty string, meaning
+"use the request's original host/port".
+
+A hostname specified to this option is compared as a string, so it needs to
+match the name used in request URL. It can be either numerical such as
+`127.0.0.1` or the full host name such as `example.org`.

docs/cmdline-opts/continue-at.d → docs/cmdline-opts/continue-at.md

@@ -1,16 +1,22 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Short: C
 Long: continue-at
 Arg: <offset>
 Help: Resumed transfer offset
-See-also: range
 Category: connection
-Example: -C - $URL
-Example: -C 400 $URL
 Added: 4.8
 Multi: single
+See-also:
+  - range
+Example:
+  - -C - $URL
+  - -C 400 $URL
 ---
+
+# `--continue-at`
+
 Continue/Resume a previous file transfer at the given offset. The given offset
 is the exact number of bytes that are skipped, counting from the beginning
 of the source file before it is transferred to the destination. If used with

docs/cmdline-opts/cookie-jar.d → docs/cmdline-opts/cookie-jar.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Short: c
@@ -6,12 +7,17 @@ Arg: <filename>
 Protocols: HTTP
 Help: Write cookies to <filename> after operation
 Category: http
-Example: -c store-here.txt $URL
-Example: -c store-here.txt -b read-these $URL
 Added: 7.9
-See-also: cookie
 Multi: single
+See-also:
+  - cookie
+Example:
+  - -c store-here.txt $URL
+  - -c store-here.txt -b read-these $URL
 ---
+
+# `--cookie-jar`
+
 Specify to which file you want curl to write all cookies after a completed
 operation. Curl writes all cookies from its in-memory cookie storage to the
 given file at the end of operations. If no cookies are known, no data is

docs/cmdline-opts/cookie.d → docs/cmdline-opts/cookie.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Short: b
@@ -6,13 +7,19 @@ Arg: <data|filename>
 Protocols: HTTP
 Help: Send cookies from string/file
 Category: http
-Example: -b "" $URL
-Example: -b cookiefile $URL
-Example: -b cookiefile -c cookiefile $URL
-See-also: cookie-jar junk-session-cookies
 Added: 4.9
 Multi: append
+See-also:
+  - cookie-jar
+  - junk-session-cookies
+Example:
+  - -b "" $URL
+  - -b cookiefile $URL
+  - -b cookiefile -c cookiefile $URL
 ---
+
+# `--cookie`
+
 Pass the data to the HTTP server in the Cookie header. It is supposedly the
 data previously received from the server in a "Set-Cookie:" line. The data
 should be in the format "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the

docs/cmdline-opts/create-dirs.d → docs/cmdline-opts/create-dirs.md

@@ -1,13 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: create-dirs
 Help: Create necessary local directory hierarchy
 Category: curl
-Example: --create-dirs --output local/dir/file $URL
 Added: 7.10.3
-See-also: ftp-create-dirs output-dir
 Multi: boolean
+See-also:
+  - ftp-create-dirs
+  - output-dir
+Example:
+  - --create-dirs --output local/dir/file $URL
 ---
+
+# `--create-dirs`
+
 When used in conjunction with the --output option, curl creates the necessary
 local directory hierarchy as needed. This option creates the directories
 mentioned with the --output option combined with the path possibly set with

docs/cmdline-opts/create-file-mode.d → docs/cmdline-opts/create-file-mode.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: create-file-mode
@@ -5,11 +6,16 @@ Arg: <mode>
 Help: File mode for created files
 Protocols: SFTP SCP FILE
 Category: sftp scp file upload
-See-also: ftp-create-dirs
 Added: 7.75.0
-Example: --create-file-mode 0777 -T localfile sftp://example.com/new
 Multi: single
+See-also:
+  - ftp-create-dirs
+Example:
+  - --create-file-mode 0777 -T localfile sftp://example.com/new
 ---
+
+# `--create-file-mode`
+
 When curl is used to create files remotely using one of the supported
 protocols, this option allows the user to set which 'mode' to set on the file
 at creation time, instead of the default 0644.

docs/cmdline-opts/crlf.d → docs/cmdline-opts/crlf.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: crlf
 Help: Convert LF to CRLF in upload
 Protocols: FTP SMTP
 Category: ftp smtp
-Example: --crlf -T file ftp://example.com/
 Added: 5.7
-See-also: use-ascii
 Multi: boolean
+See-also:
+  - use-ascii
+Example:
+  - --crlf -T file ftp://example.com/
 ---
+
+# `--crlf`
+
 Convert line feeds to carriage return plus line feeds in upload. Useful for
 **MVS (OS/390)**.
 

docs/cmdline-opts/crlfile.d → docs/cmdline-opts/crlfile.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: crlfile
@@ -6,9 +7,15 @@ Protocols: TLS
 Help: Use this CRL list
 Added: 7.19.7
 Category: tls
-Example: --crlfile rejects.txt $URL
-See-also: cacert capath
 Multi: single
+See-also:
+  - cacert
+  - capath
+Example:
+  - --crlfile rejects.txt $URL
 ---
+
+# `--crlfile`
+
 Provide a file using PEM format with a Certificate Revocation List that may
 specify peer certificates that are to be considered revoked.

docs/cmdline-opts/curves.d → docs/cmdline-opts/curves.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: curves
@@ -6,14 +7,19 @@ Help: (EC) TLS key exchange algorithm(s) to request
 Protocols: TLS
 Added: 7.73.0
 Category: tls
-Example: --curves X25519 $URL
-See-also: ciphers
 Multi: single
+See-also:
+  - ciphers
+Example:
+  - --curves X25519 $URL
 ---
+
+# `--curves`
+
 Tells curl to request specific curves to use during SSL session establishment
-according to RFC 8422, 5.1.  Multiple algorithms can be provided by separating
-them with ":" (e.g.  "X25519:P-521").  The parameter is available identically
-in the "openssl s_client/s_server" utilities.
+according to RFC 8422, 5.1. Multiple algorithms can be provided by separating
+them with `:` (e.g. `X25519:P-521`). The parameter is available identically in
+the OpenSSL `s_client` and `s_server` utilities.
 
 --curves allows a OpenSSL powered curl to make SSL-connections with exactly
 the (EC) curve requested by the client, avoiding nontransparent client/server

docs/cmdline-opts/data-ascii.d → docs/cmdline-opts/data-ascii.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: data-ascii
@@ -5,9 +6,16 @@ Arg: <data>
 Help: HTTP POST ASCII data
 Protocols: HTTP
 Category: http post upload
-Example: --data-ascii @file $URL
 Added: 7.2
-See-also: data-binary data-raw data-urlencode
 Multi: append
+See-also:
+  - data-binary
+  - data-raw
+  - data-urlencode
+Example:
+  - --data-ascii @file $URL
 ---
+
+# `--data-ascii`
+
 This is just an alias for --data.

docs/cmdline-opts/data-binary.d → docs/cmdline-opts/data-binary.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: data-binary
@@ -5,11 +6,16 @@ Arg: <data>
 Help: HTTP POST binary data
 Protocols: HTTP
 Category: http post upload
-Example: --data-binary @filename $URL
 Added: 7.2
-See-also: data-ascii
 Multi: append
+See-also:
+  - data-ascii
+Example:
+  - --data-binary @filename $URL
 ---
+
+# `--data-binary`
+
 This posts data exactly as specified with no extra processing whatsoever.
 
 If you start the data with the letter @, the rest should be a filename. Data

docs/cmdline-opts/data-raw.d → docs/cmdline-opts/data-raw.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: data-raw
@@ -5,11 +6,16 @@ Arg: <data>
 Protocols: HTTP
 Help: HTTP POST data, '@' allowed
 Added: 7.43.0
-See-also: data
 Category: http post upload
-Example: --data-raw "hello" $URL
-Example: --data-raw "@at@at@" $URL
 Multi: append
+See-also:
+  - data
+Example:
+  - --data-raw "hello" $URL
+  - --data-raw "@at@at@" $URL
 ---
+
+# `--data-raw`
+
 This posts data similarly to --data but without the special
 interpretation of the @ character.

docs/cmdline-opts/data-urlencode.d → docs/cmdline-opts/data-urlencode.md

@@ -1,18 +1,25 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: data-urlencode
 Arg: <data>
 Help: HTTP POST data URL encoded
 Protocols: HTTP
-See-also: data data-raw
 Added: 7.18.0
 Category: http post upload
-Example: --data-urlencode name=val $URL
-Example: --data-urlencode =encodethis $URL
-Example: --data-urlencode name@file $URL
-Example: --data-urlencode @fileonly $URL
 Multi: append
+See-also:
+  - data
+  - data-raw
+Example:
+  - --data-urlencode name=val $URL
+  - --data-urlencode =encodethis $URL
+  - --data-urlencode name@file $URL
+  - --data-urlencode @fileonly $URL
 ---
+
+# `--data-urlencode`
+
 This posts data, similar to the other --data options with the exception
 that this performs URL-encoding.
 

docs/cmdline-opts/data.d → docs/cmdline-opts/data.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: data
@@ -5,15 +6,22 @@ Short: d
 Arg: <data>
 Help: HTTP POST data
 Protocols: HTTP MQTT
-See-also: data-binary data-urlencode data-raw
 Mutexed: form head upload-file
 Category: important http post upload
-Example: -d "name=curl" $URL
-Example: -d "name=curl" -d "tool=cmdline" $URL
-Example: -d @filename $URL
 Added: 4.0
 Multi: append
+See-also:
+  - data-binary
+  - data-urlencode
+  - data-raw
+Example:
+  - -d "name=curl" $URL
+  - -d "name=curl" -d "tool=cmdline" $URL
+  - -d @filename $URL
 ---
+
+# `--data`
+
 Sends the specified data in a POST request to the HTTP server, in the same way
 that a browser does when a user has filled in an HTML form and presses the
 submit button. This makes curl pass the data to the server using the

docs/cmdline-opts/delegation.d → docs/cmdline-opts/delegation.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: delegation
@@ -5,11 +6,17 @@ Arg: <LEVEL>
 Help: GSS-API delegation permission
 Protocols: GSS/kerberos
 Category: auth
-Example: --delegation "none" $URL
 Added: 7.22.0
-See-also: insecure ssl
 Multi: single
+See-also:
+  - insecure
+  - ssl
+Example:
+  - --delegation "none" $URL
 ---
+
+# `--delegation`
+
 Set LEVEL to tell the server what it is allowed to delegate when it
 comes to user credentials.
 

docs/cmdline-opts/digest.d → docs/cmdline-opts/digest.md

@@ -1,15 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: digest
 Help: Use HTTP Digest Authentication
 Protocols: HTTP
 Mutexed: basic ntlm negotiate
-See-also: user proxy-digest anyauth
 Category: proxy auth http
-Example: -u name:password --digest $URL
 Added: 7.10.6
 Multi: boolean
+See-also:
+  - user
+  - proxy-digest
+  - anyauth
+Example:
+  - -u name:password --digest $URL
 ---
+
+# `--digest`
+
 Enables HTTP Digest authentication. This is an authentication scheme that
 prevents the password from being sent over the wire in clear text. Use this in
 combination with the normal --user option to set user name and password.

docs/cmdline-opts/disable-eprt.d → docs/cmdline-opts/disable-eprt.md

@@ -1,14 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: disable-eprt
 Help: Inhibit using EPRT or LPRT
 Protocols: FTP
 Category: ftp
-Example: --disable-eprt ftp://example.com/
 Added: 7.10.5
-See-also: disable-epsv ftp-port
 Multi: boolean
+See-also:
+  - disable-epsv
+  - ftp-port
+Example:
+  - --disable-eprt ftp://example.com/
 ---
+
+# `--disable-eprt`
+
 Tell curl to disable the use of the EPRT and LPRT commands when doing active
 FTP transfers. Curl normally first attempts to use EPRT before using PORT, but
 with this option, it uses PORT right away. EPRT is an extension to the

docs/cmdline-opts/disable-epsv.d → docs/cmdline-opts/disable-epsv.md

@@ -1,14 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: disable-epsv
 Help: Inhibit using EPSV
 Protocols: FTP
 Category: ftp
-Example: --disable-epsv ftp://example.com/
 Added: 7.9.2
-See-also: disable-eprt ftp-port
 Multi: boolean
+See-also:
+  - disable-eprt
+  - ftp-port
+Example:
+  - --disable-epsv ftp://example.com/
 ---
+
+# `--disable-epsv`
+
 Tell curl to disable the use of the EPSV command when doing passive FTP
 transfers. Curl normally first attempts to use EPSV before PASV, but with this
 option, it does not try EPSV.

docs/cmdline-opts/disable.d → docs/cmdline-opts/disable.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: disable
 Short: q
 Help: Disable .curlrc
 Category: curl
-Example: -q $URL
 Added: 5.0
-See-also: config
 Multi: boolean
+See-also:
+  - config
+Example:
+  - -q $URL
 ---
+
+# `--disable`
+
 If used as the **first** parameter on the command line, the *curlrc* config
 file is not read or used. See the --config for details on the default config
 file search path.

docs/cmdline-opts/disallow-username-in-url.d → docs/cmdline-opts/disallow-username-in-url.md

@@ -1,12 +1,18 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: disallow-username-in-url
 Help: Disallow username in URL
 Added: 7.61.0
-See-also: proto
 Category: curl
-Example: --disallow-username-in-url $URL
 Multi: boolean
+See-also:
+  - proto
+Example:
+  - --disallow-username-in-url $URL
 ---
+
+# `--disallow-username-in-url`
+
 This tells curl to exit if passed a URL containing a username. This is probably
 most useful when the URL is being provided at runtime or similar.

docs/cmdline-opts/dns-interface.d → docs/cmdline-opts/dns-interface.md

@@ -1,16 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: dns-interface
 Arg: <interface>
 Help: Interface to use for DNS requests
 Protocols: DNS
-See-also: dns-ipv4-addr dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
-Example: --dns-interface eth0 $URL
 Multi: single
+See-also:
+  - dns-ipv4-addr
+  - dns-ipv6-addr
+Example:
+  - --dns-interface eth0 $URL
 ---
+
+# `--dns-interface`
+
 Tell curl to send outgoing DNS requests through <interface>. This option is a
 counterpart to --interface (which does not affect DNS). The supplied string
 must be an interface name (not an address).

docs/cmdline-opts/dns-ipv4-addr.d → docs/cmdline-opts/dns-ipv4-addr.md

@@ -1,16 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: dns-ipv4-addr
 Arg: <address>
 Help: IPv4 address to use for DNS requests
 Protocols: DNS
-See-also: dns-interface dns-ipv6-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
-Example: --dns-ipv4-addr 10.1.2.3 $URL
 Multi: single
+See-also:
+  - dns-interface
+  - dns-ipv6-addr
+Example:
+  - --dns-ipv4-addr 10.1.2.3 $URL
 ---
+
+# `--dns-ipv4-addr`
+
 Tell curl to bind to a specific IP address when making IPv4 DNS requests, so
 that the DNS requests originate from this address. The argument should be a
 single IPv4 address.

docs/cmdline-opts/dns-ipv6-addr.d → docs/cmdline-opts/dns-ipv6-addr.md

@@ -1,16 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: dns-ipv6-addr
 Arg: <address>
 Help: IPv6 address to use for DNS requests
 Protocols: DNS
-See-also: dns-interface dns-ipv4-addr
 Added: 7.33.0
 Requires: c-ares
 Category: dns
-Example: --dns-ipv6-addr 2a04:4e42::561 $URL
 Multi: single
+See-also:
+  - dns-interface
+  - dns-ipv4-addr
+Example:
+  - --dns-ipv6-addr 2a04:4e42::561 $URL
 ---
+
+# `--dns-ipv6-addr`
+
 Tell curl to bind to a specific IP address when making IPv6 DNS requests, so
 that the DNS requests originate from this address. The argument should be a
 single IPv6 address.

docs/cmdline-opts/dns-servers.d → docs/cmdline-opts/dns-servers.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: dns-servers
@@ -7,10 +8,16 @@ Protocols: DNS
 Requires: c-ares
 Added: 7.33.0
 Category: dns
-Example: --dns-servers 192.168.0.1,192.168.0.2 $URL
-See-also: dns-interface dns-ipv4-addr
 Multi: single
+See-also:
+  - dns-interface
+  - dns-ipv4-addr
+Example:
+  - --dns-servers 192.168.0.1,192.168.0.2 $URL
 ---
+
+# `--dns-servers`
+
 Set the list of DNS servers to be used instead of the system default.
 The list of IP addresses should be separated with commas. Port numbers
 may also optionally be given as *:<port-number>* after each IP

docs/cmdline-opts/doh-cert-status.d → docs/cmdline-opts/doh-cert-status.md

@@ -1,11 +1,17 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: doh-cert-status
 Help: Verify the status of the DoH server cert via OCSP-staple
 Added: 7.76.0
 Category: dns tls
-Example: --doh-cert-status --doh-url https://doh.example $URL
-See-also: doh-insecure
 Multi: boolean
+See-also:
+  - doh-insecure
+Example:
+  - --doh-cert-status --doh-url https://doh.example $URL
 ---
+
+# `--doh-cert-status`
+
 Same as --cert-status but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-insecure.d → docs/cmdline-opts/doh-insecure.md

@@ -1,11 +1,17 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: doh-insecure
 Help: Allow insecure DoH server connections
 Added: 7.76.0
 Category: dns tls
-Example: --doh-insecure --doh-url https://doh.example $URL
-See-also: doh-url
 Multi: boolean
+See-also:
+  - doh-url
+Example:
+  - --doh-insecure --doh-url https://doh.example $URL
 ---
+
+# `--doh-insecure`
+
 Same as --insecure but used for DoH (DNS-over-HTTPS).

docs/cmdline-opts/doh-url.d → docs/cmdline-opts/doh-url.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: doh-url
@@ -5,10 +6,15 @@ Arg: <URL>
 Help: Resolve host names over DoH
 Added: 7.62.0
 Category: dns
-Example: --doh-url https://doh.example $URL
-See-also: doh-insecure
 Multi: single
+See-also:
+  - doh-insecure
+Example:
+  - --doh-url https://doh.example $URL
 ---
+
+# `--doh-url`
+
 Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames,
 instead of using the default name resolver mechanism. The URL must be HTTPS.
 

docs/cmdline-opts/dump-header.d → docs/cmdline-opts/dump-header.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: dump-header
@@ -5,12 +6,17 @@ Short: D
 Arg: <filename>
 Help: Write the received headers to <filename>
 Protocols: HTTP FTP
-See-also: output
 Category: http ftp
-Example: --dump-header store.txt $URL
 Added: 5.7
 Multi: single
+See-also:
+  - output
+Example:
+  - --dump-header store.txt $URL
 ---
+
+# `--dump-header`
+
 Write the received protocol headers to the specified file. If no headers are
 received, the use of this option creates an empty file.
 

docs/cmdline-opts/egd-file.d → docs/cmdline-opts/egd-file.md

@@ -1,15 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: egd-file
 Arg: <file>
 Help: EGD socket path for random data
 Protocols: TLS
-See-also: random-file
 Category: tls
-Example: --egd-file /random/here $URL
 Added: 7.7
 Multi: single
+See-also:
+  - random-file
+Example:
+  - --egd-file /random/here $URL
 ---
+
+# `--egd-file`
+
 Deprecated option (added in 7.84.0). Prior to that it only had an effect on
 curl if built to use old versions of OpenSSL.
 

docs/cmdline-opts/engine.d → docs/cmdline-opts/engine.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: engine
@@ -5,11 +6,17 @@ Arg: <name>
 Help: Crypto engine to use
 Protocols: TLS
 Category: tls
-Example: --engine flavor $URL
 Added: 7.9.3
-See-also: ciphers curves
 Multi: single
+See-also:
+  - ciphers
+  - curves
+Example:
+  - --engine flavor $URL
 ---
+
+# `--engine`
+
 Select the OpenSSL crypto engine to use for cipher operations. Use --engine
 list to print a list of build-time supported engines. Note that not all (and
 possibly none) of the engines may be available at runtime.

docs/cmdline-opts/etag-compare.d → docs/cmdline-opts/etag-compare.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: etag-compare
@@ -6,10 +7,16 @@ Help: Pass an ETag from a file as a custom header
 Protocols: HTTP
 Added: 7.68.0
 Category: http
-Example: --etag-compare etag.txt $URL
-See-also: etag-save time-cond
 Multi: single
+See-also:
+  - etag-save
+  - time-cond
+Example:
+  - --etag-compare etag.txt $URL
 ---
+
+# `--etag-compare`
+
 This option makes a conditional HTTP request for the specific ETag read
 from the given file by sending a custom If-None-Match header using the
 stored ETag.

docs/cmdline-opts/etag-save.d → docs/cmdline-opts/etag-save.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: etag-save
@@ -6,10 +7,15 @@ Help: Parse ETag from a request and save it to a file
 Protocols: HTTP
 Added: 7.68.0
 Category: http
-Example: --etag-save storetag.txt $URL
-See-also: etag-compare
 Multi: single
+See-also:
+  - etag-compare
+Example:
+  - --etag-save storetag.txt $URL
 ---
+
+# `--etag-save`
+
 This option saves an HTTP ETag to the specified file. An ETag is a
 caching related header, usually returned in a response.
 

docs/cmdline-opts/expect100-timeout.d → docs/cmdline-opts/expect100-timeout.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: expect100-timeout
@@ -5,11 +6,16 @@ Arg: <seconds>
 Help: How long to wait for 100-continue
 Protocols: HTTP
 Added: 7.47.0
-See-also: connect-timeout
 Category: http
-Example: --expect100-timeout 2.5 -T file $URL
 Multi: single
+See-also:
+  - connect-timeout
+Example:
+  - --expect100-timeout 2.5 -T file $URL
 ---
+
+# `--expect100-timeout`
+
 Maximum time in seconds that you allow curl to wait for a 100-continue
 response when curl emits an Expects: 100-continue header in its request. By
 default curl waits one second. This option accepts decimal values! When

docs/cmdline-opts/fail-early.d → docs/cmdline-opts/fail-early.md

@@ -1,14 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: fail-early
 Help: Fail on first transfer error, do not continue
 Added: 7.52.0
 Category: curl
-Example: --fail-early $URL https://two.example
-See-also: fail fail-with-body
 Multi: boolean
 Scope: global
+See-also:
+  - fail
+  - fail-with-body
+Example:
+  - --fail-early $URL https://two.example
 ---
+
+# `--fail-early`
+
 Fail and exit on the first detected transfer error.
 
 When curl is used to do multiple transfers on the command line, it attempts to

docs/cmdline-opts/fail-with-body.d → docs/cmdline-opts/fail-with-body.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: fail-with-body
@@ -5,11 +6,17 @@ Protocols: HTTP
 Help: Fail on HTTP errors but save the body
 Category: http output
 Added: 7.76.0
-See-also: fail fail-early
 Mutexed: fail
-Example: --fail-with-body $URL
 Multi: boolean
+See-also:
+  - fail
+  - fail-early
+Example:
+  - --fail-with-body $URL
 ---
+
+# `--fail-with-body`
+
 Return an error on server errors where the HTTP response code is 400 or
 greater). In normal cases when an HTTP server fails to deliver a document, it
 returns an HTML document stating so (which often also describes why and

docs/cmdline-opts/fail.d → docs/cmdline-opts/fail.md

@@ -1,16 +1,23 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: fail
 Short: f
 Protocols: HTTP
 Help: Fail fast with no output on HTTP errors
-See-also: fail-with-body fail-early
 Category: important http
-Example: --fail $URL
 Mutexed: fail-with-body
 Added: 4.0
 Multi: boolean
+See-also:
+  - fail-with-body
+  - fail-early
+Example:
+  - --fail $URL
 ---
+
+# `--fail`
+
 Fail fast with no output at all on server errors. This is useful to enable
 scripts and users to better deal with failed attempts. In normal cases when an
 HTTP server fails to deliver a document, it returns an HTML document stating

docs/cmdline-opts/false-start.d → docs/cmdline-opts/false-start.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: false-start
@@ -5,10 +6,15 @@ Help: Enable TLS False Start
 Protocols: TLS
 Added: 7.42.0
 Category: tls
-Example: --false-start $URL
-See-also: tcp-fastopen
 Multi: boolean
+See-also:
+  - tcp-fastopen
+Example:
+  - --false-start $URL
 ---
+
+# `--false-start`
+
 Tells curl to use false start during the TLS handshake. False start is a mode
 where a TLS client starts sending application data before verifying the
 server's Finished message, thus saving a round trip when performing a full

docs/cmdline-opts/form-escape.d → docs/cmdline-opts/form-escape.md

@@ -1,13 +1,19 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: form-escape
 Help: Escape multipart form field/file names using backslash
 Protocols: HTTP
-See-also: form
 Added: 7.81.0
 Category: http upload
-Example: --form-escape -F 'field\\name=curl' -F 'file=@load"this' $URL
 Multi: single
+See-also:
+  - form
+Example:
+  - --form-escape -F 'field\name=curl' -F 'file=@load"this' $URL
 ---
+
+# `--form-escape`
+
 Tells curl to pass on names of multipart form fields and files using
 backslash-escaping instead of percent-encoding.

docs/cmdline-opts/form-string.d → docs/cmdline-opts/form-string.md

@@ -1,15 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: form-string
 Help: Specify multipart MIME data
 Protocols: HTTP SMTP IMAP
 Arg: <name=string>
-See-also: form
 Category: http upload
-Example: --form-string "data" $URL
 Added: 7.13.2
 Multi: append
+See-also:
+  - form
+Example:
+  - --form-string "data" $URL
 ---
+
+# `--form-string`
+
 Similar to --form except that the value string for the named parameter is used
 literally. Leading '@' and '<' characters, and the ';type=' string in
 the value have no special meaning. Use this in preference to --form if

docs/cmdline-opts/form.d → docs/cmdline-opts/form.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: form
@@ -7,11 +8,18 @@ Help: Specify multipart MIME data
 Protocols: HTTP SMTP IMAP
 Mutexed: data head upload-file
 Category: http upload
-Example: --form "name=curl" --form "file=@loadthis" $URL
 Added: 5.0
-See-also: data form-string form-escape
 Multi: append
+See-also:
+  - data
+  - form-string
+  - form-escape
+Example:
+  - --form "name=curl" --form "file=@loadthis" $URL
 ---
+
+# `--form`
+
 For HTTP protocol family, this lets curl emulate a filled-in form in which a
 user has pressed the submit button. This causes curl to POST data using the
 Content-Type multipart/form-data according to RFC 2388.
@@ -37,38 +45,38 @@ such data is sent as chunks by HTTP and rejected by IMAP.
 Example: send an image to an HTTP server, where 'profile' is the name of the
 form-field to which the file **portrait.jpg** is the input:
 
- curl -F profile=@portrait.jpg https://example.com/upload.cgi
+    curl -F profile=@portrait.jpg https://example.com/upload.cgi
 
 Example: send your name and shoe size in two text fields to the server:
 
- curl -F name=John -F shoesize=11 https://example.com/
+    curl -F name=John -F shoesize=11 https://example.com/
 
 Example: send your essay in a text field to the server. Send it as a plain
 text field, but get the contents for it from a local file:
 
- curl -F "story=<hugefile.txt" https://example.com/
+    curl -F "story=<hugefile.txt" https://example.com/
 
 You can also tell curl what Content-Type to use by using 'type=', in a manner
 similar to:
 
- curl -F "web=@index.html;type=text/html" example.com
+    curl -F "web=@index.html;type=text/html" example.com
 
 or
 
- curl -F "name=daniel;type=text/foo" example.com
+    curl -F "name=daniel;type=text/foo" example.com
 
 You can also explicitly change the name field of a file upload part by setting
 filename=, like this:
 
- curl -F "file=@localfile;filename=nameinpost" example.com
+    curl -F "file=@localfile;filename=nameinpost" example.com
 
 If filename/path contains ',' or ';', it must be quoted by double-quotes like:
 
- curl -F "file=@\\"local,file\\";filename=\\"name;in;post\\"" example.com
+    curl -F "file=@\"local,file\";filename=\"name;in;post\"" example.com
 
 or
 
- curl -F 'file=@"local,file";filename="name;in;post"' example.com
+    curl -F 'file=@"local,file";filename="name;in;post"' example.com
 
 Note that if a filename/path is quoted by double-quotes, any double-quote
 or backslash within the filename must be escaped by backslash.
@@ -76,15 +84,15 @@ or backslash within the filename must be escaped by backslash.
 Quoting must also be applied to non-file data if it contains semicolons,
 leading/trailing spaces or leading double quotes:
 
- curl -F 'colors="red; green; blue";type=text/x-myapp' example.com
+    curl -F 'colors="red; green; blue";type=text/x-myapp' example.com
 
 You can add custom headers to the field by setting headers=, like
 
-  curl -F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com
+    curl -F "submit=OK;headers=\"X-submit-type: OK\"" example.com
 
 or
 
-  curl -F "submit=OK;headers=@headerfile" example.com
+    curl -F "submit=OK;headers=@headerfile" example.com
 
 The headers= keyword may appear more that once and above notes about quoting
 apply. When headers are read from a file, Empty lines and lines starting
@@ -93,12 +101,12 @@ between two words and starting the continuation line with a space; embedded
 carriage-returns and trailing spaces are stripped.
 Here is an example of a header file contents:
 
-  # This file contain two headers.
-  X-header-1: this is a header
+    # This file contain two headers.
+    X-header-1: this is a header
 
-  # The following header is folded.
-  X-header-2: this is
-   another header
+    # The following header is folded.
+    X-header-2: this is
+     another header
 
 To support sending multipart mail messages, the syntax is extended as follows:
 
@@ -113,10 +121,10 @@ Example: the following command sends an SMTP mime email consisting in an
 inline part in two alternative formats: plain text and HTML. It attaches a
 text file:
 
- curl -F '=(;type=multipart/alternative' \\
-      -F '=plain text message' \\
-      -F '= <body>HTML message</body>;type=text/html' \\
-      -F '=)' -F '=@textfile.txt' ...  smtp://example.com
+    curl -F '=(;type=multipart/alternative' \
+         -F '=plain text message' \
+         -F '= <body>HTML message</body>;type=text/html' \
+         -F '=)' -F '=@textfile.txt' ...  smtp://example.com
 
 Data can be encoded for transfer using encoder=. Available encodings are
 *binary* and *8bit* that do nothing else than adding the corresponding
@@ -128,7 +136,7 @@ characters.
 Example: send multipart mail with a quoted-printable text message and a
 base64 attached file:
 
- curl -F '=text message;encoder=quoted-printable' \\
-      -F '=@localfile;encoder=base64' ... smtp://example.com
+    curl -F '=text message;encoder=quoted-printable' \
+         -F '=@localfile;encoder=base64' ... smtp://example.com
 
 See further examples and details in the MANUAL.

docs/cmdline-opts/ftp-account.d → docs/cmdline-opts/ftp-account.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-account
@@ -6,9 +7,14 @@ Help: Account data string
 Protocols: FTP
 Added: 7.13.0
 Category: ftp auth
-Example: --ftp-account "mr.robot" ftp://example.com/
-See-also: user
 Multi: single
+See-also:
+  - user
+Example:
+  - --ftp-account "mr.robot" ftp://example.com/
 ---
+
+# `--ftp-account`
+
 When an FTP server asks for "account data" after user name and password has
 been provided, this data is sent off using the ACCT command.

docs/cmdline-opts/ftp-alternative-to-user.d → docs/cmdline-opts/ftp-alternative-to-user.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-alternative-to-user
@@ -6,10 +7,16 @@ Help: String to replace USER [name]
 Protocols: FTP
 Added: 7.15.5
 Category: ftp
-Example: --ftp-alternative-to-user "U53r" ftp://example.com
-See-also: ftp-account user
 Multi: single
+See-also:
+  - ftp-account
+  - user
+Example:
+  - --ftp-alternative-to-user "U53r" ftp://example.com
 ---
+
+# `--ftp-alternative-to-user`
+
 If authenticating with the USER and PASS commands fails, send this command.
 When connecting to Tumbleweed's Secure Transport server over FTPS using a
 client certificate, using "SITE AUTH" tells the server to retrieve the

docs/cmdline-opts/ftp-create-dirs.d → docs/cmdline-opts/ftp-create-dirs.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-create-dirs
 Protocols: FTP SFTP
 Help: Create the remote dirs if not present
-See-also: create-dirs
 Category: ftp sftp curl
-Example: --ftp-create-dirs -T file ftp://example.com/remote/path/file
 Added: 7.10.7
 Multi: boolean
+See-also:
+  - create-dirs
+Example:
+  - --ftp-create-dirs -T file ftp://example.com/remote/path/file
 ---
+
+# `--ftp-create-dirs`
+
 When an FTP or SFTP URL/operation uses a path that does not currently exist on
 the server, the standard behavior of curl is to fail. Using this option, curl
 instead attempts to create missing directories.

docs/cmdline-opts/ftp-method.d → docs/cmdline-opts/ftp-method.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-method
@@ -6,12 +7,17 @@ Help: Control CWD usage
 Protocols: FTP
 Added: 7.15.1
 Category: ftp
-Example: --ftp-method multicwd ftp://example.com/dir1/dir2/file
-Example: --ftp-method nocwd ftp://example.com/dir1/dir2/file
-Example: --ftp-method singlecwd ftp://example.com/dir1/dir2/file
-See-also: list-only
 Multi: single
+See-also:
+  - list-only
+Example:
+  - --ftp-method multicwd ftp://example.com/dir1/dir2/file
+  - --ftp-method nocwd ftp://example.com/dir1/dir2/file
+  - --ftp-method singlecwd ftp://example.com/dir1/dir2/file
 ---
+
+# `--ftp-method`
+
 Control what method curl should use to reach a file on an FTP(S)
 server. The method argument should be one of the following alternatives:
 

docs/cmdline-opts/ftp-pasv.d → docs/cmdline-opts/ftp-pasv.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-pasv
 Help: Use PASV/EPSV instead of PORT
 Protocols: FTP
 Added: 7.11.0
-See-also: disable-epsv
 Category: ftp
-Example: --ftp-pasv ftp://example.com/
 Multi: boolean
+See-also:
+  - disable-epsv
+Example:
+  - --ftp-pasv ftp://example.com/
 ---
+
+# `--ftp-pasv`
+
 Use passive mode for the data connection. Passive is the internal default
 behavior, but using this option can be used to override a previous --ftp-port
 option.

docs/cmdline-opts/ftp-port.d → docs/cmdline-opts/ftp-port.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-port
@@ -5,14 +6,20 @@ Arg: <address>
 Help: Use PORT instead of PASV
 Short: P
 Protocols: FTP
-See-also: ftp-pasv disable-eprt
 Category: ftp
-Example: -P - ftp:/example.com
-Example: -P eth0 ftp:/example.com
-Example: -P 192.168.0.2 ftp:/example.com
 Added: 4.0
 Multi: single
+See-also:
+  - ftp-pasv
+  - disable-eprt
+Example:
+  - -P - ftp:/example.com
+  - -P eth0 ftp:/example.com
+  - -P 192.168.0.2 ftp:/example.com
 ---
+
+# `--ftp-port`
+
 Reverses the default initiator/listener roles when connecting with FTP. This
 option makes curl use active mode. curl then tells the server to connect back
 to the client's specified address and port, while passive mode asks the server
@@ -37,7 +44,7 @@ connection. This is the recommended choice.
 Disable the use of PORT with --ftp-pasv. Disable the attempt to use the EPRT
 command instead of PORT by using --disable-eprt. EPRT is really PORT++.
 
-You can also append ":[start]-[end]\&" to the right of the address, to tell
+You can also append ":[start]-[end]" to the right of the address, to tell
 curl what TCP port range to use. That means you specify a port range, from a
 lower to a higher number. A single number works as well, but do note that it
 increases the risk of failure since the port may not be available.

docs/cmdline-opts/ftp-pret.d → docs/cmdline-opts/ftp-pret.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-pret
@@ -5,10 +6,16 @@ Help: Send PRET before PASV
 Protocols: FTP
 Added: 7.20.0
 Category: ftp
-Example: --ftp-pret ftp://example.com/
-See-also: ftp-port ftp-pasv
 Multi: boolean
+See-also:
+  - ftp-port
+  - ftp-pasv
+Example:
+  - --ftp-pret ftp://example.com/
 ---
+
+# `--ftp-pret`
+
 Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers,
 mainly drftpd, require this non-standard command for directory listings as
 well as up and downloads in PASV mode.

docs/cmdline-opts/ftp-skip-pasv-ip.d → docs/cmdline-opts/ftp-skip-pasv-ip.md

@@ -1,14 +1,20 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-skip-pasv-ip
 Help: Skip the IP address for PASV
 Protocols: FTP
 Added: 7.14.2
-See-also: ftp-pasv
 Category: ftp
-Example: --ftp-skip-pasv-ip ftp://example.com/
 Multi: boolean
+See-also:
+  - ftp-pasv
+Example:
+  - --ftp-skip-pasv-ip ftp://example.com/
 ---
+
+# `--ftp-skip-pasv-ip`
+
 Tell curl to not use the IP address the server suggests in its response to
 curl's PASV command when curl connects the data connection. Instead curl
 reuses the same IP address it already uses for the control connection.

docs/cmdline-opts/ftp-ssl-ccc-mode.d → docs/cmdline-opts/ftp-ssl-ccc-mode.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-ssl-ccc-mode
@@ -5,11 +6,16 @@ Arg: <active/passive>
 Help: Set CCC mode
 Protocols: FTP
 Added: 7.16.2
-See-also: ftp-ssl-ccc
 Category: ftp tls
-Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
 Multi: boolean
+See-also:
+  - ftp-ssl-ccc
+Example:
+  - --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
 ---
+
+# `--ftp-ssl-ccc-mode`
+
 Sets the CCC mode. The passive mode does not initiate the shutdown, but
 instead waits for the server to do it, and does not reply to the shutdown from
 the server. The active mode initiates the shutdown and waits for a reply from

docs/cmdline-opts/ftp-ssl-ccc.d → docs/cmdline-opts/ftp-ssl-ccc.md

@@ -1,14 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-ssl-ccc
 Help: Send CCC after authenticating
 Protocols: FTP
-See-also: ssl ftp-ssl-ccc-mode
 Added: 7.16.1
 Category: ftp tls
-Example: --ftp-ssl-ccc ftps://example.com/
 Multi: boolean
+See-also:
+  - ssl
+  - ftp-ssl-ccc-mode
+Example:
+  - --ftp-ssl-ccc ftps://example.com/
 ---
+
+# `--ftp-ssl-ccc`
+
 Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
 authenticating. The rest of the control channel communication is be
 unencrypted. This allows NAT routers to follow the FTP transaction. The

docs/cmdline-opts/ftp-ssl-control.d → docs/cmdline-opts/ftp-ssl-control.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: ftp-ssl-control
@@ -5,10 +6,15 @@ Help: Require SSL/TLS for FTP login, clear for transfer
 Protocols: FTP
 Added: 7.16.0
 Category: ftp tls
-Example: --ftp-ssl-control ftp://example.com
-See-also: ssl
 Multi: boolean
+See-also:
+  - ssl
+Example:
+  - --ftp-ssl-control ftp://example.com
 ---
-Require SSL/TLS for the FTP login, clear for transfer.  Allows secure
-authentication, but non-encrypted data transfers for efficiency.  Fails the
+
+# `--ftp-ssl-control`
+
+Require SSL/TLS for the FTP login, clear for transfer. Allows secure
+authentication, but non-encrypted data transfers for efficiency. Fails the
 transfer if the server does not support SSL/TLS.

docs/cmdline-opts/gen.pl

@@ -90,52 +90,8 @@ sub printdesc {
     my @desc = @_;
     my $exam = 0;
     for my $d (@desc) {
-        if($d =~ /\(Added in ([0-9.]+)\)/i) {
-            my $ver = $1;
-            if(too_old($ver)) {
-                $d =~ s/ *\(Added in $ver\)//gi;
-            }
-        }
-        if($d !~ /^.\\"/) {
-            # **bold**
-            $d =~ s/\*\*(.*?)\*\*/\\fB$1\\fP/g;
-            # *italics*
-            $d =~ s/\*(.*?)\*/\\fI$1\\fP/g;
-        }
-        if(!$exam && ($d =~ /^ /)) {
-            # start of example
-            $exam = 1;
-            print ".nf\n"; # no-fill
-        }
-        elsif($exam && ($d !~ /^ /)) {
-            # end of example
-            $exam = 0;
-            print ".fi\n"; # fill-in
-        }
-        # skip lines starting with space (examples)
-        if($d =~ /^[^ ]/ && $d =~ /--/) {
-            # scan for options in longest-names first order
-            for my $k (sort {length($b) <=> length($a)} keys %optlong) {
-                # --tlsv1 is complicated since --tlsv1.2 etc are also
-                # acceptable options!
-                if(($k eq "tlsv1") && ($d =~ /--tlsv1\.[0-9]\\f/)) {
-                    next;
-                }
-                my $l = manpageify($k);
-                $d =~ s/\-\-$k([^a-z0-9-])/$l$1/g;
-            }
-        }
-        # quote minuses in the output
-        $d =~ s/([^\\])-/$1\\-/g;
-        # replace single quotes
-        $d =~ s/\'/\\(aq/g;
-        # handle double quotes first on the line
-        $d =~ s/^(\s*)\"/$1\\(dq/;
         print $d;
     }
-    if($exam) {
-        print ".fi\n"; # fill-in
-    }
 }
 
 sub seealso {
@@ -200,9 +156,173 @@ sub added {
     }
 }
 
+sub render {
+    my ($fh, $f, $line) = @_;
+    my @desc;
+    my $tablemode = 0;
+    my $header = 0;
+    # if $top is TRUE, it means a top-level page and not a command line option
+    my $top = ($line == 1);
+    my $quote;
+    $start = 0;
+
+    while(<$fh>) {
+        my $d = $_;
+        $line++;
+        if($d =~ /^\.(SH|BR|IP|B)/) {
+            print STDERR "$f:$line:1:ERROR: nroff instruction in input: \".$1\"\n";
+            return 4;
+        }
+        if(/^ *<!--/) {
+            # skip comments
+            next;
+        }
+        if((!$start) && ($_ =~ /^[\r\n]*\z/)) {
+            # skip leading blank lines
+            next;
+        }
+        $start = 1;
+        if(/^# (.*)/) {
+            $header = 1;
+            if($top != 1) {
+                # ignored for command line options
+                $blankline++;
+                next;
+            }
+            push @desc, ".SH $1\n";
+            next;
+        }
+        elsif(/^###/) {
+            print STDERR "$f:$line:1:ERROR: ### header is not supported\n";
+            exit 3;
+        }
+        elsif(/^## (.*)/) {
+            my $word = $1;
+            # if there are enclosing quotes, remove them first
+            $word =~ s/[\"\'](.*)[\"\']\z/$1/;
+
+            # remove backticks from headers
+            $words =~ s/\`//g;
+
+            # if there is a space, it needs quotes
+            if($word =~ / /) {
+                $word = "\"$word\"";
+            }
+            if($top == 1) {
+                push @desc, ".IP $word\n";
+            }
+            else {
+                if(!$tablemode) {
+                    push @desc, ".RS\n";
+                    $tablemode = 1;
+                }
+                push @desc, ".IP \\fB$word\\fP\n";
+            }
+            $header = 1;
+            next;
+        }
+        elsif(/^##/) {
+            if($top == 1) {
+                print STDERR "$f:$line:1:ERROR: ## empty header top-level mode\n";
+                exit 3;
+            }
+            if($tablemode) {
+                # end of table
+                push @desc, ".RE\n.IP\n";
+                $tablmode = 0;
+            }
+            $header = 1;
+            next;
+        }
+        elsif(/^\.(IP|RS|RE)/) {
+            my ($cmd) = ($1);
+            print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n";
+            return 3;
+        }
+        elsif(/^[ \t]*\n/) {
+            # count and ignore blank lines
+            $blankline++;
+            next;
+        }
+        elsif($d =~ /^    (.*)/) {
+            my $word = $1;
+            if(!$quote) {
+                push @desc, ".nf\n";
+            }
+            $quote = 1;
+            $d = "$word\n";
+        }
+        elsif($quote && ($d !~ /^    (.*)/)) {
+            # end of quote
+            push @desc, ".fi\n";
+            $quote = 0;
+        }
+
+        $d =~ s/`%DATE`/$date/g;
+        $d =~ s/`%VERSION`/$version/g;
+        $d =~ s/`%GLOBALS`/$globals/g;
+
+        # convert single backslahes to doubles
+        $d =~ s/\\/\\\\/g;
+
+        # convert backticks to double quotes
+        $d =~ s/\`/\"/g;
+
+        if(!$quote && $d =~ /--/) {
+            # scan for options in longest-names first order
+            for my $k (sort {length($b) <=> length($a)} keys %optlong) {
+                # --tlsv1 is complicated since --tlsv1.2 etc are also
+                # acceptable options!
+                if(($k eq "tlsv1") && ($d =~ /--tlsv1\.[0-9]\\f/)) {
+                    next;
+                }
+                my $l = manpageify($k);
+                $d =~ s/\-\-$k([^a-z0-9-])/$l$1/g;
+            }
+        }
+
+        if($d =~ /\(Added in ([0-9.]+)\)/i) {
+            my $ver = $1;
+            if(too_old($ver)) {
+                $d =~ s/ *\(Added in $ver\)//gi;
+            }
+        }
+
+        if(!$quote && ($d =~ /^(.*)  /)) {
+            printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
+                length($1);
+            return 3;
+        }
+        # quote minuses in the output
+        $d =~ s/([^\\])-/$1\\-/g;
+        # replace single quotes
+        $d =~ s/\'/\\(aq/g;
+        # handle double quotes or periods first on the line
+        $d =~ s/^([\.\"])/\\&$1/;
+        # **bold**
+        $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g;
+        # *italics*
+        $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g;
+
+        # trim trailing spaces
+        $d =~ s/[ \t]+\z//;
+        push @desc, "\n" if($blankline && !$header);
+        $blankline = 0;
+        push @desc, $d;
+        $header = 0;
+
+    }
+    if($tablemode) {
+        # end of table
+        push @desc, ".RE\n.IP\n";
+    }
+    return @desc;
+}
+
 sub single {
     my ($f, $standalone)=@_;
-    open(F, "<:crlf", "$f") ||
+    my $fh;
+    open($fh, "<:crlf", "$f") ||
         return 1;
     my $short;
     my $long;
@@ -213,7 +333,7 @@ sub single {
     my $mutexed;
     my $requires;
     my $category;
-    my $seealso;
+    my @seealso;
     my $copyright;
     my $spdx;
     my @examples; # there can be more than one
@@ -223,8 +343,19 @@ sub single {
     my $multi;
     my $scope;
     my $experimental;
-    while(<F>) {
+    my $start;
+    my $list; # identifies the list, 1 example, 2 see-also
+    while(<$fh>) {
         $line++;
+        if(/^ *<!--/) {
+            next;
+        }
+        if(!$start) {
+            if(/^---/) {
+                $start = 1;
+            }
+            next;
+        }
         if(/^Short: *(.)/i) {
             $short=$1;
         }
@@ -249,12 +380,18 @@ sub single {
         elsif(/^Protocols: *(.*)/i) {
             $protocols=$1;
         }
-        elsif(/^See-also: *(.*)/i) {
+        elsif(/^See-also: +(.+)/i) {
             if($seealso) {
                 print STDERR "ERROR: duplicated See-also in $f\n";
                 return 1;
             }
-            $seealso=$1;
+            push @seealso, $1;
+        }
+        elsif(/^See-also:/i) {
+            $list=2;
+        }
+        elsif(/^  *- (.*)/i && ($list == 2)) {
+            push @seealso, $1;
         }
         elsif(/^Requires: *(.*)/i) {
             $requires=$1;
@@ -262,7 +399,14 @@ sub single {
         elsif(/^Category: *(.*)/i) {
             $category=$1;
         }
-        elsif(/^Example: *(.*)/i) {
+        elsif(/^Example: +(.+)/i) {
+            push @examples, $1;
+        }
+        elsif(/^Example:/i) {
+            # '1' is the example list
+            $list = 1;
+        }
+        elsif(/^  *- (.*)/i && ($list == 1)) {
             push @examples, $1;
         }
         elsif(/^Multi: *(.*)/i) {
@@ -284,6 +428,7 @@ sub single {
             ;
         }
         elsif(/^---/) {
+            $start++;
             if(!$long) {
                 print STDERR "ERROR: no 'Long:' in $f\n";
                 return 1;
@@ -300,7 +445,7 @@ sub single {
                 print STDERR "$f:$line:1:ERROR: no 'Added:' version present\n";
                 return 2;
             }
-            if(!$seealso) {
+            if(!$seealso[0]) {
                 print STDERR "$f:$line:1:ERROR: no 'See-also:' field present\n";
                 return 2;
             }
@@ -316,42 +461,17 @@ sub single {
         }
         else {
             chomp;
-            print STDERR "WARN: unrecognized line in $f, ignoring:\n:'$_';"
+            print STDERR "$f:$line:1:WARN: unrecognized line in $f, ignoring:\n:'$_';"
         }
     }
-    my @desc;
-    my $tablemode = 0;
-    while(<F>) {
-        $line++;
-        $dline++;
-        if(($dline == 1) && ($_ =~ /^[\r\n]*\z/)) {
-            print STDERR "$f:$line:1:ERROR: unnecessary leading blank line\n";
-            return 3;
-        }
-        if(/^## (.*)/) {
-            if(!$tablemode) {
-                push @desc, ".RS\n";
-                $tablemode = 1;
-            }
-            push @desc, ".IP \"\\fB$1\\fP\"\n";
-            next;
-        }
-        elsif(/^##/) {
-            if($tablemode) {
-                # end of table
-                push @desc, ".RE\n.IP\n";
-                $tablmode = 0;
-            }
-            next;
-        }
-        elsif(/^\.(IP|RS|RE)/) {
-            my ($cmd) = ($1);
-            print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n";
-            return 3;
-        }
-        push @desc, $_;
+
+    if($start < 2) {
+        print STDERR "$f:1:1:ERROR: no proper meta-data header\n";
+        return 2;
     }
-    close(F);
+
+    my @desc = render($fh, $f, $line);
+    close($fh);
     if($tablemode) {
         # end of table
         push @desc, ".RE\n.IP\n";
@@ -442,30 +562,28 @@ sub single {
     printdesc(@extra);
 
     my @foot;
-    if($seealso) {
-        my @m=split(/ /, $seealso);
-        my $mstr;
-        my $and = 0;
-        my $num = scalar(@m);
-        if($num > 2) {
-            # use commas up to this point
-            $and = $num - 1;
+
+    my $mstr;
+    my $and = 0;
+    my $num = scalar(@seealso);
+    if($num > 2) {
+        # use commas up to this point
+        $and = $num - 1;
+    }
+    my $i = 0;
+    for my $k (@seealso) {
+        if(!$helplong{$k}) {
+            print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n";
         }
-        my $i = 0;
-        for my $k (@m) {
-            if(!$helplong{$k}) {
-                print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n";
-            }
-            my $l = manpageify($k);
-            my $sep = " and";
-            if($and && ($i < $and)) {
-                $sep = ",";
-            }
-            $mstr .= sprintf "%s$l", $mstr?"$sep ":"";
-            $i++;
+        my $l = manpageify($k);
+        my $sep = " and";
+        if($and && ($i < $and)) {
+            $sep = ",";
         }
-        push @foot, seealso($standalone, $mstr);
+        $mstr .= sprintf "%s$l", $mstr?"$sep ":"";
+        $i++;
     }
+    push @foot, seealso($standalone, $mstr);
 
     if($requires) {
         my $l = manpageify($long);
@@ -491,8 +609,10 @@ sub single {
         print "\nExample$s:\n.nf\n";
         foreach my $e (@examples) {
             $e =~ s!\$URL!https://example.com!g;
-            $e =~ s/-/\\-/g;
-            $e =~ s/\'/\\(aq/g;
+            #$e =~ s/-/\\-/g;
+            #$e =~ s/\'/\\(aq/g;
+            # convert single backslahes to doubles
+            $e =~ s/\\/\\\\/g;
             print " curl $e\n";
         }
         print ".fi\n";
@@ -518,7 +638,14 @@ sub getshortlong {
     my $arg;
     my $protocols;
     my $category;
+    my $start = 0;
     while(<F>) {
+        if(!$start) {
+            if(/^---/) {
+                $start = 1;
+            }
+            next;
+        }
         if(/^Short: (.)/i) {
             $short=$1;
         }
@@ -563,15 +690,10 @@ sub indexoptions {
 
 sub header {
     my ($f)=@_;
-    open(F, "<:crlf", "$f");
-    my @d;
-    while(<F>) {
-        s/%DATE/$date/g;
-        s/%VERSION/$version/g;
-        s/%GLOBALS/$globals/g;
-        push @d, $_;
-    }
-    close(F);
+    my $fh;
+    open($fh, "<:crlf", "$f");
+    my @d = render($fh, $f, 1);
+    close($fh);
     printdesc(@d);
 }
 
@@ -687,7 +809,17 @@ sub listglobals {
         open(F, "<:crlf", "$f") ||
             next;
         my $long;
+        my $start = 0;
         while(<F>) {
+            if(/^---/) {
+                if(!$start) {
+                    $start = 1;
+                    next;
+                }
+                else {
+                    last;
+                }
+            }
             if(/^Long: *(.*)/i) {
                 $long=$1;
             }
@@ -695,9 +827,6 @@ sub listglobals {
                 push @globalopts, $long;
                 last;
             }
-            elsif(/^---/) {
-                last;
-            }
         }
         close(F);
     }
@@ -721,17 +850,60 @@ sub sortnames {
 sub mainpage {
     my (@files) = @_;
     my $ret;
-    # show the page header
-    header("page-header");
+    my $fh;
+    open($fh, "<:crlf", "mainpage.idx") ||
+        return 1;
 
-    # output docs for all options
-    foreach my $f (sort sortnames @files) {
-        $ret += single($f, 0);
-    }
+    print <<HEADER
+.\\" **************************************************************************
+.\\" *                                  _   _ ____  _
+.\\" *  Project                     ___| | | |  _ \\| |
+.\\" *                             / __| | | | |_) | |
+.\\" *                            | (__| |_| |  _ <| |___
+.\\" *                             \\___|\\___/|_| \\_\\_____|
+.\\" *
+.\\" * Copyright (C) Daniel Stenberg, <daniel\@haxx.se>, et al.
+.\\" *
+.\\" * This software is licensed as described in the file COPYING, which
+.\\" * you should have received as part of this distribution. The terms
+.\\" * are also available at https://curl.se/docs/copyright.html.
+.\\" *
+.\\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\\" * copies of the Software, and permit persons to whom the Software is
+.\\" * furnished to do so, under the terms of the COPYING file.
+.\\" *
+.\\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\\" * KIND, either express or implied.
+.\\" *
+.\\" * SPDX-License-Identifier: curl
+.\\" *
+.\\" **************************************************************************
+.\\"
+.\\" DO NOT EDIT. Generated by the curl project gen.pl man page generator.
+.\\"
+.TH curl 1 "$date" "curl $version" "curl Manual"
+HEADER
+        ;
 
-    if(!$ret) {
-        header("page-footer");
+    while(<$fh>) {
+        my $f = $_;
+        chomp $f;
+        if($f =~ /^#/) {
+            # stardard comment
+            next;
+        }
+        if(/^%options/) {
+            # output docs for all options
+            foreach my $f (sort sortnames @files) {
+                $ret += single($f, 0);
+            }
+        }
+        else {
+            # render the file
+            header($f);
+        }
     }
+    close($fh);
     exit $ret if($ret);
 }
 

docs/cmdline-opts/get.d → docs/cmdline-opts/get.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: get
@@ -5,13 +6,19 @@ Short: G
 Help: Put the post data in the URL and use GET
 Protocols: HTTP
 Category: http upload
-Example: --get $URL
-Example: --get -d "tool=curl" -d "age=old" $URL
-Example: --get -I -d "tool=curl" $URL
 Added: 7.8.1
-See-also: data request
 Multi: boolean
+See-also:
+  - data
+  - request
+Example:
+  - --get $URL
+  - --get -d "tool=curl" -d "age=old" $URL
+  - --get -I -d "tool=curl" $URL
 ---
+
+# `--get`
+
 When used, this option makes all data specified with --data, --data-binary
 or --data-urlencode to be used in an HTTP GET request instead of the POST
 request that otherwise would be used. The data is appended to the URL

docs/cmdline-opts/globoff.d → docs/cmdline-opts/globoff.md

@@ -1,14 +1,21 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: globoff
 Short: g
 Help: Disable URL sequences and ranges using {} and []
 Category: curl
-Example: -g "https://example.com/{[]}}}}"
 Added: 7.6
-See-also: config disable
 Multi: boolean
+See-also:
+  - config
+  - disable
+Example:
+  - -g "https://example.com/{[]}}}}"
 ---
+
+# `--globoff`
+
 This option switches off the "URL globbing parser". When you set this option,
 you can specify URLs that contain the letters {}[] without having curl itself
 interpret them. Note that these letters are not normal legal URL contents but

docs/cmdline-opts/happy-eyeballs-timeout-ms.d → docs/cmdline-opts/happy-eyeballs-timeout-ms.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: happy-eyeballs-timeout-ms
@@ -5,10 +6,16 @@ Arg: <milliseconds>
 Help: Time for IPv6 before trying IPv4
 Added: 7.59.0
 Category: connection
-Example: --happy-eyeballs-timeout-ms 500 $URL
-See-also: max-time connect-timeout
 Multi: single
+See-also:
+  - max-time
+  - connect-timeout
+Example:
+  - --happy-eyeballs-timeout-ms 500 $URL
 ---
+
+# `--happy-eyeballs-timeout-ms`
+
 Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
 addresses for dual-stack hosts, giving IPv6 a head-start of the specified
 number of milliseconds. If the IPv6 address cannot be connected to within that

docs/cmdline-opts/haproxy-clientip.d → docs/cmdline-opts/haproxy-clientip.md

@@ -1,3 +1,4 @@
+---
 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: haproxy-clientip
@@ -6,10 +7,15 @@ Help: Sets client IP in HAProxy PROXY protocol v1 header
 Protocols: HTTP
 Added: 8.2.0
 Category: http proxy
-Example: --haproxy-clientip $IP
-See-also: proxy
 Multi: single
+See-also:
+  - proxy
+Example:
+  - --haproxy-clientip $IP
 ---
+
+# `--haproxy-clientip`
+
 Sets a client IP in HAProxy PROXY protocol v1 header at the beginning of the
 connection.