Re: Best practice for referring to specifications which may update

Henry Thompson writes:

> Comments welcome.

I think this is good for the common case where you >do< want to 
future-proof your references, as in:

"Conformant implementations may follow the edition cited and/or any later 
edition(s). "

I do think it would be a step too far for the TAG to imply or require that 
such language be used in all cases.  I can easily imagine cases in which 
what's desired is to specifically require use of the "edition cited", or 
else to allow only later editions meeting certain criteria.  So:

> When citing a W3C specification in the normative references 
> section of another specification, care should be taken to be 
> clear about the status of editions of the referenced 
> specification other than the then-current one. 

This should be the binding recommendation from the TAG, and perhaps should 
be rephrased using MUST.

> In order to on the one hand acknowledge that
>   implementations sometimes lag behind specifications, and on the
>   other that implementations of new editions of referenced
>   specifications should be encouraged, wording along the following
>   lines should be used:

I might prefer:

--------
"It is often, but not always, good practice to encourage use of new 
editions of referenced specifications.  In that common case, wording along 
the following lines is recommended:

        (this is unchanged from Henry's)
    Left-Handed Sewer Flutes 1.0 (Second edition), P.D.Q. Bach and
    Peter Schickele, Editors.  World Wide Consortium, 29 February
    2009.  The edition cited (http://www.w3.org/TR/2009/REC-lhsf-20090229/
)
    is the earliest appropriate for use with this specification.
    Conformant implementations may follow the edition cited and/or any
    later edition(s).  The latest edition of LHSF 1.0 is available at
    http://www.w3.org/TR/lhsf/.  It is implementation-defined which
    editions of LHSF 1.0 are supported.

Note that this wording also accounts for the fact that implementations 
sometimes lag behind specifications."
--------

Noah

--------------------------------------
Noah Mendelsohn 
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------








ht@inf.ed.ac.uk (Henry S. Thompson)
Sent by: www-tag-request@w3.org
10/28/2009 10:57 AM
 
        To:     www-tag@w3.org
        cc:     "C. M. Sperberg-McQueen" <cmsmcq@blackmesatech.com>, (bcc: 
Noah Mendelsohn/Cambridge/IBM)
        Subject:        Best practice for referring to specifications 
which may update


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

In the context of an extended discussion at the recent TAG f2f
regarding references to potential time-varying specification URIs [1]
I took an action [2] to suggest wording for a Best Practice in this
area, based on wording developed by C. M. Sperberg-McQueen, who also
reviewed and contributed to the following.

Here's what I think this might look like:

  When citing a W3C specification in the normative references section
  of another specification, care should be taken to be clear about the
  status of editions of the referenced specification other than the
  then-current one.  In order to on the one hand acknowledge that
  implementations sometimes lag behind specifications, and on the
  other that implementations of new editions of referenced
  specifications should be encouraged, wording along the following
  lines should be used:

    Left-Handed Sewer Flutes 1.0 (Second edition), P.D.Q. Bach and
    Peter Schickele, Editors.  World Wide Consortium, 29 February
    2009.  The edition cited (http://www.w3.org/TR/2009/REC-lhsf-20090229/
)
    is the earliest appropriate for use with this specification.
    Conformant implementations may follow the edition cited and/or any
    later edition(s).  The latest edition of LHSF 1.0 is available at
    http://www.w3.org/TR/lhsf/.  It is implementation-defined which
    editions of LHSF 1.0 are supported.

  The appropriateness of this approach is based on the W3C rules
  regarding what constitutes an acceptable new edition of an existing
  W3C Recommendation.  For references to publications from other
  standards bodies with similar expectations regarding backwards
  compatibility, for example IETF or ISO, a similar approach to
  citation is also called for, along the following lines:

    The Extension of MIME Content-Types to a New Medium, N. Borenstein
    and M. Linimon.  Internet Engineering Task Force RFC 1437, 1 April
    1993.  RFC 1437 was current at the date of publication of this
    specification, but may be updated or obsoleted by later RFCs.
    Conformant implementations may follow the RFC cited and/or any
    later RFCs which update or obsolete it.  It is
    implementation-defined which RFCs are supported.

    Intelligent transport systems -- Physical characterisation of
    vehicles and equipment -- International airline seat pitch
    measurements. Part 1: Measurement architecture.  International
    Standard ISO 314159-1:2009, 29 February 2009.  The referenced
    specification may from time to time be amended, replaced by a new
    edition, or expanded by the addition of new parts.  See
    http://www.iso.org/iso/home.htm for up-to-date information.
    Conformant implementations may follow the edition cited and/or any
    amendments etc.  It is implementation-defined which amendments
    etc. are supported.

  In cases where many references require similar treatment, a blanket
  statement at the top of the references section may be more
  appropriate:

    Dated references below are to the earliest known or appropriate
    edition of the referenced work.  The referenced works may be
    subject to revision, and conformant implementations may follow,
    and are encouraged to investigate the appropriateness of
    following, some or all more recent editions or replacements of the
    works cited.  It is in each case implementation-defined which
    editions are supported.

   and then simply

    Left-Handed Sewer Flutes 1.0 (Second edition), P.D.Q. Bach and
    Peter Schickele, Editors.  World Wide Consortium, 29 February 2009
    (http://www.w3.org/TR/2009/REC-lhsf-20090229/).  The latest
    edition of LHSF 1.0 is available at http://www.w3.org/TR/lhsf/.

    The Extension of MIME Content-Types to a New Medium, N. Borenstein
    and M. Linimon.  Internet Engineering Task Force RFC 1437, 1 April
    1993.

    Intelligent transport systems -- Physical characterisation of
    vehicles and equipment -- International airline seat pitch
    measurements. Part 1: Measurement architecture.  International
    Standard ISO 314159-1:2009, 29 February 2009.  See
    http://www.iso.org/iso/home.htm for up-to-date information.

  All of the above formulations assume a definition of
  'implementation-dependent' along the following lines:

    If a choice is described as 'implementation-dependent', then
    conformant implementations must document which choice they make.

Comments welcome.

ht

[1] http://www.w3.org/2001/tag/2009/09/23-minutes#item03
[2] http://www.w3.org/2001/tag/group/track/actions/303
- -- 
       Henry S. Thompson, School of Informatics, University of Edinburgh
                         Half-time member of W3C Team
      10 Crichton Street, Edinburgh EH8 9AB, SCOTLAND -- (44) 131 650-4440
                Fax: (44) 131 651-1426, e-mail: ht@inf.ed.ac.uk
                       URL: http://www.ltg.ed.ac.uk/~ht/
[mail really from me _always_ has this .sig -- mail without it is forged 
spam]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.6 (GNU/Linux)

iD8DBQFK6FvskjnJixAXWBoRAkMoAJwLt6r3r+Vv0Bafj7VXG3lTwTUZCQCbBUQt
vLwTcIIeuu0opUPciRUtZ/g=
=TIg8
-----END PGP SIGNATURE-----

Received on Wednesday, 28 October 2009 15:21:21 UTC