bin/145912: trivial enhancement patch for man crontab

[Julian H. Stacey]

The following reply was made to PR docs/145912; it has been noted by GNATS.

From: "Julian H. Stacey" <jhs at berklix.com>
To: Garrett Cooper <yanefbsd at gmail.com>
Cc: bug-followup at 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 <yanefbsd at gmail.com> 
 > Date:		Wed, 21 Apr 2010 09:47:35 -0700 
 > Message-id:	<j2k7d6fde3d1004210947h7df71d8ar192fedbd74152d23 at mail.gmail.com> 
 
 Garrett Cooper wrote:
 > On Wed, Apr 21, 2010 at 6:38 AM, Julian H. Stacey <jhs at berklix.com> wrote:
 > >> From:         Garrett Cooper <yanefbsd at gmail.com>
 > >
 > > Garrett Cooper wrote:
 > >> On Wed, Apr 21, 2010 at 3:12 AM, Julian H. Stacey <jhs at berklix.com> 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