[rfc-i] What the text version is used for (was Re: The <tt> train wreck)

tom petch daedulus at btconnect.com
Mon Aug 23 09:00:28 PDT 2021


On 23/08/2021 13:31, Julian Reschke wrote:
> Am 23.08.2021 um 13:51 schrieb tom petch:
>> On 22/08/2021 21:36, Brian E Carpenter wrote:
>>> On 23-Aug-21 07:39, tom petch wrote:
>>>> On 21/08/2021 22:33, Brian E Carpenter wrote:
>>>>> On 22-Aug-21 05:55, Robert Sparks wrote:
>>>>>
>>>>> <snip>
>>>>>
>>>> <snip>
>>>>>
>>>>> It's easy enough to cite details by section number or by URL
>>>>> (even figures, e.g. https://www.rfc-editor.org/rfc/rfc8989#venn1).
>>>>> So losing page numbers, a feature of .txt that I've often seen
>>>>> mentioned, seems unimportant. This applies to drafts as much
>>>>> as to RFCs.
>>>>
>>>> May be but when the section spans what would be 50 pages were there to
>>>> be pages, then I find it somewhat difficult, especially when the same
>>>> text e.g. 'leaf name', appears in multiple places.  I refer, of course,
>>>> to YANG modules.  Perhaps YANG version 2.1 will introduce the
>>>> concept of
>>>> sections.
>>>
>>> Shouldn't we be handling YANG modules differently, i.e. using some
>>> system for handling diffs and issues in code? Handling them as if
>>> they are English text make no sense.
>>
>> Yes!  Most of the languages I have dealt with have the concept of
>> sequence numbers, so that when you drop the card deck on the floor, you
>> can sort it back into order, but that is now history!  I note that some
>> AD reviews use line numbers for their comments, I think generated by ID
>> nits.
>>
>> The better authors of YANG, like the better authors of other languages,
>> make extensive use of comments which can then be used for identifying
>> 'sections' (as well as providing a narrative that can be read to get an
>> overview of the module).  Perhaps that needs formalising.
>> ...
>
> Would adding optional line numbers to artwork/sourcecode help?

With YANG, I am not sure where they would go.  A lot of YANG modules 
(most?) bump up against the RFC line length limit because the language 
is heavily nested and the convention is to indent further each level of 
nesting; and there are path statements which, with such nesting, can 
exceed the line length limit on their own so a sequence number in 
columns 72-80 (e.g.) would not work.  (There is already an RFC8792 which 
provides a convention for dealing with long lines but I do not find that 
that makes for a document that is easy to read).

Rather inserting a comment line every 50 or so lines (or at the end of 
what used to be a page) such as
/* line 1250*/
would work for me.  An example of a YANG module comes in
draft-ietf-i2nsf-nsf-monitoring-data-model
which is 86pp of which 41 are the model itself.  This is an author whose 
used of comment lines is sparing but had no need to split long lines. 
The AD, Roman, comments are on the i2nsf list 25jun21; I can marry those 
that have no section numbers to the text but then I have studied and 
commented on the I-D previously.

Tom Petch



> Best regards, Julian
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest


More information about the rfc-interest mailing list