Re: Patch: signalling offlineimap to synch immediately and to terminate

[Jim Pryor <lists+offlineimap@xxxxxxxxxxxx>]

On Mon, Dec 01, 2008 at 04:16:15PM -0600, John Goerzen wrote:
> Jim Pryor wrote:
> > Here's the way I'd like to use offlineimap on my laptop:
> > OK, to put my money where my mouth is, I attach two patches against 
> > offlineimap
> > 6.0.3.
> > 
> > The first, "cleanup.patch", cleans up a few spots that tend to throw 
> > exceptions
> > for me as offlineimap is exiting from a KeyboardInterrupt.
> > 
> > The second adds signaling capabilities to offlineimap.
> 
> Great!  Thank you very much!  I have applied both to my git tree and
> pushed them.  Would you be willing to send a patch documenting the new
> signal-handling features in the manpage?

Fair enough! (You're good at managing people, you know that?)

However, I've hit some snags doing this. I checked the Makefile to see
how was the manpage generated. I added the following snippet to the
offlineimap.sgml file, replacing an older partly-commented out section
on Signals:


    <refsect1>
            <title>Signals</title>
            <para>
                You can get &OfflineIMAP;'s PID using <command>pidof -x 
offlineimap</command>.
                &OfflineIMAP; also writes its current PID into
                <filename>METADATA/pid</filename> when it is running, where 
METADATA
                is the value of the <property>metadata</property>
                property (by default, <property>metadata</property> is 
"~/.offlineimap").
                It is not guaranteed that the <filename>pid</filename>
                file will not exist when &OfflineIMAP; is not running.
            </para>
            <para>
                                        You can send various signals to 
&OfflineIMAP; using this file
                                        to kill it or tell it to immediately 
resync:
                        </para>
                        <itemizedlist>
                                <listitem>
                                        <para>
                                                Sending a SIGTERM tells 
&OfflineIMAP; to terminate
                                                immediately (but cleanly, as 
though "q" had been
                                                pressed in the GUI interface).
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Sending a SIGHUP tells every 
account to die, but only
                                                after finishing any sync it 
might be currently engaged in.
                                                When all the accounts have 
died, &OfflineIMAP; terminates.
                                        </para>
                                </listitem>
                                <lisitem>
                                        <para>
                                                Sending a SIGUSR1 tells every 
account to do a full sync
                                                as soon as possible: if the 
account is sleeping, it
                                                wakes up and syncs now. If the 
account is mid-sync,
                                                then all folders are marked as 
unsynced and the sync
                                                restarts.
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Sending a SIGUSR2 is the 
equivalent of sending a SIGUSR1 
                                                followed by a SIGHUP: every 
account immediately wakes up and/or 
                                                restarts its sync, and when 
they're all finished, &OfflineIMAP;
                                                terminates.
                                        </para>
                                </listitem>
                        </itemizedlist>
                        <para>
                                Here's an example of how to use this code:
            </para>
                        <PROGRAMLISTING>
                                kill $(cat ~/.offlineimap/pid)                  
# terminate immediately
                                kill -TERM $(cat ~/.offlineimap/pid)    # same 
as preceding (TERM is default signal)
                                kill -USR2 $(cat ~/.offlineimap/pid)    # 
resync everything, then terminate
                        </PROGRAMLISTING>

    </refsect1>

I just based that on the existing markup elsewhere in the file; I haven't 
learned sgml syntax
specifically. However, when I try to
    docbook2man offlineimap.sgml
I get tons of parsing errors, most having to do with the entity &OfflineIMAP;
not being defined, or with closing tags of the form '</>'. Since most of
these errors are not in the markup block I added, I assume you've got
some config settings somewhere that your docbook2man is aware of but
mine is not.

I wonder how the manpage was generated on my system in the first place,
since I didn't have docbook2man installed until just now... Ah, I see I
downloaded a pre-generated manpage from somewhere else.

Well, I could make a patch against a gunzipped copy of the manpage, but
I expect you'd prefer to integrate the changes into your existing build
chain. So can you use the above block of sgml?


Some comments:

1. Could you perhaps also add a few lines to the package README instructing
others what they need to do to enable "make doc" to build the docs for
them, instead of kicking back ninety-some parser errors?

2. The Makefile has "docbook2man offlineimap.sgml" twice, on subsequent
lines. Typo?

> 
> [ snip ]
> 
> > With offlineimap patched in the ways I'm attaching, here's my mutt-wrapper 
> > script, described
> > in item 2 at the top. I've edited it here to remove stuff specific to my
> > system; I think I didn't leave anything out but let me know if you try it 
> > out
> > and it doesn't work.
> 
> Might you be willing to add this to the wiki at
> http://software.complete.org/offlineimap?

OK, I'll do that later. (Probably I'll wait until there's a release 
incorporating these
changes.)


-- 
Jim Pryor
jim@xxxxxxxxxxxx