| Message ID | 20241105041507.1292595-1-alexhenrie24@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | rtnetlink.7: Document struct ifa_cacheinfo | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Not a local patch |
From: Alex Henrie <alexhenrie24@gmail.com> Date: Mon, 4 Nov 2024 21:14:20 -0700 > struct ifa_cacheinfo contains the address's creation time, update time, > preferred lifetime, and valid lifetime. See > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 > > Signed-off-by: Alex Henrie <alexhenrie24@gmail.com> > --- > man/man7/rtnetlink.7 | 10 +++++++++- > 1 file changed, 9 insertions(+), 1 deletion(-) > > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7 > index 86ed459bb..b05654315 100644 > --- a/man/man7/rtnetlink.7 > +++ b/man/man7/rtnetlink.7 > @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address > IFA_ANYCAST:raw protocol address:anycast address > IFA_CACHEINFO:struct ifa_cacheinfo:Address information > .TE > -.\" FIXME Document struct ifa_cacheinfo > +.IP > +.EX > +struct ifa_cacheinfo { > + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ > + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned. Also, it would be nice to mention that ifa_prefered must be less than or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for ifa_valid. 0 <= ifa_prefered <= ifa_valid 0 < ifa_valid <= 0xFFFFFFFF > + __u32 cstamp; /* Creation timestamp in hundredths of seconds */ > + __u32 tstamp; /* Update timestamp in hundredths of seconds */ > +}; Maybe the explanation can follow the struct here as sentences. > +.EE > .TP > .B RTM_NEWROUTE > .TQ > -- > 2.47.0
Hi Alex, Kuniyuki, Branden, On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote: > From: Alex Henrie <alexhenrie24@gmail.com> > Date: Mon, 4 Nov 2024 21:14:20 -0700 > > struct ifa_cacheinfo contains the address's creation time, update time, > > preferred lifetime, and valid lifetime. See We use two spaces after period (the correct amount). :) (I'm thinking we probably want to document something about it in man-pages(7). Branden, do you want to send a patch about it? I want to include the references you showed to me, and you probably remember better those links.) > > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 Please use this format for links: Link: <http://example.com> > > > > Signed-off-by: Alex Henrie <alexhenrie24@gmail.com> > > --- > > man/man7/rtnetlink.7 | 10 +++++++++- > > 1 file changed, 9 insertions(+), 1 deletion(-) > > > > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7 > > index 86ed459bb..b05654315 100644 > > --- a/man/man7/rtnetlink.7 > > +++ b/man/man7/rtnetlink.7 > > @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address > > IFA_ANYCAST:raw protocol address:anycast address > > IFA_CACHEINFO:struct ifa_cacheinfo:Address information > > .TE > > -.\" FIXME Document struct ifa_cacheinfo > > +.IP > > +.EX Which include provides the structure? > > +struct ifa_cacheinfo { > > + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ > > + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ > > -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned. I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it has. > Also, it would be nice to mention that ifa_prefered must be less than > or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for > ifa_valid. > > 0 <= ifa_prefered <= ifa_valid > 0 < ifa_valid <= 0xFFFFFFFF You may want to use interval notation, like we do in timespec(3type). struct timespec { time_t tv_sec; /* Seconds */ /* ... */ tv_nsec; /* Nanoseconds [0, 999'999'999] */ }; It might also be interesting to add a separate manual page for the type, and reference it here. Otherwise, the page starts getting fatty. Have a lovely day! Alex > > > > + __u32 cstamp; /* Creation timestamp in hundredths of seconds */ > > + __u32 tstamp; /* Update timestamp in hundredths of seconds */ > > +}; > > Maybe the explanation can follow the struct here as sentences. > > > > +.EE > > .TP > > .B RTM_NEWROUTE > > .TQ > > -- > > 2.47.0 >
On Tue, 5 Nov 2024 12:33:48 +0100 Alejandro Colomar <alx@kernel.org> wrote: > Hi Alex, Kuniyuki, Branden, > > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote: > > From: Alex Henrie <alexhenrie24@gmail.com> > > Date: Mon, 4 Nov 2024 21:14:20 -0700 > > > struct ifa_cacheinfo contains the address's creation time, update time, > > > preferred lifetime, and valid lifetime. See > > We use two spaces after period (the correct amount). :) Double spacing after period is a leftover from using typewriters. Modern usage is single space after period. https://www.grammarly.com/blog/punctuation-capitalization/spaces-after-period/ These days most contemporary style guides also recommend using a single space between sentences, including: The Chicago Manual of Style The American Psychological Association (often referred to as “APA”) Microsoft Manual of Style The Gregg Reference Manual The Associated Press Stylebook
Hi Stephen, On Wed, Nov 06, 2024 at 09:18:01AM GMT, Stephen Hemminger wrote: > On Tue, 5 Nov 2024 12:33:48 +0100 > Alejandro Colomar <alx@kernel.org> wrote: > > > Hi Alex, Kuniyuki, Branden, > > > > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote: > > > From: Alex Henrie <alexhenrie24@gmail.com> > > > Date: Mon, 4 Nov 2024 21:14:20 -0700 > > > > struct ifa_cacheinfo contains the address's creation time, update time, > > > > preferred lifetime, and valid lifetime. See > > > > We use two spaces after period (the correct amount). :) > > Double spacing after period is a leftover from using typewriters. That's a lie that modern style guides repeat believing that repeating it will eventually make it true (as if that were possible). The origin is much older, and ancient (pre-typewriter) books already used different space lengths for after period. The true reason why the 2-space tradition was replaced by the 1-space modern rule is that editorials started hiring incompetent people, and it seems it was hard for that incompetent people to decide if one space or two spaces were appropriate at a given place, so they would get it wrong. To avoid being embarrased by frequent spacing typos, instead of hiring competent people (which would have been expensive), they simply changed the rules to accomodate for those incompetent ones, and told them to unconditionally use 1 space always. That also reduces the time they had to think about the number of spaces being used, so they became more efficient. But that removes information from the text. If a sentence ends in some initials, it's hard to distinguish if it's the end of a sentence, or if the sentence continues and the dot is just for the initials. It seems the editorials just cared about generating text faster, and didn't care at all about readers having more difficulty in reading what they wrote (which just shows the low quality of what they produced). Ironically enough, studies promoted by the defendants of the one-space rule proof that two spaces result in more readable text. They try to write their conclusions as if not, but if you read enough in their experiments, you realize how blind they are with their own experiments. And also ironically, those one-space defendants say two-space tradition is obsolete cruft from times where mono-spaced fonts were prevalent. Guess what? We here still live in a world were mono-spaced fonts are the rule (anyone reading manual pages in a terminal here?) (I guess none of us programs with proportional fonts, right?), so even if all those lies were true (and they are not), in our reigns two-spaces should still be the rule. We had some discussion about this a few years ago, and we had links for the claims I'm making, so I want to eventually recollect those links and document it well for all contributors to see. > Modern usage is single space after period. > > https://www.grammarly.com/blog/punctuation-capitalization/spaces-after-period/ > > These days most contemporary style guides also recommend using a single space between sentences, > including: > > The Chicago Manual of Style > The American Psychological Association (often referred to as “APA”) > Microsoft Manual of Style > The Gregg Reference Manual > The Associated Press Stylebook Paraphrasing the Linux kernel coding style... First off, I’d suggest printing out a copy of the Chicago Manual of Style, and NOT read it. Burn it, it’s a great symbolic gesture. Have a lovely night! Alex
Hi Stephen, At 2024-11-06T09:18:01-0800, Stephen Hemminger wrote: > Alejandro Colomar <alx@kernel.org> wrote: > > We use two spaces after period (the correct amount). :) > > Double spacing after period is a leftover from using typewriters. No, it isn't. See URL below. > Modern usage is single space after period. [...] > These days most contemporary style guides also recommend using a > single space between sentences, including: > > The Chicago Manual of Style > The American Psychological Association (often referred to as “APA”) > Microsoft Manual of Style > The Gregg Reference Manual > The Associated Press Stylebook You're not bringing any new information to the table, and you don't appear to understand why the two-space rule is in place for _typesetting software_. I don't just mean *roff, but TeX as well. Neither of these is a WYSIWYG system. Neither of them is Markdown. The rule is not there so that people can argue over how many space widths should separate sentences. The rule is there so that the formatter knows where the boundaries between sentences _are_. If you despise the use of two spaces between sentences in a *roff source document, there's an easy solution: use what Alex calls "semantic newlines". https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html#Sentences I furthermore remind the reader that, in GNU troff/man(7), the intersentence space width is configurable at _rendering_ time--if the author of the man(7) document honors one of the conventions that permits the formatter to detect sentence boundaries. For example... groff_man_style(7): Files ... /usr/groff/site-tmac/man.local Put site‐local changes and customizations into this file. .\" Put only one space after the end of a sentence. .ss 12 0 \" See groff(7). .\" Keep pages narrow even on wide terminals. .if n .if \n[LL]>80n .nr LL 80n Arguing about the number of spaces between sentences in a discussion of "semantic newlines" (or whatever you want to call them) is counterproductive and wasteful of time. Regards, Branden
At 2024-11-06T18:44:08+0100, Alejandro Colomar wrote: > Paraphrasing the Linux kernel coding style... > > First off, I’d suggest printing out a copy of the Chicago Manual > of Style, and NOT read it. Burn it, it’s a great symbolic > gesture. I wouldn't go that far. CMoS has much that is valuable. Russell Harper is simply not a reliable source regarding the inter-sentence spacing issue. As we've seen, he has a lot of company. Regards, Branden
Hi Branden, On Wed, Nov 06, 2024 at 11:45:31AM GMT, G. Branden Robinson wrote: > You're not bringing any new information to the table, and you don't > appear to understand why the two-space rule is in place for _typesetting > software_. I don't just mean *roff, but TeX as well. > > Neither of these is a WYSIWYG system. Neither of them is Markdown. > > The rule is not there so that people can argue over how many space > widths should separate sentences. The rule is there so that the > formatter knows where the boundaries between sentences _are_. Actually, in this case it was about the use of intersentence space in a commit message. It was not about the contents of a manual page itself. However, I think that loss of information is equally bad for a human than for a type-setting system such as roff(1) or TeX. > If you despise the use of two spaces between sentences in a *roff source > document, there's an easy solution: use what Alex calls "semantic > newlines". > > https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html#Sentences [...] > Arguing about the number of spaces between sentences in a discussion of > "semantic newlines" (or whatever you want to call them) is > counterproductive and wasteful of time. Hmmm, you're right. Using semantic newlines completely removes intersentence spaces in manual pages; we shouldn't document that in man-pages(7). However, for commit messages I still want to enforce two spaces, so we should probably document it in CONTRIBUTING.d/patches. Have a lovely night! Alex
On Mon, 4 Nov 2024 21:14:20 -0700 Alex Henrie <alexhenrie24@gmail.com> wrote: > struct ifa_cacheinfo contains the address's creation time, update time, > preferred lifetime, and valid lifetime. See > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 > > Signed-off-by: Alex Henrie <alexhenrie24@gmail.com> > --- > man/man7/rtnetlink.7 | 10 +++++++++- > 1 file changed, 9 insertions(+), 1 deletion(-) > > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7 > index 86ed459bb..b05654315 100644 > --- a/man/man7/rtnetlink.7 > +++ b/man/man7/rtnetlink.7 > @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address > IFA_ANYCAST:raw protocol address:anycast address > IFA_CACHEINFO:struct ifa_cacheinfo:Address information > .TE > -.\" FIXME Document struct ifa_cacheinfo > +.IP > +.EX > +struct ifa_cacheinfo { > + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ > + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ > + __u32 cstamp; /* Creation timestamp in hundredths of seconds */ > + __u32 tstamp; /* Update timestamp in hundredths of seconds */ > +}; > +.EE > .TP > .B RTM_NEWROUTE > .TQ This is for man pages, not iproute2. Resetting in patchwork
On Tue, Nov 5, 2024 at 4:33 AM Alejandro Colomar <alx@kernel.org> wrote: > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote: > > From: Alex Henrie <alexhenrie24@gmail.com> > > Date: Mon, 4 Nov 2024 21:14:20 -0700 > > > struct ifa_cacheinfo contains the address's creation time, update time, > > > preferred lifetime, and valid lifetime. See > > We use two spaces after period (the correct amount). :) > (I'm thinking we probably want to document something about it in > man-pages(7). Branden, do you want to send a patch about it? I want > to include the references you showed to me, and you probably remember > better those links.) > > > > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 > > Please use this format for links: > > Link: <http://example.com> Since the second sentence will be eliminated in favor of a Link line, the first sentence will no longer have any spaces after its period. > Which include provides the structure? linux/if_addr.h, which is the file I linked to in the commit message, and the same file that contains struct ifaddrmsg which is documented a few paragraphs earlier in the same section of the man page. > > > +struct ifa_cacheinfo { > > > + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ > > > + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ > > > > -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned. > > I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it > has. INFINITY_LIFE_TIME is not defined in any public header, so let's not mention it. I agree that it's hard to see at a glance how many F's are in 0xFFFFFFFF. I would suggest ~0u, which is short and sweet, but UINT32_MAX is a little better because ~0u isn't 32 bits on all C compilers that have ever existed. > > Also, it would be nice to mention that ifa_prefered must be less than > > or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for > > ifa_valid. > > > > 0 <= ifa_prefered <= ifa_valid > > 0 < ifa_valid <= 0xFFFFFFFF I'll add a paragraph to explain those relationships. > It might also be interesting to add a separate manual page for the type, > and reference it here. Otherwise, the page starts getting fatty. Perhaps. In my opinion, there's not enough material here to be worthy of its own page. Thanks for the feedback, -Alex
Bon dia Alex, :) On Sun, Nov 10, 2024 at 11:17:40PM GMT, Alex Henrie wrote: > On Tue, Nov 5, 2024 at 4:33 AM Alejandro Colomar <alx@kernel.org> wrote: > > > On Mon, Nov 04, 2024 at 09:53:38PM GMT, Kuniyuki Iwashima wrote: > > > From: Alex Henrie <alexhenrie24@gmail.com> > > > Date: Mon, 4 Nov 2024 21:14:20 -0700 > > > > struct ifa_cacheinfo contains the address's creation time, update time, > > > > preferred lifetime, and valid lifetime. See > > > > We use two spaces after period (the correct amount). :) > > (I'm thinking we probably want to document something about it in > > man-pages(7). Branden, do you want to send a patch about it? I want > > to include the references you showed to me, and you probably remember > > better those links.) > > > > > > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 > > > > Please use this format for links: > > > > Link: <http://example.com> > > Since the second sentence will be eliminated in favor of a Link line, > the first sentence will no longer have any spaces after its period. > > > Which include provides the structure? The manual page should document it. Readers should know which header they need to include to use a structure, no? > > linux/if_addr.h, which is the file I linked to in the commit message, > and the same file that contains struct ifaddrmsg which is documented a > few paragraphs earlier in the same section of the man page. > > > > > +struct ifa_cacheinfo { > > > > + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ > > > > + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ > > > > > > -1 should be rather 0xFFFFFFFF (INFINITY_LIFE_TIME) as it's unsigned. > > > > I prefer UINT32_MAX over 0xF...F, which might be unclear how many Fs it > > has. > > INFINITY_LIFE_TIME is not defined in any public header, so let's not > mention it. I agree that it's hard to see at a glance how many F's are > in 0xFFFFFFFF. I would suggest ~0u, which is short and sweet, but > UINT32_MAX is a little better because ~0u isn't 32 bits on all C > compilers that have ever existed. > > > > Also, it would be nice to mention that ifa_prefered must be less than > > > or equal to ifa_valid (ifa_prefered <= ifa_valid) and 0 is invalid for > > > ifa_valid. > > > > > > 0 <= ifa_prefered <= ifa_valid > > > 0 < ifa_valid <= 0xFFFFFFFF > > I'll add a paragraph to explain those relationships. > > > It might also be interesting to add a separate manual page for the type, > > and reference it here. Otherwise, the page starts getting fatty. > > Perhaps. In my opinion, there's not enough material here to be worthy > of its own page. If you see the pages in section 2type or 3type, they're pretty small. Types don't have that much to tell. But they're nevertheless useful. When you just want to see which header you need for a given type, just run `make type`, and you'll immediately see it. It also has a few lines of description. But up to you. > Thanks for the feedback, Have a lovely day! Alex > > -Alex >
diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7 index 86ed459bb..b05654315 100644 --- a/man/man7/rtnetlink.7 +++ b/man/man7/rtnetlink.7 @@ -176,7 +176,15 @@ IFA_BROADCAST:raw protocol address:broadcast address IFA_ANYCAST:raw protocol address:anycast address IFA_CACHEINFO:struct ifa_cacheinfo:Address information .TE -.\" FIXME Document struct ifa_cacheinfo +.IP +.EX +struct ifa_cacheinfo { + __u32 ifa_prefered; /* Preferred lifetime in seconds, -1 = forever */ + __u32 ifa_valid; /* Valid lifetime in seconds, -1 = forever */ + __u32 cstamp; /* Creation timestamp in hundredths of seconds */ + __u32 tstamp; /* Update timestamp in hundredths of seconds */ +}; +.EE .TP .B RTM_NEWROUTE .TQ
struct ifa_cacheinfo contains the address's creation time, update time, preferred lifetime, and valid lifetime. See https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/if_addr.h?h=v6.11#n60 Signed-off-by: Alex Henrie <alexhenrie24@gmail.com> --- man/man7/rtnetlink.7 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-)