Bug 43364

Summary: Man page for hier(7) doesn' have /var/empty
Product: Documentation Reporter: Kim Scarborough <sluggo>
Component: Books & ArticlesAssignee: Ceri Davies <ceri>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
file.diff none

Description Kim Scarborough 2002-09-25 16:50:02 UTC 
 The man page for hier(7) doesn't explain what /var/empty is.

How-To-Repeat: man 7 hier
Comment 1 Gary W. Swearingen 2002-09-25 18:29:28 UTC 
> + empty directory used by sshd(8) for privilege separation;
> + see
> + .Xr sshd 8

That huge manual doesn't need the extra words "for privilege separation"
which will make sense to few and which those who "see sshd(8)" will find
used there (as if it'll be of any real help to them).
Comment 2 Kim Scarborough 2002-09-25 18:42:57 UTC 
> That huge manual doesn't need the extra words "for privilege separation"
> which will make sense to few and which those who "see sshd(8)" will find
> used there (as if it'll be of any real help to them).

Heh, as opposed to user-friendly terms such as "POSIX real-time extensions
includes" or "genclass prototype/template class files", I suppose. If the 15
bytes saved by the deletion of those three words is really that important,
then yeah, take it out; otherwise, I think it should follow the format of just
about every other cross-referenced listing in there and have a brief
explanation of its function.
Comment 3 Gary W. Swearingen 2002-09-25 23:20:32 UTC 
"Kim Scarborough" <sluggo@unknown.nu> writes:

> > That huge manual doesn't need the extra words "for privilege separation"
> > which will make sense to few and which those who "see sshd(8)" will find
> > used there (as if it'll be of any real help to them).
> 
> Heh, as opposed to user-friendly terms such as "POSIX real-time extensions
> includes" or "genclass prototype/template class files", I suppose. If the 15
> bytes saved by the deletion of those three words is really that important,
> then yeah, take it out; otherwise, I think it should follow the format of just
> about every other cross-referenced listing in there and have a brief
> explanation of its function.

It's not about saving 15 bytes.  It's about saving people from having to
think about an explanation which explains nothing.  It's just noise.
Following the bad example of some other entries of the manual only makes
a poor manual worse.
Comment 4 Ceri Davies freebsd_committer freebsd_triage 2002-09-26 18:07:16 UTC 
Gary W. Swearingen wrote:
>On Wed, Sep 25, 2002 at 11:46:47AM -0400, Kim Scarborough wrote:
> 
>  > + empty directory used by sshd(8) for privilege separation;
>  > + see
>  > + .Xr sshd 8
>  
>  That huge manual doesn't need the extra words "for privilege separation"
>  which will make sense to few and which those who "see sshd(8)" will find
>  used there (as if it'll be of any real help to them).

I think it's reasonable to expect users to cross-reference manuals.
With the privilege separation pointer, they'll know what they are looking for
when they fire up the sshd manual as well.

Ceri

-- 
you can't see when light's so strong
you can't see when light is gone
Comment 5 Ceri Davies freebsd_committer freebsd_triage 2002-09-26 18:12:20 UTC 
State Changed
From-To: open->patched

Your patch was committed to -current. 
Thanks for your submission.
Comment 6 Ceri Davies freebsd_committer freebsd_triage 2002-09-26 18:12:20 UTC 
Responsible Changed
From-To: freebsd-doc->ceri

My MFC reminder.
Comment 7 Ceri Davies freebsd_committer freebsd_triage 2002-10-10 20:24:02 UTC 
State Changed
From-To: patched->closed

Your change was MFC'd.  Thanks again!