Documentation cross references

Hagrinas
2007-11-01
2012-08-14
  • Hagrinas
    Hagrinas
    2007-11-01

    One thing that's largely missing from the reference manual that is common in references for other programming languages is cross references in the index that show where to look based on concepts. For example it's common to see, xyz -- see (also) abc 24 229 330.

    In ooRexx, it would be nice to see:

    Case construct, see select.

    Scope of variables (There's a scope entry referring to the term as used in ooRexx, but not in reference to variables within a main routine or subroutine.) A cross reference to the procedure clause on a label could clear part of that up. A reference to Drop could clear up variables within a single routine. The Call statement is the most clear with respect to internal and external routines. The concept is referenced clearly for objects and methods only. A programmer who is used to the concept of local variables with a scope within a clause (the equivalent of a do group) will not figure things out by looking at the index. A "see" that references the corresponding concepts and page numbers would be clearer.

    Passing parameters by value/reference could say "see arg, use."

    Reordering strings is another example and the manual has an index entry that takes the user to translate. So the manual is not devoid of this type of cross reference, but it is missing for for many terms that a programmer might look for.