Re: [PATCH net-next 9/9] net: document RFC6724 rule 5.5 implementation

[Jonathan Corbet <corbet@lwn.net>]

David 'equinox' Lamparter <equinox@diac24.net> writes:

> On Tue, Jul 14, 2026 at 07:01:13AM -0600, Jonathan Corbet wrote:
>> David 'equinox' Lamparter <equinox@diac24.net> writes:
>> >  create mode 100644 Documentation/networking/ipv6-addrsel.rst
>>
>> You need to add this new document to the index.rst file or it won't be
>> part of the docs build...you should have seen a warning when you built
>> the docs.
>
> Indeed... I missed it between the other warnings.  Downside of doing
> clean runs without a sphinx cache, sigh.

*Sigh* ... one of these years we'll clean up all those warnings, and
have them actually stay cleaned...

>> > +====================================
>> > +IPv6 source address selection trivia
>> > +====================================
>> > +
>> > +
>> > +RFC6724 rule 5.5 support
>> > +------------------------
>>
>> Please stick with the section markup guidelines in
>> Documentation/doc-guide/sphinx.rst.
>
> Oh, you mean I shouldn't skip the "Chapter" level?
>
> Now that you mention it, maybe I should include the file from ipv6.rst,
> and remove the document title entirely - it looks quite weird in the TOC
> with the direct reference from index.rst.  (Or rather, I've made weird
> choices with the headings.)  Does that sound good to you?
>
> (Or, I could just put the entire text into ipv6.rst...)

I would take that latter approach myself.  But others may differ :)

>> > +RFC6724 rule 5.5 is a very short paragraph in a complex RFC that has turned
>> > +out quite tricky, but also immensely useful in multihoming scenarios.  For
>> > +reference, it says:
>> > +
>> > +::
>> 
>> You'll likely get more visually pleasing results if you just leave out
>> the "::" here; you don't need literal formatting.
>
> I did that because RFCs are historically shipped & cited monospaced, and
> that's direct from the RFC.  My tendency is to keep it this way for
> "established convention" reasons, but I don't care that much - does
> anyone have stronger feelings?

You're writing the document, it's up to you in the end.

(But if you keep it that way, you can end the previous paragraph with
"it says::" and drop the separate "::" line).

Thanks,

jon