From owner-freebsd-doc@FreeBSD.ORG Wed Feb 15 04:03:14 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 60F8C1065745 for ; Wed, 15 Feb 2012 04:03:14 +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 0C4D68FC1A for ; Wed, 15 Feb 2012 04:03:13 +0000 (UTC) Received: (qmail 98548 invoked by uid 0); 14 Feb 2012 23:03:13 -0500 Received: from unknown (HELO glenbarber.us) (76.124.49.145) by 0 with SMTP; 14 Feb 2012 23:03:13 -0500 Date: Tue, 14 Feb 2012 23:03:11 -0500 From: Glen Barber To: Eitan Adler Message-ID: <20120215040311.GB1862@glenbarber.us> References: 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: Wed, 15 Feb 2012 04:03:14 -0000 Off hand... On Tue, Feb 14, 2012 at 10:36:19PM -0500, Eitan Adler wrote: > What about the following? > > 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 15 Feb 2012 03:34:17 -0000 > @@ -473,13 +473,14 @@ > 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 ^^^^^ Please use 2 spaces between sentences. > + 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. > + > s should be on the same line as the ending sentence. > > User crontabs allow individual users to schedule tasks without the > @@ -487,10 +488,10 @@ > 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. root's crontab is I'd prefer "The root user crontab .... here. > + distinct from /etc/crontab (the system crontab). > + Because of the system crontab, there is usually no need to > + create a user crontab for root. "Because of the system crontab" is something I'm not fond of. I'd prefer "Since the system crontab effectively invokes the specified commands as root..." or something. Not a nit directly about your patch; I wasn't fond of the original version. > > > 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. Grammar nit: What do you think about "This field specifies the user root under which the command should run." ? > > > > @@ -584,13 +582,14 @@ > Installing a Crontab > > > - You must not use the procedure described here to > - edit/install the system crontab. Simply use your favorite > - editor: the cron utility will notice that the file > - has changed and immediately begin using the updated version. > - See > - > - this FAQ entry for more information. > + 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. > + See > + > + this FAQ entry for more information. > I don't see any content changes here outside of the first two lines of the . > > To install a freshly written user > @@ -613,8 +612,7 @@ > 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 crontab command. Personal nit: I'd prefer using "&man.crontab.8;" over "crontab command." > > If you later want to remove your user crontab > completely, use crontab with the > @@ -636,7 +634,7 @@ > > > > - Using rc under &os; > + Using <literal>rc</literal> Under &os; > > In 2002 &os; integrated the NetBSD > rc.d system for system initialization. > @@ -1674,7 +1672,7 @@ > > > > - Tuning with sysctl > + Tuning with <command>sysctl</command> > > sysctl > > @@ -1944,7 +1942,7 @@ > out of space and the update to fail. > > > - More Details about Soft Updates > + More Details About Soft Updates > > > 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. > + > + > + 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. > > > > @@ -2739,7 +2758,7 @@ > > An ACPI-compliant system has various > components. The BIOS and chipset vendors > - provide various fixed tables (e.g., FADT) > + provide various fixed tables (e.g., FADT) The space between the comma and opening tag is not necessary. It also makes things more difficult for translators to find what changed. > in memory that specify things like the APIC > map (used for SMP), config registers, and > simple configuration values. Additionally, a table of bytecode > @@ -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