Documentation problems from chapters 1-4

dthomson

Hi,

Here's my list of nits I picked up in chapters 1 through 4 of the Ice documentation. Most are cut and paste type errors. Others may just be my own humble opinion, so use or ignore as you see fit.

p22

**********
The Ice protocol is suitable for building highly-efficient event
forwarding mechanisms because they permit forwarding of a message
without knowledge of the details of the information inside a message.
**********

This switches plurality with regards to "The Ice protocol" part way
through. It should be:

**********
The Ice protocol is suitable for building highly-efficient event
forwarding mechanisms because *it* *permits* forwarding of a message
without knowledge of the details of the information inside a message.
**********

p58

**********
Section 4.4.2 File Format

You may wish to follow the style I have used for the Slice examples
throughout this book.
**********

I think using the personal pronoun "I" like this is not well suited to
technical documentation. I don't think "we" is appropriate, either.

May I suggest simply:

**********
You may wish to follow the style used for the Slice examples
throughout this book.
**********


p63

**********
Section 4.6.3 Strings

If you need the notion of an optional string, use a class (see Section
4.9), a sequence of strings (see Section 4.7.3), or use an empty
string represent the idea of a null string.
**********


The end of this sentence is just grammatically incorrect.

Perhaps you mean "or use an empty string *to* represent the
idea of a null string". But it could be "or an empty
string *represents* the idea of a null string".

Hard to disambiguate, incorrect grammar is

p68

Dictionary mapping English to German weekdays looks bad on my acroread
viewer I get badly positioned and clipped words in German.

That's acroread 4.0 on SuSE Linux 8.0

**********
The server implementation would take care of initializing this map with the key value pairs Monday Montag , Tuesday Dienstag , and so on.
**********

p100

Section 4.9.4 Classes as Unions

**********
The parameter s of the translate operation can be viewed as a union a
of two members: a Circle and a Rectangle.
**********

"can be viewed as a union a of two members" has a spurious "a" in
there. How about "can be viewed as a union of two members"?

This example isn't really very useful, by the way. I'd like to see
actual union-like behaviour explicitly shown.

p131

Section 4.19.2

**********
Especially language mappings suffer badly from unions.
**********

Ugh.

p132

**********
there is no guarantee that the client [...] will send contexts
other than those named,
**********

You mean "*won't* send contexts other than those named". Or to put it another way, why would you want to guarantee that it will send unnamed contexts?

michi

Re: Documentation problems from chapters 1-4

Originally posted by dthomson
Hi,

Here's my list of nits I picked up in chapters 1 through 4 of the Ice documentation. Most are cut and paste type errors. Others may just be my own humble opinion, so use or ignore as you see fit.

Hi Derek,

thanks muchly for the review! I've made all these changes for the next version. BTW, the PDF problem happens here too, using Acrobat 5 under Win XP. The messed-up rendering is caused by a right-arrow character in Symbol font. For some reason, Acrobat won't space the text correctly for that (even though Framemaker does). I've replaced the arrows with hyphens, shrug...

Cheers,

Michi.