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

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 <at> jimpryor.net