Re: [dispatch] [rfc-i] Advice when converting W3C ED to I-D

[tom petch <[e-mail]>]

From: rfc-interest <[e-mail]> on behalf of Rahul Gupta <cxres=[e-mail]>
Sent: 11 September 2023 20:11

Hi there,

I am currently in the process of converting a W3C Editors Draft <https://cxres.github.io/per-resource-events/protocol/> (previously shared on Dispatch) into an Internet Draft for submission with IETF.  There are few things which do not translate well, I could not discern from the various documents on how to act and would like to seek the group's advice:

  1.  In W3C Drafts, we explicitly mark sections as non-normative. For example, sections 1 (introduction) and 2 (design) are non-normative in my proposal. What is the best practice to indicate the same in I-D? Alternatively, how best can I rejig the order of sections in my specification to achieve the same effect.

<tp>
RFC produced by the RPC have a style.  It may or may not be a good style but it is >the<  style so that is what is published (regardless of what other SDO think and do). 

RFC7322 is the style guide and there are some updates on the RFC Editor web page.

At a quick look, 'Normative' appears many times but not in any way that would help you.  The convention has been and I believe still is is that the numbered sections are Normative unless there is a statement to the contrary and Appendices are Informative unless there is a statement to the contrary and everything after the Abstract and some boiler plate is either a numbered section or a lettered Appendix (apart from the Authors' Addresses and Contributors).

An Introduction is REQUIRED (RFC7322 section 4) as a numbered section so it is Normative - tough!

The Introduction comes after the Abstract, Status, Copyright and Table of Contents (optional with small documents) and before (almost) everything else 

A section on References is REQUIRED and again is Normative.

Appendices get used for examples, implementation reports.  These days YANG module trees get big and so may be put in an Appendix but still be Normative in which case there should be a statement to that effect at the start of the Appendix.  

There are often sections on oustanding issues, changes made and so on with a note for  the RFC Editor to remove then before publication

If you used one of the tools then you will likely be forced to conform to the RFC style even if you do not think it a good idea!

Opinions on tools vary.

Last week I could view your draft and saw a number of things that needed to be numbered, Normative sections. Now my browser and operating system have been upgraded and I no longer can.  Such is progress on the Internet.

HTH

Tom Petch

  2.  There are specific text boxes in W3C specs available for noting "issues" and "advisement". I am unsure what to use and have currently replaced these with <aside>. Is there a better alternative?
  3.  W3C helpfully provides a Security and Privacy Review Questionnaire which in large parts deals with these two considerations. What is the best practice for writing a security considerations section? Should I submit an I-D on a best effort basis with the understanding that WG will help fix this section with their knowledge?

There is a license issue on which I seek advice:

  1.  Over at W3C Solid Community Group, Tim Berners-Lee has insisted on a license for code snippets in specifications that do not require a notice to be attached when copying them from a specification (https://github.com/solid/process/blob/main/solid-cg-charter.md#license 3rd Bullet Point) to allow free use. Is there any possibility of including such an exception to the Revised BSD License made for an I-D?


I shall be able to share an I-D version of the specification through Github, as soon as some bugs in the tooling (kramdown-rfc) are resolved.

Thanks in advance for any help and advice,

Rahul