Re: [Tools-discuss] xml2rfc in --v2 mode -- bug report?

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

--On Sunday, June 12, 2022 20:58 +0200 Carsten Bormann
<[e-mail]> wrote:

> A couple of comments to some specifics:
> 
>> 
>> Epsilon (and emacs) are "just" editors.  Their modes for
>> handling XML are not aware of schema, just such fundamental
>> --and essentially lexical-- issues as formatting, element
>> matching, and so on. 
> 
> Emacs' nxml-mode can use a Relax-NG grammar (which is the
> usual way I edit RFCXML if I really really have to).

Sorry... As I have probably said, I don't use emacs much because
it has, for my needs and taste, gotten too cluttered.  But that
probably just means my example should have mentioned vi (I
assume), ed, Notepad, etc., and not emacs. 

>> (1) They would seem to lead to documents that are v2-v3
>> hybrids. I don't know how the current versions of xml2rfc
>> would deal with that but, given assorted v2 elements and
>> constructions that were deprecated in v3, I'd guess it would
>> be very hard to get right and that going in that direction
>> would be a bad idea.
 
> One of the problems with RFC 7991 is that it doesn't make
> explicit the relationship between authoring/contribution and
> publishing formats.  So there is tons of deprecated stuff in
> the published RFCs which is just needed to supply defaults to
> attributes that are deprecated in v3. Of course a published
> RFC should be clean of that and conform to a publishing
> grammar, which should be related to, but not identical, to the
> contribution grammar.

Understood.  And understood that there is a revision in the pipe
(draft-iab-rfc7991bis ?).  But, until and unless that revision
is approved with community consensus (presumably starting with,
or at least including, the RSWG), 7991 is what we have and
IETF-sponsored or -supplied tools should presumably not be
trying to enforce anything lese for v3.
 
>> […] given the very
> 
>> large number of documents in the RFC Editor's collection in v2
>> format
> 
> The RFC editor does not really deal in v2 RFCXML.
> They can give out some v2 RFCXML that was used in the
> publishing of a pre-8650 RFC, but it is then the job of the
> author to:

Understood, but I think we are splitting hairs.  If the RFC
Editor has v2 RFCXML on hand (which I understand they do for
most documents since they stopped going through an intermediate
nroff step), and someone comes along who have drawn the short
straw to updata that RFC, and that parson is moderately familiar
with XML and the RFCXML format(s), we presumably would prefer
that said lucky person be able to work as efficiently as
possible rather than creating stumbling blocks and unnecessary
work for them.  In most cases, that will involve starting with
the XML.  But then, we had better have at least one of:

 * a working interpreter for the v2 format
 * a working converter between v2 and v3 that gets very
	nearly everything right and produces clear messages when
	it does not
 * really good documentation about differences to look
	for and what to do about them.  Such documentation is
	different from just supplying two or more
	carefully-written "vocabulary" documents.

Otherwise, we are not only creating barriers to entry for
newcomers (including ones a WG Chair or AD might talk into
becoming editor for a new and modified version of an old
document), but are imposing barriers on continued participation
by existing participants who have limited time to spend on the
IETF.

>> that, I assume, have not been converted to v3 and tested
>> for consistency with the output produced,
> 
> I generally convert dusty XML decks to an authoring format
> (not v3, but kramdown-rfc) and then do an rfcdiff to the
> actual published RFC, tweaking the authoring format until the
> rfcdiff is empty (or just has some inevitable differences).

Glad that works for you.  I note that rfcdiff has largely
stopped being available and that iddiff, while it has improved
hugely in the last few months, is still not problem-free.  And,
unless what works for you works for everyone else, we either
figure out different ways of working or we impose more barriers
on participation (no matter how the possible argument of how
high those barriers are comes out).  Drawing on a different
conversation, if I (pretending to be a naive newcomer) somehow
get to author-tools.ietf.org, click on the "Getting Started"
link there, it seems to send me down the path of editing RFCXML
directly, not using Kramdown-RFC of anything else.
 
> So this is not really a good argument in favor of:
> 
>> a decision to retire
>> support for v2 should be taken only with great care (and, IMO,
>> given the risks and tradeoffs, made only with IESG signoff
>> after a community Last Call).  Until then, I believe the
>> tools team and IETF staff have considerable responsibility
>> for keeping version 2 supported.  I don't think a few
>> spurious warning messages are a big deal unless they are a
>> sign of things to come,
> 
> Which I agree wholeheartedly with until this:
> 
>> but, when the answer to a problem with constructions that
>> are valid and well-documented under v2 is "convert to v3",
>> that is not supporting v2 properly and as the community has a
>> reasonable right to expect.  
 
> Converting to v3 *is* the answer.

> If we had infinite resources, we could spend some of the
> energy keeping v2 more alive than it is, but with 138 open
> issues, we'll need to focus on keeping v3 alive.

I actually agree with that prioritization.  I would also
prioritize getting (and keeping) the converter working well over
maintaining/ improving the v2 processor, especially if we had a
copy of the pre-transition v2 processor around and could make it
available online and/or for distribution to people to run in
their local environments.    Where we might disagree is on
priority to be given the converter versus priority to fixing
bugs in v3.  I don't know the best answer to that one but one
other thing concerns me.  When someone describes a relatively
new piece of software as having a rather large number of open
issues, insufficient resources to deal with them quickly and
well, and a "need to focus on keeping it alive", the message I
get --after over a half-century of involvement in software
development projects in a variety of roles -- is "not ready for
production use".  That is a rather scary thought.

> To me, continuing to work on a document in v2 format really is
> a waste of time, unless there are some very specific reasons
> that we haven't discussed here. Convert to an authoring
> format, e.g., kramdown-rfc, mmark, or if it must be, RFCXMLv3,
> and take it from there.

Well, for assorted historical reasons, including experience with
[S]GML going back to the early 1970s and having a collection of
local macros and templates, RFCXMLv3 is the best choice for me.
Another reason is that I was taught, at about the same time,
that the idea behind generic markup was that no separate
authorizing language was needed and that the terms for markup
arrangements that either put enough burden on authors that an
authoring language was needed to manage the authoring language
or that mixed generic and format markup started with "broken"
and "ill-conceived" and went downhill from there.   I may be the
only one with those views, but it means that high-quality
conversion support (which, IIR, the IETF community was promised
when v3 was proposed) is important.   It is probably almost
equally important to be able to generate good text output from
something (v2 or post-conversion v3) for those other tools to be
maximally useful.

The other problem is that, if the authoring languages are really
an important part of the solution, the web pages under
authors.ietf.org appear to be in need of considerable work. 

> We need some continued working v2 support in xml2rfc to do
> other things with pre-8650 contributions, but we don't need
> to make it good enough for authoring RFCs, as these will be
> v3, and the earlier in the authoring process you can make the
> conversion, the less the pain and the better the results will
> be.

The above comments notwithstanding, my strategy --at least in
the last few years-- has been consistent with what you suggest:
get the documents into v3 as quickly as possible and go from
there.  The problem is that conversion failures send a message
of either "not possible yet, wait a few more months" or "v3
isn't ready; just continue for a while with something that
works".

best,
   john