Re: tweaks to namei.9
On Thu, Aug 02, 2018 at 07:41:01PM +0200, Ingo Schwarze wrote: > Hi Jason, > > Jason McIntyre wrote on Thu, Aug 02, 2018 at 05:41:22PM +0100: > > > ok by me. > > Thanks for checking, committed. > > > you might get away with removing the last sentence of BUGS > > now, since HISTORY almost provides the same. > > Maybe, but i don't know enough about ufs and vfs to judge whether > it really says the same or hides some additional, useful information > behind a clumsy wording. > > So i'll leave cleaning that up to someone more knowlegeable, if it > needs cleanup. > > > while we're chopping, i'd prefer to see the one line section > > that is CODE REFERENCES integrated into DESCRIPTION. > > Maybe, but it is kind of conventional in section 9 manual pages: > >$ grep CODE * > autoconf.9:.Sh CODE REFERENCES > buffercache.9:.Sh CODE REFERENCES > disk.9:.Sh CODE REFERENCES > extent.9:.Sh CODE REFERENCES > file.9:.Sh CODE REFERENCES > hardclock.9:.Sh CODE REFERENCES > intro.9:.Sh CODE REFERENCES > ktrace.9:.Sh CODE REFERENCES > mbuf.9:.Sh CODE REFERENCES > mbuf_tags.9:.Sh CODE REFERENCES > microtime.9:.Sh CODE REFERENCES > namei.9:.Sh CODE REFERENCES > pool.9:.Sh CODE REFERENCES > pool_cache_init.9:.Sh CODE REFERENCES > printf.9:.Sh CODE REFERENCES > psignal.9:.Sh CODE REFERENCES > rasops.9:.Sh CODE REFERENCES > rssadapt.9:.Sh CODE REFERENCES > syscall.9:.Sh CODE REFERENCES > tc_init.9:.Sh CODE REFERENCES > tfind.9:.Sh CODE REFERENCES > timeout.9:.Sh CODE REFERENCES > tsleep.9:.Sh CODE REFERENCES > tvtohz.9:.Sh CODE REFERENCES > vfs_cache.9:.Sh CODE REFERENCES > vinvalbuf.9:.Sh PSEUDOCODE > vnsubr.9:.Sh CODE REFERENCES > wdog_register.9:.Sh CODE REFERENCES > > NetBSD has it, too: > > > https://man.openbsd.org/?query=Sh%3DCODE\+REFERENCES=1=NetBSD-7.1 > > On the one hand, i agree that very short sections aren't very pretty. > On the other hand, the purpose of CODE REFERENCES is sufficiently > different from DESCRIPTION, and its use sufficiently widespread, > that it may help kernel hackers to quickly locate this information. > > I'm not sure in this respect. > > Yours, > Ingo these sections are generally from imported netbsd pages. there's enough that we never killed them (like LIBRARY) but never officially supported them either. i think my request to kill it was unfair, since it'd be better done consistently rather than picking on one page. jmc
Re: tweaks to namei.9
Hi Jason, Jason McIntyre wrote on Thu, Aug 02, 2018 at 05:41:22PM +0100: > ok by me. Thanks for checking, committed. > you might get away with removing the last sentence of BUGS > now, since HISTORY almost provides the same. Maybe, but i don't know enough about ufs and vfs to judge whether it really says the same or hides some additional, useful information behind a clumsy wording. So i'll leave cleaning that up to someone more knowlegeable, if it needs cleanup. > while we're chopping, i'd prefer to see the one line section > that is CODE REFERENCES integrated into DESCRIPTION. Maybe, but it is kind of conventional in section 9 manual pages: $ grep CODE * autoconf.9:.Sh CODE REFERENCES buffercache.9:.Sh CODE REFERENCES disk.9:.Sh CODE REFERENCES extent.9:.Sh CODE REFERENCES file.9:.Sh CODE REFERENCES hardclock.9:.Sh CODE REFERENCES intro.9:.Sh CODE REFERENCES ktrace.9:.Sh CODE REFERENCES mbuf.9:.Sh CODE REFERENCES mbuf_tags.9:.Sh CODE REFERENCES microtime.9:.Sh CODE REFERENCES namei.9:.Sh CODE REFERENCES pool.9:.Sh CODE REFERENCES pool_cache_init.9:.Sh CODE REFERENCES printf.9:.Sh CODE REFERENCES psignal.9:.Sh CODE REFERENCES rasops.9:.Sh CODE REFERENCES rssadapt.9:.Sh CODE REFERENCES syscall.9:.Sh CODE REFERENCES tc_init.9:.Sh CODE REFERENCES tfind.9:.Sh CODE REFERENCES timeout.9:.Sh CODE REFERENCES tsleep.9:.Sh CODE REFERENCES tvtohz.9:.Sh CODE REFERENCES vfs_cache.9:.Sh CODE REFERENCES vinvalbuf.9:.Sh PSEUDOCODE vnsubr.9:.Sh CODE REFERENCES wdog_register.9:.Sh CODE REFERENCES NetBSD has it, too: https://man.openbsd.org/?query=Sh%3DCODE\+REFERENCES=1=NetBSD-7.1 On the one hand, i agree that very short sections aren't very pretty. On the other hand, the purpose of CODE REFERENCES is sufficiently different from DESCRIPTION, and its use sufficiently widespread, that it may help kernel hackers to quickly locate this information. I'm not sure in this respect. Yours, Ingo
Re: tweaks to namei.9
On Thu, Aug 02, 2018 at 05:16:18PM +0200, Ingo Schwarze wrote:
> Hi,
>
> the first paragraph of the DESCRIPTION is all fluff.
> Let's just wipe it away completely, we always want
> the DESCRIPTION to be concise and get to the point.
>
> Instead, provide some real HISTORY.
>
> DESCRIPTION: minus five lines, same amount of information.
> HISTORY: plus three lines, but now containing some real data.
>
> OK?
> Ingo
>
ok by me. you might get away with removing the last sentence of BUGS
now, since HISTORY almost provides the same. while we're chopping, i'd
prefer to see the one line section that is CODE REFERENCES integrated
into DESCRIPTION.
jmc
>
> Index: namei.9
> ===
> RCS file: /cvs/src/share/man/man9/namei.9,v
> retrieving revision 1.18
> diff -u -r1.18 namei.9
> --- namei.9 23 Nov 2015 17:53:57 - 1.18
> +++ namei.9 2 Aug 2018 15:07:03 -
> @@ -57,20 +57,9 @@
> .Sh DESCRIPTION
> The
> .Fn namei
> -function is used to convert pathnames to file system vnodes.
> -The
> -name of the function is actually a contraction of the words
> -.Em name
> -and
> -.Em inode
> -for name-to-inode conversion, in the days before the
> -.Xr vfs 9
> -interface was implemented.
> -.Pp
> -The arguments passed to the functions are encapsulated in the
> -.Em nameidata
> -structure.
> -It has the following structure:
> +function converts a pathname to a
> +.Xr vnode 9 .
> +It uses the following structure:
> .Bd -literal
> struct nameidata {
> /*
> @@ -309,6 +298,16 @@
> .Xr vfs 9 ,
> .Xr vnode 9 ,
> .Xr VOP_LOOKUP 9
> +.Sh HISTORY
> +The
> +.Fn namei
> +function first appeared in
> +.At v4 .
> +Its name is an abbreviation for the name-to-inode conversion
> +which it performed before the appearance of
> +.Xr vfs 9
> +in
> +.Bx 4.3 Reno .
> .Sh BUGS
> It is unfortunate that much of the
> .Nm
>
Re: tweaks to namei.9
Hi,
the first paragraph of the DESCRIPTION is all fluff.
Let's just wipe it away completely, we always want
the DESCRIPTION to be concise and get to the point.
Instead, provide some real HISTORY.
DESCRIPTION: minus five lines, same amount of information.
HISTORY: plus three lines, but now containing some real data.
OK?
Ingo
Index: namei.9
===
RCS file: /cvs/src/share/man/man9/namei.9,v
retrieving revision 1.18
diff -u -r1.18 namei.9
--- namei.9 23 Nov 2015 17:53:57 - 1.18
+++ namei.9 2 Aug 2018 15:07:03 -
@@ -57,20 +57,9 @@
.Sh DESCRIPTION
The
.Fn namei
-function is used to convert pathnames to file system vnodes.
-The
-name of the function is actually a contraction of the words
-.Em name
-and
-.Em inode
-for name-to-inode conversion, in the days before the
-.Xr vfs 9
-interface was implemented.
-.Pp
-The arguments passed to the functions are encapsulated in the
-.Em nameidata
-structure.
-It has the following structure:
+function converts a pathname to a
+.Xr vnode 9 .
+It uses the following structure:
.Bd -literal
struct nameidata {
/*
@@ -309,6 +298,16 @@
.Xr vfs 9 ,
.Xr vnode 9 ,
.Xr VOP_LOOKUP 9
+.Sh HISTORY
+The
+.Fn namei
+function first appeared in
+.At v4 .
+Its name is an abbreviation for the name-to-inode conversion
+which it performed before the appearance of
+.Xr vfs 9
+in
+.Bx 4.3 Reno .
.Sh BUGS
It is unfortunate that much of the
.Nm
Re: tweaks to namei.9
Rob Pierce(r...@2keys.ca) on 2018.08.02 14:26:54 +:
> On Thu, Aug 02, 2018 at 03:15:14PM +0100, Jason McIntyre wrote:
> > On Thu, Aug 02, 2018 at 01:58:38PM +, Rob Pierce wrote:
> > > A little less wordy when introducing the namieidata structure.
> > >
> > > Ok?
> > >
> > > Index: namei.9
> > > ===
> > > RCS file: /cvs/src/share/man/man9/namei.9,v
> > > retrieving revision 1.18
> > > diff -u -p -r1.18 namei.9
> > > --- namei.9 23 Nov 2015 17:53:57 - 1.18
> > > +++ namei.9 2 Aug 2018 13:51:43 -
> > > @@ -67,10 +67,9 @@ for name-to-inode conversion, in the day
> > > .Xr vfs 9
> > > interface was implemented.
> > > .Pp
> > > -The arguments passed to the functions are encapsulated in the
> > > +Arguments passed to these functions are encapsulated in the following
> > > .Em nameidata
> > > -structure.
> > > -It has the following structure:
> > > +structure:
> > > .Bd -literal
> > > struct nameidata {
> > > /*
> > >
> >
> > hi.
> >
> > i'm not sure it's a big win - it's just another way of saying the same
> > thing. but now it can be interpreted to mean that there are more than one
> > type of namei structure.
> >
> > the use of "structure" twice isn;t ideal though, i agree.
> >
> > jmc
>
> I agree, this is not a big win, but when I read four instances of "the" and
> two
> instances of "structure" in two sentence where one would do, I start to lose
> focus. I don't see how this could be misinterpreted, but maybe I am missing
> something.
One could even drop the .Em nameidata because the
name of the structure is given just below.
And the functions signatures have struct nameidata *ndp, so there is no
reason to think there might be some other...
Re: tweaks to namei.9
On Thu, Aug 02, 2018 at 03:15:14PM +0100, Jason McIntyre wrote:
> On Thu, Aug 02, 2018 at 01:58:38PM +, Rob Pierce wrote:
> > A little less wordy when introducing the namieidata structure.
> >
> > Ok?
> >
> > Index: namei.9
> > ===
> > RCS file: /cvs/src/share/man/man9/namei.9,v
> > retrieving revision 1.18
> > diff -u -p -r1.18 namei.9
> > --- namei.9 23 Nov 2015 17:53:57 - 1.18
> > +++ namei.9 2 Aug 2018 13:51:43 -
> > @@ -67,10 +67,9 @@ for name-to-inode conversion, in the day
> > .Xr vfs 9
> > interface was implemented.
> > .Pp
> > -The arguments passed to the functions are encapsulated in the
> > +Arguments passed to these functions are encapsulated in the following
> > .Em nameidata
> > -structure.
> > -It has the following structure:
> > +structure:
> > .Bd -literal
> > struct nameidata {
> > /*
> >
>
> hi.
>
> i'm not sure it's a big win - it's just another way of saying the same
> thing. but now it can be interpreted to mean that there are more than one
> type of namei structure.
>
> the use of "structure" twice isn;t ideal though, i agree.
>
> jmc
I agree, this is not a big win, but when I read four instances of "the" and two
instances of "structure" in two sentence where one would do, I start to lose
focus. I don't see how this could be misinterpreted, but maybe I am missing
something.
Rob
Re: tweaks to namei.9
On Thu, Aug 02, 2018 at 01:58:38PM +, Rob Pierce wrote:
> A little less wordy when introducing the namieidata structure.
>
> Ok?
>
> Index: namei.9
> ===
> RCS file: /cvs/src/share/man/man9/namei.9,v
> retrieving revision 1.18
> diff -u -p -r1.18 namei.9
> --- namei.9 23 Nov 2015 17:53:57 - 1.18
> +++ namei.9 2 Aug 2018 13:51:43 -
> @@ -67,10 +67,9 @@ for name-to-inode conversion, in the day
> .Xr vfs 9
> interface was implemented.
> .Pp
> -The arguments passed to the functions are encapsulated in the
> +Arguments passed to these functions are encapsulated in the following
> .Em nameidata
> -structure.
> -It has the following structure:
> +structure:
> .Bd -literal
> struct nameidata {
> /*
>
hi.
i'm not sure it's a big win - it's just another way of saying the same
thing. but now it can be interpreted to mean that there are more than one
type of namei structure.
the use of "structure" twice isn;t ideal though, i agree.
jmc
tweaks to namei.9
A little less wordy when introducing the namieidata structure.
Ok?
Index: namei.9
===
RCS file: /cvs/src/share/man/man9/namei.9,v
retrieving revision 1.18
diff -u -p -r1.18 namei.9
--- namei.9 23 Nov 2015 17:53:57 - 1.18
+++ namei.9 2 Aug 2018 13:51:43 -
@@ -67,10 +67,9 @@ for name-to-inode conversion, in the day
.Xr vfs 9
interface was implemented.
.Pp
-The arguments passed to the functions are encapsulated in the
+Arguments passed to these functions are encapsulated in the following
.Em nameidata
-structure.
-It has the following structure:
+structure:
.Bd -literal
struct nameidata {
/*
