Re: [PATCH] rtnetlink.7: Document metrics attributes (RTAX_*).

[Guillaume Nault <gnault@redhat.com>]

On Wed, Oct 08, 2025 at 06:05:41PM +0200, Alejandro Colomar wrote:
> Hi Guillaume,
> 
> On Wed, Oct 08, 2025 at 04:41:19PM +0200, Guillaume Nault wrote:
> > > > +.IP
> > > > +.in +4n
> > > 
> > > I would use
> > > 
> > > 	.RS
> > > 	.IP
> > > 
> > > and get rid of the .in +4n.
> > 
> > I have no preference, I was just following the commands used elsewhere
> > in this man page.
> 
> Hmmm, I'll have a look at the source of that page later.  Maybe I need
> to fix the existing code.
> 
> > > > +.TE
> > > 
> > > And here use .RE.
> > 
> > Okay, I'll use .RS/.RE in v2.
> > 
> > > > +.IP
> > > > +Metrics that are locked with
> > > > +.B RTAX_LOCK
> > > > +take precedence over the values normally used by the kernel
> > > > +(computed or assigned by a sysctl or setsockopt(2)).
> > > > +Therefore, some metrics, like
> > > > +.BR RTAX_RTO_MIN ,
> > > > +have no effect unless their bit is set in
> > > > +.BR RTAX_LOCK .
> > > > +.in
> > > 
> > > I find this placement of .in weird.  The preceding paragraph isn't
> > > indented by it.  I think I prefer using .RS/.RE, and then you'd have to
> > > put .RE before this paragraph to get the same indentation.
> > > 
> > > Here's how your patch looks like:
> > > 
> > > 	$ MANWIDTH=72 diffman-git HEAD 2>/dev/null
> > > 	--- HEAD^:man/man7/rtnetlink.7
> > > 	+++ HEAD:man/man7/rtnetlink.7
> > > 	@@ -218,7 +218,8 @@ DESCRIPTION
> > > 		     RTA_GATEWAY     protocol address      The gateway of the route
> > > 		     RTA_PRIORITY    int                   Priority of route
> > > 		     RTA_PREFSRC     protocol address      Preferred source address
> 
> [...]
> 
> > > 	+                RTAX_RTO_MIN              __u32           Minimum Retransmission TimeOut to use for this route
> > > 	+                RTAX_INITRWND             __u32           Initial size of the receive window for this route
> > > 	+                RTAX_QUICKACK             __u32           Use quick ack for this route
> > > 	+                RTAX_CC_ALGO              asciiz string   Congestion Control algorithm to use for this route
> > > 	+                RTAX_FASTOPEN_NO_COOKIE   __u32           Allow TCP Fast Open without cookie
> > > 	+
> > > 	+            Metrics that are locked with RTAX_LOCK take precedence over
> > > 	+            the values normally used by the kernel (computed or as‐
> > > 	+            signed by a sysctl or setsockopt(2)).  Therefore, some met‐
> > > 	+            rics, like RTAX_RTO_MIN, have no effect unless their bit is
> > > 	+            set in RTAX_LOCK.
> > > 	+
> > > 		     RTA_MULTIPATH contains several packed instances of struct
> > > 		     rtnexthop together with nested RTAs (RTA_GATEWAY):
> > > 	 
> > > Is this indentation what you intended?
> > 
> > Yes.
> 
> Thanks!
> 
> > Is that indentation confusing? I can change it if necessary.
> 
> The indentation is fine.  Please keep it like that.  What's confusing is
> the source code, since the '.in' goes after the unindented paragraph,
> while I'd expect it to be the indentation terminator.  .RS/.RE is much
> more intuitive.

I understand what you mean now. Placing '.in' after the RTAX_LOCK
paragraph was an oversight.

I'm about to send v2, with .in replaced by .RS/.RE, as you proposed.
Thanks for the feedbacks!

> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es>
> Use port 80 (that is, <...:80/>).