Re: [Tools-discuss] I-Ds, submission, and preferred formats

[Jay Daley <[e-mail]>]

Hi John

Thank you for the detailed review - some responses below.

> On 25 May 2022, at 01:13, John C Klensin <[e-mail]> wrote:
> 
> Hi.
> 
> I hope this is the right place to make these comments.  If it is
> not (and maybe it it is), see (1) below.
> 
> I had occasion to look at the relatively new authors' [1] and
> submission [2] pages today.  Nice looking, good explanations,
> and good work.  I do have some suggestions -- three minor (I
> hope small patches) and one more substantive.
> 
> (1) Minor: Traditionally, a contact address for suggestions and
> bug reports has been included on every datatracker and other
> tools page.

While that may be your impression, I struggle to see evidence of such ubiquitous coverage on the tools site.  For example, the following page was important source material for this new site https://xml2rfc.tools.ietf.org/xml2rfc-doc.html and that doesn’t have such a contact.

>  It is not on either of these and there is no
> obvious way to get that information.  Unless there is a reason
> for leaving it out that is not obvious to me, I suggest figuring
> out a way to restore it.

Adding this is a good idea - it probably warrants its own page so that it is quick and simple to find.  I am happy to provide text.  Adding it to the footer of each page is impractical given the feature set of the wiki tool.

> 
> (2) Also minor:  I would have expected to find a subsection on
> the authors' page [1] titled something like "Submitting Your
> Internet Draft" even if all the test says is "When you are ready
> to have your draft posted, <Submitting your Internet-Draft> [2]".

There was much community discussion on this list on the best way to lead people through the stages and it was agreed to have a 'Getting Started" page that set out the steps and with links to the detail behind them.  That is at https://authors.ietf.org/en/getting-started

> 
> (3) Another issue/nit: These documents have apparently renamed
> "xml2rfc" to "RFCXML" even though the relevant RFCs (and even
> the I-D with the proposed new vocabulary [3]) still use the
> original terminology.  The only use of "RFCXML" I can find in
> the datatracker is draft-rfcxml-general-the-new-webiquette [4].
> It does not use the term in its actual title or in the body of
> the document.  It also violates the naming rules for I-Ds.  
> 
> It is also not clear from the many contexts in which the new
> term is used whether it is intended to be a synonym for the
> "xml2rfc" vocabulary/format, in which case it should appear
> fairly consistently with a version number unless that is
> irrelevant or if it refers to version 3, at least unless a
> version number is given, which appears be the case in some
> contexts.
> 
> I can think of good reasons for the new terminology, especially
> if you are trying to distinguish between the conversion
> procedure and the format.  If it is going to be used, please
> define it precisely and then use it consistently.    However,
> changes from long-standing and well-established terms to new
> ones inevitably creates confusion and, in today's world where
> someone might use xml2rfc as a search term and, sooner or later,
> won't find relevant pages with it, I think some sort of
> discussion with the community about the change and tradeoffs
> would be in order.  Or, if you and others disagree, at least say
> a bit more than 'RFCXML was previously known as the "xml2rfc
> vocabulary".' in the body of the "RFCXML overview and
> background"' page [5].

This has also been discussed extensively on this list.  The underlying issue was the confusion between the tool and the language because they both shared the same name.  This has led to both issues of understanding and issues of design.  An example of the former has been the limited use of local schema validation, which has also now been addressed through the production of templates that automatically support that functionality, where it exists.  An example of the latter, which is also now largely tidied up, is the use of XML processing instructions, which are unique to xml2rfc.  

> 
> (4) There is an increasing push to submit "RFCXML I-Ds" or
> "RFCXML" (even that terminology is not completely consistent).
> The "Submitting..." page [2] uses some fairly strong language
> like "If an RFCXML submission is not possible..." and "submit
> RFCXML if at all possible,...".   There is a problem with that
> recommendation and at least some document authors who are
> developing directly in that format (I don't have any idea how
> many of us are left).

There is nothing new here.  This is taken straight from the ancestor I-D Guidelines as written by various community members and agreed by the IESG: https://github.com/ietf/id-guidelines#the-submission-process

>  When a document, especially a WG one,
> goes through many iterations, author comments are an invaluable
> and, at least for me, nearly essential tool for tracking
> changes, including making notes on when they were introduced and
> why, and even potential changes.  Those comments are written for
> authors as notes to themselves and maybe to other authors.  They
> are not suitable for public availability, especially if they
> include evaluations of particular ideas or critical comments
> about the relationships among various suggestions.  And some of
> the comments are just confusing.   To take a handy example, the
> working source version of draft-ietf-emailcore-rfc5321bis
> contains enough information to allow me to identify the source
> and reasons for most potentially controversial text going back
> to before RFC 2821 was finalized.   
> 
> As the RPC might remember, I started removing all of those
> comments either before the document went over the wall to them
> or late in the AUTH48 process, but that means I have to maintain
> a private working copy and retrofit AUTH48 changes into it to
> preserve information between RFC-published versions.  In theory,
> I could do the same thing before submitting each version  --
> using an emacs/epsilon macro or private extension to remove all
> of the comments -- is not that big a deal, but it is extra work.
> But, unless you want to have a serious conversation about
> additional tools, I'm going to interpret posting the XML form as
> "not possible" and you keep getting plain text.  Maybe that is
> ok, but I want to be sure that the "post XML" near-requirement
> can be bar to effective and efficient document development and
> evolution.

I want to make sure that I understand this correctly - you are saying that you have an RFCXML draft that contains comments and you do not want those comments included when that draft is submitted and so you find it easier to run a conversion to Plain Text and submit that than to run a conversion that outputs the RFCXML without comments?  (Presumably, because the former is a well established workflow and the latter is not?).

As I understand it, and emacs is by no means by strong point, there is a standard "xml-remove-comments" macro, but if that’s too long winded then how about a tick box on the submission form that says "Remove XML comments" or a new function on the Author Tools site that strips comments?

cheers
Jay
> 
> thanks,
>   john
> 
> 
> 
> 
> [1] https://authors.ietf.org/
> [2] https://authors.ietf.org/en/submitting-your-internet-draft
> [3] https://datatracker.ietf.org/doc/draft-iab-rfc7991bis/
> [4]
> https://datatracker.ietf.org/doc/draft-rfcxml-general-the-new-webiquette/
> [5] https://authors.ietf.org/en/rfcxml-overview
> 
> ___________________________________________________________
> Tools-discuss mailing list - [e-mail]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [e-mail]
> * Report tools.ietf.org bugs to: [e-mail]
> * Report all other bugs or issues to: [e-mail]
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss
> 

-- 
Jay Daley
IETF Executive Director
[e-mail]