ca reference manual issues

[Jeff Hill]

Here are some issues with the CA Reference Manual reported by Jie Chen at SLAC

1) ca_add_event and ca_clear_event still appear many places in the supporting documentation despite their deprecated status
2) we should probably deprecate the evid typedef and supplant it with a functionally equivalent sid typedef
3) It needs to be clear that in the non-preemptive callback mode the user needs to periodically call ca_poll or ca_pend_event
4) there should be an explanation that ca_xxx calls that pass a chid know how to find the ca context that the channel was created in, but ca_xxx calls that dont pass in a chid will attach to the current threads context, or lacking that create a new context. So creating a channel B in ctx A, spawning a thread, not attaching any ctx to this thread, calling get for channel B in this new thread followed by pend_io will not work. There should be some warning about this type of cinfusion in the manual.
5) Jie mentioned that the ca create subscription mentions that ca_pend_io could be one of the options for flushing the subscription request. This certainly isn't the best choice, and its not clear that it does actually force out the flush.
6)The document should clearly state that ca_pend_event routinely returns ECA_TIMEOUT.

Original Mantis Bug: mantis-365
    http://www.aps.anl.gov/epics/mantis/view_bug_page.php?f_id=365

[Andrew Johnson (anj)]

Doug Murray reports these have all been corrected by now.