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

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

--On Sunday, March 17, 2024 09:36 +1300 Brian E Carpenter
<[e-mail]> wrote:

> John,
> 
> Thanks for explaining.
> 
> In line...
> 
> 
> On 17-Mar-24 07:51, John C Klensin wrote:
>> 
>> 
>> --On Saturday, March 16, 2024 17:13 +1300 Brian E Carpenter
>> <[e-mail]> wrote:
>> 
>>> ...
>>> More confusingly, there are still a few current drafts
>>> submitted as txt only. No XML at all. I wonder why we still
>>> allow that, and what tools people are using. 
> 
> I certainly don't care about the XML as such; what I miss
> is the HTML version, which is much nicer to read than either
> the plain text or the HTMLized version. My problem statement
> was too simple.
> 
> Is it possible for you to submit the .txt and the .html
> versions?

Have not investigated that, but maybe.  Can try to look into it
when I have time.  The one difficulty is that, if someone is
going to hold be responsible for the HTML being nicely
formatted, that could easily be another matter because, for a
long document, I don't even feel like taking the time to check
it (an issue that has come up with the RPC during AUTH48 as well.

>>> Doesn't this
>>> create busywork if the document progresses?
>> 
>> As one of the offenders, I think I have explained this before
>> but let me do it again.  Short answer: it is a side-effect of
>> work that makes the document development process in WGs much
>> more efficient in part because it makes "we have been over
>> that before, in YYYYMM, and reached those conclusions
>> because..." input much easier and more accessible.  It also
>> helps in preparation of accurate final change summaries and
>> acknowledgment easier and more accurate.  The "tools" are an
>> emacs-clone editor with an XML mode and a handful of personal
>> macros and templates.   The only "busywork" is stripping that
>> stuff out just before the XML is handed to the RPC.

> Good. I was concerned about the RPC having to synthesize the
> XML from a plain text submission.

A different problem entirely even though we do allow that.  But
I believe I have always made a sanitized version of my XML
available to them or at least offered to do so.

>>     =================
>> 
>> For anyone interested and in the hope of not having to repeat
>> this again...
>> 
>> Especially for long, complex, and long-lived documents,
>> especially those that are replacements, significant updates
>> for earlier documents, or merges of others, I use extensive
>> comments in the XML to track changes and decisions.   Other
>> comments are used to provide information to, or prepare for
>> discussions with, the RPC about why particular text phrasing
>> and constructions or document organizations were chosen, etc.
>> With one current document, those comments add up to more that
>> 30% of the size of the XML file.  Some of those comments are
>> over 20 years old and have been carried forward from xml2rfc
>> v1 files associated with previous documents.

> Understood. The "modern" approach is of course to embed such
> comments in GitHub issues, which tends to lead to
> self-censorship
> of any "unkind" comments, and then the nit-picking takes place
> on GitHub too.

Setting aside my issues with GitHub --most of which also have to
do with acting to exclude people who are not very active
participants in WGs that have been discussed as part of the
"pre-meeting document posting deadlines" thread on the IETF
list-- that approach asks for an additional investment of author
time that does not contribute directly to the quality of the
resulting document.

>> Why not just post all of that information?  Because, given
>> experience with the IETF community, it would be only a matter
>> of time before someone, probably several someones, decided to
>> nit-pick details of the comments or complain about the
>> incorrect or unkind terminology in some of them, even some of
>> the 20-year-old ones.  They are personal notes and neither I
>> nor the community would need the wasted time that could be
>> spent on the substantive parts of the document or on other
>> work.  For those and other reasons, I don't want to share
>> those comments, and hence the XML, with the community.  Too
>> many of them are personal notes.  They could be edited into
>> generally acceptable forms, but it would take significant
>> work and time that could be better spent in other ways.
 
>> When the I-D is approved and handed off to the RPC for
>> production and publishing, I prepare a version of the RFCXML
>> file that contains only the comments that are likely to be
>> helpful to the RPC or in conversations with them.   Certainly
>> those that are relevant only to prior RFCs that the new
>> document replaces are gone.  However that is a
>> comment-by-comment editing job that typically takes some
>> hours, not something I want to do with every I-D posting.
 
>> Could I establish conventions within the comments that would
>> permit automatic removal such that there would be the
>> copy/version I work on and an easily generated redacted one I
>> could post?  Yes, probably, but that would be extra work too.
>> Moreover, over the quarter-century since xml2rfc was
>> introduced, my conventions have changed -- I have even used
>> different conventions during the WG I-D development period
>> and during IETF LC.  If I had perfect foresight around 2000,
>> maybe, but...
>> 
>> So, not going to happen.  And if someone makes a rule that the
>> XML must (MUST?) be posted, I've authored or edited my last
>> long and/or complex and/or updating or replacing document.
>> Find someone else to do it.  Or conclude the IETF is not
>> interested in the topic area any more.
 
> Rules of course are made to be bypassed.

Which, to the extent to which there is already moaning about my
not posting XML for I-Ds, is what I am doing by posting the text
only.  Of course, those whom we still allow to prepare documents
using MSWord, nroff, or other tools that don't involve editing
XML or an XML intermediary have an even better problem.  And,
IMO, deciding we want to drive some or all of them away or tell
them they can't write I-Ds and get them posted would not be
exactly welcoming, newcomer-friendly, open, or many of the other
things we claim to be.   And, IMO, not an issue that can or
should be resolved on  this particular list.

>> Maybe I'm the only one, but I suspect I'm not.
 
>> I don't know. Your usage is rational but I'm genuinely unsure
>> about the ones that have crossed my screen lately.

As suggested above, I'm guessing that we still have some people
preparing documents in non-RFCXML forms or using mechanisms that
do not have it as an intermediary.  While I note that following
the path from the IETF home page through to
https://authors.ietf.org/choosing-a-format-and-tools leads to a
statement "3. Drafting in any other format is not recommended
for new authors." (a statement I don't remember anyone asking
the community about and determining consensus), some authors are
not new and even that page goes on to list, under "Full list of
authoring formats", several other formats (including plain text
submissions and word processors) are listed.  FWIW, I have some
other quibbles about the content of that page, but will save
them until after this week and, if everyone is lucky, not
remember by then.

best,
   john