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

[Hanno Perrey <hanno@hoowl.se>]

[-- Attachment #1: Type: text/plain, Size: 3958 bytes --]


Hej,

> If I understood the calling conventions for
> jami-bot and the calling conventions for org-capture, rather than
> guessing them, I might be able to quickly develop something comparable
> to org-jami-bot which does not depend on Org.

I am really glad for your interest in jami-bot and happy to help you
with the above!

> I observed another gap: org-jami-bot does not contain documentation
> that answers the basic questions, "What does this do, and how do you use it?"
> Its user options and function arguments were carefully documented in detail;
> what was missing was the overall framework to understand it all.

You have a point in that the documentation has been quite sparse in the
code. I have started to close that gap and extended the documentation in
both jami-bot and org-jami-bot. The latter refers to the former where
appropriate.

It might also be useful to summarize the usage of org-jami-bot here with
a focus to clarify its function to any non-Org mode users:

As a user, the setup of org-jami-bot is done by calling
`org-jami-bot-default-setup' which is now highlighted more explicitly in
the commentary to the package. This function does the following:

- set up a Org mode capture template. Think of this as a combined format
  string and file name to save anything "captured".

- register a hook each to `jami-bot-text-message-functions' and
  `jami-bot-data-transfer-functions'. Both use the capture template to
  save any plain text message and data transfer, respectively, to the
  default notes file. Both message types are essentially just appended
  (under their own Org mode header as the template adds a leading '*'),
  but file transfers have an automatically generated header and include
  a link to the file already downloaded by jami-bot as well as some
  additional meta information such as the timestamp.

- add four entries to `jami-bot-command-function-alist'. jami-bot
  handles plain text messages that start with an exclamation mark
  followed by a single word as a "command" which is mapped to a function
  by said alist. The function then can parse the message or perform any
  other action. The return string of the function is sent as a reply to
  the original message. So this registers four new "commands" in
  jami-bot that are for further, more refined captures (explained below).

The four commands are as follows:

- "!today" and "!schedule" (`org-jami-bot--command-function-today' and
  `org-jami-bot--command-function-schedule', respectively) simply add
  today's date or a date specified in the message, respectively, to the
  Org mode header together with the "SCHEDULED:" keyword. Within Org
  mode, this makes this particular entry appear e.g. in time-based
  searches or the Org mode agenda which summarizes TODO entries for each
  day.

- "!start" and "!done" (`org-jami-bot--command-function-start' and
  `org-jami-bot--command-function-done', respectively) are used to
  redirect captures to a temporary buffer created when sending "!start"
  and finally captured/saved when sending "!done". The idea is that one
  might want to have several messages appended to a single Org mode
  header. So this is only necessary as each message by default (due to
  the capture template format) is added under its own header.

For a user that does not want to modify this behavior, only the call to
`org-jami-bot-default-setup' is needed, everything else is called via
jami-bot when sending messages.

A version without Org mode would only need to adjust the two hooks for
plain text and file transfer handling and store the messages in some
other format to a file. Whether or not the commands introduced by
org-jami-bot make sense in that context depends on the chosen format I
guess.


I attach the new versions of jami-bot and org-jami-bot with the extended
documentation. Please let me know whether or not these close any gap for
you and -- if not -- what to improve.


Thanks and cheers,
Hanno


[-- Attachment #2: jami-bot.el --]
[-- Type: application/emacs-lisp, Size: 15618 bytes --]

[-- Attachment #3: org-jami-bot.el --]
[-- Type: application/emacs-lisp, Size: 15236 bytes --]