code.delx.au - gnu-emacs-elpa/blob - packages/excorporate/excorporate.texi

   1 \input texinfo
   2 @setfilename excorporate.info
   3 @settitle Excorporate Manual
   4
   5 @dircategory Emacs
   6 @direntry
   7 * Excorporate: (excorporate).  Exchange Web Services integration for Emacs.
   8 @end direntry
   9
  10 @copying
  11 Copyright @copyright{} 2016 Free Software Foundation, Inc.
  12
  13 @quotation
  14 Permission is granted to copy, distribute and/or modify this document
  15 under the terms of the GNU Free Documentation License, Version 1.2 or
  16 any later version published by the Free Software Foundation; with no
  17 Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of
  18 the license is included in the section entitled ``GNU Free Documentation
  19 License'' in the Emacs manual.
  20
  21 This document is part of a collection distributed under the GNU Free
  22 Documentation License.  If you want to distribute this document
  23 separately from the collection, you can do so by adding a copy of the
  24 license to the document, as described in section 6 of the license.
  25
  26 All Emacs Lisp code contained in this document may be used, distributed,
  27 and modified without restriction.
  28 @end quotation
  29 @end copying
  30
  31 @titlepage
  32 @title Excorporate Manual
  33 @author Thomas Fitzsimmons
  34 @page
  35 @insertcopying
  36 @end titlepage
  37
  38 @contents
  39
  40 @node Top
  41 @top Excorporate Manual
  42
  43 Excorporate provides Exchange Web Services (EWS) support for Emacs.
  44
  45 If the Exchange server you access is configured to provide EWS
  46 support, then there's a 76% chance that Excorporate will enable you to
  47 retrieve your calendar entries from the comfort of Emacs.
  48
  49 The 24% failure rate is because accessing -- in particular,
  50 authenticating against -- an Exchange server can be challenging.
  51
  52 Known to fail are Kerberos/GSSAPI authentication and accessing the
  53 server through a proxy
  54 (@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10}).
  55
  56 Patches are welcome to enable more of these access scenarios.
  57
  58 @menu
  59 * Installation::                Getting and installing @code{excorporate}.
  60 * Configuration::               Configuring @code{excorporate}.
  61 * Usage::                       Using @code{excorporate}.
  62 * Troubleshooting::             Debugging why a connection failed
  63 @end menu
  64
  65 @node Installation
  66 @chapter Installation
  67
  68 Excorporate works on Emacs versions >= 24.1.
  69
  70 @noindent
  71 Install @code{excorporate} from the GNU ELPA repository:
  72
  73 @code{M-x package-install RET excorporate}
  74
  75 @node Configuration
  76 @chapter Configuration
  77
  78 Ideally you won't need to configure Excorporate at all.  On friendly
  79 Exchange setups, Excorporate can discover the EWS URL automatically.
  80
  81 @noindent
  82 First try:
  83
  84 @code{M-x excorporate}
  85
  86 @noindent
  87 which will prompt you for the Exchange account email address.  Follow
  88 the prompts and if all goes well, you'll see a message in the
  89 minibuffer or in *Messages* saying that the connection is ready.
  90
  91 If autodiscovery runs out of URLs to try, then customize
  92 @code{excorporate-configuration}:
  93
  94 @code{M-x customize-variable RET excorporate-configuration}
  95
  96 From the value menu select ``Skip autodiscovery''.  This allows you to
  97 enter the Exchange account email address and the EWS URL directly.
  98 The EWS URL is of the form
  99 @code{https://mail.gnu.org/ews/exchange.asmx}.
 100
 101 After saving the configuration, try @code{M-x excorporate} again.
 102
 103 If that doesn't work, then you're probably out of luck, or you'll have
 104 to start a troubleshooting deep dive (@pxref{Troubleshooting}).
 105
 106 @node Usage
 107 @chapter Usage
 108
 109 Excorporate binds `e' in @code{*Calendar*} buffers.  Open the calendar
 110 with:
 111
 112 @code{M-x calendar}
 113
 114 @noindent
 115 move the cursor to the date you want to see meetings for, and press
 116 `e'.  This will show the meetings in a temporary read-only Org Mode
 117 buffer named @code{*Excorporate*}.
 118
 119 @node Troubleshooting
 120 @chapter Troubleshooting
 121
 122 First, you'll want to double-check that the Exchange server you're
 123 trying to access provides EWS support.  If it doesn't, Excorporate
 124 can't do anything for you.  Before asking your Exchange administrator,
 125 check intranet wikis and so forth; other users of non-standard clients
 126 may have already found the EWS URL.
 127
 128 The buffer @code{*fsm-debug*} shows @code{excorporate} state
 129 transitions and should provide details of where things went wrong.
 130
 131 Also check @code{*Messages*} for anything obvious.
 132
 133 If you suspect something wrong with accessing the EWS URL, try setting
 134 @code{url-debug} to t and retry @code{M-x excorporate}, then check the
 135 @code{*URL-DEBUG*} buffer for output.
 136
 137 If you suspect NTLM authentication is failing, as a long shot, you
 138 might try setting @code{ntlm-compatibility-level} to 0 and retrying
 139 @code{M-x excorporate}.
 140
 141 Excorporate's dependencies implement the tricky elements of
 142 asynchronous Exchange access: a state machine (@code{fsm}), TLS
 143 negotiation (@code{gnutls}), NTLM authentication (@code{ntlm} and
 144 @code{url-http-ntlm}) and SOAP communication (@code{soap-client}).
 145
 146 @bye