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                         
    address@hidden                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc