FreeLists / haiku-doc / [haiku-doc] Re: Phase III .diff List.dox

[Thom Holwerda <slakje@xxxxxxxxxxx>]

> Are the extra commas around between 'in turn' necessary? It might be
> correct, but it looks a bit awkward (3 comma's in a row). Plus, in
> regular speech you would not pronounce it as which (pause) in turn
> (high pitch ending, pause),
Well, I actually did, but I agree that it looks awkward. Commas removed.

> because it not realy is in turn anyway. I
> actually would like to remove the in turn at all since the allocation
> is expensive, and it's not hte expensiveness that is a result of the
> fact that you allocate new memory. (does that make sense?)
Well, I'm not a programmer, so that is for someone else to decide.  
Removed it for now.
> I guess overthinking is from my original version, and I'm affraid that
> it's a dutchism, since the dictionary does not mention you can think
> over something, let alone overthink something. Rather change it to
> 'not to worry too much'.
We had a little chat about this one in #haiku-doc. I was a bit stuck  
at "overthink", because I didn't know of a better word. I removed  
the  sentence with 'overthink' altogether.
> I think both the original and the new version are wrong. This is a
> header, as such it should be 'Adding and Removing Items'. I bet the
> other headers share the same problem.
All headers should be fixed now. Question: are there any rules for  
which words are capitalised in headers? I wrote the entire style  
guide for OSNews earlier this year, and I set the following rule:  
capitalise each word in the headline except for: a, and, for, of, on,  
the, to, by, in, with. I followed this rule when doing the headers  
for the new diff.
> -  \param index The offset in the list where to put the item.
> +  \param index The offset in the list where the item should be put.
>
> Though your improvement may be more correct, it sounds a bit awkward.
> Should we replace it with 'placed' or 'end up'
Again, we had a long discussion on this. Our conclusion: fcuk modals,  
let's stick to the original version.
> The wrapping did not go very well there. Your editor ate up all the
> newlines and now it's one big line. I think there is another case
> where I suddenly saw some lines disappear. Could you please
> doublecheck this again.
Error on my end. I found the option which enables linebreak markers,  
so all should be ok now.
> If you fix the problem of the eaten newlines and think about my
> commentary (which you are free to accept or reject), I will accept the
> next patch, though probably tomorrow, since I'll be going home in a
> few minutes.
Thanks for the comments! I have also added John Drinkwater as  
proofreader, since he attended me to some changes here and there.

Thom Holwerda