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

[Benjamin Kaduk]

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