From 70ecad1ef5aeea76ae4328d2b4fa77986f307d58 Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons Date: Fri, 26 Feb 2016 06:54:15 -0500 Subject: [PATCH] packages/excorporate/excorporate.texi: New manual * packages/excorporate/excorporate.texi, packages/excorporate/excorporate.info, packages/excorporate/dir: New files. --- packages/excorporate/dir | 18 ++++ packages/excorporate/excorporate.info | 150 ++++++++++++++++++++++++++ packages/excorporate/excorporate.texi | 146 +++++++++++++++++++++++++ 3 files changed, 314 insertions(+) create mode 100644 packages/excorporate/dir create mode 100644 packages/excorporate/excorporate.info create mode 100644 packages/excorporate/excorporate.texi diff --git a/packages/excorporate/dir b/packages/excorporate/dir new file mode 100644 index 000000000..c0433c308 --- /dev/null +++ b/packages/excorporate/dir @@ -0,0 +1,18 @@ +This is the file .../info/dir, which contains the +topmost node of the Info hierarchy, called (dir)Top. +The first time you invoke Info you start off looking at this node. + +File: dir, Node: Top This is the top of the INFO tree + + This (the Directory node) gives a menu of major topics. + Typing "q" exits, "?" lists all Info commands, "d" returns here, + "h" gives a primer for first-timers, + "mEmacs" visits the Emacs manual, etc. + + In Emacs, you can click mouse button 2 on a menu item or cross reference + to select it. + +* Menu: + +Emacs +* Excorporate: (excorporate). Exchange Web Services integration for Emacs. diff --git a/packages/excorporate/excorporate.info b/packages/excorporate/excorporate.info new file mode 100644 index 000000000..31119301f --- /dev/null +++ b/packages/excorporate/excorporate.info @@ -0,0 +1,150 @@ +This is excorporate.info, produced by makeinfo version 6.0 from +excorporate.texi. + +Copyright (C) 2016 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover, or + Back-Cover Texts. A copy of the license is included in the section + entitled "GNU Free Documentation License" in the Emacs manual. + + This document is part of a collection distributed under the GNU + Free Documentation License. If you want to distribute this + document separately from the collection, you can do so by adding a + copy of the license to the document, as described in section 6 of + the license. + + All Emacs Lisp code contained in this document may be used, + distributed, and modified without restriction. +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* Excorporate: (excorporate). Exchange Web Services integration for Emacs. +END-INFO-DIR-ENTRY + + +File: excorporate.info, Node: Top, Next: Installation, Up: (dir) + +Excorporate Manual +****************** + +Excorporate provides Exchange Web Services (EWS) support for Emacs. + + If the Exchange server you access is configured to provide EWS +support, then there's a 76% chance that Excorporate will enable you to +retrieve your calendar entries from the comfort of Emacs. + + The 24% failure rate is because accessing - in particular, +authenticating against - an Exchange server can be challenging. + + Known to fail are Kerberos/GSSAPI authentication and accessing the +server through a proxy +(). + + Patches are welcome to enable more of these access scenarios. + +* Menu: + +* Installation:: Getting and installing 'excorporate'. +* Configuration:: Configuring 'excorporate'. +* Usage:: Using 'excorporate'. +* Troubleshooting:: Debugging why a connection failed + + +File: excorporate.info, Node: Installation, Next: Configuration, Prev: Top, Up: Top + +1 Installation +************** + +Excorporate works on Emacs versions >= 24.1. + +Install 'excorporate' from the GNU ELPA repository: + + 'M-x package-install RET excorporate' + + +File: excorporate.info, Node: Configuration, Next: Usage, Prev: Installation, Up: Top + +2 Configuration +*************** + +Ideally you won't need to configure Excorporate at all. On friendly +Exchange setups, Excorporate can discover the EWS URL automatically. + +First try: + + 'M-x excorporate' + +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 +'excorporate-configuration': + + 'M-x customize-variable RET excorporate-configuration' + + 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. + + 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 + +3 Usage +******* + +Excorporate binds 'e' in '*Calendar*' buffers. Open the calendar with: + + 'M-x calendar' + +move the cursor to the date you want to see meetings for, and press 'e'. +This will show the meetings in a temporary read-only Org Mode buffer +named '*Excorporate*'. + + +File: excorporate.info, Node: Troubleshooting, Prev: Usage, Up: Top + +4 Troubleshooting +***************** + +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. + + The buffer '*fsm-debug*' shows 'excorporate' state transitions and +should provide details of where things went wrong. + + 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 +'*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 +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'). + + + +Tag Table: +Node: Top1103 +Node: Installation2077 +Node: Configuration2340 +Node: Usage3400 +Node: Troubleshooting3771 + +End Tag Table diff --git a/packages/excorporate/excorporate.texi b/packages/excorporate/excorporate.texi new file mode 100644 index 000000000..1683b9f38 --- /dev/null +++ b/packages/excorporate/excorporate.texi @@ -0,0 +1,146 @@ +\input texinfo +@setfilename excorporate.info +@settitle Excorporate Manual + +@dircategory Emacs +@direntry +* Excorporate: (excorporate). Exchange Web Services integration for Emacs. +@end direntry + +@copying +Copyright @copyright{} 2016 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of +the license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. + +All Emacs Lisp code contained in this document may be used, distributed, +and modified without restriction. +@end quotation +@end copying + +@titlepage +@title Excorporate Manual +@author Thomas Fitzsimmons +@page +@insertcopying +@end titlepage + +@contents + +@node Top +@top Excorporate Manual + +Excorporate provides Exchange Web Services (EWS) support for Emacs. + +If the Exchange server you access is configured to provide EWS +support, then there's a 76% chance that Excorporate will enable you to +retrieve your calendar entries from the comfort of Emacs. + +The 24% failure rate is because accessing -- in particular, +authenticating against -- an Exchange server can be challenging. + +Known to fail are Kerberos/GSSAPI authentication and accessing the +server through a proxy +(@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=10}). + +Patches are welcome to enable more of these access scenarios. + +@menu +* Installation:: Getting and installing @code{excorporate}. +* Configuration:: Configuring @code{excorporate}. +* Usage:: Using @code{excorporate}. +* Troubleshooting:: Debugging why a connection failed +@end menu + +@node Installation +@chapter Installation + +Excorporate works on Emacs versions >= 24.1. + +@noindent +Install @code{excorporate} from the GNU ELPA repository: + +@code{M-x package-install RET excorporate} + +@node Configuration +@chapter Configuration + +Ideally you won't need to configure Excorporate at all. On friendly +Exchange setups, Excorporate can discover the EWS URL automatically. + +@noindent +First try: + +@code{M-x excorporate} + +@noindent +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 +@code{excorporate-configuration}: + +@code{M-x customize-variable RET excorporate-configuration} + +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}. + +After saving the configuration, try @code{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 (@pxref{Troubleshooting}). + +@node Usage +@chapter Usage + +Excorporate binds `e' in @code{*Calendar*} buffers. Open the calendar +with: + +@code{M-x calendar} + +@noindent +move the cursor to the date you want to see meetings for, and press +`e'. This will show the meetings in a temporary read-only Org Mode +buffer named @code{*Excorporate*}. + +@node Troubleshooting +@chapter Troubleshooting + +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. + +The buffer @code{*fsm-debug*} shows @code{excorporate} state +transitions and should provide details of where things went wrong. + +Also check @code{*Messages*} for anything obvious. + +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. + +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}. + +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}). + +@bye -- 2.39.2