Do you understand this?

Do you understand this?

[Richard Stallman]

Here's some text in man/url.texi that I don't understand.

    HTTP allows specifying a list of MIME charsets which indicate your
    preferred character set encodings, e.g.@: Latin-9 or Big5, and these
    can be weighted.  This list is generated automatically from the list
    of defined coding systems which have associated MIME types.  These are
    sorted by coding priority.

I am not sure what "these can be weighted" means, or what is
generated from what.  Can someone please clarify this?

Re: Do you understand this?

[Nic Ferrier]

Richard Stallman <rms@gnu.org> writes:

> Here's some text in man/url.texi that I don't understand.
>
>     HTTP allows specifying a list of MIME charsets which indicate your
>     preferred character set encodings, e.g.@: Latin-9 or Big5, and these
>     can be weighted.  This list is generated automatically from the list
>     of defined coding systems which have associated MIME types.  These are
>     sorted by coding priority.
>
> I am not sure what "these can be weighted" means, or what is
> generated from what.  Can someone please clarify this?

I don't know the specific code but I know about HTTP so here's an
explanation from that bias.


An HTTP request can specify the MIME types / charsets that are
accepted by the client. User agents can make the specification with
floating point values.

An example, from the HTTP spec (rfc2616) is:

       Accept: text/plain; q=0.5, text/html,
               text/x-dvi; q=0.8, text/x-c

If sent in an HTTP request for a resource /fred the above Accept
headers tells the server that the user will ideally accept /fred as an
HTML document or a text/x-c document. If those reprsentations are not
available then dvi is next preference. If none of those are available
then  plain text should be sent. If plain text is not acceptable then
the response would indicate a failure to find a representation that
satisfied the user's specifications.

This applies equally to charsets as well as type representations like
text/html and text/plain. You could, for exakple say this:

       Accept: text/html; charset=utf-8; q=0.5, 
               text/html; charset=iso-8859-1; q=0.3,


So when Emacs makes an HTTP request it should state the character sets
that Emacs could use to display a response in a buffer.

So the Accept header is generated automatically from the list of
available encodings.



Nic

Re: Do you understand this?

[Robert J. Chassell]

           Accept: text/plain; 
                   q=0.5, text/html, text/x-dvi; 
                   q=0.8, text/x-c

    If sent in an HTTP request for a resource /fred the above Accept
    headers tells the server that the user will ideally accept /fred as an
    HTML document or a text/x-c document. 

I do not understand.

Am I right in formatting the statement such that semi-colons have a
higher precedence than commas?

And that a grouping is between semi-colons?

If that is the case, then the above sequency looks to me to favor

  * text/x-c                as the highest priority;

  * text/html, text/x-dvi   both equally as the second priorty; and, 

  * text/plain              as the third, lowest priority.

But I do not know anything about this and would like to be told more.

An alternative formatting is that semi-colons precede q settings, and
that if a format lacks a q setting, it has the highest priority.

Thus, the above could be formatted like this

       Accept: text/plain; q=0.5, 
               text/html, text/x-dvi; q=0.8, 
               text/x-c

and mean the same as

       Accept: text/plain           ; q=0.5, 
               text/html, text/x-dvi; q=0.8, 
               text/x-c             ; q=1.0

Is this the case?

Thank you.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Do you understand this?

[Andreas Schwab]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>            Accept: text/plain; 
>                    q=0.5, text/html, text/x-dvi; 
>                    q=0.8, text/x-c
>
>     If sent in an HTTP request for a resource /fred the above Accept
>     headers tells the server that the user will ideally accept /fred as an
>     HTML document or a text/x-c document. 
>
> I do not understand.
>
> Am I right in formatting the statement such that semi-colons have a
> higher precedence than commas?

The header's value is a comma separated list of elements, where each one
can contain parameters separated by semicolons.  The "q" parameter
defaults to 1 if absent.

       Accept         = "Accept" ":"
                        #( media-range [ accept-params ] )

       media-range    = ( "*/*"
                        | ( type "/" "*" )
                        | ( type "/" subtype )
                        ) *( ";" parameter )
       accept-params  = ";" "q" "=" qvalue *( accept-extension )
       accept-extension = ";" token [ "=" ( token | quoted-string ) ]

> Thus, the above could be formatted like this
>
>        Accept: text/plain; q=0.5, 
>                text/html, text/x-dvi; q=0.8, 
>                text/x-c
>
> and mean the same as
>
>        Accept: text/plain           ; q=0.5, 
>                text/html, text/x-dvi; q=0.8, 
>                text/x-c             ; q=1.0
>
> Is this the case?

Close.

       Accept: text/plain; q=0.5, 
               text/html ; q=1,
               text/x-dvi; q=0.8, 
               text/x-c  ; q=1

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Do you understand this?

[Jason Rumney]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>            Accept: text/plain; 
>                    q=0.5, text/html, text/x-dvi; 
>                    q=0.8, text/x-c
>
>     If sent in an HTTP request for a resource /fred the above Accept
>     headers tells the server that the user will ideally accept /fred as an
>     HTML document or a text/x-c document. 
>
> I do not understand.
>
> Am I right in formatting the statement such that semi-colons have a
> higher precedence than commas?

Somewhat unintuitively in HTTP headers their precedence is reversed
from what you might expect in English text. Commas seperate header
values and are shorthand for multiple headers, so the above could be
rewritten more clearly as:

Accept: text/plain; q=0.5
Accept: text/html
Accept: text/x-dvi; q=0.8
Accept: text/x-c

Also q defaults to 1.0 if not explicitly stated, so text/x-c and
text/html have highest priority.

> An alternative formatting is that semi-colons precede q settings, and
> that if a format lacks a q setting, it has the highest priority.

