Re: [Oorexx-devel] Latest ooRexx Draft Docs

[Rony G. F. <Ron...@wu...>]

Hi David,

looks really *great*, thank you very much!

> Here are some things to look for:
>
> - New info on the title page (the html version now has the same info
> on the title page)
>
Great!
>
> - Footers now contain the doc title and SVN revision number
>
Great!

Just a question: would it be possible to include the current/running
subtitle in the footer as well? E.g. in chapter 2 "2.1 ADDRESS" or "2.2
ARG", etc.?

> - The builtin classes chapter in the rexxref is now completely reorganized
>
Looks fine.

> - Lots of new graphics in rexxref
>
Look great.

> - Lots of new hyperlinks in rexxref
>
Those that I noticed, I like a lot (like links to the inherit class, but
also all links from the inherited methods right to the method definition)!

> Feedback, as always, is welcome. Enjoy!
>
Just a few little remarks:

    * in general: when a class is defined as a mixin class, such that
      the user is aware that it can be inherited. E.g. supply the
      sentence "This class is defined as a mixin class." immediately
      after explaining the purpose of a class. The reference card marks
      such classes with the string "(M)".
    * p.107, "5.1.1.7. identityHash", the text states: "Returns an
      identity number for the object. This number is not guaranteed to
      be unique." This is not correct: the "identityHash" method *does*
      return a unique number which can be regarded as a unique
      identifier of an object in that particular run of the program.
    * p.158, "5.1.3.1 Inherited Methods": method "compareYo" wrongly
      spelled ("Y" instead of "T")
    * p. 170, "5.2.3.1. Inherited Methods", sequence of classes wrong,
      should be (exchange the OutputStream and InputStream): Object <-
      OutputStream <-InputStream <-InputOutputStream
    * p.189, "5.3 Collection Classes": graphic of figure spells
      "Collections" (superfluous "s")
    * p. 190, "5.3.3. The Ordered Collection Classes": graphic of figure
      spells "Collections" (superfluous "s")
    * "Ordered Collection Classes" should be listed after "Map
      Collection Classes" (alphabetic ordering)
    * p. 217, "5.3.3. The Map Collection Classes": graphic of figure
      spells "Collections" (superfluous "s")
    * p. 242, "5.3.3. The Set Collection Classes": graphic of figure
      spells "Collections" (superfluous "s")
    * p. 271, "5.4.14. The RegularExpression Class": the text states
      that it is not a builtin-class, therefore one needs to use the
      requires directive to load it; however, this class is listed under
      the chapter "Builtin Classes" such that this text would be
      contradictory. Suggesting therefore to state: "The built in
      RegularExpression class is not preloaded, therefore one needs to
      explicitly call or require the program that defines it
      ('rxregexp.cls'), hence: 'call rxregexp.cls' or '::requires
      rxregexp.cls' ."
      Or any other text, which would not contradict the classes'
      positioning within chapter 5.

HTH,

---rony