NetBSD Problem Report #35718

From woods@always.weird.com  Mon Feb 19 21:01:16 2007
Return-Path: <woods@always.weird.com>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
	by narn.NetBSD.org (Postfix) with ESMTP id 26F4963B879
	for <gnats-bugs@gnats.NetBSD.org>; Mon, 19 Feb 2007 21:01:16 +0000 (UTC)
Message-Id: <m1HJFdI-0051gFC@always.weird.com>
Date: Mon, 19 Feb 2007 16:01:12 -0500 (EST)
From: "Greg A. Woods" <woods@planix.com>
Sender: "Greg A. Woods" <woods@always.weird.com>
Reply-To: "Greg A. Woods" <woods@planix.com>
To: NetBSD GNATS <gnats-bugs@NetBSD.org>
Subject: security(8) should be renamed to not be confused as a man page for the /etc/security script
X-Send-Pr-Version: 3.95

>Number:         35718
>Category:       misc
>Synopsis:       security(8) should be renamed to not be confused as a man page for the /etc/security script
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Feb 19 21:05:00 +0000 2007
>Closed-Date:    Fri Mar 18 15:25:24 +0000 2011
>Last-Modified:  Fri Mar 18 15:35:01 +0000 2011
>Originator:     Greg A. Woods
>Release:        NetBSD 4.0
>Organization:
Planix, Inc.; Toronto, Ontario; Canada
>Environment:
System: NetBSD-4
>Description:

	The new security(8) manual page should be renamed such that it
	cannot be confused as a manual page for the /etc/security
	script.

	There should also be a section-8 manual page for all the
	standard cron-driven system management and maintenance scripts
	too I suppose.

>How-To-Repeat:

>Fix:

	One possibility to dealing with the security(8) conflict would
	be to move the page about systems security into section 7.

	The problem with section 8 of BSD's manual is that it is
	over-loaded in meaning.  That was one of the really nice
	things about the UNIX manuals having *m sections for
	maintenance and management related programs and files and such
	and not cluttering any section with both references for
	specific commands and files along with other general
	information.

	In fact it might be nice if all the manual pages similar to
	this new security(8) manual page, i.e. the ones which don't
	explicitly deal with files, programs, or APIs, were moved into
	share/doc where they could be made chapters in the relevant
	book.  It would also be nice if "man" or some similar tool
	(e.g. "doc") could display (and search!) online readable
	copies of the share/doc books too of course.

	I could provide the missing cron-script manual pages as
	starters if that would help.

	I'd be happy to help edit some existing documents into
	suitable form to be used as chapters in share/doc books too.

	I could even help convert some of the share/doc books into
	mdoc intput too, since that might help make them more usable
	and easier to maintain and add onto in the ways I'm suggesting.

>Release-Note:

>Audit-Trail:
From: "Jeremy C. Reed" <reed@reedmedia.net>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: misc/35718: security(8) should be renamed to not be confused as
 a man page for the /etc/security script
Date: Mon, 19 Feb 2007 15:18:46 -0600 (CST)

 On Mon, 19 Feb 2007, Greg A. Woods wrote:

 > 	The new security(8) manual page should be renamed such that it
 > 	cannot be confused as a manual page for the /etc/security
 > 	script.
 > 
 > 	There should also be a section-8 manual page for all the
 > 	standard cron-driven system management and maintenance scripts
 > 	too I suppose.

 I recently proposed that. At first my diff has security.8 also because I 
 forgot about existing security(8).

 Index: share/man/man5/Makefile
 ===================================================================
 RCS file: /cvsroot/src/share/man/man5/Makefile,v
 retrieving revision 1.56
 diff -u -r1.56 Makefile
 --- share/man/man5/Makefile	12 Dec 2005 22:26:53 -0000	1.56
 +++ share/man/man5/Makefile	19 Feb 2007 21:15:31 -0000
 @@ -20,6 +20,9 @@
  MLINKS=	dir.5 dirent.5 fs.5 inode.5 hosts.equiv.5 rhosts.5
  MLINKS+=utmp.5 wtmp.5 utmp.5 lastlog.5 passwd.5 master.passwd.5
  MLINKS+=utmpx.5 wtmpx.5 utmpx.5 lastlogx.5
 +MLINKS+=daily.conf.5 daily.8 monthly.conf.5 monthly.8 weekly.conf.5 weekly.8
 +# No symlink is done for security.conf.5 because we have a
 +# different security.8 already.

  .include <bsd.man.mk>
  .include <bsd.subdir.mk>

 > >Fix:
 > 
 > 	One possibility to dealing with the security(8) conflict would
 > 	be to move the page about systems security into section 7.

 That is what I am thinking also:
 http://mail-index.netbsd.org/tech-userlevel/2007/02/06/0002.html

 > 	The problem with section 8 of BSD's manual is that it is
 > 	over-loaded in meaning.  That was one of the really nice
 > 	things about the UNIX manuals having *m sections for
 > 	maintenance and management related programs and files and such
 > 	and not cluttering any section with both references for
 > 	specific commands and files along with other general
 > 	information.
 > 
 > 	In fact it might be nice if all the manual pages similar to
 > 	this new security(8) manual page, i.e. the ones which don't
 > 	explicitly deal with files, programs, or APIs, were moved into
 > 	share/doc where they could be made chapters in the relevant
 > 	book.  It would also be nice if "man" or some similar tool
 > 	(e.g. "doc") could display (and search!) online readable
 > 	copies of the share/doc books too of course.
 > 
 > 	I could provide the missing cron-script manual pages as
 > 	starters if that would help.

 What are they?

 > 	I'd be happy to help edit some existing documents into
 > 	suitable form to be used as chapters in share/doc books too.
 > 
 > 	I could even help convert some of the share/doc books into
 > 	mdoc intput too, since that might help make them more usable
 > 	and easier to maintain and add onto in the ways I'm suggesting.

 Can you bring that up on maybe tech-userlevel list instead of proposing 
 that part in a PR?


   Jeremy C. Reed

State-Changed-From-To: open->closed
State-Changed-By: jruoho@NetBSD.org
State-Changed-When: Fri, 18 Mar 2011 15:25:24 +0000
State-Changed-Why:
I moved security(8) to the section 7, as suggested. If you have additional
concerns about documentation, a proper mailing list is a better medium.


From: "Jukka Ruohonen" <jruoho@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/35718 CVS commit: src
Date: Fri, 18 Mar 2011 15:21:58 +0000

 Module Name:	src
 Committed By:	jruoho
 Date:		Fri Mar 18 15:21:57 UTC 2011

 Modified Files:
 	src/distrib/sets/lists/man: mi
 	src/share/man/man7: Makefile intro.7
 	src/share/man/man8: Makefile
 Added Files:
 	src/share/man/man7: security.7
 Removed Files:
 	src/share/man/man8: security.8

 Log Message:
 Move security(8) to the section 7. Discussed on source-changes a while back.
 Should address PR # 35718 at least partially.


 To generate a diff of this commit:
 cvs rdiff -u -r1.1302 -r1.1303 src/distrib/sets/lists/man/mi
 cvs rdiff -u -r1.26 -r1.27 src/share/man/man7/Makefile
 cvs rdiff -u -r1.18 -r1.19 src/share/man/man7/intro.7
 cvs rdiff -u -r0 -r1.1 src/share/man/man7/security.7
 cvs rdiff -u -r1.99 -r1.100 src/share/man/man8/Makefile
 cvs rdiff -u -r1.28 -r0 src/share/man/man8/security.8

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

>Unformatted:

Home	PR Database Search