[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master ca6d981 2/8: packages/excorporate: Update manual
From: |
Thomas Fitzsimmons |
Subject: |
[elpa] master ca6d981 2/8: packages/excorporate: Update manual |
Date: |
Wed, 16 Mar 2016 16:08:31 +0000 |
branch: master
commit ca6d9818902a6a632740c840f675aba5d3d487eb
Author: Thomas Fitzsimmons <address@hidden>
Commit: Thomas Fitzsimmons <address@hidden>
packages/excorporate: Update manual
* packages/excorporate/excorporate.texi: Update troubleshooting
section, add bug reporting section.
---
packages/excorporate/excorporate.info | 104 ++++++++++++++++++++++++++-------
packages/excorporate/excorporate.texi | 89 ++++++++++++++++++++++++++++-
2 files changed, 171 insertions(+), 22 deletions(-)
diff --git a/packages/excorporate/excorporate.info
b/packages/excorporate/excorporate.info
index 3111930..fdab71d 100644
--- a/packages/excorporate/excorporate.info
+++ b/packages/excorporate/excorporate.info
@@ -50,6 +50,7 @@ server through a proxy
* Configuration:: Configuring 'excorporate'.
* Usage:: Using 'excorporate'.
* Troubleshooting:: Debugging why a connection failed
+* Reporting Bugs:: Reporting bugs
File: excorporate.info, Node: Installation, Next: Configuration, Prev: Top,
Up: Top
@@ -80,19 +81,19 @@ which will prompt you for the Exchange account email
address. Follow
the prompts and if all goes well, you'll see a message in the minibuffer
or in *Messages* saying that the connection is ready.
- If autodiscovery runs out of URLs to try, then customize
+If autodiscovery runs out of URLs to try, then customize
'excorporate-configuration':
'M-x customize-variable RET excorporate-configuration'
- From the value menu select "Skip autodiscovery". This allows you to
+From the value menu select "Skip autodiscovery". This allows you to
enter the Exchange account email address and the EWS URL directly. The
EWS URL is of the form 'https://mail.gnu.org/ews/exchange.asmx'.
- After saving the configuration, try 'M-x excorporate' again.
+After saving the configuration, try 'M-x excorporate' again.
- If that doesn't work, then you're probably out of luck, or you'll
-have to start a troubleshooting deep dive (*note Troubleshooting::).
+If that doesn't work, then you're probably out of luck, or you'll have
+to start a troubleshooting deep dive (*note Troubleshooting::).
File: excorporate.info, Node: Usage, Next: Troubleshooting, Prev:
Configuration, Up: Top
@@ -109,7 +110,7 @@ This will show the meetings in a temporary read-only Org
Mode buffer
named '*Excorporate*'.
-File: excorporate.info, Node: Troubleshooting, Prev: Usage, Up: Top
+File: excorporate.info, Node: Troubleshooting, Next: Reporting Bugs, Prev:
Usage, Up: Top
4 Troubleshooting
*****************
@@ -118,33 +119,94 @@ First, you'll want to double-check that the Exchange
server you're
trying to access provides EWS support. If it doesn't, Excorporate can't
do anything for you. Before asking your Exchange administrator, check
intranet wikis and so forth; other users of non-standard clients may
-have already found the EWS URL.
+have already found the EWS URL. This is called the "EWS endpoint". I
+can be as simple as something like:
- The buffer '*fsm-debug*' shows 'excorporate' state transitions and
+ 'https://mail.gnu.org/ews/exchange.asmx'
+
+First you need to make sure you can access the endpoint.
+
+For Exchange Web Services (EWS) which Excorporate uses, you'll have to
+determine the EWS endpoint for your Exchange account, call it 'ews-url'.
+It is usually something like:
+
+ https://<mail host name>/ews/exchange.asmx
+
+Excorporate calculates the WSDL URL, call it 'wsdl-url', by replacing
+the endpoint's last path element with "Services.wsdl":
+
+ https://<mail host name>/ews/Services.wsdl
+
+Before even attempting Excorporate, you have to make these succeed:
+
+ (with-current-buffer
+ (url-retrieve-synchronously ews-url)
+ (buffer-string))
+
+When this works, you'll see web page text in *Messages*, containing a
+message about having created a service.
+
+ (with-current-buffer
+ (url-retrieve-synchronously wsdl-url)
+ (buffer-string))
+
+When this works, it will show a bunch of WSDL (XML) in *Messages*.
+
+Debug the above URL retrievals with (setq url-debug t), and with this
+patch:
+
+ diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
+ index d49e527..0f1c8ae 100644
+ --- a/lisp/url/url-http.el
+ +++ b/lisp/url/url-http.el
+ @ -869,6 +869,7 @ url-http-parse-headers
+ (url-handle-content-transfer-encoding))
+ (url-http-debug "Finished parsing HTTP headers: %S" success)
+ (widen)
+ + (url-http-debug "Response: %s" (buffer-string))
+ (goto-char (point-min))
+ success))
+
+
+(Beware that HTTP responses are out-of-order with this patch.)
+
+Once you're sure the above steps are working, try 'M-x excorporate'.
+
+The buffer '*fsm-debug*' shows 'excorporate' state transitions and
should provide details of where things went wrong.
- Also check '*Messages*' for anything obvious.
+Also check '*Messages*' for anything obvious.
- If you suspect something wrong with accessing the EWS URL, try
-setting 'url-debug' to t and retry 'M-x excorporate', then check the
+If you suspect something wrong with accessing the EWS URL, try setting
+'url-debug' to t and retry 'M-x excorporate', then check the
'*URL-DEBUG*' buffer for output.
- If you suspect NTLM authentication is failing, as a long shot, you
-might try setting 'ntlm-compatibility-level' to 0 and retrying 'M-x
+If you suspect NTLM authentication is failing, as a long shot, you might
+try setting 'ntlm-compatibility-level' to 0 and retrying 'M-x
excorporate'.
- Excorporate's dependencies implement the tricky elements of
-asynchronous Exchange access: a state machine ('fsm'), TLS negotiation
-('gnutls'), NTLM authentication ('ntlm' and 'url-http-ntlm') and SOAP
-communication ('soap-client').
+Excorporate's dependencies implement the tricky elements of asynchronous
+Exchange access: a state machine ('fsm'), TLS negotiation ('gnutls'),
+NTLM authentication ('ntlm' and 'url-http-ntlm') and SOAP communication
+('soap-client').
+
+
+File: excorporate.info, Node: Reporting Bugs, Prev: Troubleshooting, Up: Top
+
+5 Reporting Bugs
+****************
+
+To report a bug, use 'M-x report-emacs-bug', and put Excorporate
+somewhere in the subject.
Tag Table:
Node: Top1103
-Node: Installation2077
-Node: Configuration2340
-Node: Usage3400
-Node: Troubleshooting3771
+Node: Installation2124
+Node: Configuration2387
+Node: Usage3435
+Node: Troubleshooting3806
+Node: Reporting Bugs6649
End Tag Table
diff --git a/packages/excorporate/excorporate.texi
b/packages/excorporate/excorporate.texi
index 1683b9f..99cb9d1 100644
--- a/packages/excorporate/excorporate.texi
+++ b/packages/excorporate/excorporate.texi
@@ -60,6 +60,7 @@ Patches are welcome to enable more of these access scenarios.
* Configuration:: Configuring @code{excorporate}.
* Usage:: Using @code{excorporate}.
* Troubleshooting:: Debugging why a connection failed
+* Reporting Bugs:: Reporting bugs
@end menu
@node Installation
@@ -75,6 +76,7 @@ Install @code{excorporate} from the GNU ELPA repository:
@node Configuration
@chapter Configuration
address@hidden
Ideally you won't need to configure Excorporate at all. On friendly
Exchange setups, Excorporate can discover the EWS URL automatically.
@@ -88,24 +90,29 @@ which will prompt you for the Exchange account email
address. Follow
the prompts and if all goes well, you'll see a message in the
minibuffer or in *Messages* saying that the connection is ready.
address@hidden
If autodiscovery runs out of URLs to try, then customize
@code{excorporate-configuration}:
@code{M-x customize-variable RET excorporate-configuration}
address@hidden
From the value menu select ``Skip autodiscovery''. This allows you to
enter the Exchange account email address and the EWS URL directly.
The EWS URL is of the form
@code{https://mail.gnu.org/ews/exchange.asmx}.
address@hidden
After saving the configuration, try @code{M-x excorporate} again.
address@hidden
If that doesn't work, then you're probably out of luck, or you'll have
to start a troubleshooting deep dive (@pxref{Troubleshooting}).
@node Usage
@chapter Usage
address@hidden
Excorporate binds `e' in @code{*Calendar*} buffers. Open the calendar
with:
@@ -119,28 +126,108 @@ buffer named @code{*Excorporate*}.
@node Troubleshooting
@chapter Troubleshooting
address@hidden
First, you'll want to double-check that the Exchange server you're
trying to access provides EWS support. If it doesn't, Excorporate
can't do anything for you. Before asking your Exchange administrator,
check intranet wikis and so forth; other users of non-standard clients
-may have already found the EWS URL.
+may have already found the EWS URL. This is called the ``EWS
+endpoint''. I can be as simple as something like:
+
address@hidden://mail.gnu.org/ews/exchange.asmx}
+
address@hidden
+First you need to make sure you can access the endpoint.
+
address@hidden
+For Exchange Web Services (EWS) which Excorporate uses, you'll have to
+determine the EWS endpoint for your Exchange account, call it
address@hidden It is usually something like:
+
+ https://<mail host name>/ews/exchange.asmx
+
address@hidden
+Excorporate calculates the WSDL URL, call it @code{wsdl-url}, by
+replacing the endpoint's last path element with ``Services.wsdl'':
+
+ https://<mail host name>/ews/Services.wsdl
+
address@hidden
+Before even attempting Excorporate, you have to make these succeed:
+
address@hidden
+(with-current-buffer
+ (url-retrieve-synchronously ews-url)
+ (buffer-string))
address@hidden example
address@hidden
+When this works, you'll see web page text in *Messages*, containing a
+message about having created a service.
+
address@hidden
+(with-current-buffer
+ (url-retrieve-synchronously wsdl-url)
+ (buffer-string))
address@hidden example
+
address@hidden
+When this works, it will show a bunch of WSDL (XML) in *Messages*.
+
address@hidden
+Debug the above URL retrievals with (setq url-debug t), and with this
+patch:
+
address@hidden
+diff --git a/lisp/url/url-http.el b/lisp/url/url-http.el
+index d49e527..0f1c8ae 100644
+--- a/lisp/url/url-http.el
++++ b/lisp/url/url-http.el
+@@ -869,6 +869,7 @@ url-http-parse-headers
+ (url-handle-content-transfer-encoding))
+ (url-http-debug "Finished parsing HTTP headers: %S" success)
+ (widen)
++ (url-http-debug "Response: %s" (buffer-string))
+ (goto-char (point-min))
+ success))
+
address@hidden example
+
address@hidden
+(Beware that HTTP responses are out-of-order with this patch.)
+
address@hidden
+Once you're sure the above steps are working, try @code{M-x
+excorporate}.
+
address@hidden
The buffer @code{*fsm-debug*} shows @code{excorporate} state
transitions and should provide details of where things went wrong.
address@hidden
Also check @code{*Messages*} for anything obvious.
address@hidden
If you suspect something wrong with accessing the EWS URL, try setting
@code{url-debug} to t and retry @code{M-x excorporate}, then check the
@code{*URL-DEBUG*} buffer for output.
address@hidden
If you suspect NTLM authentication is failing, as a long shot, you
might try setting @code{ntlm-compatibility-level} to 0 and retrying
@code{M-x excorporate}.
address@hidden
Excorporate's dependencies implement the tricky elements of
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}).
address@hidden Reporting Bugs
address@hidden Reporting Bugs
+
address@hidden
+To report a bug, use @code{M-x report-emacs-bug}, and put Excorporate
+somewhere in the subject.
+
@bye
- [elpa] master updated (bbfbd6e -> 4e40ea1), Thomas Fitzsimmons, 2016/03/16
- [elpa] master a887c8a 4/8: packages/excorporate: Change server version lookup, Thomas Fitzsimmons, 2016/03/16
- [elpa] master 4366491 3/8: packages/excorporate: Retrieve Services.wsdl directly, Thomas Fitzsimmons, 2016/03/16
- [elpa] master e9107ba 5/8: packages/excorporate: Improve exco-get-meetings-for-day, Thomas Fitzsimmons, 2016/03/16
- [elpa] master ff37d3a 7/8: packages/excorporate: Require soap-client 3.1.1, Thomas Fitzsimmons, 2016/03/16
- [elpa] master 530b4e2 1/8: packages/excorporate: Handle nil list of main invitees, Thomas Fitzsimmons, 2016/03/16
- [elpa] master 4e40ea1 8/8: packages/excorporate: Bump version to 0.7.2, Thomas Fitzsimmons, 2016/03/16
- [elpa] master ca6d981 2/8: packages/excorporate: Update manual,
Thomas Fitzsimmons <=
- [elpa] master a418805 6/8: packages/excorporate: Acknowledge Erik Hetzner, Thomas Fitzsimmons, 2016/03/16