Re: Session management patch, please comment.

[Richard Stallman]

    Well, actually I didn't even want this function, but I could not find 
    another way to call C from lisp.  It is not meant to be "external", 
    rather a link between the C part and the lisp part of the session 
    management code.

It is a good idea to document it clearly anyway, even though it is not
meant for general use.  The doc string can say "Don't call this
yourself."

    "End interaction as a response to save_yourself.
    A session manager can tell Emacs that the window system is shutting down 
    by sending Emacs a save_yourself message.  Emacs then executes functions 
    in `save-yourself-hook'.  After that, this function shall be called to 
    inform the session manager that it can continue or abort shutting down 
    the window system.

    If the argument CANCEL is non-nil, Emacs will tell the session manager 
    to cancel the shutdown."

That is good, except for "this function shall be called", which is vague.
What code is supposed to call this function?

    How about this (a bit long perhaps):

    "The previous session id Emacs got from session manager.
    If Emacs is running on a window system that has a session manager, the 
    session manager gives Emacs a session id.  It is feasible for Emacs lisp 
    code to use the session id to save configuration in, for example, a file 
    with a file name based on the session id...

That is good.

    The idea was that as functions in save-yourself-hook are executing, they 
    might interact with the user, for instance pop up a dialog.  That dialog 
    can have the possibility to cancel the whole window system shutdown.  If 
    the lisp code wants to do that, it shall set this variable to something 
    non-nil.

Please document that clearly (but don't use "shall").