Basically right, but your reformatting suggests that you may be
thinking that text/html inherits the q=0.8, which is not correct.

>
> Thus, the above could be formatted like this
>
>        Accept: text/plain; q=0.5, 
>                text/html, text/x-dvi; q=0.8, 
>                text/x-c

There is also an Accept-Charset header with the same rules, which fits
the original manual description slightly better.

Re: Do you understand this?

[Robert J. Chassell]

Thanks to Andreas, Jason, and Nic I think I now understand the rfc2616
HTTP specification a great deal better than before.

Perhaps we should add the following to

    emacs/man/url.texi

after the text saying:

    @node HTTP language/coding
    @subsection Language and Encoding Preferences

    HTTP allows clients to express preferences for the language and
    encoding of documents which servers may honour.

Is this now an accurate description?


An @samp{Accept:} or @samp{Accept-Charset} statement or @samp{headers}
allows you to specify the priority or weighing of the type of
statement you would like to accept.

In contrast to their precedence in English text, commas separate
@emph{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 @samp{Accept:}
or @samp{Accept-Charset} list need not be in priority or precedence
order.

@need 800
@noindent
Thus, an accept statement such as

@smallexample
Accept: text/plain;
        q=0.5, text/html, text/x-dvi;
        q=0.8, text/x-c
@end smallexample

@need 1000
@noindent
could be reformatted as

@smallexample
Accept: text/plain; q=0.5,
        text/x-dvi; q=0.8,
        text/html ; q=1.0,
        text/x-c  ; q=1.0
@end smallexample

@noindent 
This latter expression shows the list in order from lower to higher
priority.  Both @samp{text/html} and @samp{text/x-c} are of equal
(and highest) priority.

When sent in an HTTP request for a resource, the above @samp{Accept:}
statement tells the server that the user prefers to 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.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Do you understand this?

[Jason Rumney]

Robert J. Chassell wrote:

>Thanks to Andreas, Jason, and Nic I think I now understand the rfc2616
>HTTP specification a great deal better than before.
>
>Perhaps we should add the following to
>
>    emacs/man/url.texi
>
>after the text saying:
>
>    @node HTTP language/coding
>    @subsection Language and Encoding Preferences
>
>    HTTP allows clients to express preferences for the language and
>    encoding of documents which servers may honour.
>
>Is this now an accurate description?
>  
>
Yes.

>An @samp{Accept:} or @samp{Accept-Charset} statement or @samp{headers}
>allows you to specify the priority or weighing of the type of
>statement you would like to accept.
>
>  
>
In the Emacs manual, we need to explain how the user configures this in 
Emacs. Describing what RFC2616 says is not very useful if url provides a 
higher level interface for configuring language preferences. If the 
Emacs interface is simply providing a list of HTTP request headers, then 
we need to say that, or the user will think that these two headers are 
the only two they can configure.

Re: Do you understand this?

[Robert J. Chassell]

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.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Do you understand this?

[Nic Ferrier]

"Robert J. Chassell" <bob@rattlesnake.com> 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

Re: Do you understand this?

[Robert J. Chassell]

Regarding HTTP/1.1 Accept: and Accept-Charset: statements, Nic Ferrier
wrote

   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.

At the very least, some comment in the Emacs Lisp sources should tell
people that

    ;; In contrast to their precedence in English text, commas
    ;; separate _bigger_ groupings than semi-colons, which are used to
    ;; prefix weightings or priority values.

Sections 14.1 and 14.2 of rfc2616 only list semi-colons in the BNF.
The reverse English language convention is so strong that the protocol
specification ought to be mentioned in another part of the RFC; and
since it is not, in an Emacs comment.

While we are mentioning the precedence convention, we might as well
add the rest:

    ;; 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.

You ask

   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.

That is fine, in addition to the segment above.

In addition it is worth stating that

    ;;      Accept: text/plain; q=0.5,
    ;;              text/html,
    ;;              text/x-dvi; q=0.8,
    ;;              text/x-c

can 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 will make understanding easier for the person who comes on all
this in 10 or 20 years.

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

Yes -- that is a good reason to put comments in the relevant source.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Do you understand this?

[Richard Stallman]

I installed some text that I hope explains this better.

Re: Do you understand this?

[Nic Ferrier]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>            Accept: text/plain; 
>                    q=0.5, text/html, text/x-dvi; 
>                    q=0.8, text/x-c
>
>     If sent in an HTTP request for a resource /fred the above Accept
>     headers tells the server that the user will ideally accept /fred as an
>     HTML document or a text/x-c document. 
>
> I do not understand.
>
> Am I right in formatting the statement such that semi-colons have a
> higher precedence than commas?

Yes. A media-type is a major-type / minor-type plus an optional list
of parameters which are separated from themselves and the major/minor
type info by semi-colons, eg:

   text/plain; charset=utf-8; otherparam=xxx; q=0.5



> If that is the case, then the above sequency looks to me to favor
>
>   * text/x-c                as the highest priority;
>
>   * text/html, text/x-dvi   both equally as the second priorty; and, 
>
>   * text/plain              as the third, lowest priority.

No quality specifier indicates priority 1.0 (the highest).


> But I do not know anything about this and would like to be told more.
>
> An alternative formatting is that semi-colons precede q settings, and
> that if a format lacks a q setting, it has the highest priority.
>
> Thus, the above could be formatted like this
>
>        Accept: text/plain; q=0.5, 
>                text/html, text/x-dvi; q=0.8, 
>                text/x-c

My original was cut straight out of rfc2616 and is formatted badly (I
think to empahsise the syntax over any arbritary textual ordering).

A more sensible textual rendering would look like this:

        Accept: text/plain; q=0.5, 
                text/html; q=1.0, 
                text/x-dvi; q=0.8, 
                text/x-c; q=1.0

Hope that's clearer.