Re: [jose] AppsDir reviews of draft-ietf-jose-json-web-signature-32

Barry Leiba <barryleiba@computer.org> Wed, 15 October 2014 12:54 UTC

Return-Path: <barryleiba@gmail.com>
X-Original-To: jose@ietfa.amsl.com
Delivered-To: jose@ietfa.amsl.com
Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 6E8E31A6F5D; Wed, 15 Oct 2014 05:54:35 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.278
X-Spam-Level:
X-Spam-Status: No, score=-1.278 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FM_FORGED_GMAIL=0.622, FREEMAIL_FROM=0.001, SPF_PASS=-0.001] autolearn=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id cXJqHQHKVSyO; Wed, 15 Oct 2014 05:54:34 -0700 (PDT)
Received: from mail-la0-x22b.google.com (mail-la0-x22b.google.com [IPv6:2a00:1450:4010:c03::22b]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 798BD1A6F61; Wed, 15 Oct 2014 05:54:33 -0700 (PDT)
Received: by mail-la0-f43.google.com with SMTP id mc6so995990lab.2 for <multiple recipients>; Wed, 15 Oct 2014 05:54:31 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:sender:in-reply-to:references:date:message-id:subject :from:to:cc:content-type; bh=tCJ/D4waFMxDT9g9GPMx6ofwUV4/IsQAHUjLtSttQNk=; b=x4IKGcQor296VXbtsM1i39nS3h6ClAAjhP9HM4QIXCHNj2od+uJU/a2pa78sWaZMwG 3A+6pPQCaoM3b2Thiw2ctAdPLCuwV3mvtwENzfrh4ACnEvCqXwsqNNqDWmxe/CTIynkM F44JkiDN8mMUj1OIzLYv71wFAXJ9NvU6b7VrMF22UHxj8UOS9/FXnNKkIQAlX2jWC5jB p8S9tpffsog9D9eupwYU8+DzjQY7/q1Tb7OW7wigQrussAcAJT/+uDk6SGosrVkrjiMb 20mVertnvgqzc5tTUDCEQU0jCvV5HHIstxz7Dt1HfRepihQF9kaM8SK+g4ON7hwLymMB co+A==
MIME-Version: 1.0
X-Received: by 10.112.146.5 with SMTP id sy5mr2622083lbb.97.1413377671580; Wed, 15 Oct 2014 05:54:31 -0700 (PDT)
Sender: barryleiba@gmail.com
Received: by 10.152.8.103 with HTTP; Wed, 15 Oct 2014 05:54:31 -0700 (PDT)
In-Reply-To: <4E1F6AAD24975D4BA5B16804296739439BB0F8CD@TK5EX14MBXC286.redmond.corp.microsoft.com>
References: <alpine.OSX.2.02.1410020829170.34905@synx02.dir.garr.it> <4E1F6AAD24975D4BA5B16804296739439BB0F8CD@TK5EX14MBXC286.redmond.corp.microsoft.com>
Date: Wed, 15 Oct 2014 08:54:31 -0400
X-Google-Sender-Auth: Nh607jtMVQFvVN_1j64UvxIl7nU
Message-ID: <CALaySJKTevU0MhVDU0fOVm-K4qDFK4n7uo=PPQwOxyg8SBamew@mail.gmail.com>
From: Barry Leiba <barryleiba@computer.org>
To: Mike Jones <Michael.Jones@microsoft.com>
Content-Type: text/plain; charset=ISO-8859-1
Archived-At: http://mailarchive.ietf.org/arch/msg/jose/d0iItLFzUlYU9iL5-UZ51pOyr0Y
Cc: "apps-discuss@ietf.org" <apps-discuss@ietf.org>, Claudio Allocchio <Claudio.Allocchio@garr.it>, Ray Polk <ray.polk@oracle.com>, "iesg@ietf.org" <iesg@ietf.org>, "jose@ietf.org" <jose@ietf.org>, "draft-ietf-jose-json-web-signature.all@tools.ietf.org" <draft-ietf-jose-json-web-signature.all@tools.ietf.org>
Subject: Re: [jose] AppsDir reviews of draft-ietf-jose-json-web-signature-32
X-BeenThere: jose@ietf.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: Javascript Object Signing and Encryption <jose.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/jose>, <mailto:jose-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/jose/>
List-Post: <mailto:jose@ietf.org>
List-Help: <mailto:jose-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/jose>, <mailto:jose-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 15 Oct 2014 12:54:35 -0000

>> 4.1.1. & 4.1.2. The links to Section 4.1 and Section 5.1 of JWA are incorrect.
>> They link to JWE instead of JWA.
>>
>> In 4.1.1. the link is:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-4.1
>> ...but it should be:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-4.1
>>
>> In 4.1.2. the link is:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-32#section-5.1
>> ...but it should be:
>> https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-33#section-5
>> (JWA doesn't seem to have an anchor for 5.1)
>
> These link URLs are actually created by the IETF tools - not in the
> draft itself.  (You'll see "Html markup produced by rfcmarkup 1.109,
> available from https://tools.ietf.org/tools/rfcmarkup/" at the bottom
> of the drafts.)  I'm not sure who to file a bug on this with.

Ray is looking at the HTML generated by tools.ietf.org, which creates
the HTML by analyzing the text, not by looking at the markup.  When
the section name is separated from the reference, it can't figure it
out, and assumes that the section reference is to the current
document.  So, in JWE, for example, this:

   the initial contents of this registry are the values defined
   in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification.

...doesn't work, and makes "Section 4.1" link to Section 4.1 of the
current document, JWE, and then gives a link to the top of JWA at
"[JWA]".

You can make it work as desired by doing this:

OLD
   the initial contents of this registry are the values defined
   in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification.
NEW
   the initial contents of this registry are the values defined
   in the JSON Web Algorithms specification (JWA) [JWA], Section 4.1.
END

That will cause "[JWA], Section 4.1" to link as you'd expect.

(I also suggest that you don't need "(JWA) [JWA]" and can just use
"[JWA]" there, but perhaps that is an artifact of your markup tool.)

There are many places where this is an issue -- it's a tools issue,
not a document issue.  If you're willing to "fix" this in the
documents, please go through and try to find all the places where that
sentence structure is used.

Barry