From owner-freebsd-doc@FreeBSD.ORG Wed Apr 21 17:20:06 2010 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 68E081065672 for ; Wed, 21 Apr 2010 17:20:06 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 3E6238FC16 for ; Wed, 21 Apr 2010 17:20:06 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id o3LHK5Wi060916 for ; Wed, 21 Apr 2010 17:20:05 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id o3LHK5TW060913; Wed, 21 Apr 2010 17:20:05 GMT (envelope-from gnats) Date: Wed, 21 Apr 2010 17:20:05 GMT Message-Id: <201004211720.o3LHK5TW060913@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: "Julian H. Stacey" Cc: Subject: Re: bin/145912: trivial enhancement patch for man crontab X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: "Julian H. Stacey" List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 21 Apr 2010 17:20:06 -0000 The following reply was made to PR docs/145912; it has been noted by GNATS. From: "Julian H. Stacey" To: Garrett Cooper Cc: bug-followup@freebsd.org Subject: Re: bin/145912: trivial enhancement patch for man crontab Date: Wed, 21 Apr 2010 19:17:40 +0200 Hi, Reference: > From: Garrett Cooper > Date: Wed, 21 Apr 2010 09:47:35 -0700 > Message-id: Garrett Cooper wrote: > On Wed, Apr 21, 2010 at 6:38 AM, Julian H. Stacey wrote: > >> From:         Garrett Cooper > > > > Garrett Cooper wrote: > >> On Wed, Apr 21, 2010 at 3:12 AM, Julian H. Stacey wrote: > >> > >> >  .Bl -tag -width /var/cron/allow -compact > >> >  .It Pa /var/cron/allow > >> >  .It Pa /var/cron/deny > >> > + .It Pa /var/cron/tabs/{login_names} > >> > >>     Should {login_names} be removed > > > > It cant be removed because it does not exist to remove, > > until after my send-pr is commited. > > > > > >>  because of the potential ambiguity > >> that it introduces > > > > What ambiguity ? > > /var/cron/tabs/{login_names} -> ENOENT (does not exist). > > The entry should be consistent in cron(8) and say: > > /var/cron/tabs > > at least, no more. OK, accepted. Possibly with a terminal slash ? eg /var/cron/tabs ? There's perhaps a style standard on omitting or appending '/' after "tabs" so I won't express opinion either way, whatever a committer chooses. > >> and be better defined through a description like > >> with cron(8)? > > > > Dont know what you mean. > > FILE DESCRIPTION > > /etc/crontab System crontab file > /etc/pam.d/cron pam.conf(5) configuration file for cron > /var/cron/tabs Directory for personal crontab files > > The files should be keyed pairs. This is an inconsistency in the > documentation that should be corrected. OK. (dont need a terminal '/' if we have description :-) > >> Also, there's no description of the proposed change in > >> the bug report, so for someone that's trying to figure out what this > >> change is doing > > > > It's a proposal for a one line change to a manual ! > > Yes, and if we're going to change this now, we might as well make it a > three line change to be consistent with cron(8) :)... /usr/bin/crontab does not edit /etc/crontab, so better mention /etc/crontab under SEE ALSO, not under FILES > >> from a customer perspective it would be nice if it > >> said something like 'add a reference noting where the default > >> installed crontabs are located', etc. > > > > > > Yawn !  Add that comment to the send-pr if you want, pretty obvious. > > Any `customer' who cant figure what a one line diff to a manual > > does is a customer opinion I dont care about :-) > > Posting to bug-followup already did that. OK > >>     Finally, this documentation kind of duplicates what's already in cron(8): > >> > >>      The cron utility searches /var/cron/tabs for crontab files which are > >>      named after accounts in /etc/passwd; crontabs found are loaded into mem- > >>      ory.  The cron utility also searches for /etc/crontab which is in a dif- > >>      ferent format (see crontab(5)). > > > > If you want, feel free to submit a send-pr for some wider consolidation > > of documentation, perhaps to move some tect from man cron to man crontab. > > Perhaps, but again... the details need to be logically consolidated. > Some entries are best kept in crontab(5) (like your proposed addition, > plus the description for it that's missing, and the reference to > /etc/crontab), and other pieces should be in cron(8) (like > /etc/pam.d/cron). > > If you don't want to provide the patch then I will make the > modification and post it ... inconsistent documentation leads to user > confusion which doesn't help the overall goal trying to be achieved in > having the documentation in the first place :). Well uou spotted more than me, so please post. > >> [...] > >> > >> FILES > >>      /etc/crontab     System crontab file > >>      /etc/pam.d/cron  pam.conf(5) configuration file for cron > >>      /var/cron/tabs   Directory for personal crontab files > > Thanks, > -Garrett Cheers, Julian -- Julian Stacey: BSD Unix Linux C Sys Eng Consultants Munich http://berklix.com Mail plain text, Not HTML quoted-printable Base64 http://www.asciiribbon.org