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: Taras Korenko <ds at ukrhub.net>, freebsd-doc at freebsd.org,
        freebsd-gnats-submit at freebsd.org
Subject: Re: docs/159897: [patch] improve HAST section of Handbook
Date: Tue, 23 Aug 2011 21:04:27 -0400 (EDT)

 On Tue, 23 Aug 2011, Warren Block wrote:
 
 > On Tue, 23 Aug 2011, Taras Korenko wrote:
 >
 >> On Mon, Aug 22, 2011 at 06:08:09PM -0600, Warren Block wrote:
 >>> On Mon, 22 Aug 2011, Benjamin Kaduk wrote:
 >>> 
 >>>> 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?
 >>> 
 >>> Allowing any file system versus allowing only file systems made for
 >>> HAST.  Looking at it again, the problem is the word "allowing".  What
 >>> this is really saying is: "File system agnostic, compatible with any
 >>> file system supported by &os;."
 >>> 
 >> 
 >> File system agnostic, thus allowing laying out any file
 >> system supported by &os;.
 >
 > Another day and now "agnostic" looks wrong.  IMO, the meaning is not "HAST is 
 > unsure that file systems exist", but that it operates at a block level and is 
 > not even aware of file systems.  More simply, it doesn't care which file 
 > system is used.
 >
 > So my latest proposal for the simplest rewording is
 >
 > "Works with any file system supported by FreeBSD."
 
 Filesystem-agnostic is something of a term of art for this sort of thing; 
 I would stick with:
 "File system agnostic; works with any file system supported by FreeBSD."
 (This is where bde comes in and tells me off for condensing filesystem 
 into a single word, per
 http://lists.freebsd.org/pipermail/svn-src-head/2011-June/028709.html )
 
 >>>>> - <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". 
 >
 > The idea is that "synchronization of the node" is ambiguous about which node
 > is being changed, where "synchronization on the node", er, isn't.
 
 It is "synchronization of the node to the reference state" versus "a 
 synchronization process on the [broken] node to bring it back into a good 
 state".  In going for concision, we necessarily introduce some ambiguity; 
 I'm not equipped to say which one has the greater ambiguity for more 
 people.
 
 Thanks again,
 
 Ben