Re: CVS commit: src/usr.bin/chflags
Valery Ushakov wrote: > I think that information *must* be there, as that's *the* place where > the names are (un)parsed. I'm not sure whether this information has > to be duplicated as-is in chflags(1), or whether chflags(1) can have a > less verbose version. Perhaps a simple See stat_flags(3) for a more detailed description of the meaning of these flags. or something like that? -Jan
Re: CVS commit: src/usr.bin/chflags
On Thu, May 25, 2023 at 09:59:41 -0400, Greg Troxel wrote: > Taylor R Campbell writes: > > > jschauma@'s change did help clarify (1) and (2). Let's try to work > > together to make it better? [...] > I would recommend: > > Noting that archive flag represents something in some foreign > filesystems, currently known to exist only for some MSDOS filesystems, > and that the specific filesystem should document that. > > Explaining that the nodump flag is a request that backup programs omit > the file from backups and to see dump(8). > > Be clearer about permissions. > > Drop the restatement of tokens into a third only-here namespace. > Instead, use paragraphs following to describe that each token means. I have added slightly more verbose descriptions to stat_flags(3) - which are the functions in -lutil used by several programs that deal with flag names and added a xref to it from chflags(1). That man page now lists all the alternative flag names too and explicitly mentions dump/nonodump as negation of nodump. I think that information *must* be there, as that's *the* place where the names are (un)parsed. I'm not sure whether this information has to be duplicated as-is in chflags(1), or whether chflags(1) can have a less verbose version. -uwe
Re: CVS commit: src/usr.bin/chflags
Date:Thu, 25 May 2023 09:59:41 -0400 From:Greg Troxel Message-ID: | Also, the man page does not explain that because "nodump" is the name of | a flag, one does "chflags dump foo" to remove the nodump flag. It doesn't really need to, as while that works, so does nonodump, which is more consistent with the others. kre
Re: CVS commit: src/usr.bin/chflags
Taylor R Campbell writes: > jschauma@'s change did help clarify (1) and (2). Let's try to work > together to make it better? Well said. I can shed a little light on some of the questions. > 1. What is `arch' or `archived' supposed to mean? Who sets it, who >pays attention to it, and what consequences does it have? Is it >obsolete? What was it used for? From the current text, I have no >idea! >From reading sources, I think it is exactly "the archive bit is set in the foreign filesystem entry that this vnode is representting" and that it is basically an MS-DOS thing that is likely not important (even to people that do not dismiss all things Windows!) any more. > 2. What is `nodump' supposed to mean? Who sets it, who pays attention >to it, and what consequences does it have? Does the kernel do >anything about it, or is it just an extra bit of storage that >programs like dump(8) can choose to examine? From the current >text, I have no idea! I believe it is just a bit that other programs can query, and that the intent is that dump(8) will decline to dump files with the bit set. (I intend, in my Copious Spare Time, to extend pkgsrc/sysutils/bup to respect this flag. I have previously made extensive use of nodump with dump. Partly because of lack of the bit in bup and partly for organizational sanity, I use /u0 and /n0 for things that should and should not be backed up. But that's me in case it helps motivate why nodump is useful, not about flag docs.) I believe that nodump continues to be relevant today. > 3. What is the difference between `system' and `user' immutable or >append-only? If I set uchg, does that mean the _owner_ can't >modify the file, or that _nobody_ can modify the file? Not useful for a 1 man page, but egrep '[SU]F_' /usr/include/sys/stat.h is illuminating to programmers. I believe, but would have to read the code to be 100% sure, that only root can modify schg and sappnd flags (and archive) either root or the owner can modify other flags (except on device files, on which only root may modify flags, for reasons that are unclear, but the rationale seems unimportant) etiher schg or uchg means the file can't be modified, probably, but it's possible that uchg applies to everybody but root and schg applies to everybody. A quick experiment shows that root cannot write to a gdt-owned file with the uchg bit set. Fundamentally there are 16 flag bits for user and 16 for system and I think it is baked in hard that only root can modify the system set. > jschauma@'s change did help clarify (1) and (2). Let's try to work > together to make it better? The fundamental issue is that the table attempts to - map the tokens used by chflags(1) (good) - to names that sort of represent the flags (which are fundamentally C preprocessor token) but are a third namespace that exists only here (bad) - describe the flags permissions as if they are individual, instead of simly saying that schg and sappend may be changed by superuser only (confusing) - does not give semantics (ok, because that is not consistent with a table) Also, the man page does not explain that because "nodump" is the name of a flag, one does "chflags dump foo" to remove the nodump flag. (I don't think it needs explanation that the design decision is that nodump is a flag, instead of dump, because the norms are that files tend not to have any flags set and that all files should be backed up.) I would recommend: Noting that archive flag represents something in some foreign filesystems, currently known to exist only for some MSDOS filesystems, and that the specific filesystem should document that. Explaining that the nodump flag is a request that backup programs omit the file from backups and to see dump(8). Be clearer about permissions. Drop the restatement of tokens into a third only-here namespace. Instead, use paragraphs following to describe that each token means.
Re: CVS commit: src/usr.bin/chflags
> Date: Thu, 25 May 2023 15:10:41 +0300 > From: Valery Ushakov > > This new paragraph is wedged right between the list of the options and > the continuation of that same paragraph that says that they can be > prefixed with "no". > > A description of an obsolete flag right in the middle of the manpage > is a very poor narrative choice. > > Calling nodump "not intuitive" is not intuitive. > > Anyway, this change is strictly for the worse. If you want to keep > these random tidbits of information, move them elsewhere, like HISTORY > section (which is probably the most appropriate place for the > obsolete, unused, compat-only msdos flag). Can I suggest framing this a little more constructively and a little less derisively? Personally I find the chflags options confusing, and I appreciate jschauma@ taking the time to sort them out and clarify the documentation even if it's not perfect the first time around. Here are some questions that come to mind when I read the man page as it is: 1. What is `arch' or `archived' supposed to mean? Who sets it, who pays attention to it, and what consequences does it have? Is it obsolete? What was it used for? From the current text, I have no idea! 2. What is `nodump' supposed to mean? Who sets it, who pays attention to it, and what consequences does it have? Does the kernel do anything about it, or is it just an extra bit of storage that programs like dump(8) can choose to examine? From the current text, I have no idea! 3. What is the difference between `system' and `user' immutable or append-only? If I set uchg, does that mean the _owner_ can't modify the file, or that _nobody_ can modify the file? jschauma@'s change did help clarify (1) and (2). Let's try to work together to make it better?
Re: CVS commit: src/usr.bin/chflags
Valery Ushakov wrote: > Anyway, this change is strictly for the worse. ¯\_(ツ)_/¯ I've reverted the change. -Jan
Re: CVS commit: src/usr.bin/chflags
Valery Ushakov writes: > On Thu, May 25, 2023 at 07:17:52 -0400, Greg Troxel wrote: > >> Jan Schaumann writes: >> >> > Valery Ushakov wrote: >> >> On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: >> > >> >> > Briefly describe the 'arch' and 'nodump' flags. >> >> >> >> What makes them special and why is that these two have to be described >> >> here and not in chflags(2), where the flags are actually defined? >> > >> > Unlike the other flags, they are not intuitive. As >> > they are exposed to the end-user (versus the >> > programmer), it seems useful to describe them in >> > section 1 of the manual pages. >> >> FWIW, I agree that the flags are user-facing rather than (only) >> programmer-facing, and thus should be described in a 1/8 manpage vs only >> a 2 manpage. > > Then *all* of them should be described in a proper narration. I'm not > objecting to that. I'm objecting to sticking the description of two > of them chosen seemingly at random in a place selected seemingly at > random. OK, that's a perfectly reasonable objection.
Re: CVS commit: src/usr.bin/chflags
On Thu, May 25, 2023 at 07:17:52 -0400, Greg Troxel wrote: > Jan Schaumann writes: > > > Valery Ushakov wrote: > >> On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: > > > >> > Briefly describe the 'arch' and 'nodump' flags. > >> > >> What makes them special and why is that these two have to be described > >> here and not in chflags(2), where the flags are actually defined? > > > > Unlike the other flags, they are not intuitive. As > > they are exposed to the end-user (versus the > > programmer), it seems useful to describe them in > > section 1 of the manual pages. > > FWIW, I agree that the flags are user-facing rather than (only) > programmer-facing, and thus should be described in a 1/8 manpage vs only > a 2 manpage. Then *all* of them should be described in a proper narration. I'm not objecting to that. I'm objecting to sticking the description of two of them chosen seemingly at random in a place selected seemingly at random. Yes, I can see how archive vs dump might be puzzling. But I still maintain that the last change made the narration strictly worse compositionally. -uwe
Re: CVS commit: src/usr.bin/chflags
On Wed, May 24, 2023 at 23:44:07 -0400, Jan Schaumann wrote: > Valery Ushakov wrote: > > On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: > > > > Briefly describe the 'arch' and 'nodump' flags. > > > > What makes them special and why is that these two have to be described > > here and not in chflags(2), where the flags are actually defined? > > Unlike the other flags, they are not intuitive. As > they are exposed to the end-user (versus the > programmer), it seems useful to describe them in > section 1 of the manual pages. This new paragraph is wedged right between the list of the options and the continuation of that same paragraph that says that they can be prefixed with "no". A description of an obsolete flag right in the middle of the manpage is a very poor narrative choice. Calling nodump "not intuitive" is not intuitive. Anyway, this change is strictly for the worse. If you want to keep these random tidbits of information, move them elsewhere, like HISTORY section (which is probably the most appropriate place for the obsolete, unused, compat-only msdos flag). -uwe
Re: CVS commit: src/usr.bin/chflags
Jan Schaumann writes: > Valery Ushakov wrote: >> On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: > >> > Briefly describe the 'arch' and 'nodump' flags. >> >> What makes them special and why is that these two have to be described >> here and not in chflags(2), where the flags are actually defined? > > Unlike the other flags, they are not intuitive. As > they are exposed to the end-user (versus the > programmer), it seems useful to describe them in > section 1 of the manual pages. FWIW, I agree that the flags are user-facing rather than (only) programmer-facing, and thus should be described in a 1/8 manpage vs only a 2 manpage.
Re: CVS commit: src/usr.bin/chflags
Valery Ushakov wrote: > On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: > > Briefly describe the 'arch' and 'nodump' flags. > > What makes them special and why is that these two have to be described > here and not in chflags(2), where the flags are actually defined? Unlike the other flags, they are not intuitive. As they are exposed to the end-user (versus the programmer), it seems useful to describe them in section 1 of the manual pages. > In any case, please, at least skim through mdoc.samples(7) once. I did. I suspect sometimes what's "obvious" ends up being subjective, though. 'Cm' looked to me to be intended for use with non-dash-preceded flags, not as arguments to the command. I might even have considered 'Ar' more "obvious". -Jan
Re: CVS commit: src/usr.bin/chflags
On Wed, May 24, 2023 at 22:33:17 +, Jan Schaumann wrote: > Module Name: src > Committed By: jschauma > Date: Wed May 24 22:33:17 UTC 2023 > > Modified Files: > src/usr.bin/chflags: chflags.1 > > Log Message: > Briefly describe the 'arch' and 'nodump' flags. What makes them special and why is that these two have to be described here and not in chflags(2), where the flags are actually defined? In any case, please, at least skim through mdoc.samples(7) once. Using Va, a "generic variable reference", is pretty obviously a wrong choice for a command line argument I would think. And nothing in the surrounding source to cargo-cult from (which is not a bad strategy, in general, if done judiciously) suggests that particular choice. -uwe
