Bug 55653

Tony Maher <tonymaher@optushome.com.au> writes:

> 	Attached is patch which just notes this in the chflags.1 man page.

Good idea.

> +.Sh BUGS

The warning note would be better placed in a custom WARNING (or NOTES)
section, or in a standard COMPATIBILITY section or even in the
DESCRIPTION.  It's not about a chflags(1) bug.  The fact that other
manpages abuse their BUGS section is no reason for this one to do it.

> +Only a limited number of tools know about about chflags.

  --  Only a limited number of tools know about chflags.
  --  Only a limited number of tools know about file flags.
  --  Only a limited number of programs know about file flags.
  --  A limited number of programs know about file flags.
  --  Some programs do not know about file flags.
  --  Some programs do not handle file flags.
  --  Some programs which should handle file flags do not.

> +Some of the tools which are

It's debatable whether any of these tools/utilities/programs should be
listed in the manpage, mainly because it adds a continual source of
manpage bugs as file flags and their support changes from time to
time.  Also, the info would, to be consistent, need to be added to
chflags(2) and other manpages that deal with file flags.

I tend to like helpful manpages, but in this case I think it's better
to limit that help to the generic warning note and put these lists of
programs in a Handbook "File Flags" section, if anywhere.


Also: The tar(1) and pax(1) manpages should say in their BUGS sections
that they don't support file flags, if that's the case.

Hello,

thanks for feedback.

>> +.Sh BUGS
>
> The warning note would be better placed in a custom WARNING (or NOTES)
> section, or in a standard COMPATIBILITY section or even in the
> DESCRIPTION.  It's not about a chflags(1) bug.  The fact that other
> manpages abuse their BUGS section is no reason for this one to do it.

I agree but the example man pages I looked at used bugs.
But I dont care how its done, I'll leave it up to a docs person.

> It's debatable whether any of these tools/utilities/programs should be
> listed in the manpage, mainly because it adds a continual source of
> manpage bugs as file flags and their support changes from time to
> time.  Also, the info would, to be consistent, need to be added to
> chflags(2) and other manpages that deal with file flags.
>
> I tend to like helpful manpages, but in this case I think it's better
> to limit that help to the generic warning note and put these lists of
> programs in a Handbook "File Flags" section, if anywhere.

I prefer man pages since they are more accessible. I liked the info
all in the once place so that someone reading about chflags would
immediately be aware that there could be problems using copy mecahnisms like
tar and pax.

That said I am happy for whatever the docs people decide 
matches best with FreeBSD docs practice.

> Also: The tar(1) and pax(1) manpages should say in their BUGS sections
> that they don't support file flags, if that's the case.

That would be useful.

cheers
--
tonym

Comment 3 Tom Rhodes 2005-02-23 23:08:27 UTC

State Changed
From-To: open->patched

Slightly modified version committed to CURRENT, MFC pending. 

Comment 4 Tom Rhodes 2005-02-23 23:08:27 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

Over to me for the pending MFC.

Comment 5 Tom Rhodes 2005-02-26 04:50:33 UTC

State Changed
From-To: patched->closed

MFC complete, close this PR.