#397 'dire.sgml' - patch supplied

3.2.0
closed
5
2012-08-14
2007-08-25
No

Referring to rev. 709.

Hi there,

the enclosed patch is meant for "dire.sgml" ("Chapter 3. Directives"). It incorporates the following bug-fixes and edits:

  • After each directive heading there is one sentence, indicating that the interpreter is carrying out whatever the directive is supposed to do. Only after that is the syntax diagram shown.

  • Code samples: code underneath of directives is slightly indented, such that the directives stand out. In addition comments were added to some statements to make it clear for the reader (by means of repetition too) what the statements do/cause.

  • p. 81, The second last sentence is extended by "value" to make clear, that the attribute value is set or retrieved, not the attribute itself.

  • p. 82, The second example was totally wrong, corrected.

  • p. 85, The paragraph at the end starting with "If you specify the ABSTRACT ..." was moved after the next paragraph (the one starting with "If you specify the PROTECTED ...").

  • p. 97, The syntax diagram was corrected (first line is not shifted enough).

---rony

Discussion

  • Rony G. Flatscher

    Patch for "dire.sgml"

     
  • David Ashley

    David Ashley - 2007-08-25

    Logged In: YES
    user_id=931756
    Originator: NO

    Fixed in SVN rev 714.

     
  • Rony G. Flatscher

    Logged In: YES
    user_id=662126
    Originator: YES

    Checking the suggested changes uploaded with the patches with rev. 717 shows that not all suggestions, edits and error corrections got incorporated.

    Here's a list of those which I would suggest to change/correct:

    • p. 82: the code examples entitled "::method size get" and "::method size set" are wrong (there are no method directives having a subdirective/attribute/option named "get" or "set")! Obviously in the context of describing the attribute directive the attribute directive was meant. Also the attribuition which of the two methods is the setter and which is the getter seems to have been mixed up.

    Hence suggesting the following correction:

    ::attribute size get
    ::attribute size set
    expose size / establish direct access to object variable (attribute) /
    use arg value / retrieve argument /
    if datatype(value, "Whole") = .false | value < 0 then
    raise syntax 93.906 array ("size", value)
    size=value

    [The second method is obviuosly the setter as argument checking takes place, which would not make any sense in a getter. For that reason the argument is not stored in the object variable right away, but only after all the checks went through correctly.]

    Instead the original (wrong) code is still there, which would even cause a runtime error (every sample in the documentation should be error free).

    • p. 85: the set and get methods depicted should have exactly the same comments as those in the attribute directive section on p.81, such that people can see for themselves that both are 100% the same code with the same comments.

    • p. 87: the ROUTINE rail/syntax-diagram is still not correct (the +-PRIVATE-+ option is still shifted).

    As for readers of documentations examples are very helpful, I think it is important to give as much information/comments as possible, such that a reader who may not have read the docs from page 1 sequentially, can still see or learn from the comments in a piece of code, what the different methods are about. E.g. the information "::method init / constructor method /" gives more information to a casual reader than only "::method init" (assuming that a reader would know that it is a constructor already).

    This is more so important when there are newcomers, who are overwhelmed at first because of the wealth of information that swaps over their heads, which makes it difficult for them to digest everything. Hence such comments, but also repetitions (of patterns) would help them.

    That's also the reason behind suggesting to explicitly state what the interpreter does when processing a directive. For us it may be clear and obvious that the interpreter will carry out the directive in that point in time, but for casual users or beginners that is not the case at all! E.g. look for the questions about the requires directive; although it is clear that it is used to incorporate public classes and public routines, it is not clear at all that actually a "plain" CALL is carried out by the interpreter! Hence the suggestion "The ::REQUIRES directive causes the interpreter to call an external program.", rather than "The ::REQUIRES directive specifies that the program requires access to the classes and objects of the Rexx program.". This information is still there such that a reader gets both information.

    It may look a little bit like nit-picking, but please believe that is not so (at least it is not meant so). I have every semester "newcomers" to teach and there are recurring patterns of questions, which I have been trying to incorporate in my slides (re-arranging slides, explaining sometimes concepts "out-of-proportion", if not doing so costs more time to answer questions). Needless to say it takes a lot of time to go over thoroughly and to come up with suggestions here and there about hints, formulation that should make it even easier for newcomers to understand what is being explained, including the commenting of code to make it a little bit clearer what happens for people who just happen to stop at one of the examples.


    P.S.: The build machine is really great, David! It allowed me to have the rev 717 documentation created in the first place, thank you very much there as well !

     
  • David Ashley

    David Ashley - 2007-08-28

    Logged In: YES
    user_id=931756
    Originator: NO

    I implemented most of your suggestion in SVN rev 718.

    I disagree with your analysis of the word CALL in the ::REQUIRES directive. I believe that a classic Rexx programmer would interpret that to mean that anything defined in the required program would become unavailable to the calling program once it ran. Of course, that is not the case, but I think that it would be better to keep the wording we have it now and add further explanation in the text (which is what I did).

     


Anonymous

Cancel  Add attachments