Re: [ELPA] New package: jami-bot and org-jami-bot

[Stefan Kangas]

Hanno Perrey <hanno@hoowl.se> writes:

> I would like to propose two tightly-coupled packages for inclusion into
> ELPA: jami-bot and org-jami-bot.
>
> jami-bot is an extendable chat bot for the distributed, private
> messenger Jami. It interacts with the locally-installed Jami daemon via
> D-Bus and reacts to both plain text messages and file transfers sent to
> local accounts.
>
> org-jami-bot builds upon jami-bot and extends it with Org mode capture
> functionality for text messages and images. It allows to schedule agenda
> items at specific dates, compose multi-measure captures and capture
> images -- all by sending a message via the GNU Jami messenger.
>
> I would like to keep maintaining both packages at their current
> repositories:
>
> - https://gitlab.com/hperrey/jami-bot
> - https://gitlab.com/hperrey/org-jami-bot
>
> I have signed the copyright paperwork with the FSF already and changed
> the copyright in the respective files for both packages.

Sounds great.  Since Jami is a GNU project, it's a no-brainer that we should
have support for it in a GNU ELPA package.  I enjoyed your blog posts
about it too, and could easily see myself using something like this myself.

In other words, I don't see any reason why it couldn't go in.

> As this is the first time I am proposing a package for ELPA, any
> guidance on the process and feedback would be highly welcome!

Just some stylistic remarks:

1. Add .elpaignore files to both repositories containing, on a line of
   its own:

LICENSE

2. Here are some proposed changes, for your consideration.  This makes
   the package better follow some of our conventions:


diff --git a/org-jami-bot.el b/org-jami-bot.el
index 9cee94f..6d2f515 100644
--- a/org-jami-bot.el
+++ b/org-jami-bot.el
@@ -1,7 +1,7 @@
 ;;; org-jami-bot.el --- Capture GNU Jami messages as notes and todos
in Org mode -*- lexical-binding: t; -*-
-;;
+
 ;; Copyright (C) 2023 Free Software Foundation, Inc.
-;;
+
 ;; Author: Hanno Perrey <http://gitlab.com/hperrey>
 ;; Maintainer: Hanno Perrey <hanno@hoowl.se>
 ;; Created: April 16, 2023
@@ -10,46 +10,46 @@
 ;; Keywords: comm, outlines, org-capture, jami
 ;; Homepage: https://gitlab.com/hperrey/org-jami-bot
 ;; Package-Requires: ((emacs "28.1") (jami-bot "0.0.1"))
-;;
+
 ;; This file is not part of GNU Emacs.
 ;;
-;;    This program is free software: you can redistribute it and/or modify
-;;    it under the terms of the GNU General Public License as published by
-;;    the Free Software Foundation, either version 3 of the License, or
-;;    (at your option) any later version.
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
 ;;
-;;    This program is distributed in the hope that it will be useful,
-;;    but WITHOUT ANY WARRANTY; without even the implied warranty of
-;;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-;;    GNU General Public License for more details.
-;;
-;;    You should have received a copy of the GNU General Public License
-;;    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
 ;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
 ;;; Commentary:
 ;;
 ;; `org-jami-bot' builds upon `jami-bot' and extends it with Org mode capture
-;; functionality for text messages and images. It allows to schedule agenda
+;; functionality for text messages and images.  It allows to schedule agenda
 ;; items at specific dates, compose multi-measure captures and
