Re: [Tools-discuss] Why post text and not XML? (was: I-D statistics)

[John C Klensin <[e-mail]>]

--On Sunday, March 17, 2024 10:13 +1000 Jay Daley
<[e-mail]> wrote:

>> On 17 Mar 2024, at 07:33, Carsten Bormann <[e-mail]>
>> wrote:
>> 
>> Toerless,
>> 
>> we do have crefs in RFCXML for exactly this purpose: editors'
>> comments, properly highlighted as such (and switchable with
>> comments=no, although the anti-PI crusade may have made this
>> harder in RFCXMLv3; I haven't tried this in RFCXMLv3 yet).
> 
> The <cref> construct is a heavyweight solution and heavyweight
> constructs are often not used.

I agree.  I also somewhat disagree with what I understand to be
Carsten's characterization of editor's comments.  If nothing
else (and as I sort of said earlier in passing) there are
multiple types of editor's comments.  Some are just notes by the
editor to the editor.  When there are multiple editors, they may
be comments to keep each other informed about what is being
done.  One set of comments I didn't mention in my response to
Brian is that, if there are disagreements within a WG about how
a particular issue should be handled, I will often include
comments with pointers to discussion threads or even text of
multiple suggested changes in comments so I can make the shift
quickly if and when the discussion converges on one of them or a
small variation on it.   When it seems useful to include those
pointers in a document, I will try to push them all into a CREF
(an element that, btw, is not particularly well-designed for
that purpose... and yes, there are outstanding tickets are
earlier discussions on this list).  But, more often than not,
keeping them as notes to the editorial team in comments seems
more appropriate.

And then there is the stuff that clearly belongs in <CREF>s,
e.g., issues that an editor wants to call to the attention of
the WG and promote discussion for some reason including known
loose ends.

> I am strongly against PIs because they can only be actioned by
> a custom written tool and will be ignored by all standard XML
> tools.  In this specific case I also consider a PI as the
> wrong solution because it means changing the content of the
> document to choose a specific output format.

I'm not completely sure I understand parts of the issue, but
agree in general with being cautious about the use of PIs unless
they are clearly needed.

> If people want to remove comments (real XML comments or a
> specific element) then that's best left as an operation they
> invoke in their preferred tool.  (If there are well used tools
> that don't do this then we can write some custom XSLT that
> people can run that will remove comments.)

The problem discussed in my response to Brian was not "removing
comments" but "removing selected groups/types of comments".  The
problem there is that we have no established conventions about
groups or types and how to identify them.  For reasons that I
think are very similar to Carsten's arguments for treating the
authoring language differently from the production/publication
one, I don't think we should spend time trying to invent such a
typology or associated syntax.  Even if we were to do so,
retrofitting existing documents, even working drafts, would be a
fairly significant issue in many cases.  So I think we are
talking about author-specific or document-specific tools: not a
big deal for many of us, probably not a big deal for anyone who
is actually working directly in XML, but, as usual, I think the
edge cases are worth worrying about.

> The analog here is for a command line switch to xml2rfc to
> strip comments (real XML comments or a specific element).

Yes.  And with the same observation about types of comments
rather than all comments.   If we were to decide that we simply
did not want comments (any comments) in the posted versions of
RFCXML for I-Ds, such an option might actually make sense (and
would be a good match for some comments made to me offlist).
But I don't think we are there yet and, personally, hope we
don't get there.

best,
  john