Re: [Oorexx-devel] Plan to do a 4.1.3 bug release

[Erich S. <eri...@gm...>]

I'm currently going through *ooRexx Reference* and have submitted a first
patch with a bunch of corrections to typos, inconsistencies in examples &
code snippets etc.

While at it, I'm wondering whether there's already a wishlist as to how *ooRexx
Reference* should be improved.  Any known ideas, wishes?

There's one thing I always wanted: direct links (instead of static text) in
the method description figures (e. g. Figure 5-41. The MutableBuffer class
and methods) to the method descriptions.  Not sure if/how this is possible,
as the figures are in .odg format.  Does anyone know whether this can be
done?
In general, what's the suggested tool to edit the .odg files?


I'd also like to open a discussion about some specific questions
regarding *ooRexx
Reference:


**2.18. PARSE, PARSE VERSION
*"This information consists of five blank-delimited words:
- The string REXX-ooRexx
- The language level description, for example 6.03.
- Three tokens that describe the language processor release date .. for
example, 27 Sep 2007
"
On a Windows 7 system parse version currently returns
"REXX-ooRexx_4.1.2(MT) 6.03 28 Aug 2012"
So the description "The string REXX-ooRexx" needs to be expanded.  Can
someone knowledgeable enough please explain how the version string is
composed?


*5.1.3.14. c2x, 7.4.11. C2X, examples:
*C2X("0123"X) -> "0123" /* "30313233"X in ASCII */
C2X("ZD8") -> "5A4438" /* "354134343338"X in ASCII */
I suggest deleting the comment for the first line, as C2X("0123"X) will be
"0123" in *any* implementation
And I suggest changing the comment for the second line to "/* in ASCII */"
only, as the ASCII representation of the output string is not relevant here
Pros, contras?


*Implementation maximum:
*5.1.3.32. d2c and 7.4.21. D2C: "Implementation maximum: The
returned/output string must not have more than 250 significant characters,
although a longer result is possible if it has additional leading sign
characters ("00"x and "FF"x)."
5.1.3.33. d2x and 7.4.22. D2X: "Implementation maximum: The returned/output
string must not have more than 500 significant hexadecimal characters,
although a longer result is possible if it has additional leading sign
characters (0 and F).
"
I cannot confirm either.  "numeric digits 5000; say d2x(copies('3',5000));"
works fine, so I suggest deleting those paragraphs.

At the same time I suggest deleting three more "Implementation maximum:"
paragraphs, as none of them states a maximum. As an alternative, if we want
to keep the "unlimited" information, we might just remove the wording
"Implementation maximum:" from each of those paragraphs
Implementation maximum: A literal string has no upper bound on the number
of characters, limited on by available memory.
Implementation maximum: The packed length of a hexadecimal string (the
string with whitespace removed) is unlimited.
Implementation maximum: The packed length of a binary-literal string is
unlimited.

The only two "Implementation maximum:" left in the ooRexx reference would
then be:
Implementation maximum: The exponent of a number expressed in exponential
notation can have up to nine digits.
Implementation maximum: If the number of seconds in the elapsed time
exceeds nine digits
(equivalent to over 31.6 years), an error results.


*dataType/DATATYPE
*5.1.3.34. dataType and 7.4.23. DATATYPE: "You need to specify only the
capitalized letter, or the number of the last type listed. The language
processor ignores all characters surrounding it.
"
To make it clearer how to correctly specify "types" (to avoid that users
might wonder why "datatype('1','lOgical')" returns "0") I suggest renaming
types "lOgical" and "heXadecimal" to "O (logical)" resp. "X (hexadecimal)"
and change the text to "Only the first letter is needed. All characters
following it are ignored"

Furthermore there's this "Note: The dataType method/function tests the
meaning or type of characters in a string, independent of the encoding of
those characters (for example, ASCII or EBCDIC)."
I suggest completely removing this note.


*5.3.13.21. removeItem
*">>-removeItem(item,index)--------------------------------------><
Returns and removes from a relation the member item *item* (associated with
index *index*). Returns the Nil object if *value* is not a member item
associated with index *index*. If *item* is the only member with *index*)
then the *index*) is also removed from the Relation.
"
The railroad diagram misses the fact that *index* is optional, the
description mentions a parameter *value (*which doesn't exist) and there
are too many closing brackets.
Would anyone of you native speakers like to suggest a new and correct
wording?


*DateTime
*Various DateTime methods (5.4.1.x.) state that "The default offset is the
current system offset timezone offset.".  Is "current system offset
timezone offset" a correct wording?  Or is that a typo?


*7.4.49 RANDOM
*The railroad diagram allows for specification of *min* only through
"random(100,)" - i.e. *min*=100, *max*=999 (default)
But the interpreter will interpret this the same as "random(100)" -  i.e. *
max*=100, *min*=0 (default)
Is that to be regarded as an interpreter or a documentation bug?

If it's a doc bug, does anyone volunteer for a correct railroad diagram? :-)
Also the description should add that (besides *seed*) also *min* and
*max*must be whole numbers


*SysUtilVersion
*8.76. SysUtilVersion: "Return code: The REXXUTIL version number in the
format n.mm.
"
On Windows 7 SysUtilVersion() currently returns "4.1.2", not "4.12".
Is that to be regarded as an interpreter or a documentation bug?


*SysWinVer()/SysLinVer()/SysVersion()
*8.87. SysWinVer (Windows only): "Returns a string specifying the Windows
operating system version information in the form x.xx."
On Windows 7 SysWinVer() currently returns "WindowsNT 6.01", not just "6.01"
Is that to be regarded as an interpreter or a documentation bug?

Additionally: can someone running ooRexx on a Linux system supply me with a
more recent SysLinVer() and a SysVersion() string, so I can update the
examples in the docs with (currently a rather old 2006 string is in there).


*10.2.2. Integer Division
*"The % (integer divide) operator divides two numbers and returns the
integer part of the result. The result is calculated by repeatedly
subtracting the divisor from the dividend as long as the dividend is larger
than the divisor. During this subtraction, the absolute values of both the
dividend and the divisor are used: the sign of the final result is the same
as that which would result from regular division."

ooRexx surely doesn't repeatedly subtract the divisor from the dividend, I
assume. Even if so, "as long as the dividend is larger than the divisor"
would stop too early.
Would the first sentence be sufficient? Delete everything from "The result
.. regular division"?


*Arithmetic overflow
*C.1.38. Error 42: "The result of an arithmetic operation requires an
exponent that is greater than the platform limit of nine digits for 32-bit
systems or 18 for 64-bit systems.
"
On a 64-bit Windows 7 system, currently "say 1e999999999*10" returns "Error
42.901:  Arithmetic overflow; exponent ("1000000000") exceeds 9 digits"
with both the default NUMERIC DIGITS setting and a "NUMERIC DIGITS 18"
setting.
Is that to be regarded as an interpreter or a documentation bug?


*NUMERIC DIGITS
*There's another reference to numeric digits 9 vs. 18 in 7.4. Built-in
Functions, "The built-in functions internally work with NUMERIC DIGITS 9
for 32-bit systems or NUMERIC DIGITS 18 for 64-bit systems"
I do not know whether this is true or not, nor do I know what effect to the
user an internal "NUMERIC DIGITS 18" on a 64-bit system would have.  Can
anyone comment, please?


Erich