djavu-asus/elpa/jabber-20230715.456/README.org

   1 #+TITLE: jabber.el - an XMPP client for Emacs
   2 #+DESCRIPTION: Documentation
   3 #+startup: inlineimages
   4
   5 * Description
   6 :PROPERTIES:
   7 :CUSTOM_ID: explanation
   8 :END:
   9 jabber.el is an [[http://xmpp.org][XMPP]] client for Emacs.  XMPP (also known as 'Jabber') is an IETF-standard federated instant messaging protocol.
  10
  11 To try it out, see the [[#installation][install instructions]].
  12
  13 New resources
  14 + [[https://codeberg.org/emacs-jabber/emacs-jabber/][project page]]
  15 + chat: [[xmpp:emacs@salas.suchat.org?join][xmpp:emacs@salas.suchat.org?join]] (general Emacs and jabber.el talk)
  16 + chat: xmpp:jabber-el@conference.hmm.st?join (jabber.el developement)
  17
  18 Old resources
  19 + [[http://sourceforge.net/projects/emacs-jabber][project page]]
  20 + [[http://emacs-jabber.sourceforge.net][home page]]
  21 + [[http://www.emacswiki.org/cgi-bin/wiki/JabberEl][wiki page]]
  22 + mailing list:
  23   * http://lists.sourceforge.net/lists/listinfo/emacs-jabber-general
  24   * http://dir.gmane.org/gmane.emacs.jabber.general
  25 + chat: jabber.el@conference.jabber.se and emacs@conference.jabber.ru (Russian, English)
  26
  27 ** Differences from [[https://github.com/legoscia/emacs-jabber][upstream]]
  28 :PROPERTIES:
  29 :CUSTOM_ID: upstream-differences
  30 :END:
  31 1. (WIP) Support for [[https://xmpp.org/extensions/xep-0363.html][XEP-0363: HTTP File Upload]]
  32 2. Support for [[https://xmpp.org/extensions/xep-0280.html][XEP-0280: Message Carbons]]
  33 3. Use of the deprecated =cl= library is almost completely replaced with =cl-lib=
  34 4. Build system changed from Autotools to a =Makefile=
  35 5. Lots of cleanup by addressing =checkdoc= and byte-compiler warnings - addition/improvement of docstrings, function/variable declarations, etc
  36
  37 ** Requirements
  38 :PROPERTIES:
  39 :CUSTOM_ID: requirements
  40 :END:
  41 jabber.el runs on GNU Emacs 27.1 or later.
  42
  43 The file hexrgb.el (http://www.emacswiki.org/emacs/hexrgb.el) used to be required for the MUC nick coloring feature. However, the code depending on it has been reworked to instead use the =color.el= library, which is part of Emacs.
  44
  45 ** Encrypted connections
  46 :PROPERTIES:
  47 :CUSTOM_ID: encrypted-connections
  48 :END:
  49 Many Jabber servers require encrypted connections, and even if yours doesn't it may be good idea.  To get an encrypted connection, the most convenient option is to use GNU Emacs 24 with GnuTLS support compiled in.  You can check whether you have that by typing:
  50
  51 : M-: (gnutls-available-p)
  52
  53 If that commands shows =t= in the echo area, then you have working GnuTLS support.  If it shows =nil= or signals an error, then you don't.
  54
  55 Failing that, jabber.el will use the starttls.el library, which requires that the GnuTLS command line tool "gnutls-cli" is installed.
  56
  57 In Debian-based distributions, "gnutls-cli" is in the "gnutls-bin" package.
  58
  59 The above applies to STARTTLS connections, the most common way to encrypt a Jabber connection and the only one specified in the standards.  STARTTLS connections start out unencrypted, but switch to encrypted after negotiation.  jabber.el also supports connections that are encrypted from start.  For this it uses the tls.el library, which requires either "gnutls-cli" or the OpenSSL command line tool "openssl" to be installed.
  60
  61 To use the latter form of encryption, customize =jabber-account-list=.
  62
  63 Note that only the connection from you to the server is encrypted; there is no guarantee of connections from your server to your contacts' server being encrypted.
  64
  65 ** Usage
  66 :PROPERTIES:
  67 :CUSTOM_ID: usage
  68 :END:
  69 To connect to a Jabber server, type =C-x C-j C-c= (or equivalently =M-x jabber-connect-all=) and enter your JID.  With prefix argument, register a new account.  You can set your JID permanently with =M-x jabber-customize=.
  70
  71 Your roster is displayed in a buffer called *-jabber-*.  To disconnect, type =C-x C-j C-d= or =M-x jabber-disconnect=.
  72
  73 You may want to use the menu bar to execute Jabber commands.  To enable the Jabber menu, type =M-x jabber-menu=.
  74
  75 For a less terse description, read the enclosed manual.
  76
  77 For bug reports, help requests and other feedback, use the trackers and forums at the project page mentioned above.
  78
  79 ** Configuration
  80 :PROPERTIES:
  81 :CUSTOM_ID: configuration
  82 :END:
  83 All available configuration options are described in the manual.  This section only serves to point out the most important ones.
  84
  85 To change how you are notified about incoming events, type =M-x customize-group RET jabber-alerts=.
  86
  87 To activate logging of all chats, set =jabber-history-enabled= to =t=.  By default, history will be saved in =~/.jabber_global_message_log=; make sure that this file has appropriate permissions.  Type =M-x customize-group RET jabber-history= for more options.
  88
  89 By default, jabber.el will send a confirmation when messages sent to you are delivered and displayed, and also send "contact is typing" notifications.  To change this, type =M-x customize-group RET jabber-events=, and set the three =jabber-events-confirm-*= variables to nil.
  90
  91 By default, jabber.el logs all MUC presence announcements to the chat buffer.  With the advent of mobile clients that frequently lose and regain network connectivity, the user left/joined messages can flood the chat.  Customize =jabber-muc-decorate-presence-patterns= to hide or deemphasize presence announcements.  See the manual for details [[info:jabber#Presence announcements][(info "(jabber) Presence announcements")]].
  92
  93 ** File transfer
  94 :PROPERTIES:
  95 :CUSTOM_ID: file-transfer
  96 :END:
  97 This release of jabber.el contains support for file transfer.  You may need to configure some variables to make it work; see the manual for details.
  98
  99 ** XMPP URIs
 100 :PROPERTIES:
 101 :CUSTOM_ID: xmpp-uris
 102 :END:
 103 It is possible to make various web browsers pass links starting with "xmpp:" to jabber.el.  In the ideal case, this works right after running "make install".  Otherwise, see the manual, section "XMPP URIs".
 104
 105 ** Further reading
 106 :PROPERTIES:
 107 :CUSTOM_ID: further-reading
 108 :END:
 109 Documentation for developers is present in [[file:DEV.org][DEV.org]].
 110
 111 * How-to guides
 112 :PROPERTIES:
 113 :CUSTOM_ID: how-to-guides
 114 :END:
 115 See also - [[file:DEV.org#how-to-guides][how-to guides in the developer documentation]].
 116
 117 ** How to install jabber.el
 118 :PROPERTIES:
 119 :CUSTOM_ID: installation
 120 :END:
 121 *** from MELPA
 122 :PROPERTIES:
 123 :CUSTOM_ID: from-melpa
 124 :END:
 125 1. Add the MELPA repositories to your Emacs - https://melpa.org/#/getting-started
 126 2. Type =M-x package-install RET jabber RET=
 127
 128 If all goes well, =jabber.el= commands like =jabber-connect= should now be available in the =M-x= menu.
 129
 130 *** from source
 131 :PROPERTIES:
 132 :CUSTOM_ID: from-source
 133 :END:
 134 1. Ensure you have =git=, and Emacs 27.1 or newer
 135
 136 2. Clone the repository by typing the following into a terminal -
 137    #+BEGIN_SRC shell
 138    mkdir ~/emacs-jabber/
 139    cd ~/emacs-jabber/
 140    git clone https://codeberg.org/emacs-jabber/emacs-jabber
 141    make
 142    #+END_SRC
 143
 144 3. Add the following lines to your =init.el= -
 145    #+BEGIN_SRC emacs-lisp
 146    (add-to-list 'load-path "~/emacs-jabber/lisp/")
 147    (load "~/emacs-jabber/jabber-autoloads")
 148    #+END_SRC
 149    ...and, while still in your =init.el=, type =M-x eval-buffer RET=.
 150
 151 If all goes well, =jabber.el= commands like =jabber-connect= should now be available in the =M-x= menu.
 152
 153 To install the Info documentation, copy =jabber.info= to =/usr/local/info= and run ="install-info /usr/local/info/jabber.info"=.
 154
 155 * TODO maintenance [16%]
 156 :PROPERTIES:
 157 :CUSTOM_ID: maintenance
 158 :END:
 159 1. [ ] Satisfy =M-x checkdoc=
 160 2. [ ] Use =rx= where regular expressions get hairy
 161    * [ ] =jabber-jid-username=
 162    * [ ] =jabber-jid-server=
 163    * [ ] =jabber-jid-resource=
 164 3. [X] Remove dependency on hexrgb.el (it's not available on MELPA)
 165 4. [ ] Migrate tests to ERT/Buttercup/etc
 166 5. [ ] Add Windows support to developer tutorial
 167 6. [ ] Create testing for tutorial
 168
 169 * Credits
 170 :PROPERTIES:
 171 :CUSTOM_ID: credits
 172 :END:
 173 ** Developers
 174 :PROPERTIES:
 175 :CUSTOM_ID: developers
 176 :END:
 177 + Tom Berger
 178 + Magnus Henoch
 179 + Kirill A. Korinskiy
 180 + Detlev Zundel
 181   - wmii support
 182 + Evgenii Terechkov
 183
 184 ** Contributors
 185 :PROPERTIES:
 186 :CUSTOM_ID: contributors
 187 :END:
 188 + Georg Lehner
 189   - network transport functions
 190 + Anthony Chaumas-Pellet
 191 + Jérémy Compostella
 192 + Mathias Dahl
 193   - history logging
 194   - watch functionality
 195 + Mario Domenech Goulart
 196   - sawfish support
 197   - xmessage support
 198 + Nolan Eakins
 199 + Ami Fischman
 200   - Chat State Notifications
 201 + François Fleuret
 202 + David Hansen
 203 + Adam Sjøgren
 204   - notifications.el support
 205 + Rodrigo Lazo
 206   - notifications.el support
 207   - libnotify.el support
 208 + Justin Kirby
 209 + Carl Henrik Lunde
 210   - network transport functions
 211   - activity tracking
 212 + Olivier Ramonat
 213 + Andrey Slusar
 214 + Valery V. Vorotyntsev
 215   - GMail notifications
 216 + Milan Zamazal
 217 + Xavier Maillard
 218 + Vitaly Mayatskikh
 219 + Alexander Solovyov
 220 + Demyan Rogozhin
 221   - XML console mode
 222 + Michael Cardell Widerkrantz
 223   - tmux support
 224 + Case Duckworth (acdw)
 225   - [[https://codeberg.org/emacs-jabber/emacs-jabber/pulls/2][PR #2]]
 226 + Hugh Daschbach (hdasch)
 227   - MUC presence announcements
 228   - Enable XEP-0280 (message carbons) by default
 229
 230 ** Maintainers
 231 :PROPERTIES:
 232 :CUSTOM_ID: maintainers
 233 :END:
 234 + wgreenhouse
 235   - 2021 resurrection
 236 + cngimenez
 237   - HTTP Upload support
 238   - documentation for FSM and its use in this project
 239 + contrapunctus
 240   - literate Org migration
 241   - Makefile (shoutout to tomasino of #team@irc.tilde.chat for the Makefile-debugging help)
 242   - migration back to traditional source files