From: Georges Khaznadar <georgesk@debian.org>
Date: Wed, 11 Oct 2023 11:43:22 +0200
Subject: crontab_5_manpage
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Fixed the phrasing of the manual page, tanks to Reuben Thomas, and
included 積丹尼 Dan Jacobson's nice example into crontab.5
---
 crontab.5 | 114 ++++++++++++++++++++------------------------------------------
 1 file changed, 36 insertions(+), 78 deletions(-)

diff --git a/crontab.5 b/crontab.5
index 260fee9..a49d89f 100644
--- a/crontab.5
+++ b/crontab.5
@@ -33,20 +33,15 @@ their own crontabs, eliminating the need for explicitly running
 .IR su (1)
 as part of a cron command.
 .PP
-Blank lines and leading spaces and tabs are ignored.  Lines whose first
-non-space character is a hash-sign (#) are comments, and are ignored.
-Note that comments are not allowed on the same line as cron commands, since
-they will be taken to be part of the command.  Similarly, comments are not
-allowed on the same line as environment variable settings.
+Note that comments on the same line as cron commands are not interpreted as
+comments in the cron sense, but are considered part of the command and passed
+to the shell. This is similarly true for comments on the same line as
+environment variable settings.
 .PP
 An active line in a crontab will be either an environment setting or a cron
-command.  The crontab file is parsed from top to bottom, so any environment
-settings will affect only the cron commands below them in the file.
-An environment setting is of the form,
+command.  An environment setting is of the form,
 .PP
-.in +4n
-name = value
-.in
+    name = value
 .PP
 where the spaces around the equal-sign (=) are optional, and any subsequent
 non-leading spaces in
@@ -91,53 +86,21 @@ Several environment variables are set up automatically by the
 .IR cron (8)
 daemon.
 SHELL is set to /bin/sh, and LOGNAME and HOME are set from the /etc/passwd
-line of the crontab's owner.  PATH is set to "/usr/bin:/bin".
-HOME, SHELL, and PATH may be overridden by settings in the crontab;
-LOGNAME is the user that the job is running from, and may not be changed.
+line of the crontab's owner.
+HOME and SHELL may be overridden by settings in the crontab; LOGNAME may not.
 .PP
 (Another note: the LOGNAME variable is sometimes called USER on BSD systems...
 on these systems, USER will be set also.)
 .PP
 In addition to LOGNAME, HOME, and SHELL,
 .IR cron (8)
-will look at MAILTO and MAILFROM if it has any reason to send mail as a result
-of running commands in ``this'' crontab.
-.PP
-If MAILTO is defined (and non-empty), mail is sent to the user so named.
-MAILTO may also be used to direct mail to multiple recipients by separating
-recipient users with a comma.  If MAILTO is defined but empty (MAILTO=""),
-no mail will be sent.  Otherwise mail is sent to the owner of the crontab.
-.PP
-If MAILFROM is defined, the sender email address is set to MAILFROM. Otherwise
-mail is sent as "root (Cron Daemon)".
-.PP
-On the Debian GNU/Linux system, cron supports the
-.B pam_env
-module, and loads the environment specified by
-.I /etc/environment
-and
-.IR /etc/security/pam_env.conf .
-It also reads locale information from
-.IR /etc/default/locale .
-However, the PAM settings do
-.B NOT
-override the settings described above nor any settings in the
-.I crontab
-file itself.  Note in particular that if you want a PATH other than
-"/usr/bin:/bin", you will need to set it in the crontab file.
-.PP
-By default, cron will send mail using the mail "Content-Type:" header of
-"text/plain" with the "charset=" parameter set to the charmap / codeset of the
-locale in which
-.IR crond (8)
-is started up \(en i.e.\& either the default system locale,
-if no LC_* environment variables are set, or the locale specified by
-the LC_* environment variables
-( see
-.IR locale (7) ).
-You can use different character encodings for mailed cron job output by
-setting the CONTENT_TYPE and CONTENT_TRANSFER_ENCODING variables in crontabs,
-to the correct values of the mail headers of those names.
+will look at MAILTO if it has any reason to send mail as a result of running
+commands in ``this'' crontab.  If MAILTO is defined (and non-empty), mail is
+sent to the user so named.  If MAILTO is defined but empty (MAILTO=""), no
+mail will be sent.  Otherwise mail is sent to the owner of the crontab.  This
+option is useful if you decide on /bin/mail instead of /usr/lib/sendmail as
+your mailer when you install cron -- /bin/mail doesn't do aliasing, and UUCP
+usually doesn't read its mail.
 .PP
 The format of a cron command is very much the V7 standard, with a number of
 upward-compatible extensions.  Each line has five time and date fields,
@@ -163,30 +126,30 @@ field	allowed values
 .br
 -----	--------------
 .br
-minute	0\(en59
+minute	0-59
 .br
-hour	0\(en23
+hour	0-23
 .br
-day of month	1\(en31
+day of month	0-31
 .br
-month	1\(en12 (or names, see below)
+month	0-12 (or names, see below)
 .br
-day of week	0\(en7 (0 or 7 is Sun, or use names)
+day of week	0-7 (0 or 7 is Sun, or use names)
 .br
 .PP
 A field may be an asterisk (*), which always stands for ``first\-last''.
 .PP
 Ranges of numbers are allowed.  Ranges are two numbers separated
 with a hyphen.  The specified range is inclusive.  For example,
-8\-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
+8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
 and 11.
 .PP
 Lists are allowed.  A list is a set of numbers (or ranges)
-separated by commas.  Examples: ``1,2,5,9'', ``0\-4,8\-12''.
+separated by commas.  Examples: ``1,2,5,9'', ``0-4,8-12''.
 .PP
 Step values can be used in conjunction with ranges.  Following
 a range with ``/<number>'' specifies skips of the number's value
-through the range.  For example, ``0\-23/2'' can be used in the hours
+through the range.  For example, ``0-23/2'' can be used in the hours
 field to specify command execution every other hour (the alternative
 in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22'').  Steps are
 also permitted after an asterisk, so if you want to say ``every two
@@ -201,16 +164,15 @@ The ``sixth'' field (the rest of the line) specifies the command to be
 run.
 The entire command portion of the line, up to a newline or %
 character, will be executed by /bin/sh or by the shell
-specified in the SHELL variable of the crontab file.
+specified in the SHELL variable of the cronfile.
 Percent-signs (%) in the command, unless escaped with backslash
-(\e), will be changed into newline characters, and all data
+(\\), will be changed into newline characters, and all data
 after the first % will be sent to the command as standard
-input.  There is no way to split a single command line onto multiple
-lines, like the shell's trailing "\e".
+input.
 .PP
 Note: The day of a command's execution can be specified by two
 fields \(em day of month, and day of week.  If both fields are
-restricted (i.e., don't start with *), the command will be run when
+restricted (i.e., aren't *), the command will be run when
 .I either
 field matches the current time.  For example,
 .br
@@ -252,19 +214,16 @@ or other facilities, were startup.  This is due to the boot order
 sequence of the machine.
 
 .SH EXAMPLE CRON FILE
-
-The following lists an example of a user crontab file.
-
 .nf
 
-# use /bin/bash to run commands, instead of the default /bin/sh
-SHELL=/bin/bash
+# use /bin/sh to run commands, no matter what /etc/passwd says
+SHELL=/bin/sh
 # mail any output to `paul', no matter whose crontab this is
 MAILTO=paul
 #
 # run five minutes after midnight, every day
 5 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
-# run at 2:15pm on the first of every month \(em output mailed to paul
+# run at 2:15pm on the first of every month -- output mailed to paul
 15 14 1 * *     $HOME/bin/monthly
 # run at 10 pm on weekdays, annoy Joe
 0 22 * * 1\-5    mail \-s "It's 10pm" joe%Joe,%%Where are your kids?%
@@ -338,13 +297,12 @@ cron(8), crontab(1)
 When specifying day of week, both day 0 and day 7 will be considered Sunday.
 BSD and AT&T seem to disagree about this.
 .PP
-Lists and ranges are allowed to co-exist in the same field.
-"1\-3,7\-9" would be rejected by AT&T or BSD cron \(em they want
-to see "1\-3" or "7,8,9" ONLY.
+Lists and ranges are allowed to co-exist in the same field.  "1-3,7-9" would
+be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY.
 .PP
-Ranges can include "steps", so "1\-9/2" is the same as "1,3,5,7,9".
+Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
 .PP
-Months or days of the week can be specified by name.
+Names of monts or days of the week can be specified by name.
 .PP
 Environment variables can be set in the crontab.  In BSD or AT&T, the
 environment handed to child processes is basically the one from /etc/rc.
@@ -420,5 +378,5 @@ A warning will be written to syslog.
 Paul Vixie <paul@vix.com> is the author of
 .I cron
 and original creator of this manual page.  This page has also been modified for
-Debian by Steve Greenland, Javier Fernandez-Sanguino, Christian Kastner and
-Christian Pekeler.
+Debian by Steve Greenland, Javier Fernandez-Sanguino, Christian Kastner,
+Christian Pekeler, Georges Khaznadar.