REST API examples using curl -F are incorrect and can lead to confusing errors.

For example, the following command, copied from https://www.wikidata.org/api/rest_v1/, which I needed to demonstrate the bug in T228616:

curl -X POST "https://www.wikidata.org/api/rest_v1/transform/html/to/wikitext" -H "accept: text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0"" -H "Content-Type: multipart/form-data" -F "html=<a href='./Wikidata:Administrators%27_noticeboard'>test</a>" -F "scrub_wikitext=true"

Will fail with the following incomprehensible error:

Warning: setting file a
Warning: href='./Wikidata:Administrators%27_noticeboard'>test</a> failed!
curl: (26) read function returned funny value

Reading the man page (https://manpage.me/?q=curl), one can learn that < in a -F parameter has special meaning:

This enables uploading of binary files etc. To force the
'content' part to be a file, prefix the file name with an @
sign. To just get the content part from a file, prefix the file
name with the symbol <. The difference between @ and < is then
that @ makes a file get attached in the post as a file upload,
while the < makes a text field and just get the contents for
that text field from a file.

And that --form-string should be used instead:

--form-string <name=string>
(HTTP SMTP IMAP) Similar to -F, --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 -F, --form if there's
any possibility that the string value may accidentally trigger
the '@' or '<' features of -F, --form.

The REST API should generate examples using that option, for example:

curl -X POST "https://www.wikidata.org/api/rest_v1/transform/html/to/wikitext" -H "accept: text/plain; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/wikitext/1.0.0"" -H "Content-Type: multipart/form-data" --form-string "html=<a href='./Wikidata:Administrators%27_noticeboard'>test</a>" --form-string "scrub_wikitext=true"