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

Hi Thom,

A few more nitpicks to perfect the thing

2007/5/22, Thom Holwerda <slakje@xxxxxxxxxxx>:

> 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.


-  If you are unsure, you don't have to overthink this. Just make sure you don't
-  use a lot of lists and as long as the list isn't used in one of the
-  performance critical parts of the code, you are safe to go with the default
-  values.
+  Just make sure you do not use a lot of lists, and as long as the list is not
+  used in one of the performance critical parts of the code, you are safe to go
+  with the default values.

The thing is that the meaning changed now. What I want to say is that
as long as you don't use too many lists, and the lists you are using
aren't in any performance critical parts of the code, you don't have
to worry too much about the size of the list if you are unsure.


> 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.


I think the more common thing we should settle on is "capitalization
of all words, except for internal articles, prepositions and
conjunctions" (wikipedia). There is one header where you capitalised
'Over', which I don't think is necessary.

There is one more technical point:

  \warning If there is anything you want, for which you need the list of
-    objects, please understand that that probably means that what you
want to do
-    is a bad idea to begin with and you should avoid this method. The list of
-    objects doesn't belong to you. See if DoForEach() can help you out instead.
+  objects, please realize that that probably means that what you want
to do is a
+  bad idea to begin with and that you should avoid this method. The list of
+  objects does not belong to you. See also DoForEach() for an alternate method.

You should put the spaces back. The \warning command takes a paragraph
as argument, as such all the following lines should be considered as
part of the paragraph and therefore should be indented with two more
spaces.

Thanks,

Niels

Other related posts: