CfR: config chapter changes
Glen Barber
gjb at FreeBSD.org
Thu Feb 16 01:53:06 UTC 2012
On Wed, Feb 15, 2012 at 08:31:33PM -0500, Eitan Adler wrote:
> Everyone,
>
> Thanks for the input.
>
> Here is the current version.
>
> Index: chapter.sgml
> ===================================================================
> RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v
> retrieving revision 1.251
> diff -u -r1.251 chapter.sgml
> --- chapter.sgml 13 Feb 2012 04:28:35 -0000 1.251
> +++ chapter.sgml 16 Feb 2012 01:29:21 -0000
> @@ -473,13 +473,13 @@
> certain times.</para>
>
> <para>The <command>cron</command> utility uses two different
> - types of configuration files, the system crontab and user crontabs. The
> - only difference between these two formats is the sixth field. In the
> - system crontab, the sixth field is the name of a user for the command
> - to run as. This gives the system crontab the ability to run commands
> - as any user. In a user crontab, the sixth field is the command to run,
> - and all commands run as the user who created the crontab; this is an
> - important security feature.</para>
> + types of configuration files, the system crontab and user crontabs.
> + These formats only differ in the sixth field and later. In the
> + system crontab, <command>cron</command> will run the command as the user
> + specified in the sixth field. In a user crontab, all commands run as
> + the user who created the crontab, 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
> @@ -487,10 +487,11 @@
> permissions of the user who owns the crontab.</para>
>
> <para>The <username>root</username> user can have a user
> crontab just like
> - any other user. This one is different from
> - <filename>/etc/crontab</filename> (the system crontab). Because of the
> - system crontab, there is usually no need to create a user crontab
> - for <username>root</username>.</para>
> + any other user. The <username>root</username> user crontab is
> + distinct from <filename>/etc/crontab</filename> (the system crontab).
I don't understand this sentence. "Distinct" why/how? Maybe it would
be better to just say "separate" here.
> + Because the system system crontab effectively invokes the
> + specified commands as root there is usually no need to
> + create a user crontab for <username>root</username>.</para>
> </note>
>
> <para>Let us take a look at the <filename>/etc/crontab</filename> file
> @@ -547,11 +548,8 @@
> day of the week. All these fields must be numeric values, and follow
> the twenty-four hour clock. The <literal>who</literal> field is special,
> and only exists in the <filename>/etc/crontab</filename> file.
> - This field specifies which user the command should be run as.
> - When a user installs his or her <filename>crontab</filename> file, they
> - will not have this option. Finally, the <literal>command</literal>
> option is listed.
> - This is the last field, so naturally it should designate the command
> - to be executed.</para>
> + This field specifies which user the command should be run
> + as. The last field is the command to be executed.</para>
> </callout>
>
> <callout arearefs="co-main">
> @@ -584,8 +582,9 @@
> <title>Installing a Crontab</title>
>
> <important>
> - <para>You must not use the procedure described here to
> - edit/install the system crontab. Simply use your favorite
> + <para>Do not use the procedure described here to
> + edit and install the system crontab,
> + <filename>/etc/crontab</filename>. Simply use your favorite
> editor: the <command>cron</command> utility will notice that the file
> has changed and immediately begin using the updated version.
I would vote to reword this sentence. It's not part of the original
reasons for the changes to this file, I agree, but "simply" is
subjective. If it's so simple, why document it? Or, if it's so simple,
why did I need to read about it in the handbook?
> See
> @@ -596,7 +595,7 @@
> <para>To install a freshly written user
> <filename>crontab</filename>, first use your favorite editor to create
> a file in the proper format, and then use the
> - <command>crontab</command> utility. The most common usage
> + <command>crontab</command>man.crontab.8; utility. The most common usage
What I meant here is replacing the '<command>' tags entirely with
&man.crontab.8;. However, it looks like I fat-fingered the mdoc entity
reference; the crontab manual is in section 1, not section 8.
> is:</para>
>
> <screen>&prompt.user; <userinput>crontab
> crontab-file</userinput></screen>
> @@ -606,18 +605,17 @@
>
> <para>There is also an option to list installed
> <filename>crontab</filename> files: just pass the
> - <option>-l</option> option to <command>crontab</command> and look
> + <option>-l</option> option to
> <command>crontab</command>man.crontab.8; and look
I don't understand why this change was made. I think you replaced more
references to crontab than I pointed to.
> over the output.</para>
>
> <para>For users who wish to begin their own crontab file from scratch,
> without the use of a template, the <command>crontab -e</command>
> option is available. This will invoke the selected editor
> with an empty file. When the file is saved, it will be
> - automatically installed by the <command>crontab</command> command.
> - </para>
> + automatically installed by the
> <command>crontab</command>man.crontab.8; command.</para>
I don't understand why this change was made. I think you replaced more
references to crontab than I pointed to.
>
> <para>If you later want to remove your user <filename>crontab</filename>
> - completely, use <command>crontab</command> with the <option>-r</option>
> + completely, use <command>crontab</command>man.crontab.8; with the
I don't understand why this change was made. I think you replaced more
references to crontab than I pointed to.
> <option>-r</option>
> option.
> </para>
>
> @@ -636,7 +634,7 @@
> </authorgroup>
> </sect1info>
>
> - <title>Using rc under &os;</title>
> + <title>Using <literal>rc</literal> Under &os;</title>
>
I'd replace "<literal>rc</literal>" with "&man.rc.8;" here.
> <para>In 2002 &os; integrated the NetBSD
> <filename>rc.d</filename> system for system initialization.
> @@ -1674,7 +1672,7 @@
> </sect1>
>
> <sect1 id="configtuning-sysctl">
> - <title>Tuning with sysctl</title>
> + <title>Tuning with <command>sysctl</command></title>
>
I'd replace "<command>sysctl</command>" with "&man.sysctl.8;" here.
> <indexterm><primary>sysctl</primary></indexterm>
> <indexterm>
> @@ -1944,7 +1942,7 @@
> out of space and the update to fail.</para>
>
> <sect3>
> - <title>More Details about Soft Updates</title>
> + <title>More Details About Soft Updates</title>
>
I'm not sure this "about" should be capitalized. I may be wrong, but I
do not believe prepositions should be capitalized in titles like this
unless they are the first word of the title.
> <indexterm>
> <primary>Soft Updates</primary>
> @@ -2390,15 +2388,36 @@
> <xref linkend="swap-encrypting"> of the Handbook.</para>
>
> <sect2 id="new-drive-swap">
> - <title>Swap on a New Hard Drive</title>
> + <title>Swap on a New or Existing Hard Drive</title>
>
> - <para>The best way to add swap, of course, is to use this as an
> - excuse to add another hard drive. You can always use another
> - hard drive, after all. If you can do this, go reread the
> - discussion of swap space
> - in <xref linkend="configtuning-initial">
> - of the Handbook for some suggestions on how to best
> - arrange your swap.</para>
> + <para>Adding a new hard drive for swap gives better performance
> + than adding a partition on an existing drive. Setting up
> + partitions and hard drives is explained in
> + <xref linkend="disks-adding">. <xref linkend="configtuning-initial">
> + discusses partition layouts and swap partition size considerations.</para>
> +
> + <para>Use &man.swapon.8; to add a swap partition to the system.
> For example:</para>
> +
> + <screen>&prompt.root;
> <userinput>swapon<replaceable>/dev/ada1s1p2</replaceable></userinput></screen>
> +
> + <warning>
> + <para>It is possible to use any partition not currently mounted, even
> + if it already contains data. Using &man.swapon.8; on a partition that
> + contains data will overwrite and destroy that data.
> + Make sure that the partition to be added as swap
> + is really the intended partition before running
> + <command>swapon</command>.</para>
I'd replace the command tags with the mdoc macro for the swapon(8)
manual here.
> + </warning>
> +
> + <para>To automatically add this swap partition on boot,
> + add an entry to <filename>/etc/fstab</filename> for the
> + partition:</para>
> +
> + <programlisting><replaceable>/dev/ada1s1p1</replaceable> none swap sw 0 0</programlisting>
> +
> + <para>&man.fstab.5; explains the meaning of the entries and
> + their format in
> + <filename>/etc/fstab</filename>.</para>
> </sect2>
>
> <sect2 id="nfs-swap">
> @@ -2878,7 +2897,7 @@
> on Linux, it is likely a &os; driver problem and narrowing down
> which driver causes the problems will help us fix the problem.
> Note that the <acronym>ACPI</acronym> maintainers do not
> - usually maintain other drivers (e.g sound,
> + usually maintain other drivers (e.g., sound,
> <acronym>ATA</acronym>, etc.) so any work done on tracking
> down a driver problem should probably eventually be posted
> to the &a.current.name; list and mailed to the driver
> @@ -2898,7 +2917,7 @@
> </sect3>
>
> <sect3>
> - <title>System Hangs (temporary or permanent)</title>
> + <title>System Hangs (Temporary or Permanent)</title>
>
> <para>Most system hangs are a result of lost interrupts or an
> interrupt storm. Chipsets have a lot of problems based on how
> @@ -3058,7 +3077,7 @@
> how to fix them:</para>
>
> <sect3>
> - <title>_OS dependencies</title>
> + <title>_OS Dependencies</title>
>
> <para>Some <acronym>AML</acronym> assumes the world consists of
> various &windows; versions. You can tell &os; to claim it is
> @@ -3070,7 +3089,7 @@
> </sect3>
>
> <sect3>
> - <title>Missing Return statements</title>
> + <title>Missing Return Statements</title>
>
> <para>Some methods do not explicitly return a value as the
> standard requires. While <acronym>ACPI-CA</acronym>
> @@ -3112,8 +3131,7 @@
> </sect2>
>
> <sect2 id="ACPI-debugoutput">
> - <title>Getting Debugging Output From
> - <acronym>ACPI</acronym></title>
> + <title>Getting Debugging Output from <acronym>ACPI</acronym></title>
>
> <indexterm>
> <primary>ACPI</primary>
>
>
>
Glen
More information about the freebsd-doc
mailing list