Draft text: Feature Negotiation Notation Conventions

We (meaning Andy Mutz and me) have been working among ourselves for
some time on feature tag registration and on the core feature set.
See

http://gewis.win.tue.nl/~koen/conneg/draft-holtman-http-negotiation-03.html#8

for some background. Here is some draft text we have come up with.
Please send comments to the list.

Koen.

---snip---

  Feature Negotiation Notation Conventions
  ========================================

 The four sections below are provided as background for the text on
 the core feature set.

 They probably belong in main document on transparent content
 negotiation.


C.1 Feature tag naming conventions

 Feature tag names are case insensitive HTTP tokens.  They are usually
 written in lowercase letters with underscores as separators.
 Examples are:

    html_dir, html_ol_start, form_mailto.

 As a general rule, a feature tag should be short, but not opaque.  It
 is not necessary that a tag name unambiguously describes the
 indicated feature.  However, a tag name should always provide a rough
 indication of the area of negotiation it applies to, for example by
 starting with a name (html, java, style_sheets) or well-known term
 (tables, color) associated with that area.  When a tag consists of
 multiple parts, a `top level first' notation should be used:

     area_subarea_subsubarea_....

 Thus, feature tags associated with some lesser-known markup tag T in
 some markup language L should be named `L_T' or `L_T_something'.  If
 the feature tag refers to a specific attribute A of the markup tag T,
 it should be named `L_T_A' or `L_T_A_something'.  An example of the
 latter case is `html_img_usemap_external'


C.2 Short feature tag descriptions

 In the text on the core feature set, feature tags are described using
 the following short description format:

   <tag declaration>

     <some text describing the tag>

 The `tag declaration' part gives the tag name, and specifies the
 intended use of the tag:

   Form of declaration:            Intended use of tag:
   ==============================  ===========================
    tag_name                        without a value

    tag_name=value_description      with zero or more values

    tag_name={value_description}    with a single value

    tag_name<=value_description     with a numeric range


C.3 Conventions for tag values

 All values associated with feature tags must be HTTP tokens.  For
 some areas of negotiation, the `canonical' representations of the
 associated values could contain ASCII characters not allowed in HTTP
 tokens.  An example is the URL value `http://x.com', or the MIME type
 value `text/html'. 

 This section defines two conventions for dealing with such
 situations.

C.3.1 Escaped tag values

 If a value_description in a tag declaration ends with `_escaped', for
 example

    blah=url_escaped

 this indicates that the tag values may contain URL-style escape
 sequences of the form

    % HEX HEX

 which must be converted back to ASCII to get the `canonical'
 representation of the tag value.  Example:

   Accept-Features: blah=http:%2f%2fx.com

C.3.2 Tokenized tag values

 A string of characters is `tokenized' by replacing all characters not
 legal in a HTTP token with an underscore.  For example, `text/html'
 is `text_html' after tokenization.

 If a value_description in a tag declaration ends with `_tokenized',
 for example

   form_enctype=mime-type_tokenized

 this indicates that the tag values are tokenized versions of the
 `canonical' values associated with the tag value datatype.  Example:

   Accept-Features: form_enctype=application_x-form-base64-encoded

--snip--

Received on Thursday, 3 October 1996 05:17:11 UTC