From owner-freebsd-doc@FreeBSD.ORG Thu Feb 16 01:53:06 2012 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 976031065674 for ; Thu, 16 Feb 2012 01:53:06 +0000 (UTC) (envelope-from gjb@FreeBSD.org) Received: from glenbarber.us (onyx.glenbarber.us [199.48.134.227]) by mx1.freebsd.org (Postfix) with SMTP id 4AD8F8FC18 for ; Thu, 16 Feb 2012 01:53:06 +0000 (UTC) Received: (qmail 37729 invoked by uid 0); 15 Feb 2012 20:53:05 -0500 Received: from unknown (HELO glenbarber.us) (76.124.49.145) by 0 with SMTP; 15 Feb 2012 20:53:05 -0500 Date: Wed, 15 Feb 2012 20:53:00 -0500 From: Glen Barber To: Eitan Adler Message-ID: <20120216015300.GA1837@glenbarber.us> References: <20120215040311.GB1862@glenbarber.us> <20120215213448.GA29817@hemlock.hydra> <20120215221813.GB5203@glenbarber.us> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Operating-System: FreeBSD 10.0-CURRENT amd64 User-Agent: Mutt/1.5.21 (2010-09-15) Cc: freebsd-doc@FreeBSD.org Subject: Re: CfR: config chapter changes X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 16 Feb 2012 01:53:06 -0000 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. > > The cron 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. > + types of configuration files, the system crontab and user crontabs. > + These formats only differ in the sixth field and later. In the > + system crontab, cron 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. > > > User crontabs allow individual users to schedule tasks without the > @@ -487,10 +487,11 @@ > permissions of the user who owns the crontab. > > The root user can have a user > crontab just like > - any other user. This one is different from > - /etc/crontab (the system crontab). Because of the > - system crontab, there is usually no need to create a user crontab > - for root. > + any other user. The root user crontab is > + distinct from /etc/crontab (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 root. > > > Let us take a look at the /etc/crontab file > @@ -547,11 +548,8 @@ > day of the week. All these fields must be numeric values, and follow > the twenty-four hour clock. The who field is special, > and only exists in the /etc/crontab file. > - This field specifies which user the command should be run as. > - When a user installs his or her crontab file, they > - will not have this option. Finally, the command > option is listed. > - This is the last field, so naturally it should designate the command > - to be executed. > + This field specifies which user the command should be run > + as. The last field is the command to be executed. > > > > @@ -584,8 +582,9 @@ > Installing a Crontab > > > - You must not use the procedure described here to > - edit/install the system crontab. Simply use your favorite > + Do not use the procedure described here to > + edit and install the system crontab, > + /etc/crontab. Simply use your favorite > editor: the cron 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 @@ > To install a freshly written user > crontab, first use your favorite editor to create > a file in the proper format, and then use the > - crontab utility. The most common usage > + crontabman.crontab.8; utility. The most common usage What I meant here is replacing the '' 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: > > &prompt.user; crontab > crontab-file > @@ -606,18 +605,17 @@ > > There is also an option to list installed > crontab files: just pass the > - option to crontab and look > + option to > crontabman.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. > > For users who wish to begin their own crontab file from scratch, > without the use of a template, the crontab -e > 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 crontab command. > - > + automatically installed by the > crontabman.crontab.8; command. I don't understand why this change was made. I think you replaced more references to crontab than I pointed to. > > If you later want to remove your user crontab > - completely, use crontab with the > + completely, use crontabman.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. > > > @@ -636,7 +634,7 @@ > > > > - Using rc under &os; > + Using <literal>rc</literal> Under &os; > I'd replace "rc" with "&man.rc.8;" here. > In 2002 &os; integrated the NetBSD > rc.d system for system initialization. > @@ -1674,7 +1672,7 @@ > > > > - Tuning with sysctl > + Tuning with <command>sysctl</command> > I'd replace "sysctl" with "&man.sysctl.8;" here. > sysctl > > @@ -1944,7 +1942,7 @@ > out of space and the update to fail. > > > - More Details about Soft Updates > + More Details About Soft Updates > 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. > > Soft Updates > @@ -2390,15 +2388,36 @@ > of the Handbook. > > > - Swap on a New Hard Drive > + Swap on a New or Existing Hard Drive > > - 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 > - of the Handbook for some suggestions on how to best > - arrange your swap. > + 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 > + . > + discusses partition layouts and swap partition size considerations. > + > + Use &man.swapon.8; to add a swap partition to the system. > For example: > + > + &prompt.root; > swapon/dev/ada1s1p2 > + > + > + 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 > + swapon. I'd replace the command tags with the mdoc macro for the swapon(8) manual here. > + > + > + To automatically add this swap partition on boot, > + add an entry to /etc/fstab for the > + partition: > + > + /dev/ada1s1p1 none swap sw 0 0 > + > + &man.fstab.5; explains the meaning of the entries and > + their format in > + /etc/fstab. > > > > @@ -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 ACPI maintainers do not > - usually maintain other drivers (e.g sound, > + usually maintain other drivers (e.g., sound, > ATA, 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 @@ > > > > - System Hangs (temporary or permanent) > + System Hangs (Temporary or Permanent) > > 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: > > > - _OS dependencies > + _OS Dependencies > > Some AML assumes the world consists of > various &windows; versions. You can tell &os; to claim it is > @@ -3070,7 +3089,7 @@ > > > > - Missing Return statements > + Missing Return Statements > > Some methods do not explicitly return a value as the > standard requires. While ACPI-CA > @@ -3112,8 +3131,7 @@ > > > > - Getting Debugging Output From > - <acronym>ACPI</acronym> > + Getting Debugging Output from <acronym>ACPI</acronym> > > > ACPI > > > Glen