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

[Carsten Bormann <[e-mail]>]

On 17. Mar 2024, at 13:26, Toerless Eckert <[e-mail]> wrote:
> 
> I don't even know what PI or cref are in details,

The PI “comments" was about rendering the crefs or not (and not about XML comments…).
It seems we don't have that at the moment in RFCXMLv3.

crefs are the thing that is rendered, while XML comments are not (but they are in the XML!  
Kramdown has a third (markdown level) form of comments, which are not going into the XML.
However, kramdown-rfc stows aways the full source in an XML comment anyway, so kramdown comments are not so useful for hiding things from a determined examiner.

> but if i understand
> you correctly, a solution meeting your requirements would be something like:
> 
> Let the doc be written in e.g.: kramdown.

Fine.

> There is an appropriate tag to mark sections of the document as comment
> (so you can easily comment out/in that part)

That is the crefs, which are accessible from markdown as markdown footnotes (quite appropriately so, I might add).

> The tool can render from kramdown into XML in two fashions: One with comments included,
> for example renderred in a different color and/or italic, or one in which the comments
> would not be rendered.

That is the comments PI from RFCXMLv2, which appears to be missing in action.

> This still requires for some "comment enhanced RFCXML" to include the ability to mark blos
> of the document as comment so they can accordingly be rendered differently.

Done, that is the cref element.
We are just missing the switch, and that could be added as a command line switch to xml2rfc, as Jay suggested.

Grüße, Carsten


> 
> Yes/No ?
> 
> Cheers
>    Toerless
> 
> On Sun, Mar 17, 2024 at 10:13:18AM +1000, Jay Daley 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 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.
>> 
>> 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 analog here is for a command line switch to xml2rfc to strip comments (real XML comments or a specific element).
>> 
>> Jay
>> 
>>> 
>>> The purpose of an issue tracker is to make the submission of comments and their discussion available to people beyond the authors.  Yes, you tie yourself to the git forge that you are using, which doesn’t need to be GitHub, although that happens to be awfully convenient.
>>> 
>>> It’s 2024, get WiFi for your flight.
>>> 
>>> (And maybe we should be investing on the tool that makes issue backups today; but the point is that you really want to be able to join the discussion of each issue, not just read only.)
>>> 
>>> Grüße, Carsten
>>> 
>>> 
>>>> On 17. Mar 2024, at 07:25, Toerless Eckert <[e-mail]> wrote:
>>>> 
>>>> How do you make offline copies of github issues to read while
>>>> flying to Australia or preparing for Microsoft to disband github ?
>>>> 
>>>> To me this is like buying an eBook from Amazon just to know that Amazon
>>>> will at some point in time delete it from my (Amazon) eReader for whatever reason.
>>>> 
>>>> I would rather prefer if there was a way if our tool chain to render output
>>>> with or without comments included and being able to express that in markup. I for once
>>>> would like to be done with touching XML myself (read or write).o
>>>> 
>>>> Cheers
>>>> Toerless
>>>> 
>>>> On Sat, Mar 16, 2024 at 01:50:50PM -0700, Eric Rescorla wrote:
>>>>> On Sat, Mar 16, 2024 at 1:36 PM 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:
>>>>>> 
>>>>>>> =================
>>>>>>> 
>>>>>>> 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.
>>>>>> 
>>>>> 
>>>>> I don't much care about the comments, but I would observe that a
>>>>> consequence of having the XML kept private like this is to make it
>>>>> more difficult for others to work on the documents, either by submitting
>>>>> diffs to the text or by forking them and making their own documents.
>>>>> 
>>>>> So in that respect, I think the "modern" approach truly is superior,
>>>>> though of course it's not the only way to obtain those benefits.
>>>>> 
>>>>> -Ekr
>>>> 
>>>>> ___________________________________________________________
>>>>> Tools-discuss mailing list - [e-mail] - https://www.ietf.org/mailman/listinfo/tools-discuss
>>>> 
>>> 
>>> ___________________________________________________________
>>> Tools-discuss mailing list - [e-mail] - https://www.ietf.org/mailman/listinfo/tools-discuss
>> 
>> -- 
>> Jay Daley
>> IETF Executive Director
>> [e-mail]
> 
> -- 
> ---
> [e-mail]