Re: [Tools-discuss] Why post text and not XML?

[Jean Mahoney <[e-mail]>]

Hi all,

On 3/16/24 3:36 PM, Brian E Carpenter 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. 

[JM] The RPC still allows the submission of text files, but only 3% of 
the documents that entered the queue in 2023 were text only.

> 
> 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?
> 
>>> 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.

[JM] The RPC uses id2xml to covert text documents to RFCXML v3, but it 
is a time-consuming process to get those documents into good shape. The 
id2xml conversion step only gets a text document part of the way there.

Best regards,
Jean


> 
>>
>>     =================
>>
>> 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.
> 
>>
>> 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.
> 
>>
>> 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.
> 
> Regards
>     Brian
> 
> 
>>
>>      john
>>
>>
>>
>>
>>
> 
> ___________________________________________________________
> Tools-discuss mailing list - [e-mail] - 
> https://www.ietf.org/mailman/listinfo/tools-discuss