Date: Wed, 15 Feb 2012 20:53:00 -0500 From: Glen Barber <gjb@FreeBSD.org> To: Eitan Adler <lists@eitanadler.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: CfR: config chapter changes Message-ID: <20120216015300.GA1837@glenbarber.us> In-Reply-To: <CAF6rxgkY21MMfUWRMRnvWsTGC_2QspnfWqCKrFc_QDedTQMOoQ@mail.gmail.com> References: <CAF6rxgnvyoibFt7ijm6GpWoeF-eAOLu3SgvhEGCBDUAV4grybw@mail.gmail.com> <alpine.GSO.1.10.1202120028440.882@multics.mit.edu> <CAF6rxgmPyVXSFRJiOZZaJQFObhCsZMHS5_5UneVrb3t=wznMhA@mail.gmail.com> <20120215040311.GB1862@glenbarber.us> <20120215213448.GA29817@hemlock.hydra> <20120215221813.GB5203@glenbarber.us> <CAF6rxgkY21MMfUWRMRnvWsTGC_2QspnfWqCKrFc_QDedTQMOoQ@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120216015300.GA1837>