Rob Hamerling wrote:
Hi Joep,
On 03/21/10 08:43 am, Joep Suijs wrote:
Enclosed version0.99a of the starters guide.
Reading was at low priority with me, but I just had a look.
In general I like contents and style!
I have a few minor comments, mainline about language (although English
is not my native language, so I maybe wrong!)
(Page references are to the A4 document)
The document contains to many times 'by now'! Please make some variations.
I have read through the Guide more then once and I had not noticed an
excessive use of the phrase. I too am put off by repeated is of phrases
such as 'you know', which drives me crazy. As the information presented
in the Doc was so interesting and informative it just didn't seem
offensive, to me
Also 'next' is used too frequently, and in some cases it should be
replaced by 'following'. Use 'next' when referring to a single item and
'following' when referring to a list of items.
Again I didn't notice that either, probably for the above reasons,
Your above usage is correct though.
On several places in the document you use 'that', where I think 'which'
should be used, like:
Same comment as above.
Page 11 just below the middle:
The right hand reference ‘led’ reads the value of led (0 or 1), the
exclamation point inverts the value (so 0 becomes 1 and 1 becomes 0)
and the result is the new value _that_ is assigned to the IO pin by the
left hand reference to ‘led'.
The last part is rather difficult to read anyway. Try to avoid long
sentences where these can easily be splitted, for example:
split
DICT: {split} divide lengthwise or along a grain
DICT: {splitted} No such word.
Note: American English dictionary.
The right hand reference ‘led’ takes the value of led (0 or 1), the
exclamation point inverts the value (so 0 becomes 1 and 1 becomes 0).
The result (the inversion of the original) is assigned to the I/O-pin by
the left hand reference to ‘led'.
I would also use 'I/O-pin' in stead of 'IO pin'
(the '/' is an abbreviation of 'or': a pin is either input or output)
It ( I/O )does look better but in this context I believe either is
acceptable.
p 12 (about MSB):
I think 'MSB' stands for Most Significant Byte and 'msb' for most
significant bit. See > http://en.wikipedia.org/wiki/Most_significant_bit
Something similar for 'LSB' and 'lsb'
The MSB or msb, which could mean most significant byte or bit are not
proper nouns so do not require capitalization. If there is a rule about
this I am not aware of it. Due to the confusion MSB or msb could cause
it might be better if the abbreviation be replaced by the full word
spelling once,followed by the appropriate (MSB) or (msb), again once.
Then the abbreviated form could be used thereafter.
or
The definitions of the abbreviations could be put into a footnote to
make it clear which is which.
p 13 (top about nibbles):
Spitted refers to piece of meat and put on a rod (split) and turned
over a fire. Barbe
Variables with ‘_low’ map to the lower 4 bits of a register
> and the variables with ‘_high’ map to the higher 4 bits.
I would reword that as follows:
Variables with ‘_low’ map to the 4 low order bits of a register
(bits 3..0) and the variables with ‘_high’ map to the 4 high-order bits
(bits 7..4).
Again a matter of style your correction might be required by someone new
to programming.
p 14 (top)
'convertor' should be 'converter'
Nice catch, I missed that too.
Wayne
--
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en.
