Editorial review of cron section.

This probably belongs in Basics chapter.

1 files changed, 98 insertions, 100 deletions

diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.xml b/en_US.ISO8859-1/books/handbook/config/chapter.xml
index c85376c1e0..6fd9b20fdc 100644
--- a/en_US.ISO8859-1/books/handbook/config/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/config/chapter.xml
@@ -232,53 +232,41 @@ run_rc_command "$1"</programlisting>
       <secondary>configuration</secondary>
     </indexterm>
 
-    <para>One of the most useful utilities in &os; is &man.cron.8;.
+    <para>One of the most useful utilities in &os; is <application>cron</application>.
       This utility runs in the background and regularly checks
       <filename>/etc/crontab</filename> for tasks to execute and
       searches <filename>/var/cron/tabs</filename> for custom
-      &man.crontab.5; files.  These files store information about
-      specific functions which &man.cron.8; is supposed to perform at
-      certain times.</para>
-
-    <para>Two different types of configuration files are used by
-      &man.cron.8;: the system <filename>crontab</filename> and user
-      <filename>crontab</filename>s.  These formats only differ in the
-      sixth field and later.  In the system
-      <filename>crontab</filename>, &man.cron.8; runs the command as
-      the user specified in the sixth field.  In a user
-      <filename>crontab</filename>, all commands run as the user who
-      created the <filename>crontab</filename>, so the sixth field is
-      the last field; this is an important security feature.  The
-      final field is always the command to run.</para>
-
-    <note>
-      <para>User crontabs allow individual users to schedule tasks
-	without the need for
-	<systemitem class="username">root</systemitem> privileges.
-	Commands in a user's crontab run with the permissions of the
-	user who owns the crontab.</para>
-
-      <para>The <systemitem class="username">root</systemitem> user
-	can have a user <filename>crontab</filename> just like any
-	other user.  The
-	<systemitem class="username">root</systemitem> user
-	<filename>crontab</filename> is separate from the system
-	<filename>crontab</filename>,
-	<filename>/etc/crontab</filename>.  Because the system
-	<filename>crontab</filename> invokes the specified commands as
-	<systemitem class="username">root</systemitem>, there is
-	usually no need to create a user <filename>crontab</filename>
-	for <systemitem class="username">root</systemitem>.</para>
-    </note>
-
-    <para>Here is a sample entry from
+      crontab files.  These files are used to schedule
+      tasks which <application>cron</application> runs at the
+      specified times.  Each entry in a crontab defines a task to run
+      and is known as a <firstterm>cron job</firstterm>.</para>
+
+    <para>Two different types of configuration files are used:
+      the system crontab, which should not be modified, and user
+      crontabs, which can be created and edited as needed.  The format
+      used by these files is documented in &man.crontab.5;.  The
+      format of the system crontab, <filename>/etc/crontab</filename>
+      includes a <literal>who</literal> column which does not exist in
+      user crontabs.  In the system crontab,
+      <application>cron</application> runs the command as
+      the user specified in this column.  In a user
+      crontab, all commands run as the user who
+      created the crontab.</para>
+
+    <para>User crontabs allow
+      individual users to schedule their own tasks.  The <systemitem
+      class="username">root</systemitem> user
+      can also have a user <filename>crontab</filename> which can be
+      used to schedule tasks that do not exist in the system
+      <filename>crontab</filename>.</para>
+
+    <para>Here is a sample entry from the system crontab,
       <filename>/etc/crontab</filename>:</para>
 
     <programlisting># /etc/crontab - root's crontab for FreeBSD
 #
 # $FreeBSD$
 # <co xml:id="co-comments"/>
-#
 SHELL=/bin/sh
 PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/>
 #
@@ -288,7 +276,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/>
 
     <calloutlist>
       <callout arearefs="co-comments">
-	<para>Like most &os; configuration files, lines that begin
+	<para>Lines that begin
 	  with the <literal>#</literal> character are comments.  A
 	  comment can be placed in the file as a reminder of what and
 	  why a desired action is performed.  Comments cannot be on
@@ -302,91 +290,101 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/>
 	  define any environment settings.  In this example, it is
 	  used to define the <envar>SHELL</envar> and
 	  <envar>PATH</envar>.  If the <envar>SHELL</envar> is
-	  omitted, &man.cron.8; will use the default of &man.sh.1;.
-	  If the <envar>PATH</envar> is omitted, no default will be
-	  used and file locations will need to be absolute.</para>
+	  omitted, <application>cron</application> will use the default Bourne shell.
+	  If the <envar>PATH</envar> is omitted, the full path must be given to the
+	  command or script to run.</para>
       </callout>
 
       <callout arearefs="co-field-descr">
-	<para>This line defines a total of seven fields:
+	<para>This line defines the seven fields used in a system crontab:
 	  <literal>minute</literal>,
 	  <literal>hour</literal>, <literal>mday</literal>,
 	  <literal>month</literal>, <literal>wday</literal>,
 	  <literal>who</literal>, and <literal>command</literal>.
-	  These are almost all self explanatory.
-	  <literal>minute</literal> is the time in minutes when the
-	  specified command will be run.  <literal>hour</literal> is
-	  the hour when the specified command will be run.
-	  <literal>mday</literal> stands for day of the month and
-	  <literal>month</literal> designates the month.  The
-	  <literal>wday</literal> option stands for day of the week.
+	  The
+	  <literal>minute</literal> field is the time in minutes when the
+	  specified command will be run, the <literal>hour</literal> is
+	  the hour when the specified command will be run, the
+	  <literal>mday</literal> is the day of the month,
+	  <literal>month</literal> is the month, and
+	  <literal>wday</literal> is the day of the week.
 	  These fields must be numeric values, representing the
 	  twenty-four hour clock, or a <literal>*</literal>,
 	  representing all values for that field.  The
 	  <literal>who</literal> field only exists in the system
-	  crontab.  This field specifies which user the command
+	  crontab and specifies which user the command
 	  should be run as.  The last field is the command to be
 	  executed.</para>
       </callout>
 
       <callout arearefs="co-main">
-	<para>This last line defines the values discussed above.
-	  This example has a <literal>*/5</literal> listing,followed
-	  by several more <literal>*</literal> characters.  These
-	  <literal>*</literal> characters mean
-	  <quote>first-last</quote>, and can be interpreted as
-	  <emphasis>every</emphasis> time.  In this example,
-	  &man.atrun.8; is invoked by
+	<para>This entry defines the values for this cron job.
+	  The <literal>*/5</literal>, followed
+	  by several more <literal>*</literal> characters, specifies that
+	  <command>/usr/libexec/atrun</command> is invoked by
 	  <systemitem class="username">root</systemitem> every five
-	  minutes, regardless of the day or month.</para>
+	  minutes of every hour, of every day and day of the week, of
+	  every month.</para>
 
-	<para>Commands can have any number of flags passed to them;
-	  however, commands which extend to multiple lines need to be
+	<para>Commands can include any number of switches.
+	  However, commands which extend to multiple lines need to be
 	  broken with the backslash <quote>\</quote> continuation
 	  character.</para>
       </callout>
     </calloutlist>
 
-    <para>This is the basic setup for every &man.crontab.5;.
-      However, field number six, which specifies the username, only
-      exists in the system &man.crontab.5;.  This field should be
-      omitted for individual user &man.crontab.5; files.</para>
-
     <sect2 xml:id="configtuning-installcrontab">
-      <title>Installing a Crontab</title>
-
-      <important>
-	<para>Do not use the procedure described here to edit and
-	  install the system <filename>crontab</filename>,
-	  <filename>/etc/crontab</filename>.  Instead, use an editor
-	  and &man.cron.8; will notice that the file has changed and
-	  immediately begin using the updated version.  See <link
-	    xlink:href="&url.books.faq;/admin.html#root-not-found-cron-errors">this
-	    FAQ entry</link> for more information.</para>
-      </important>
-
-      <para>To install a freshly written user &man.crontab.5;, use
-	an editor to create and save a file in the proper format.
-	Then, specify the file name with &man.crontab.1;:</para>
-
-      <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
-
-      <para>In this example, <filename>crontab-file</filename> is the
-	filename of a &man.crontab.5; that was previously
-	created.</para>
-
-      <para>To list installed &man.crontab.5; files, pass
-	<option>-l</option> to &man.crontab.1;.</para>
-
-      <para>Users who wish to begin their own
-	<filename>crontab</filename> file from scratch, without the
-	use of a template, can use <command>crontab -e</command>.
-	This will invoke the default editor with an empty file.  When
-	this file is saved, it will be automatically installed by
-	&man.crontab.1;.</para>
-
-      <para>In order to remove a user &man.crontab.5; completely,
-	use <command>crontab -r</command>.</para>
+      <title>Creating a User Crontab</title>
+
+      <para>To create a user crontab, invoke
+	<command>crontab</command> in editor mode:</para>
+
+      <screen>&prompt.user; <userinput>crontab -e</userinput></screen>
+
+      <para>This will open the user's crontab using the default text
+	editor.  The first time a user runs this command, it will open
+	an empty file.  Once a user creates a crontab, this command
+	will open that file for editing.</para>
+
+    <para>It is useful to add these lines to the top of the crontab
+      file in order to set the environment variables and to remember
+      the meanings of the fields in the crontab:</para>
+      
+    <programlisting>SHELL=/bin/sh
+PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
+# Order of crontab fields
+# minute	hour	mday	month	wday	command</programlisting>
+
+    <para>Then add a line for each command or script to run,
+      specifying the time to run the command.  This example runs the
+      specified custom Bourne shell script every day at two in the
+      afternoon.  Since the path to the script is not specified in
+      <literal>PATH</literal>, the full path to the script is
+      given:</para>
+      
+    <programlisting>0	14	*	*	*	/usr/home/dru/bin/mycustomscript.sh</programlisting>
+
+    <tip>
+      <para>Before using a custom script, make sure it is executable
+	and test that it works as intended from the command line.
+	This is especially important if the script includes any
+	commands that deletes files using wildcards.</para>
+    </tip>
+
+      <para>When finished editing the crontab, save the file.  It
+	will automatically be installed and
+	<application>cron</application> will read the crontab and run
+	its cron jobs at their specified times.  To list the cron jobs
+	in a crontab, use this command:</para>
+
+      <screen>&prompt.user; <userinput>crontab -l</userinput>
+0	14	*	*	*	/usr/home/dru/bin/mycustomscript.sh</screen>
+
+      <para>To remove all of the cron jobs in a user crontab:</para>
+      
+      <screen>&prompt.user; <userinput>crontab -l</userinput>
+remove crontab for dru? <userinput>y</userinput></screen>
+      
     </sect2>
   </sect1>