capture images --
 ;; all by sending a message via the GNU Jami messenger.
 ;;
 ;; `org-jami-bot' provides multi-message capture from within the Jami messenger
 ;; app -- that is, a capture process that consists of several messages and can
-;; include even images and other files. The process is started by sending the
+;; include even images and other files.  The process is started by sending the
 ;; command "!start" followed by the title of the capture and finished
by sending
-;; "!done". Once the multi-message capture session is started, every following
-;; message is simply added. This includes images which will be downloaded and
-;; stored locally. A reference in the form of a link will be included in the
+;; "!done".  Once the multi-message capture session is started, every following
+;; message is simply added.  This includes images which will be downloaded and
+;; stored locally.  A reference in the form of a link will be included in the
 ;; notes.
 ;;
 ;; Every command consists of an exclamation mark and a single word,
for example:
 ;; "!help" which shows the available commands or "!today" which captures the
-;; remainder of the message as a todo entry scheduled today. Everything else is
+;; remainder of the message as a todo entry scheduled today.
Everything else is
 ;; treated as a normal message (and captured verbatim).
 ;;
 ;; Files sent separately as a single message are captured as links to the
-;; locally downloaded file and tagged as =FILE=. In principle,
further automatic
-;; processing (e.g. OCR) could easily be integrated. Any received
file will also
+;; locally downloaded file and tagged as =FILE=.  In principle,
further automatic
+;; processing (e.g. OCR) could easily be integrated.  Any received
file will also
 ;; be added to the variable =org-stored-links= and can then be easily inserted
 ;; as link in any Org mode document using =C-c C-l=.
 ;;
@@ -113,8 +113,8 @@ CONVERSATION and ACCOUNT.
 Further plain text messages processed by
 `org-jami-bot--capture-plain-messsage' or files received by
 `org-jami-bot--capture-file' will be added to this capture
-buffer. The actual capture needs to happen through a separate
-function, e.g. `org-jami-bot--command-function-done'. Return a
+buffer.  The actual capture needs to happen through a separate
+function, e.g. `org-jami-bot--command-function-done'.  Return a
 reply string informing correspondent about how to finish capture
 by sending '!done'."
   (let* ((buf (format "*jami-capture-%s-%s*" account conversation))
@@ -203,7 +203,7 @@ CONVERSATION for jami ACCOUNT."
 (defun org-jami-bot--command-function-today (_account _conversation msg)
   "Capture body of message as todo entry scheduled today.

- Returns a reply string as confirmation. MSG is the full message
+ Returns a reply string as confirmation.  MSG is the full message
  in CONVERSATION id for ACCOUNT id."
   (let* ((body (cadr (assoc-string "body" msg)))
          (lines (string-lines body))
@@ -223,10 +223,10 @@ CONVERSATION for jami ACCOUNT."
   "Capture body as todo entry and schedule it on the date given after
the command.

 The entry will be scheduled according to the first line of the
-MSG body immediately following the command string. The date will
+MSG body immediately following the command string.  The date will
 be parsed through `org-read-date' and supports the same
