[Cbor] cbor-edn-literals should introduce the whole diagnostic notation

Jeffrey Yasskin <jyasskin@google.com> Thu, 22 August 2024 16:00 UTC

Return-Path: <jyasskin@google.com>
X-Original-To: cbor@ietfa.amsl.com
Delivered-To: cbor@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id E56EFC151540 for <cbor@ietfa.amsl.com>; Thu, 22 Aug 2024 09:00:28 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -17.606
X-Spam-Level:
X-Spam-Status: No, score=-17.606 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_MED=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, ENV_AND_HDR_SPF_MATCH=-0.5, HTML_MESSAGE=0.001, RCVD_IN_ZEN_BLOCKED_OPENDNS=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, URIBL_BLOCKED=0.001, URIBL_DBL_BLOCKED_OPENDNS=0.001, URIBL_ZEN_BLOCKED_OPENDNS=0.001, USER_IN_DEF_DKIM_WL=-7.5, USER_IN_DEF_SPF_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=google.com
Received: from mail.ietf.org ([50.223.129.194]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id GTvB5jCrBHK5 for <cbor@ietfa.amsl.com>; Thu, 22 Aug 2024 09:00:24 -0700 (PDT)
Received: from mail-ed1-x533.google.com (mail-ed1-x533.google.com [IPv6:2a00:1450:4864:20::533]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature ECDSA (P-256) server-digest SHA256) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id AC5A1C14F700 for <cbor@ietf.org>; Thu, 22 Aug 2024 09:00:24 -0700 (PDT)
Received: by mail-ed1-x533.google.com with SMTP id 4fb4d7f45d1cf-5bebc830406so17593a12.0 for <cbor@ietf.org>; Thu, 22 Aug 2024 09:00:24 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1724342421; x=1724947221; darn=ietf.org; h=to:subject:message-id:date:from:mime-version:from:to:cc:subject :date:message-id:reply-to; bh=SGMuxjhfmrAJoS5I+c+/JtITSkwXLiawfCgt9Hlfy8c=; b=eeyH5Q16QKwiEC2yam4aYJQOar/CntMPxLVW6eitDCxCLC4LON2riyZnmVQCol0P53 IQAj+A9BK46sFnFng1pYNc1HQ98yNQxEAvFZwSw9D52De5nrV5zKiAjemo2p11mQN4HR C85d55OcHjpxrq4p/zYR1DhVWnjyKIlOLF1ZA3egsm1WqLH/wYRLIYpZD9WMSZVpdeWD 9gYqOmeSekgw9BTvVILVTWEBHQKB2qFq8r7AWqcQ2w4OEiuns++OIZzFqwNWd2jYVUYH MlHpcZ2YPrOtnTN2NIoLqjmqduZY3Z8jhSOC4ZmmU2eaNv/5mi01ITVp68il7zeryRab UlIA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724342421; x=1724947221; h=to:subject:message-id:date:from:mime-version:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=SGMuxjhfmrAJoS5I+c+/JtITSkwXLiawfCgt9Hlfy8c=; b=AIF0wv34CzQL28NeikfwUNuqdu1IwK8j/M3fgVqtIkCfP03G7BknZf4y+rvVK/83MO yu6psubhXgnLm2Ac7EVt7zz+qHUTqZADG5BYC3sHSCNIngT48LMVGUkUmJuSV7cUl8On lZxVmIGTCgRniZSxZFafku6FBvauCAX1lefCmOqI4L7blDhuvcm+Y+I0ocJV3ui7WTLW 4UoDrbu5zWotllXymLfZs5u+vVk/BYSuzcTYTrlHR1n/SgEe3zvxa+BdZpIS7QAe6zkq mvf8enmlB/ZHPKnBmuc0JQ/l4rXEQsGCr7gq8RG8NBsuk8zo0vUAzhYPRbnpO5c3GNX+ jdJg==
X-Gm-Message-State: AOJu0YxJESgPZP5eXjNKkJSBYnvTIbcBFITSVCRnxXDiH8dit28PAjtb H/Akr545MOXyeWEBUQqX7nSWFtW93cNtvD/cOs60+MF8TvhAdIZL4gLCwd2haDPjiw2hsrVPyAd UjvYU8NJrQ6MEbpxn6H9oYEp/Lh00Z4oZeP6rNcyGC3Wq8x4oqjqs
X-Google-Smtp-Source: AGHT+IE7SOEL7dB2ML2qr0IRdeVCwKfhD5OQo5W3makbunIC1DHcyRTj1TeB1ZQBuQDJL0+fkUckM8rZZChs5lYaMpg=
X-Received: by 2002:a05:6402:26cf:b0:5b4:df4a:48bb with SMTP id 4fb4d7f45d1cf-5bf63d33c61mr220057a12.0.1724342420753; Thu, 22 Aug 2024 09:00:20 -0700 (PDT)
MIME-Version: 1.0
From: Jeffrey Yasskin <jyasskin@google.com>
Date: Thu, 22 Aug 2024 09:00:03 -0700
Message-ID: <CANh-dXmO2rF5PohfRtnvYxaC-fQc=zLjmkModLsxiRTivJFZ_A@mail.gmail.com>
To: cbor@ietf.org
Content-Type: multipart/alternative; boundary="000000000000765860062047c10d"
Message-ID-Hash: B3VV2MUZIAYPUNMVQSUYTA75IBOP4M56
X-Message-ID-Hash: B3VV2MUZIAYPUNMVQSUYTA75IBOP4M56
X-MailFrom: jyasskin@google.com
X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-cbor.ietf.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header
X-Mailman-Version: 3.3.9rc4
Precedence: list
Subject: [Cbor] cbor-edn-literals should introduce the whole diagnostic notation
List-Id: "Concise Binary Object Representation (CBOR)" <cbor.ietf.org>
Archived-At: <https://mailarchive.ietf.org/arch/msg/cbor/ZyHTarajxxSPqqqTgDnogC0b0pk>
List-Archive: <https://mailarchive.ietf.org/arch/browse/cbor>
List-Help: <mailto:cbor-request@ietf.org?subject=help>
List-Owner: <mailto:cbor-owner@ietf.org>
List-Post: <mailto:cbor@ietf.org>
List-Subscribe: <mailto:cbor-join@ietf.org>
List-Unsubscribe: <mailto:cbor-leave@ietf.org>

Hi all,

Sorry for not noticing this in time for any of the last calls, but I'm now
trying to coach a team through writing an I-D that will include CBOR
examples, and I've discovered that while this document says "This document
... is intended to serve as a single reference target in specifications
that use EDN.", it's hard for human readers to use in that way.

Specifically, readers have to follow the links to
https://www.rfc-editor.org/rfc/rfc8949#section-8 and
https://www.rfc-editor.org/rfc/rfc8610#appendix-G in order to get the level
of introduction that
https://www.ietf.org/archive/id/draft-ietf-cbor-edn-literals-11.html#name-application-oriented-extens
provides for the new features added in this document. While I haven't found
any actual semantic holes in the ABNF section (although "The following
additional items should help in the interpretation" doesn't inspire
confidence), it's not organized so that I can expect newbies to learn the
diagnostic notation from it.

I hope that y'all can find time to copy the appropriate sections of RFCs
8949 and 8610 into this document so that we can use it as a one-stop
reference for the diagnostic notation.

Thanks,
Jeffrey