Manual documentation: errors and confusing passages

[matija]

hello,

Some further comments on manuals (and FAQ):

--  links  to "OpenAIR specification", "OpenAIR messages" and similar broken, because of incorrect link "http://www.mindmakers.org/openair/"

-- Part2: creating external modules in Java:
  -- code line:
      if ((triggerMessage = plug.waitForNewMessage(3000)) == null) {
           // ... processing ... //
         At this point you received a timeout on message reception, so there is
         nothing to process: the test should be inverted: !=
         There are several occurrences of this code line in this section and the next and in section
         "Using phases" in Part 3.
         
  -- text:
  "Note that you need to use the <executable /> tag to tell Psyclone that this is an external module.
   Otherwise, Psyclone will create it as an internal module."
     Not true: as long as you specify <module ... type=external   ...>  it'll be OK.
  -- text:
   "When this empty message is posted..."
        Unclear about what you are talking here... I see no preceding empty message... ?
       
  -- text:
  "Likewise, had the message been created with 
      msg = new Message("", "", "My.Other.Type"); 
   no message would be sent out. 
  If you wish to bypass the post section manually, you can always do: 
      msg = new Message("", "MyOtherWB", "My.Other.Type"); 
  in which case only one message would be sent to the MyOtherWB Whiteboard. "
       Unclear: in the last example, the type "My.Other.Type" is not in the <post ...> spec so
       this post should not work either.
       
   -- text:
    "You do not have to register cranks for external modules, but if you do it is a good way of telling your module what to do with a message. "
       This kind of explanation does not help much! The usage of cranks in Java is unclear: what I got to understand  (after too much
       time spent on trials) is the following:
       -- as a Java  module is external, I assume the crank name does not correspond to a method (as is the case in C++).
       -- the crank name may thus be used to identify the current phase, on condition that different phases use different crank names
       -- the crank may appear useless if the phases can be distinguished by their triggers.
       
The manual uses this kind of confusing/unclear/woolly  explanations at quite a number of places, too numerous to detail:
I'd suggest to invest in efforts at rewriting to make it more palatable for potential readers.
(And sorry if I am getting  too picky...)

yours,
Matija