Home Bug Reports

Documentation issues

Hi,


1) On page 87 interface RadioClock extends Radio and Clock interfaces. On the next page there is an inheritance diagram where RadioClock inherits from Radio and AlarmClock. So where is a "typo", in diagram or in interface definition?

2) On page 90 you introduce ProxyStore interface. In the next chapter "Null Proxies" you are referring to the ObjectStore interface. Probably, you wanted to refer to ProxyStore interface instead. (because ObjectStore was not defined at all.)

Ivan
«1

Comments

  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Documentation issues
    Originally posted by Ivan
    Hi,


    1) On page 87 interface RadioClock extends Radio and Clock interfaces. On the next page there is an inheritance diagram where RadioClock inherits from Radio and AlarmClock. So where is a "typo", in diagram or in interface definition?

    2) On page 90 you introduce ProxyStore interface. In the next chapter "Null Proxies" you are referring to the ObjectStore interface. Probably, you wanted to refer to ProxyStore interface instead. (because ObjectStore was not defined at all.)

    Ivan

    Thanks muchly for pointing this out! Your are right -- Figure 4.5 should just show inheritance from Radio and Clock, not AlarmClock. On page 90, the two mentions ObjectStore should read ProxyStore.

    I've fixed this for the next version.

    Thanks,

    Michi.
  • IvanIvan Member
    Chapter 4.9 issues

    Chapters 4.9.5/4.9.7: on both pages 102 and 103 the definition of class Operand does not extend class Node, but it should.

    Ivan
  • andreynechandreynech Member Andrey NechypurenkoOrganization: Veterobot.comProject: Robotics vehicle for researchers and makers ✭✭
    Typo in section 4.19.2

    Hi,

    On page 133 the second bulleted paragraph: "... it is NOT impossible for a process to receive... ". Should not it be: "...it is impossible..." ?

    Thanks,
    Andrey.
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Thanks muchly guys, this will be corrected in the next published version.

    And we really appreciate all the feedback and bug reports so, please, keep them coming!

    One of the problems when writing a book is that, as the author, after a while, it's very difficult to actually read the stuff as if I'd never read it before. As a result, I keep skipping over my own mistakes because I read what I meant to say, not what is actually there. So, the independent review by people who read the text with a fresh mind is really valuable!

    Thanks,

    Michi.
  • IvanIvan Member
    Chapter 14.9.3: forgotten brackets

    On pages 321 and 322, in put() method (_q.size == 1) should be (_q.size() == 1)

    Ivan
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Chapter 14.9.3: forgotten brackets
    Originally posted by Ivan
    On pages 321 and 322, in put() method (_q.size == 1) should be (_q.size() == 1)

    Ivan

    Ivan, thanks again! At the rate you are going, we will have to give you a medal! :)

    Cheers,

    Michi.
  • IvanIvan Member
    Minor correction

    Thanks Michi, gold one please ;-)

    On page 328, 4th line from bottom, "is" should be "its".

    I feel a bit uncomfortable to send such a correction ;)

    Ivan

    P.S. Doc for Ice-1.0.1
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Minor correction
    Originally posted by Ivan
    Thanks Michi, gold one please ;-)
    OK, we'll make it a gold one ;-)
    On page 328, 4th line from bottom, "is" should be "its".

    I feel a bit uncomfortable to send such a correction ;)

    No, not at all -- if it's wrong, it's wrong and needs to be fixed. Thanks!

    Cheers,

    Michi.
  • IvanIvan Member
    Again diagrams and type IDs

    As we agreed earlier AlarmClock interface should not be shown on the figure 4.5.

    Then it should not be shown also on the figure 4.7!

    And thus you have to exclude "::AlarmClock" from the last sentence in the chapter 14.13.

    Ivan
  • dhalbertdhalbert Member
    Diagrams for IcePack

    I've been reading the Ice Manual over the past few days, and it looks great! My comprehension of much of the material came easily, perhaps because I could relate and compare it to CORBA, but when I got to the IcePack chapter I slowed down. Eventually I did get an "Aha!" moment, but I think some diagrams showing the relationships between the objects mentioned in that chapter and the queries and datflow would have speeded up my understanding.

    Thanks,
    Dan
  • mesmes CaliforniaAdministrators, ZeroC Staff Mark SpruiellOrganization: ZeroC, Inc.Project: Ice Developer ZeroC Staff
    Re: Diagrams for IcePack

    Dan,

    I agree that the IcePack chapter is rather dense; it could definitely benefit from a few diagrams.

    Thanks for the suggestion.
    - Mark
  • mickmick Member
    Minor doco errors

    Here's a bunch of minor doco improvements. All but the last are simply grammatical changes.

    N.B. I pondered whether to post this here or to email [email protected] as the book suggests, but it seems like people are using this thread for the purpose and by posting publicly it saves on duplication of effort.

    Page 14: "are important because the guarantee" should be "are important because THEY guarantee"
    Page 15: "so at-most-semantics" should be "so at-most-ONCE-semantics"
    Page 24: "IcePack allows you register servers for automatic start-up:" should be "IcePack allows you TO register servers for automatic start-up:"
    Page 29: "it is possible determine" should be "it is possible TO determine"
    Page 60: "Language mappings define rules for dealing such identifiers." should be "Language mappings define rules for dealing WITH such identifiers."
    Page 63: "See BIBREF for an good treatment of the topic." should be "See BIBREF for A good treatment of the topic."
    Page 63: "or use an empty string represent the idea of a null string." should be "or use an empty string TO represent the idea of a null string."
    Page 66: "There a number of options of dealing with this situation:" should be "There ARE a number of options FOR dealing with this situation:"
    Page 67: "Strings come with their on in-built sentinel value" should be "Strings come with their OWN in-built sentinel value"
    Page 69: "sequences of with elements of integral type or string" should be "sequences with elements of integral type or string"
    Page 72: "This definition defines a interface type called Clock" should be "This definition defines AN interface type called Clock"
    Page 75: "A common example of this an iterator" should be ""A common example of this IS an iterator"
    Page 86: "(at least for statically type-safe languages, such as C++ and Java)." should say "(at least for statically TYPED languages, such as C++ and Java)."

    nb. note that C++ is statically typed, but is not type safe.


    cheers,
    mick
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Again diagrams and type IDs
    Originally posted by Ivan
    As we agreed earlier AlarmClock interface should not be shown on the figure 4.5.

    Then it should not be shown also on the figure 4.7!

    And thus you have to exclude "::AlarmClock" from the last sentence in the chapter 14.13.

    Ivan

    OK, fixed. But I fixed it by putting back the original AlarmClock (which was the idea all along). So, in Figure 4.5, AlarmClock should have been shown all along. The problem really was with the code example on page 87 -- RadioClock should inherit from Radio and AlarmClock, instead of Radio and Clock.

    Cheers,

    Michi.
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Minor doco errors
    Originally posted by mick
    Here's a bunch of minor doco improvements. All but the last are simply grammatical changes.

    N.B. I pondered whether to post this here or to email [email protected] as the book suggests, but it seems like people are using this thread for the purpose and by posting publicly it saves on duplication of effort.

    Agreed, here is just as good as via e-mail -- whatever you prefer.

    Thanks for all the detailed fixes -- I've corrected them for the next version.

    Page 86: "(at least for statically type-safe languages, such as C++ and Java)." should say "(at least for statically TYPED languages, such as C++ and Java)."

    nb. note that C++ is statically typed, but is not type safe.

    Hmmm... I'm not sure I get your meaning. C++ is statically type safe because the compiler enforces at compile time that constructs make sense as far as their types are concerned. For example, the compiler won't let me call a method on a derived type via a pointer to a base type. In contrast, languages such as SmallTalk are not statically type safe: I only find out at run time if an object actually provides the method I'm calling at it.

    So, is there any difference in meaning between "statically typed" and "statically type safe?"

    Cheers,

    Michi.


    cheers,
    mick [/B][/QUOTE]
  • mickmick Member
    Re: Re: Minor doco errors
    Originally posted by michi
    Agreed, here is just as good as via e-mail -- whatever you prefer.

    Thanks for all the detailed fixes -- I've corrected them for the next version.



    Hmmm... I'm not sure I get your meaning. C++ is statically type safe because the compiler enforces at compile time that constructs make sense as far as their types are concerned. For example, the compiler won't let me call a method on a derived type via a pointer to a base type. In contrast, languages such as SmallTalk are not statically type safe: I only find out at run time if an object actually provides the method I'm calling at it.

    So, is there any difference in meaning between "statically typed" and "statically type safe?"

    Cheers,

    Michi.


    cheers,
    mick
    Yes there is a difference. See the first 5 pages of http://research.microsoft.com/Users...TypeSystems.pdf for a good discussion from someone a lot more qualified to comment than me.

    Basically C++ is statically (strongly) typed as types are checked at compile time, but is not "safe" since it is easy to both deliberately (e.g. via reinterpret_casts) and accidentally (e.g. via array overruns) to circumvent the type system (i.e. to break safety).

    In contrast, Java is both strongly typed and safe, although as an aside, Java is arguably less strongly typed than C++ due to the lack of templates (all those pesk dynamic casts when using Java containers ...)

    cheers,
    mick
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Re: Re: Minor doco errors
    Originally posted by mick
    Yes there is a difference. See the first 5 pages of http://research.microsoft.com/Users...TypeSystems.pdf for a good discussion from someone a lot more qualified to comment than me.

    Unfortunately, Vbulletin mangled your URL into unrecognizability, so I couldn't check the paper :-(

    Basically C++ is statically (strongly) typed as types are checked at compile time, but is not "safe" since it is easy to both deliberately (e.g. via reinterpret_casts) and accidentally (e.g. via array overruns) to circumvent the type system (i.e. to break safety).

    In contrast, Java is both strongly typed and safe, although as an aside, Java is arguably less strongly typed than C++ due to the lack of templates (all those pesk dynamic casts when using Java containers ...)

    OK, I take your point -- casts allow me to violate the type system. Incidentally, I don't think that array overruns have anything to do with static type safety -- if I overrun an array, I'm still treating the overrun portion as the correct type. It's just that I'm accessing memory in an uncontrolled way. And, even in languages such as Java, array overruns are detected only at run time.

    Anyway, I've gone and made the change you suggested, thanks!

    Cheers,

    Michi.
  • mickmick Member
    Re: Re: Re: Re: Minor doco errors
    Originally posted by michi
    Unfortunately, Vbulletin mangled your URL into unrecognizability, so I couldn't check the paper :-(

    Thats a shame. Actually I must say that I find Vbulletin very frustrating to use for anything other than a very simple post. The above is just one example. It is surprising that it can't handle URLs correctly.

    Anyay, I have emailed the URL to you in case you are still interested in taking a look. The paper is written by Luca Cardelli who is a bit of a God in the "type systems" area.

    OK, I take your point -- casts allow me to violate the type system. Incidentally, I don't think that array overruns have anything to do with static type safety -- if I overrun an array, I'm still treating the overrun portion as the correct type.

    No you're not. Take for example the following variables:

    float float1;
    int array[10];
    float float2;

    Now say you execute:

    array[10] = 12;

    Depending on memory layout, the "overrun portion" is either going to be the memory referred to by float1 or float2. In either case, the memory's type is a float, and yet the code is treating it as an int. So the code is not treating the overrun portion as the correct type. Hence we have managed to violate type safety at run time.

    It's just that I'm accessing memory in an uncontrolled way. And, even in languages such as Java, array overruns are detected only at run time.

    That's right, so in this particular area Java is type safe, but is not statically typed.

    Anyway, this is moving a fair way away from a discussion on Ice documentation issues .. so apologies.

    cheers,
    mick
  • Re: Re: Minor doco errors
    Originally posted by michi
    Agreed, here is just as good as via e-mail -- whatever you prefer.


    Hmmm... I'm not sure I get your meaning. C++ is statically type safe because the compiler enforces at compile time that constructs make sense as far as their types are concerned. For example, the compiler won't let me call a method on a derived type via a pointer to a base type. In contrast, languages such as SmallTalk are not statically type safe: I only find out at run time if an object actually provides the method I'm calling at it.

    So, is there any difference in meaning between "statically typed" and "statically type safe?"

    Cheers,

    Michi.


    cheers,
    mick
    [/B][/QUOTE]

    Well, you can blow a whole through the type system of C++ by using casts, so it is not safe.
  • vBulletin & URLs
    Originally posted by mick
    Thats a shame. Actually I must say that I find Vbulletin very frustrating to use for anything other than a very simple post. The above is just one example. It is surprising that it can't handle URLs correctly.

    vBulletin can handle URLs, you may just have a look at the following link for the use of vB code and URLs:
    vB code & URLs

    Note that vB code must be ON (Check it at the lower left of this page).

    Regards,
    Patrick.
  • mickmick Member
    Re: Re: Re: Re: Re: Re: Minor doco errors
    Originally posted by Patrick Decat
    vBulletin can handle URLs, you may just have a look at the following link for the use of vB code and URLs:
    vB code & URLs

    Note that vB code must be ON for you (Check it at the lower left of this page).

    Regards,
    Patrick.

    Aha ... thanks for that.

    Ok then ..here is another attempt at the URL on type systems I was trying to post before.


    cheers,
    mick
  • georgealgeorgeal Member
    Page 116: Top line should read:
    "Table 4.2 illustrates the results of calling ..."

    instead of

    "Figure 4.9 illustrates the results of calling ..."

    Keep up the good work on the documentation front! Thanks.
  • georgealgeorgeal Member
    Page 183: Second last paragraph

    "When the enclosing scope closes...which decrements N2's reference count to 1"

    I believe the second N2 should instead be N1.

    Regards.
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Originally posted by georgeal
    Page 116: Top line should read:
    "Table 4.2 illustrates the results of calling ..."

    instead of

    "Figure 4.9 illustrates the results of calling ..."

    Keep up the good work on the documentation front! Thanks.

    Thanks for spotting this! It's fixed for the next version.

    Cheers,

    Michi.
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Originally posted by georgeal
    Page 183: Second last paragraph

    "When the enclosing scope closes...which decrements N2's reference count to 1"

    I believe the second N2 should instead be N1.

    Regards.

    Yes, you are right, thanks for that!

    Fixed for the next version :)

    Cheers,

    Michi.
  • IvanIvan Member
    UserException

    On page 151, it says "All user exceptions ultimately inherit from Ice::UserException (which is an alias for IceUtil::Exception)."

    The phrase in brackets is incorrect. Ice::UserException is not an alias for IceUtil::Exception, but Ice::Exception is.

    And minor thing.. on the next page there is definition for UserException:
    "namespace Ice {
    typedef IceUtil::Exception Exception;
    class UserException: public Exception {"

    This is correct, but just different from the header (Exception.h):
    " class UserException: public IceUtil::Exception"

    I prefer how it is in the book ;)

    Ivan
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: UserException
    Originally posted by Ivan
    On page 151, it says "All user exceptions ultimately inherit from Ice::UserException (which is an alias for IceUtil::Exception)."

    The phrase in brackets is incorrect. Ice::UserException is not an alias for IceUtil::Exception, but Ice::Exception is.

    Right, thanks for pointing that out!

    And minor thing.. on the next page there is definition for UserException:
    "namespace Ice {
    typedef IceUtil::Exception Exception;
    class UserException: public Exception {"

    This is correct, but just different from the header (Exception.h):
    " class UserException: public IceUtil::Exception"

    I prefer how it is in the book ;)

    Me too :) I think the distinction is academic because the typedef is just as good as the original type name. In the interest of clarity, I decided to leave it as is in the book.

    Cheers,

    Michi.
  • IvanIvan Member
    Typo in 15.5

    "The Ice Protocol" chapter.

    Page 164, 15.5, first paragraph:
    "...any version of the Ice protocol and be used..."

    should be "can be used".

    Ivan
  • IvanIvan Member
    Another typo in 15.5.3

    Page 366, last paragraph:

    "The server does not have a-priori knowledge of the minor highest minor version that..."

    Seems one "minor" is redundant.

    Ivan
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Typo in 15.5
    Originally posted by Ivan
    "The Ice Protocol" chapter.

    Page 164, 15.5, first paragraph:
    "...any version of the Ice protocol and be used..."

    should be "can be used".

    Thanks, fixed for the next version :)

    Cheers,

    Michi.
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Another typo in 15.5.3
    Originally posted by Ivan
    Page 366, last paragraph:

    "The server does not have a-priori knowledge of the minor highest minor version that..."

    Seems one "minor" is redundant.

    Sure is! Thanks again -- I've fixed this in the document.

    Cheers,

    Michi.
Sign In or Register to comment.