path: root/README.org

#+TITLE: jabber.el
#+SUBTITLE: XMPP client for Emacs
#+DESCRIPTION: Documentation

* Explanation
:PROPERTIES:
:CUSTOM_ID: explanation
:END:
This is jabber.el 0.8.92, an XMPP client for Emacs.  XMPP (also known as 'Jabber') is an instant messaging system; see http://xmpp.org for more information.

New resources
+ [[https://tildegit.org/wgreenhouse/emacs-jabber/][project page]]
+ chat: [[xmpp:emacs@salas.suchat.org?join][xmpp:emacs@salas.suchat.org?join]] (general Emacs and jabber.el talk)
+ chat: xmpp:jabber-el@conference.hmm.st?join (jabber.el developement)

Old resources
+ [[http://sourceforge.net/projects/emacs-jabber][project page]]
+ [[http://emacs-jabber.sourceforge.net][home page]]
+ [[http://www.emacswiki.org/cgi-bin/wiki/JabberEl][wiki page]]
+ mailing list:
  * http://lists.sourceforge.net/lists/listinfo/emacs-jabber-general
  * http://dir.gmane.org/gmane.emacs.jabber.general
+ chat: jabber.el@conference.jabber.se and emacs@conference.jabber.ru (Russian, English)

** GNU Emacs
:PROPERTIES:
:CUSTOM_ID: gnu-emacs
:END:
jabber.el runs on GNU Emacs 23.1 or later.

The file hexrgb.el (http://www.emacswiki.org/emacs/hexrgb.el) is needed for MUC nick coloring feature.  A copy is located in the compat directory, and used if the configure script doesn't find another copy already installed.

** Encrypted connections
:PROPERTIES:
:CUSTOM_ID: encrypted-connections
:END:
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:

: M-: (gnutls-available-p)

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.

Failing that, jabber.el will use the starttls.el library, which requires that the GnuTLS command line tool "gnutls-cli" is installed.

In Debian-based distributions, "gnutls-cli" is in the "gnutls-bin" package.

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.

To use the latter form of encryption, customize =jabber-account-list=.

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.

** Usage
:PROPERTIES:
:CUSTOM_ID: usage
:END:
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=.

Your roster is displayed in a buffer called *-jabber-*.  To disconnect, type =C-x C-j C-d= or =M-x jabber-disconnect=.

You may want to use the menu bar to execute Jabber commands.  To enable the Jabber menu, type =M-x jabber-menu=.

For a less terse description, read the enclosed manual.

For bug reports, help requests and other feedback, use the trackers and forums at the project page mentioned above.

** Configuration
:PROPERTIES:
:CUSTOM_ID: configuration
:END:
All available configuration options are described in the manual.  This section only serves to point out the most important ones.

To change how you are notified about incoming events, type =M-x customize-group RET jabber-alerts=.

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.

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.

** File transfer
:PROPERTIES:
:CUSTOM_ID: file-transfer
:END:
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.

** XMPP URIs
:PROPERTIES:
:CUSTOM_ID: xmpp-uris
:END:
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".

** Literate program
:PROPERTIES:
:CUSTOM_ID: literate-program
:END:
jabber.el is a literate program made using Org. Thanks to [[https://github.com/melpa/melpa/issues/7408][package.el limitations]], we check in the tangled sources to Git. The tangled sources are what Emacs knows how to load.

Alternatively, it is possible to use =literate-elisp-load= from [[https://github.com/jingtaozf/literate-elisp][literate-elisp]] to directly load this Org literate program. This way, links to the source (e.g. =xref=, =describe-*= buffers, byte-compilation messages) take the user directly to the Org file rather than to the tangled source.

If a source block does not have syntax highlighting, press =M-o M-o= (=font-lock-fontify-block=) in it.

*** TODO literate/organizational tasks [25%]
:PROPERTIES:
:CUSTOM_ID: literate-organizational-tasks
:END:
1. [ ] (maybe) make dependencies optional and tangle them to separate files, reducing load time for users.
2. [ ] contemplate [[https://github.com/melpa/melpa/issues/7408][distribution strategies]]
3. [ ] make headings for remaining definitions - some FSM-related definitions remain.
4. [ ] move tests to this file (probably migrate them to =ert= or =buttercup= first), in sub-headings of their concerned components.
5. [ ] move dependencies to the Dependencies heading; also make library headers for them
6. [X] move per-file author information and copyright notice here, and delete the empty .el files
   * But it will cease to remain applicable as soon as we move anything around...
7. [ ] "Code" has a lot of direct sub-headings, making it somewhat cumbersome to navigate; someone with a better understanding of the program could organize these better
8. [X] The tangled file currently does not list all the other authors (currently listed in =:COPYRIGHT:= drawers). We could add them all at once in the library headers section...or something else. 🤔

* Tutorials
:PROPERTIES:
:CUSTOM_ID: tutorials
:END:
** Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:
1. Clone the repository by typing the following into a terminal -
   #+BEGIN_SRC shell
   mkdir ~/emacs-jabber/
   cd ~/emacs-jabber/
   git clone https://codeberg.org/emacs-jabber/emacs-jabber
   make
   #+END_SRC
2. Add the following lines to your =init.el= -
   #+BEGIN_SRC emacs-lisp
   (add-to-list 'load-path "~/emacs-jabber/")
   (load "~/emacs-jabber/jabber-autoloads")
   #+END_SRC
   ...and, while still in your =init.el=, type =M-x eval-buffer=.

If all goes well, =jabber.el= commands like =jabber-connect= should now be available in the =M-x= menu.

To install the Info documentation, copy =jabber.info= to =/usr/local/info= and run ="install-info /usr/local/info/jabber.info"=.

** [Developers] Making your first pull request
:PROPERTIES:
:CUSTOM_ID: making-your-first-pull-request
:END:
1. Clone the jabber.el repository.
   #+BEGIN_SRC shell :tangle no
     mkdir ~/git/ && cd ~/git/
     git clone https://tildegit.org/wgreenhouse/emacs-jabber
   #+END_SRC
2. Install development dependencies.
   1. Install Org mode v9.3.8 or higher.
      #+BEGIN_SRC shell :tangle no
        git clone https://code.orgmode.org/bzg/org-mode.git
        cd ~/git/org-mode/
        make
      #+END_SRC
   2. Install Magit - type -
      #+BEGIN_SRC
        M-x package-install RET magit RET
      #+END_SRC
      or evaluate -
      #+BEGIN_SRC emacs-lisp :tangle no :load no
        (package-install 'magit)
      #+END_SRC
   3. Install the remaining tools.
      #+BEGIN_SRC shell :tangle no
        cd ~/git/emacs-jabber/
        make -f contrapunctus.mk setup
      #+END_SRC
3. Set up automatic tangling, linting, and testing - in the =emacs-jabber= directory, create a =.dir-locals-2.el= containing the following -
   #+BEGIN_SRC emacs-lisp :tangle no :load no
((org-mode . ((nameless-mode . t)
              (eval . (progn
                        (make-local-variable 'after-save-hook)
                        (add-hook 'after-save-hook
                                  (lambda ()
                                    (compile
                                     (concat
                                      "make ORG_PATH=\"~/git/org-mode/lisp/\" "
                                      "--silent --always-make "
                                      "-f contrapunctus.mk "
                                      "tangle")))
                                  nil t)))
              ;; use `vc-before-checkin-hook' instead, if using `vc'
              (eval . (add-hook 'magit-post-stage-hook
                                (lambda ()
                                  ;; check if we are in the right project
                                  (when (file-exists-p "jabber.org")
                                    (compile
                                     (concat
                                      "make --silent --always-make "
                                      "-f contrapunctus.mk lint")))))))))
   #+END_SRC
   Note -
   * =ORG_PATH= must point to the =/lisp/= subdirectory of the cloned Org repository.
   * =.dir-locals-2.el= is for your personal preferences - do not add it to the repository.
4. Create your branch, and open =jabber.org= for editing. Press =!= to accept the directory local variables, then make your changes. Always edit =jabber.org=, never =jabber.el=!
5. Stage your changes in =jabber.org=, as well as the changes in the automatically tangled sources in =jabber.el=.
6. Address the issues presented by the linters and tests. Hitting Enter on an error in the compilation buffer will take you to the source in =jabber.el= - use =org-babel-tangle-jump-to-org= to go to the source block in =jabber.org=.
7. Push and create your PR, or send a patch using [[https://git-send-email.io/][=git-send-email=]] to wgreenhouse@tilde.club

* TODO maintenance [0%]
:PROPERTIES:
:CUSTOM_ID: maintenance
:END:
1. [ ] Satisfy =M-x checkdoc=
2. [ ] Use =rx= where regular expressions get hairy
   * [ ] =jabber-jid-username=
   * [ ] =jabber-jid-server=
   * [ ] =jabber-jid-resource=
3. [ ] hexrgb.el is not available on MELPA
4. [ ] Migrate tests to ERT/Buttercup/etc
5. [ ] Add Windows support to developer tutorial
6. [ ] Create testing for tutorial

* Credits
:PROPERTIES:
:CUSTOM_ID: credits
:END:
** Developers
:PROPERTIES:
:CUSTOM_ID: developers
:END:
+ Tom Berger
+ Magnus Henoch
+ Kirill A. Korinskiy
+ Detlev Zundel
  - wmii support
+ Evgenii Terechkov

** Contributors
:PROPERTIES:
:CUSTOM_ID: contributors
:END:
+ Georg Lehner
  - network transport functions
+ Anthony Chaumas-Pellet
+ Jérémy Compostella
+ Mathias Dahl
  - history logging
  - watch functionality
+ Mario Domenech Goulart
  - sawfish support
  - xmessage support
+ Nolan Eakins
+ Ami Fischman
  - Chat State Notifications
+ François Fleuret
+ David Hansen
+ Adam Sjøgren
  - notifications.el support
+ Rodrigo Lazo
  - notifications.el support
  - libnotify.el support
+ Justin Kirby
+ Carl Henrik Lunde
  - network transport functions
  - activity tracking
+ Olivier Ramonat
+ Andrey Slusar
+ Valery V. Vorotyntsev
  - GMail notifications
+ Milan Zamazal
+ Xavier Maillard
+ Vitaly Mayatskikh
+ Alexander Solovyov
+ Demyan Rogozhin
  - XML console mode
+ Michael Cardell Widerkrantz
  - tmux support

** Maintainers
:PROPERTIES:
:CUSTOM_ID: maintainers
:END:
+ wgreenhouse
  - 2021 resurrection
+ contrapunctus
  - literate Org migration
  - Makefile
+ tomasino on #team@irc.tilde.chat
  - helping contrapunctus debug the Makefile