Matthias Petermann
2023-Feb-25 07:19 UTC
Small suggestion for improvement of pigeonhole/imapsieve documentation
Hello all, this is my first post on this list and I would like to introduce myself briefly. My name is Matthias and I am from Saxony in Germany. I'm working with Unix and mail systems for a long time - actually with focus for NetBSD and Cyrus IMAP. Occasionally I also use Dovecot, which has several reasons. Today, one of the reasons was that I would like to trigger Sieve scripts when moving mail within mailbox folders - i.e. at an unspecified time after the actual mail arrival. In doing so, I came across the imapsieve extension for Pigeonhole fairly quickly and decided that the administrative Sieve scripts in imapsieve were exactly what I needed. However, despite having debug logging fully up, I couldn't figure out until just now why my sieve script wasn't running despite having IMAP events logged. Even intentionally defining an invalid script did not result in an error, so it seemed to be ignored altogether. Until I just now came across that I seem to have misunderstood the documentation. The template shown for the imapsieve_mailboxXXX_ parameters suggested to me that a sequence number of three digits must / can be specified here. Thus, I started numbering my parameters with imapsieve_mailbox001. However, while researching in various forums, I came across only examples that use imapsieve_mailbox1_ as the first parameter. In desperation I tried this out - now it works for me, too. Long story short - I don't know if I'm the only one who has made this mistake so far. A little hint in the documentation[1] would have helped me, how the XXX is meant exactly. I am referring to this section: ``` This setting configures the name of a mailbox for which administrator scripts are configured. The `XXX? in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes. The settings defined hereafter with matching sequence numbers apply to the mailbox named by this setting. The sequence of configured mailboxes ends at the first missing imapsieve_mailboxXXX_name setting. This setting supports wildcards with a syntax compatible with the IMAP LIST command, meaning that this setting can apply to multiple or even all (?*?) mailboxes. ``` What do you think about adding a small explanatory sentence to the documentation? For example: ``` This setting configures the name of a mailbox for which administrator scripts are configured. The `XXX? in this setting is a sequence number, which allows configuring multiple associations between Sieve scripts and mailboxes. The sequence number must begin with the digit 1 without preceding zeros and may have a maximum of three digits. The settings defined hereafter with matching sequence numbers apply to the mailbox named by this setting. The sequence of configured mailboxes ends at the first missing imapsieve_mailboxXXX_name setting. This setting supports wildcards with a syntax compatible with the IMAP LIST command, meaning that this setting can apply to multiple or even all (?*?) mailboxes. ``` Many greetings Matthias [1] https://doc.dovecot.org/configuration_manual/sieve/plugins/imapsieve/