Date: Tue, 14 Feb 2012 23:03:11 -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: <20120215040311.GB1862@glenbarber.us> In-Reply-To: <CAF6rxgmPyVXSFRJiOZZaJQFObhCsZMHS5_5UneVrb3t=wznMhA@mail.gmail.com> References: <CAF6rxgnvyoibFt7ijm6GpWoeF-eAOLu3SgvhEGCBDUAV4grybw@mail.gmail.com> <alpine.GSO.1.10.1202120028440.882@multics.mit.edu> <CAF6rxgmPyVXSFRJiOZZaJQFObhCsZMHS5_5UneVrb3t=wznMhA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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.</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
^^^^^
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.
> + </para>
>
</para>s should be on the same line as the ending sentence.
> <note>
> <para>User crontabs allow individual users to schedule tasks without the
> @@ -487,10 +488,10 @@
> 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. <username>root</username>'s crontab is
I'd prefer "The <username>root</username> user crontab .... here.
> + 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>
"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.
> </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>
Grammar nit: What do you think about "This field specifies the user
<username>root</username> under which the command should run." ?
> </callout>
>
> <callout arearefs="co-main">
> @@ -584,13 +582,14 @@
> <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,
> + <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.
> + See
> + <ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">
> + this FAQ entry</ulink> for more information.</para>
> </important>
I don't see any content changes here outside of the first two lines of
the <para>.
>
> <para>To install a freshly written user
> @@ -613,8 +612,7 @@
> 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> command.</para>
Personal nit: I'd prefer using "&man.crontab.8;" over
"<command>crontab</command> command."
>
> <para>If you later want to remove your user <filename>crontab</filename>
> completely, use <command>crontab</command> with the <option>-r</option>
> @@ -636,7 +634,7 @@
> </authorgroup>
> </sect1info>
>
> - <title>Using rc under &os;</title>
> + <title>Using <literal>rc</literal> Under &os;</title>
>
> <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>
>
> <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>
>
> <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>
> + </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">
> @@ -2739,7 +2758,7 @@
>
> <para>An <acronym>ACPI</acronym>-compliant system has various
> components. The <acronym>BIOS</acronym> and chipset vendors
> - provide various fixed tables (e.g., <acronym>FADT</acronym>)
> + provide various fixed tables (e.g., <acronym>FADT</acronym>)
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 <acronym>APIC</acronym>
> map (used for <acronym>SMP</acronym>), 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 <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?20120215040311.GB1862>