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

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

MIME-Version: 1.0
Sender: barryleiba@gmail.com
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
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
Precedence: list

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

Re: [jose] AppsDir reviews of draft-ietf-jose-jso… Mike Jones
Re: [jose] AppsDir reviews of draft-ietf-jose-jso… Barry Leiba
Re: [jose] [apps-discuss] AppsDir reviews of draf… Mike Jones