bug#25735: 26.0.50; url-retrieve errors are peculiar

[Richard Copley]

Within the docstring for url-retrieve, it says: "[...] The
error can be signaled with (signal ERROR-SYMBOL DATA) [...]",
but in current master (grep for ":error" in "lisp/url/*.el") the actual
usage is that ERROR-SYMBOL is `error' and DATA is a list that starts
with a symbol, for example (connection-failed "failed with code 10061"
:host "localhost" :service 80). The docstring hints at something
like this:

  (url-retrieve (format "http://localhost/non-existent-resource";)
                (lambda (status &rest args)
                  (let ((error-info (plist-get status :error)))
                    (when error-info
                      (signal (car error-info) (cdr error-info))))
                  ;;...
                  ))

which ends up calling this:

  (signal 'error
          '(connection-failed "failed with code 10061"
            :host "localhost"
            :service 80))

which ends up printing these two lines (including the newline
embedded in a string) to the echo area:

error in process sentinel: peculiar error: "failed with code 10061
", :host, "localhost", :service, 80

Unfortunately the error code itself, `connection-failed', is dropped.
(See print_error_message in "print.c"; if ERROR-SYMBOL is `error' then
the car of DATA, say ERRMSG, is printed if it is a string; if ERRMSG
is not a string then "peculiar error" is printed instead of ERRMSG.)

Please also consider augmenting the docstring with an example of using
the error data. It's a drag for the user to have to work that out
before they are in a position to call url-retrieve!

(There's a tiny example above, but of course it assumes
that DATA has been changed to conform to the docstring.)