docs/159897: [patch] improve HAST section of Handbook

[Benjamin Kaduk]

The following reply was made to PR docs/159897; it has been noted by GNATS.

From: Benjamin Kaduk <kaduk at MIT.EDU>
To: Warren Block <wblock at wonkity.com>
Cc: freebsd-gnats-submit at freebsd.org, freebsd-doc at freebsd.org
Subject: Re: docs/159897: [patch] improve HAST section of Handbook
Date: Mon, 22 Aug 2011 12:36:42 -0400 (EDT)

 On Sun, 21 Aug 2011, Warren Block wrote:
 
 > On Sat, 20 Aug 2011, Benjamin Kaduk wrote:
 >
 >> On Thu, 18 Aug 2011, Warren Block wrote:
 >> 
 >>> -	  <para>File system agnostic, thus allowing to use any file
 >>> +	  <para>File system agnostic, thus allowing use of any file
 >> 
 >> I think "allowing the use" is better here.
 >
 > "allowing any" might be even better.
 
 I don't think that would be correct usage -- "allowing any file system" to 
 do what?
 
 >
 >>>       <para>Once the <acronym>HAST</acronym> framework is configured
 >>> 	properly, the final step is to make sure that
 >>> -	<acronym>HAST</acronym> is started during the system boot time
 >>> -	automatically.  The following line should be added to the
 >>> -	<filename>/etc/rc.conf</filename> file:</para>
 >>> +	<acronym>HAST</acronym> is started automatically during the system
 >>> +	boot.  This line is added to
 >>> +	<filename>/etc/rc.conf</filename>:</para>
 >> 
 >> "This line is added" is a pretty unusual grammatical construct for what is 
 >> attempting to be conveyed.  "To do so, add this line to" I think says 
 >> things more clearly.
 >
 > I would prefer the imperative "Add this line to...".
 
 That works.  I had initially shied away from it since it could be read to 
 imply that all users should do so, not just those wanting to use HAST. 
 But this is the HAST section, after all.
 
 >
 >>> -	<para>In order to fix this situation the administrator has to
 >>> +	<para>The administrator must
 >>> 	  decide which node has more important changes (or merge them
 >>> -	  manually) and let the <acronym>HAST</acronym> perform
 >>> +	  manually) and let <acronym>HAST</acronym> perform
 >>> 	  the full synchronization of the node which has the broken
 >> 
 >> Just "full synchronization", I think.
 >
 > Changing "of" to "on" ("full synchronization on the node") also helps a bit.
 >
 
 I think I still prefer "of", but would not object to "on".
 Can you prepare an updated patch with these changes?
 
 Thanks,
 
 Ben