[elpa] externals/excorporate fe5226e: Document how to work around a stuck connection

[Thomas Fitzsimmons]

branch: externals/excorporate
commit fe5226eefb4698ef04718f5b801194cfc7f61438
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@fitzsim.org>

    Document how to work around a stuck connection
    
    * excorporate.texi (Top): Add index.
    (Troubleshooting): Add a paragraph about stuck connections.
    (Index): New node.
    * excorporate.info: Regenerate.
---
 excorporate.info | 57 ++++++++++++++++++++++++++++++++++++++++++++++++--------
 excorporate.texi | 28 ++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 8 deletions(-)

diff --git a/excorporate.info b/excorporate.info
index 9214a8d..d38b805 100644
--- a/excorporate.info
+++ b/excorporate.info
@@ -56,6 +56,7 @@ welcome, as are patches to enable more of these access 
scenarios.  See
 * Usage::                       Using 'excorporate'.
 * Troubleshooting::             Debugging why a connection failed
 * API Usage::                   Using the API provided by 'excorporate'.
+* Index::
 
 
 File: excorporate.info,  Node: Reporting Bugs,  Next: Installation,  Prev: 
Top,  Up: Top
@@ -109,6 +110,10 @@ After saving the configuration, try 'M-x excorporate' 
again.
 If neither autodiscovery nor specifying the EWS URL work, *note
 Troubleshooting::.
 
+   To disconnect:
+
+   'M-x excorporate-disconnect'
+
 
 File: excorporate.info,  Node: Usage,  Next: Troubleshooting,  Prev: 
Configuration,  Up: Top
 
@@ -246,8 +251,28 @@ Exchange access: a state machine ('fsm'), TLS negotiation 
('gnutls'),
 NTLM authentication ('ntlm' and 'url-http-ntlm') and SOAP communication
 ('soap-client').
 
+On some servers, an active, otherwise-working connection may get stuck.
+The symptom is the attempted operation will not complete (but Emacs will
+not be blocked, because Excorporate is asynchronous).  For example
+pressing 'e' in the 'Calendar' produce a new '*Excorporate*' buffer that
+stays empty for longer than one minute.  I haven't been able to
+determine the root cause of this behaviour.  But you can work around the
+issue like this:
+
+   'M-x list-processes'
+
+   Find a line that shows the server connection.  There may be multiple
+such lines.  They will look something like this:
+
+   'mail.gnu.org -- open -- -- Main (network connection to
+mail.gnu.org:443'
+
+   Put the cursor on that line, and type 'd' to delete the process.  The
+attempted operation will now complete, usually without needing to retry
+it.
+
 
-File: excorporate.info,  Node: API Usage,  Prev: Troubleshooting,  Up: Top
+File: excorporate.info,  Node: API Usage,  Next: Index,  Prev: 
Troubleshooting,  Up: Top
 
 6 API Usage
 ***********
@@ -390,7 +415,9 @@ the asynchronous calls to avoid blocking Emacs during 
server operations.
 
 Here is a more complicated example that asynchronously queries the
 server for availability overlap for hacker1@gnu.org and hacker2@gnu.org,
-in the Eastern Time time zone.
+in the America/Toronto time zone.  Call 'exco-time-zone' to calculate,
+from Emacs's internal time zone (see 'current-time-zone'), the
+equivalent server time zone string.
 
      (exco-operate
       (car exco--connection-identifiers)
@@ -422,6 +449,7 @@ in the Eastern Time time zone.
            (ExcludeConflicts . nil)))
          (FreeBusyViewOptions
           (TimeWindow
+           (StartTimeZone (Id . "Eastern Standard Time"))
            (StartTime . "2020-09-25T00:00:00Z")
            (EndTime . "2020-09-25T23:59:00Z"))
           (MergedFreeBusyIntervalInMinutes . 60)
@@ -727,16 +755,29 @@ backward compatible.  If an existing function has an 
insufficient
 interface, make a new one.  Excorporate functions are written to work
 with older Emacs versions, back to Emacs 24.1.
 
+
+File: excorporate.info,  Node: Index,  Prev: API Usage,  Up: Top
+
+Index
+*****
+
+[index]
+* Menu:
+
+* hung connection:                       Troubleshooting.      (line 80)
+* stuck connection:                      Troubleshooting.      (line 80)
+
 
 
 Tag Table:
 Node: Top1103
-Node: Reporting Bugs2399
-Node: Installation2723
-Node: Configuration2997
-Node: Usage4017
-Node: Troubleshooting6476
-Node: API Usage9344
+Node: Reporting Bugs2409
+Node: Installation2733
+Node: Configuration3007
+Node: Usage4079
+Node: Troubleshooting6538
+Node: API Usage10221
+Node: Index27455
 
 End Tag Table
 
diff --git a/excorporate.texi b/excorporate.texi
index c4a4a58..2c16212 100644
--- a/excorporate.texi
+++ b/excorporate.texi
@@ -66,6 +66,7 @@ welcome, as are patches to enable more of these access 
scenarios.  See
 * Usage::                       Using @code{excorporate}.
 * Troubleshooting::             Debugging why a connection failed
 * API Usage::                   Using the API provided by @code{excorporate}.
+* Index::
 @end menu
 
 @node Reporting Bugs
@@ -283,6 +284,28 @@ asynchronous Exchange access: a state machine 
(@code{fsm}), TLS
 negotiation (@code{gnutls}), NTLM authentication (@code{ntlm} and
 @code{url-http-ntlm}) and SOAP communication (@code{soap-client}).
 
+@cindex hung connection
+@cindex stuck connection
+@noindent
+On some servers, an active, otherwise-working connection may get stuck.
+The symptom is the attempted operation will not complete (but Emacs will
+not be blocked, because Excorporate is asynchronous).  For example
+pressing 'e' in the @code{Calendar} produce a new @code{*Excorporate*}
+buffer that stays empty for longer than one minute.  I haven't been able
+to determine the root cause of this behaviour.  But you can work around
+the issue like this:
+
+@code{M-x list-processes}
+
+Find a line that shows the server connection.  There may be multiple
+such lines.  They will look something like this:
+
+@code{mail.gnu.org -- open -- -- Main (network connection to mail.gnu.org:443}
+
+Put the cursor on that line, and type 'd' to delete the process.  The
+attempted operation will now complete, usually without needing to retry
+it.
+
 @node API Usage
 @chapter API Usage
 
@@ -802,4 +825,9 @@ stay backward compatible.  If an existing function has an 
insufficient
 interface, make a new one.  Excorporate functions are written to work
 with older Emacs versions, back to Emacs 24.1.
 
+@node Index
+@unnumbered Index
+
+@printindex cp
+
 @bye