[rfc-i] The role of txt format in ietf document development

[Paul Kyzivat <[e-mail]>]

Brian,

[Top posting because this is a general observation provoked by your 
comments, not pertaining to any particular comment. Also changing the 
subject to relate to the content.]

I realize all the points I am making are rooted in a perceived need to 
continue using txt format (or something akin to it) for some purposes. 
And I know how archaic it seems. I would be happy to migrate to using a 
richer format for all purposes *if* there was a clear way to make the 
whole process of creating / evolving / reviewing / discussing / editing 
/ publishing documents work smoothly. IMO we are far from that state.

I spent a bit of time participating in 3GPP where they do everything 
with MSWord documents. I found that to be incredibly cumbersome.

I have *not* been involved in W3C document development. I don't know how 
that works. I'd be interested in hearing if they have something that 
works well.

In the IETF process documents are primarily discussed via email. Email 
threads often end up evolving text that goes in documents. I 
intentionally use plain text email with quoting for this purpose because 
it makes the threading clear. (Not everybody does this. When some use MS 
html email and indicate their contribution via initials things get very 
hard to follow.)

When discussing a particular part of a document it is convenient to 
simply copy/paste a few lines of the txt format into the email. The txt 
format means that the formatting is preserved and isn't reflowed. So it 
is easy to relate this to the whole document.

I can vaguely imagine working from an html form of a document and 
copying bits of text into an html email, but I am dubious that it will 
work as well.

A key part of working with documents is reviewing changes via diffs. For 
now the diff tools only work on txt documents. Relating that back to the 
txt form of the whole document is easy. Relating back to html or pdf can 
work, but isn't as straightforward. Perhaps the situation would be 
different if we had a diff that worked on the html or pdf formats.

A further complication is the evolving use of github in the management 
of ietf drafts. It has different tools for commenting and revising. How 
this interacts with the "traditional" ietf draft management is a bit 
obscure.

Bottom line: it is possible, and perhaps desirable, for the ietf to move 
to a system totally detached from plain text. But doing so will require 
many more tool and process changes than are currently planned. And it 
will require everybody involved to move to new ways of doing things. It 
is a heavy lift!

	Thanks,
	Paul

On 10/27/20 4:46 PM, Brian E Carpenter wrote:
> On 28-Oct-20 04:00, Paul Kyzivat wrote:
>> On 10/27/20 1:11 AM, Brian E Carpenter wrote:
>>> On 27-Oct-20 12:53, Benjamin Kaduk wrote:
>>>> On Mon, Oct 26, 2020 at 06:24:27PM -0400, John Levine wrote:
>>>>> In article <[e-mail]> you write:
>>>>>>> For individual sections, the TOC absolutely should provide linkage to
>>>>>>> sections, especially in formats like HTML.
>>>>>>
>>>>>> The native HTML format does.  I have no idea why the htmlization script
>>>>>> can't or does not do so for new-format RFCs.
>>>>>
>>>>> There is no htmlization script for new-format RFCs. The HTML format is
>>>>> produced directly from the XML and has all the links you'd expect, as
>>>>> does the PDF. The text format loses a lot of info visible in the other
>>>>> formats so it is a third-best option.
>>>>>
>>>>> I suppose you could render to text and try to htmlize that but it's
>>>>> hard to imagine a reason to do so.
>>>>
>>>> I don't know what https://tools.ietf.org/html/rfc8815 is (conveniently
>>>> linked from https://datatracker.ietf.org/doc/rfc8815/ as "htmlized") if not
>>>> trying to htmlize the text copy.  I am well aware that the new format
>>>> produces direct ("native") HTML output, and indeed was attempting to point
>>>> Jeff towards the native HTML output.
>>>
>>> Right. I think we should debate whether it's a good or a bad idea to run
>>> the htmlization script on v3 format documents. I'd say "bad" because all
>>> it does is create confusion.
>>>
>>> Running rfcdiff on the plain text version is very useful, however.
>>
>> I prefer to use the htmlized version when reviewing documents, for a
>> variety of reasons:
>>
>> - it has all those handly links at the top, notably for the diffs,
>> tracker, etc. So with one click I can bring up the diff showing the most
>> recent changes.
> 
> Yes, very useful. Is there any reason that a tool could not prepend
> that info to the new-normal HTML version?
> 
>>
>> - it has hot links from the TOC to the sections so that is easily navigated
> 
> That's built into the new-normal HTML.
> 
>>
>> - it is laid out just like the text version.
> 
> But the text version is now not a reference point any more, like it or not.
> 
>> I can cut out sections that
>> I want to comment on and paste them into an email while retaining the
>> formatting.
> 
> True. But if your reader is looking at the HTML version, that doesn't really work any more.
> 
> (I prefer to use the side by side diffs when reviewing
>> changes, but often then need to consult the full version for more
>> context. Having the full version match what the diff used is important
>> for this.)
> 
> True. But this is a property we lose when line-wrapped HTML is the presentation format.
> 
>>
>> Hence I would definitely like to have the htmlized format continue to be
>> available for v3 documents. Since it is created from the txt format I
>> don't see why it is harder to produce than for v2 documents.
> 
> It isn't. But since the txt version is no longer canonical, e.g. no SVG diagrams, the value is less than it used to be.
> 
>> OTOH, I do now prefer the native html version when reading/consulting a
>> document.
> 
> Me too. It also prints nicely if you want.
> 
>      Brian
> 

_______________________________________________
rfc-interest mailing list
[e-mail]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest