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

tom petch daedulus at btconnect.com
Wed Aug 25 04:59:25 PDT 2021


On 25/08/2021 02:13, Michael Richardson wrote:
>
> Carsten Bormann <cabo at tzi.org> wrote:

<snip>

> Yes, the descriptions.  It's a disaster coordinating what's in the YANG
> description, and what's in the document, and keeping them in sync.  How much
> detail do you put in each part?

I keep forgetting the obvious:-(

The YANG module be it 5 pages or 50 is a separate document.  It MUST be 
plain text that can be extracted and circulate as an independent 
document.  The descriptions, the references, the URL and so on must make 
sense when it is not part of an RFC.  The descriptions must tell the 
user what an object is with a reference to where more can be found, 
sometimes the 'mothership' RFC, usually not.

My take is that it is like documenting code, the description are what a 
good programmer places in the code with the rest of the RFC providing 
context, objectives, options rejected and so on.

The issue is how to reference into this plain text be it for a query, 
comment, erratum and so on.  As I said before, YANG is not structured 
the way SMI is so a reference to a leaf may take 10 or so lines of YANG!

Comment lines, which good authors use (as with code), are more compact 
(if a little bit too free form).

Tom Petch

>
> --
> Michael Richardson <mcr+IETF at sandelman.ca>   . o O ( IPv6 IøT consulting )
>             Sandelman Software Works Inc, Ottawa and Worldwide
>
>
>
> _______________________________________________
> 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