Re: How best to indicate a Registry section in a Rec track document?

I don't have strong opinions here, but some thoughts:

   - https://github.com/w3c/tr-design/issues/283 asked for some sample
   registry tables in tr-design. The fact that you've added CSS to support
   your registry is, I think, an indication that tr-design should have an
   opinion on what these sections look like.
   - I think I agree that a REC's SotD should mention any included
   registries, since they're parts of the document that haven't been endorsed
   by the AC, that can be republished without the WG's involvement, that aren't
   covered by the patent policy
   <https://www.w3.org/2023/Process-20231103/#reg-pub>, etc. Probably
any Patent
   Review Drafts
   <https://www.w3.org/2023/Process-20231103/#patent-review-drafts> should
   also mention the registries, because of the difference in patent policy.
   I'm less sure that any earlier stages need to call out the registries,
   since I don't think they'd get updated with any weaker change control than
   the rest of the document ... but it might still be a good idea to
   foreshadow the later stages' section about them.
   - In the SotD, I think it'd be ideal to link to the particular
   registries inside the document. That implies that the spec's metadata
   should list registry IDs for the SotD to include ... which is a decent hook
   to trigger the inclusion of the registry boilerplate.
   - The Process's discussion of "a registry section"
   <https://www.w3.org/2023/Process-20231103/#reg-pub> is in a sentence
   with a plural subject and a singular indirect object, so it's not clear
   whether the whole document gets one registry section or each registry gets
   its own section. But you're suggesting putting an individual registry into
   two different parts of the document, which doesn't follow either
   interpretation. :) But then, the "registry"
   <https://www.w3.org/2023/Process-20231103/#registries> is defined as
   having 3 components: the definition, the tables, and the referencing
   specifications, and clearly the referencing specifications aren't going to
   be inside the registry section. Also, the Process says "A ... registry
   section is purely documentational" but also "Defining a registry requires
   wide review and consensus", which isn't really compatible with the registry
   definition going into the registry section. So I think there's a Process
   bug here, and we should figure out the right thing to do and make the
   Process match that, rather than trying to conform exactly to the existing
   Process.
   - I'm nervous about putting the registry tables next to the part of the
   spec that calls them, because the change control is so different. Your
   "registry section" box could work as a way to identify that difference, and
   I agree that it makes the spec easier to use. Maybe we should have Respec
   and Bikeshed automatically include particular boilerplate next to registry
   tables that also calls out the difference in change control and links to
   the associated registry definition?
      - The tables and their definitions should cross-link to each other.
   - I think <figure> might be the right markup to surround registry tables?
   - I wouldn't put the registry section in an appendix, and I'd title it
   something like "Registry Definitions" rather than "Registry Section". This
   should roughly imitate the ways the IETF uses "IANA Considerations"
   sections to define their registries.
   https://www.rfc-editor.org/rfc/rfc8615.html#section-5 has a simple one.
   - You have a "registry tables" section
   <https://pr-preview.s3.amazonaws.com/w3c/dapt/pull/196.html#registry-table>,
   but I think the things inside it are parts of the registry definition
   rather than the registry tables.

HTH,
Jeffrey

On Mon, Nov 6, 2023 at 2:38 AM Nigel Megitt <nigel.megitt@bbc.co.uk> wrote:

> Has there been any work on specific text or formatting for indicating
> sections of Rec track documents that are Registry Sections, as per
> https://www.w3.org/2023/Process-20231103/#reg-pub ? Not sure if this is a
> question for the ProcessCG, but it feels like an editing question initially.
>
>
>
> In particular, things that occurred to me while preparing
> https://github.com/w3c/dapt/pull/196 :
>
>
>
>    - It seems like a good idea to mention in the SOTD that the document
>    contains a Registry Section – I wrote my own additional text, but maybe it
>    would be better to have common wording, and an additional value in Respec’s
>    config specStatus value to support the conditional inclusion of that
>    wording.
>
>
>
>    - The Process wording seems to allow for a single Registry Section,
>    but structurally, it would be better to put the Registry Tables inline in
>    the document in the place where they appear. I’m going to assume that it’s
>    okay to do that, but when doing so, it would be a service to the reader if
>    there were some indication that the table is subject to change outside the
>    normal Rec track update process. Hence this email!
>
>
>
>    - (maybe a Respec question) Sometimes it’s helpful to insert into the
>    document values that derive from the Respec config, but it isn’t
>    straightforward to do that. I created a clunky post-processing function for
>    Respec to replace values in elements with specific class names, but it’s
>    ugly. In this case I wanted to put in to the Registry Definition that the
>    mechanism for asking for a change is to raise an issue on the version
>    control system (aka repository), and link to it. The URL for the GitHub
>    repo is information that Respec knows, so I wanted to insert that as a
>    value into href attributes wherever they appeared.
>
>
>
> Any suggestions appreciated!
>
>
>
> Nigel
>
>
>
>
>