-string-to-date conversations. Returns a reply string as
-confirmation. ACCOUNT and CONVERSATION are not used."
+string-to-date conversations.  Returns a reply string as
+confirmation.  ACCOUNT and CONVERSATION are not used."
   (let* ((body (cadr (assoc-string "body" msg)))
          (lines (string-lines body))
          (swhen (org-read-date nil nil (car lines)))
@@ -245,9 +245,9 @@ confirmation. ACCOUNT and CONVERSATION are not used."
 (defun org-jami-bot-default-setup ()
   "Set up `org-jami-bot' with default values.

-        Create a capture template, extend `jami-bot' commands via
-        `jami-bot-command-function-alist' and add hooks to
-        `jami-bot'."
+Create a capture template, extend `jami-bot' commands via
+`jami-bot-command-function-alist' and add hooks to
+`jami-bot'."
   (if (assoc org-jami-bot-capture-key org-capture-templates)
       (message "Capture template referred to by \"%s\" key already defined!"
                org-jami-bot-capture-key)




diff --git a/jami-bot.el b/jami-bot.el
index c453469..32e13f1 100644
--- a/jami-bot.el
+++ b/jami-bot.el
@@ -1,7 +1,7 @@
 ;;; jami-bot.el --- An extendable chat bot for the private messenger
GNU Jami -*- lexical-binding: t; -*-
-;;
+
 ;; Copyright (C) 2023 Free Software Foundation, Inc.
-;;
+
 ;; Author: Hanno Perrey <http://gitlab.com/hperrey>
 ;; Maintainer: Hanno Perrey <hanno@hoowl.se>
 ;; Created: April 15, 2023
@@ -10,27 +10,27 @@
 ;; Keywords: comm, jami, messenger, chat bot, dbus
 ;; Homepage: https://gitlab.com/hperrey/jami-bot
 ;; Package-Requires: ((emacs "27.1"))
-;;
+
 ;; This file is not part of GNU Emacs.
 ;;
-;;    This program is free software: you can redistribute it and/or modify
-;;    it under the terms of the GNU General Public License as published by
-;;    the Free Software Foundation, either version 3 of the License, or
-;;    (at your option) any later version.
-;;
-;;    This program is distributed in the hope that it will be useful,
-;;    but WITHOUT ANY WARRANTY; without even the implied warranty of
-;;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-;;    GNU General Public License for more details.
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
 ;;
-;;    You should have received a copy of the GNU General Public License
-;;    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
 ;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
 ;;; Commentary:
 ;;
-;; An extendable chat bot for the distributed, private messenger Jami. It
+;; An extendable chat bot for the distributed, private messenger Jami.  It
 ;; interacts with the locally-installed Jami daemon via D-Bus and reacts to
-;; both plain text messages and file transfers sent to local accounts. Further
+;; both plain text messages and file transfers sent to local accounts.  Further
 ;; processing of either or both can be configured by adding functions to the
 ;; abnormal hooks, `jami-bot-text-message-functions' and
 ;; `jami-bot-data-transfer-functions', respectively.
@@ -40,7 +40,7 @@
 ;; Further commands than the ones included can be configured by mapping them to
 ;; functions through `jami-bot-command-function-alist'.
 ;;
-;; Set up `jami-bot' by executing `jami-bot-register'. This will set up the
+;; Set up `jami-bot' by executing `jami-bot-register'.  This will set up the
 ;; message handler, `jami-bot--messageReceived-handler', to be called on the
 ;; `messageReceived' D-Bus signal.
 ;;
@@ -51,11 +51,11 @@
 (defvar jami-bot-account-user-names nil
   "List of account user names that `jami-bot' handles messages for.

-        If set to nil then `jami-bot' will react to any message
-        send to a local account. The user name is also sometimes
-        referred to as address in Jami and should be a 40
-        character has such as
-        \"badac18e13ec1a6e1266600e457859afebfb9c46\".")
+If set to nil then `jami-bot' will react to any message
+send to a local account.  The user name is also sometimes
+referred to as address in Jami and should be a 40
+character has such as
+\"badac18e13ec1a6e1266600e457859afebfb9c46\".")

 (defvar jami-bot-command-function-alist
   '(("!ping" . jami-bot--command-function-ping)
@@ -63,15 +63,15 @@
   "Alist mapping command strings in message body to functions to be executed.

 Each command needs to start with an exclamation mark '!' and
-consist of a single (lowercase) word. The corresponding function
needs to accept
-the account id, the conversation id and the message alist as
+consist of a single (lowercase) word.  The corresponding function needs to
+accept the account id, the conversation id and the message alist as
 arguments and return a string (that is sent as reply to the original
message).")

 (defvar jami-bot-text-message-functions nil
   "A list of functions that will be called when processing a plain
text message.

 Functions must take the ACCOUNT and CONVERSATION ids as well as
-the actual MSG as arguments. Their return value will be ignored.")
+the actual MSG as arguments.  Their return value will be ignored.")

 (defvar jami-bot-download-path "~/jami/"
 "Path in which to store files downloaded from conversations.
@@ -83,21 +83,21 @@ Will be created if not existing yet.")

 Functions must take the ACCOUNT and CONVERSATION ids as well as
 the actual MSG and the local downloaded file name, DLNAME, as
-arguments. Their return value will be ignored.")
+arguments.  Their return value will be ignored.")

 (defvar jami-bot--jami-local-account-ids nil
   "List of `jami' local accounts user ids and name pairs.

-Caches output of dbus-methods 'getAccountList' and
-'getAccountDetails'. For internal use in `jami-bot'.")
+Caches output of dbus-methods \"getAccountList\" and
+\"getAccountDetails\".  For internal use in `jami-bot'.")

 (defun jami-bot--messageReceived-handler (account conversation msg)
   "Handle messages from Jami's `messageReceived' D-Bus signal.

-  ACCOUNT and CONVERSATION are the corresponding ids to which the
-  MSG belongs to. The latter contains additional fields such as
-  `author' and `body'. The field `type' is used to identify which
-  function to call for further processing."
+ACCOUNT and CONVERSATION are the corresponding ids to which the
+MSG belongs to.  The latter contains additional fields such as
+`author' and `body'.  The field `type' is used to identify which
+function to call for further processing."
   ;; make sure we are not reacting to messages sent from our own local
   ;; account(s) or accounts we are not to monitor
   (unless jami-bot--jami-local-account-ids
@@ -160,7 +160,7 @@ Caches output of dbus-methods 'getAccountList' and
   "Ping the Jami daemon and register `jami-bot' handler for receiving
messages."
   (interactive)
   (or (dbus-ping :session "cx.ring.Ring")
-      (error "Jami Daemon (jamid) not available through dbus. Please
check Jami installation"))
+      (error "Jami Daemon (jamid) not available through dbus.  Please
check Jami installation"))
   (dbus-register-signal :session "cx.ring.Ring"
                       "/cx/ring/Ring/ConfigurationManager"
                       "cx.ring.Ring.ConfigurationManager"
@@ -171,7 +171,7 @@ Caches output of dbus-methods 'getAccountList' and
   "Process plain text messages and parse the message body for commands.

   ACCOUNT and CONVERSATION are the corresponding ids to which the
-  message MSG belongs to. Messages containing commands must start
+  message MSG belongs to.  Messages containing commands must start
   with an exclamation mark (\"!\") followed by the single-word
   command. Each command is mapped to a function via
   `jami-bot-command-function-alist' which will be executed when
@@ -210,10 +210,10 @@ Caches output of dbus-methods 'getAccountList' and
                           account conversation msg))))

 (defun jami-bot--command-function-ping (_account _conversation msg)
-  "Return the string 'pong!' followed by the message's body.
+  "Return the string \"pong!\" followed by the message body.

-Example for a basic jami bot command handling function. Acts on MSG
-received via _ACCOUNT in _CONVERSATION. The latter two are unused."
+Example for a basic jami bot command handling function.  Acts on MSG
+received via _ACCOUNT in _CONVERSATION.  The latter two are unused."
   (let ((body (cadr (assoc-string "body" msg))))
     (format "pong! %s" body)))

@@ -230,10 +230,10 @@ which are used."
 (defun jami-bot--process-data-transfer (account conversation msg)
   "Process data transfer from received messages.

-  Downloads files to the path given by `jami-bot-download-path'
-  and calls the abnormal hook `jami-bot-data-transfer-functions'
-  for further processing. ACCOUNT and CONVERSATION are the
-  corresponding ids to which the message MSG belongs to."
+Downloads files to the path given by `jami-bot-download-path'
+and calls the abnormal hook `jami-bot-data-transfer-functions'
+for further processing.  ACCOUNT and CONVERSATION are the
+corresponding ids to which the message MSG belongs to."
   (let* ((id (cadr (assoc-string "id" msg)))
          (fileid (cadr (assoc-string "fileId" msg)))
          (filename (cadr (assoc-string "displayName" msg)))
@@ -254,7 +254,7 @@ which are used."
                     ,method ,@(when args args))))

 (defun jami-bot-send-message (account conversation text &optional reply)
-  "Add TEXT to CONVERSATION via ACCOUNT. REPLY specifies a message id."
+  "Add TEXT to CONVERSATION via ACCOUNT.  REPLY specifies a message id."
   (jami-bot--dbus-cfgmgr-call-method "sendMessage"
                                      account
                                      conversation