Re: Do you understand this?

[Nic Ferrier]

"Robert J. Chassell" <address@hidden> writes:

> Jason Rumney rightly noted that
>
>     In the Emacs manual, we need to explain how the user configures
>     this in Emacs.  Describing what RFC2616 says is not very useful
>     ...
>
> Good point.  How about putting the explanation in a comment in
>
>     emacs/lisp/url/url-vars.el
>
> just after
>
> (defvar url-mime-accept-string nil
>   "String to send to the server in the Accept: field in HTTP requests.")
>
> ?  Or perhaps in the `Commentary:' section of 
>
>     emacs/lisp/url/url.el
>
> with some other remarks, too.  (I do not know enough to have any idea
> what the `other remarks' should say.)
>
>
> Here is the explanation, slightly changed from before, in a format for
> an Emacs Lisp library.  Please check this wording.  I think it is a
> little clearer than before.
>
>
> ;; An `Accept:' or `Accept-Charset' statement, or a `headers' as it is
> ;; often called, allows you, a client, to specify the priority or
> ;; weighing of the type of statement you would like a server to
> ;; accept.
> ;; 
> ;; In contrast to their precedence in English text, commas separate
> ;; _bigger_ groupings than semi-colons, which are used to prefix
> ;; weightings or priority values.  Priority values go from 0.0 to 1.0,
> ;; with 1.0 being highest.  When a priority or weighting value is not
> ;; listed the value is presumed to be 1.0.  Moreover, an `Accept:' or
> ;; `Accept-Charset' list need not be in priority or precedence order.
> ;; 
> ;; Thus, an accept statement such as
> ;; 
> ;;      Accept: text/plain;
> ;;              q=0.5, text/html, text/x-dvi;
> ;;              q=0.8, text/x-c
> ;; 
> ;; could be reformatted as
> ;; 
> ;;      Accept: text/plain; q=0.5,
> ;;              text/x-dvi; q=0.8,
> ;;              text/html ; q=1.0,
> ;;              text/x-c  ; q=1.0
> ;; 
> ;; This latter expression shows the list in order from lower to higher
> ;; priority.  Both `text/html' and `text/x-c' are of equal (and
> ;; highest) priority.
> ;; 
> ;; When a client sends in an HTTP request for a resource, the above
> ;; `Accept:' statement tells the server that the user prefers either
> ;; an HTML or text/x-c document.  If neither of those reprsentations
> ;; is available, then DVI is next preference.  If none of those three
> ;; are available, then plain text should be sent.  If neither plain
> ;; text, DVI, HTML nor x-c are available, then the server's response
> ;; should indicate that it is failing to find a representation that
> ;; satisfies the request.

I find this confusing. I understand what you are saying about commas
and semi-colons... but I think it is a red herring in terms of better
documentation. You seem to be trying to explain the HTTP rfc in an
elisp comment.

Why can't you just say:

 ;; An `Accept' or `Accept-Charset' header may be specified in the
 ;; form described in rfc2616 section 14.1 and 14.2.
 ;;
 ;; For example
 ;;        Accept: text/plain; q=0.5,
 ;;                  text/html,
 ;;                  text/x-dvi; q=0.8,
 ;;                  text/x-c


Personally, I think it would be better if this was automatic anyway,
as was indicated by the doc string in rms' original post. 

Normally I want Accept-Charset to be sent to an HTTP server based on
an automatically computed list from Emacs' available character sets.

The ability to configure Accept-Charsets specifically would be a rare
requirement and should not be encouraged in elisp programming.



Nic