CfR: config chapter changes

[Benjamin Kaduk]

On Fri, 10 Feb 2012, Eitan Adler wrote:

> I started working on editing the config chapter. The following is the work of
> Niclas Zeising, wblock, myself, and others in the #bsddocs channel.
>
> I'm looking for additional review of the following patch:
> http://people.freebsd.org/~eadler/files/yoda-can-has-a-donught.diff

Inline patches are easier to review.

% Index: chapter.sgml
% ===================================================================
% RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml,v
% retrieving revision 1.250
% diff -u -r1.250 chapter.sgml
% --- chapter.sgml	31 Jan 2012 14:14:59 -0000	1.250
% +++ chapter.sgml	10 Feb 2012 01:15:29 -0000
% @@ -475,22 +475,21 @@
%      <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,
% +      system crontab, <command>cron</command> will run the command as this user.
% +      In a user crontab, the sixth field is the command to run,

I can't see how this could possibly be correct.  A command line in a 
crontab requires a command to run, which would be a seventh field in the 
system crontab.  But this is not mentioned at all, here!

%        and all commands run as the user who created the crontab; this is an
%        important security feature.</para>
% 
%      <note>
%        <para>User crontabs allow individual users to schedule tasks without the 
% -        need for <username>root</username> privileges. Commands in a user's crontab run with the 
% -        permissions of the user who owns the crontab.</para>
% +	need for <username>root</username> privileges.  Commands in a user's crontab run with the 
% +	permissions of the user who owns the crontab.</para>

Are these just whitespace changes?

% 
%        <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.  <username>root</username>'s crontab is
% +	distinct 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>
%      </note>

Fine.

% 
%      <para>Let us take a look at the <filename>/etc/crontab</filename> file
% @@ -547,11 +546,9 @@
%  	  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>
% +	  The command will be run as the user named in this
% +	  field.  Finally, the last field is the command to be
% +	  executed.</para>

This feels a bit odd; most of the sentences here have "the [nth] field" as 
the subject of the sentence, so switching to having the command be the 
subject seems out-of-place.
I think I would keep the first sentence as-is, but dropping the "When a 
user..." sentence is probably okay.
"Finally, the last field" feels a bit redundant.

%        </callout>
% 
%        <callout arearefs="co-main">
% @@ -584,13 +581,13 @@
%        <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
% -        editor: the <command>cron</command> utility will notice that the file
% -        has changed and immediately begin using the updated version. 
% -        See
% -        <ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">
% -        this FAQ entry </ulink> for more information.</para>
% +      <para>Do not use the procedure described here to
% +	edit and install the system crontab.  Simply use your favorite
% +	editor: the <command>cron</command> utility will notice that the file
% +	has changed and immediately begin using the updated version.
% +	See
% +	<ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">this FAQ entry</ulink>

We should be able to make this line shorter, right?

% +	for more information.</para>
%        </important>
% 
%        <para>To install a freshly written user
[snip some minor/formatting changes]
% @@ -2390,15 +2386,35 @@
%        <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 space, and the way that gives the best
% +	performance, is to add a new swap partition on an existing or new hard
% +	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>

The old text was sort of advocating for using a new drive for swap, but 
it seems to have not actually mentioned (at least in the context that is 
quoted) perhaps the best reason for doing so: having a dedicated spindle 
for swap avoids extra seeks from competition with normal i/o.
It would seem that if we are going to claim there is a "best" way, it 
should involve a dedicated drive.

% +
% +      <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>
% +      </warning>
% +

Hmm, I thought that that there would be a check for the swap partition 
type, but glancing through the kernel code (vm/swap_pager.c) makes it seem 
like swap can be enabled in a great many places...

% +      <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>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>&man.fstab.5; explains the entries in
% +        <filename>/etc/fstab</filename>.</para>

I kind of feel like "explains the entries" is too concise.  Are we looking 
for the meaning of the entries, or their format, or something else?

%      </sect2>
% 
%      <sect2 id="nfs-swap">
[snip more minor stuff]


-Ben Kaduk