emacs/gnu.emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2026-09-10 07:46:51 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

; Improve url info documentation

Browse source 
* doc/misc/url.texi: Synchronize function signatures with code.  Fix
formatting for variable.  Remove superfluous space.  Link directly to
referenced CL manual node.  (Bug#81505)
This commit is contained in:
Tim Landscheidt 2026-07-27 21:43:17 +00:00 committed by Eli Zaretskii
parent bd5cbf47da
commit 9fbb00331e
1 changed files with 22 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
doc/misc/url.texi
View file

@ -127,11 +127,11 @@ standard-compliant URI parser, as well as function
@code{url-recreate-url}, which converts a parsed URI back into a URI @code{url-recreate-url}, which converts a parsed URI back into a URI
string. string.
@defun url-generic-parse-url uri-string @defun url-generic-parse-url url
This function returns a parsed version of the string @var{uri-string}. This function returns a parsed version of the string @var{url}.
@end defun @end defun
@defun url-recreate-url uri-obj @defun url-recreate-url urlobj
@cindex unparsing URLs @cindex unparsing URLs
Given a parsed URI, this function returns the corresponding URI string. Given a parsed URI, this function returns the corresponding URI string.
@end defun @end defun
@ -140,7 +140,7 @@ Given a parsed URI, this function returns the corresponding URI string.
The return value of @code{url-generic-parse-url}, and the argument The return value of @code{url-generic-parse-url}, and the argument
expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL
structure whose slots hold the various components of the URI@. structure whose slots hold the various components of the URI@.
@xref{Top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for @xref{Structures,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for
details about CL structures. Most of the other functions in the details about CL structures. Most of the other functions in the
@code{url} library act on parsed URIs. @code{url} library act on parsed URIs.
@ -240,9 +240,9 @@ appear in URI components.)
string containing arbitrary characters to one that is properly string containing arbitrary characters to one that is properly
percent-encoded in accordance with RFC 3986. percent-encoded in accordance with RFC 3986.
@defun url-encode-url url-string @defun url-encode-url url
This function return a properly URI-encoded version of This function return a properly URI-encoded version of
@var{url-string}. It also performs @dfn{URI normalization}, @var{url}. It also performs @dfn{URI normalization},
e.g., converting the scheme component to lowercase if it was e.g., converting the scheme component to lowercase if it was
previously uppercase. previously uppercase.
@end defun @end defun
@ -272,8 +272,8 @@ be either a list of allowed chars, or a vector whose Nth element is
non-@code{nil} if character N is allowed. non-@code{nil} if character N is allowed.
@end defun @end defun
@defun url-unhex-string string &optional allow-newlines @defun url-unhex-string str &optional allow-newlines
This function replaces percent-encoding sequences in @var{string} with This function replaces percent-encoding sequences in @var{str} with
their character equivalents, and returns the resulting string. their character equivalents, and returns the resulting string.
If @var{allow-newlines} is non-@code{nil}, it allows the decoding of If @var{allow-newlines} is non-@code{nil}, it allows the decoding of
@ -294,20 +294,20 @@ string or a parsed URL structure. If it is a string, that string is
passed through @code{url-encode-url} before using it, to ensure that passed through @code{url-encode-url} before using it, to ensure that
it is properly URI-encoded (@pxref{URI Encoding}). it is properly URI-encoded (@pxref{URI Encoding}).
@defun url-retrieve-synchronously url &optional silent no-cookies timeout @defun url-retrieve-synchronously url &optional silent inhibit-cookies timeout
This function synchronously retrieves the data specified by @var{url}, This function synchronously retrieves the data specified by @var{url},
and returns a buffer containing the data. The return value is and returns a buffer containing the data. The return value is
@code{nil} if there is no data associated with the URL (as is the case @code{nil} if there is no data associated with the URL (as is the case
for @code{dired}, @code{info}, and @code{mailto} URLs). for @code{dired}, @code{info}, and @code{mailto} URLs).
If the optional argument @var{silent} is non-@code{nil}, progress If the optional argument @var{silent} is non-@code{nil}, progress
messages are suppressed. If the optional argument @var{no-cookies} is messages are suppressed. If the optional argument @var{inhibit-cookies} is
non-@code{nil}, cookies are not stored or sent. If the optional non-@code{nil}, cookies are not stored or sent. If the optional
argument @var{timeout} is non-@code{nil}, it should be a number that argument @var{timeout} is non-@code{nil}, it should be a number that
says (in seconds) how long to wait for a response before giving up. says (in seconds) how long to wait for a response before giving up.
@end defun @end defun
@defun url-retrieve url callback &optional cbargs silent no-cookies @defun url-retrieve url callback &optional cbargs silent inhibit-cookies
This function retrieves @var{url} asynchronously, calling the function This function retrieves @var{url} asynchronously, calling the function
@var{callback} when the object has been completely retrieved. The @var{callback} when the object has been completely retrieved. The
return value is the buffer into which the data will be inserted, or return value is the buffer into which the data will be inserted, or
@ -336,7 +336,7 @@ signaled with @code{(signal @var{error-symbol} @var{data})}.
@cindex status of GnuTLS connection, as provided by @code{url-retrieve} @cindex status of GnuTLS connection, as provided by @code{url-retrieve}
@findex gnutls-peer-status-warning-describe @findex gnutls-peer-status-warning-describe
@findex gnutls-peer-status @findex gnutls-peer-status
@item (:peer @var{gnutls-information}) @item (:peer @var{gnutls-information})
This means that GnuTLS was used for a TLS connection to the peer. The This means that GnuTLS was used for a TLS connection to the peer. The
@var{gnutls-information} has the following form: @var{gnutls-information} has the following form:
@ -362,11 +362,11 @@ containing the retrieved data (if any). The buffer also contains any
MIME headers associated with the data retrieval. MIME headers associated with the data retrieval.
If the optional argument @var{silent} is non-@code{nil}, progress If the optional argument @var{silent} is non-@code{nil}, progress
messages are suppressed. If the optional argument @var{no-cookies} is messages are suppressed. If the optional argument @var{inhibit-cookies} is
non-@code{nil}, cookies are not stored or sent. non-@code{nil}, cookies are not stored or sent.
@end defun @end defun
@defun url-queue-retrieve url callback &optional cbargs silent no-cookies @defun url-queue-retrieve url callback &optional cbargs silent inhibit-cookies
This function acts like @code{url-retrieve}, but with limits on the This function acts like @code{url-retrieve}, but with limits on the
number of concurrently-running network processes. The option number of concurrently-running network processes. The option
@code{url-queue-parallel-processes} controls the number of concurrent @code{url-queue-parallel-processes} controls the number of concurrent
@ -451,10 +451,11 @@ cookies, if there are any. You can remove a cookie using the
@kbd{C-k} (@code{url-cookie-delete}) command. @kbd{C-k} (@code{url-cookie-delete}) command.
@end defun @end defun
@defun url-cookie-delete-cookies &optional regexp @defun url-cookie-delete-cookies &optional regexp keep
This function takes a regular expression as its parameters and deletes This function takes a regular expression as its parameters and deletes
all cookies from that domain. If @var{regexp} is @code{nil}, delete all cookies from that domain. If @var{regexp} is @code{nil}, delete
all cookies. all cookies. If @var{keep} is non-@code{nil}, instead delete all cookies
that do not match @var{regexp}.
@end defun @end defun
@defopt url-cookie-file @defopt url-cookie-file
@ -533,7 +534,7 @@ HTTP supports an @samp{OPTIONS} method describing things supported by
the URL@. the URL@.
@defun url-http-options url @defun url-http-options url
Returns a property list describing options available for URL@. The Returns a property list describing options available for @var{url}. The
property list members are: property list members are:
@table @code @table @code
@ -935,10 +936,10 @@ more likely to conflict with other files.
@end smallexample @end smallexample
@end defun @end defun
@defun url-cache-expired @defun url-cache-expired url &optional expire-time
This function returns non-@code{nil} if a cache entry has expired (or is absent). This function returns non-@code{nil} if a cache entry has expired (or is absent).
The arguments are a URL and optional expiration delay in seconds The arguments are a URL and optional expiration delay in seconds
(default @var{url-cache-expire-time}). (default @code{url-cache-expire-time}).
@end defun @end defun
@defopt url-cache-expire-time @defopt url-cache-expire-time
@ -946,7 +947,7 @@ This variable is the default number of seconds to use for the
expire-time argument of the function @code{url-cache-expired}. expire-time argument of the function @code{url-cache-expired}.
@end defopt @end defopt
@defun url-fetch-from-cache @defun url-fetch-from-cache url
This function takes a URL as its argument and returns a buffer This function takes a URL as its argument and returns a buffer
containing the data cached for that URL. containing the data cached for that URL.
@end defun @end defun
@ -1037,7 +1038,7 @@ others.@footnote{Proxies (which only operate over HTTP) are
implemented using this.} The library's basic function responsible for implemented using this.} The library's basic function responsible for
making connections is @code{url-open-stream}. making connections is @code{url-open-stream}.
@defun url-open-stream name buffer host service @defun url-open-stream name buffer host service &optional gateway-method
@cindex opening a stream @cindex opening a stream
@cindex stream, opening @cindex stream, opening
Open a stream to @var{host}, possibly via a gateway. The other Open a stream to @var{host}, possibly via a gateway. The other