[Bug 210621] poor "system crontab" documentation

[bugzilla-noreply at freebsd.org]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=210621

            Bug ID: 210621
           Summary: poor "system crontab" documentation
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Only Me
          Priority: ---
         Component: Documentation
          Assignee: freebsd-doc at FreeBSD.org
          Reporter: freebsd-bugzilla at ayaken.net

cron(8) mentions: "The cron utility also searches for /etc/crontab which is in
a different format (see crontab(5))"

crontab(5) then mentions, somewhere hidden inside the wall of text, the
specifics of the different format: "Each line has five time and date fields,
followed by a user name (with optional ``:<group>'' and ``/<login-class>''
suffixes) if this is the system crontab file, followed by a command."

So the specifics of the format of /etc/crontab are mentioned in a subclause in
the middle of crontab(5). What this extra field _does_ is not specified (one
would assume it's being used to su to the user, but there's no mention of what
effect either :group, nor /login-class would do on top of the user's native
group or login class).

I suggest moving the specifics of /etc/crontab's format into an own paragraph,
complete with paragraph header so that when glancing over crontab(5) one will
find it easily and quickly, along with _detailed_ information about what this
extra field does, also in conjunction with cron(8)'s flags, see below.

cron(8) mentions: "-J rootjitter Enable time jitter for superuser jobs.  The
same as -j except that it will affect jobs run by the superuser only."
- Does this apply to the "system crontab" only? Or to the root's USER crontab
only? Or to any *tab* run by root (i.e., /etc/crontab, root's crontab, toor's
crontab, and any other uid=0 user's crontab?) What about the aforementioned
sixth-user-name-field jobs in /etc/crontab? Does it apply -j or -J?

I suggest properly documenting this in cron(8), with a reminder in crontab(5).

/etc/crontab mentions: "/etc/crontab - root's crontab for FreeBSD". Well, it is
NOT root's crontab. (A) It has support for a special field that users' crontabs
don't, (B) root's "crontab -e" will NOT pull up /etc/crontab, but root's own
crontab.

I suggest s/root's/system/;s/D/D - cf. crontab(5)/

-- 
You are receiving this mail because:
You are the assignee for the bug.