#268 Miscellaneous documentation issues for oorexx 5

[Shmuel (Seymour J.) Metz]

There are several documentation issues in the Rexx reference manual; I haven't checked whether they are also in the GA documentation or only in the oorexx 5 beta.

Throughout, there are references to Unix for things that apply equally well to bsd and Linux.

There is no explanation of how to determine whether a name exists in the environment (OS environment, not the environment object.) As documented, value('FOO',,environment) returns FOO whether FOO has the value FOO or does not exist.

Throughout, there are "[]=" methods without documentation of the order of the parameters, e.g., does foo[bar]=baz invoke foo~"[]="(bar,baz) or foo~"[]="(baz,bar)?

5.1.7.89. NEW startsWith does not explain how it differs from abbrev

Appendix B. Migration does not mention that the results of stem1. = stem2. in oorex are very different from the results in standard Rexx.

[Shmuel (Seymour J.) Metz]

Three additional issues:

There is no discussion of the difference and tradeoffs between

• ::attribute name
• ::method name ATTRIBUTE

1.13.1. Extended Assignments is incorrect; the left side is only evaluated once. This can be seen by running foo[bar(baz)] += 1, where bar has side effects.

9.1. Simple Templates for Parsing into Words was correct in classic Rexx but has been incomplete since orexx; the template can contain assignable method invocations, e.g.,
parse var foo bar[1] bar[2]

The attached files, testleft, demonstrates the last two items.

[Erich]

Hi Shmuel, thanks for identifying a bunch of rexxref issues.

Throughout, there are references to Unix for things that apply equally well to bsd and Linux.

The use of the word "Unix" within rexxref is meant to cover Linux, BSD, Darwin, Solaris, AIX and all other Unix-like platforms.

There is no explanation of how to determine whether a name exists in the environment
As documented, value('FOO',,environment) returns FOO whether FOO has the value FOO or does not exist.

Clarification added.

Throughout, there are "[]=" methods without documentation of the order of the parameters

[]= is documented in 1.15. Message Instructions.

startsWith does not explain how it differs from abbrev

I've added a "see also" from startsWith to abbrev (startsWith is equivant to abbrev except for how they treat a null string argumewnt)

Appendix B. Migration does not mention that the results of stem1. = stem2. in oorex are very different from the results in standard Rexx

The rexxref 5.0 migration chapter is intended to cover migration from previous releases, not migration from other interpreters.

There is no discussion of the difference and tradeoffs between

Added a clarification that using the ATTRIBUTE option on a ::METHOD directive is equivalent to using the ::ATTRIBUTE directive.

1.13.1. Extended Assignments is incorrect; the left side is only evaluated once.

As documented (and confirmed by your code sample) "the left side" is evaluated twice.

9.1. Simple Templates for Parsing into Words was correct in classic Rexx but has been incomplete since orexx; the template can contain assignable method invocations,

Updated 9.1.1. Message Term Assignments with an example showing both a[] and d~index message-term PARSE assignments

Committed revision [r12145].

[Erich]

Committed revision [r12146].