[plt-scheme] scribble question: @defproc when it's not an existing proc?

From: John Clements (clements at brinckerhoff.org)
Date: Wed Feb 13 19:26:52 EST 2008

In the handin-server, there's the ability to specify a file containing  
a module that exports a single function named hook.  In documenting  
this, would it be appropriate to use @defproc[(hook ...)], even though  
'hook' is something defined by the user and not by the library?  In  
fact, scribble generates a warning message (basically, "I couldn't  
find a definition for 'hook'")---that suggests that defproc might not  
be the right choice.

I've attached the text here, just in case there are other howling  
errors that I'm making in my first use of scribble.

John Clements

@item{@indexed-scheme[hook-file] --- a path (relative to handin server  
directory or
          absolute) that specifies a filename that contains a `hook'
          module.  This is useful as a general device for customizing
          the server through Scheme code.  The file is expected to
          contain a module that provides a @scheme[hook] function, which
          should be receiving three arguments:
          @comment{defproc here?}

          @defproc[(hook [operation symbol?] [connection-context (or/c  
number? symbol? false?)]
                         [relevant-info (listof (list/c symbol? any))])

          @comment{void appropriate here?}

          The @scheme[operation] argument indicates the operation that  
is now
            taking place. It can be one of the following:
            @indexed-scheme['server-start],  @indexed-scheme['server- 
            @indexed-scheme['user-create],  @indexed-scheme['user- 
change],  @indexed-scheme['login],
            @indexed-scheme['submission-received],  @indexed- 
            @indexed-scheme['submission-retrieved], @indexed- 
            or @indexed-scheme['status-file-get].

            The @scheme[connection-context] argument is a datum
            that specifies the connection context (a number for handin
            connections, a @scheme['wN] symbol for servlet connections,
            and @scheme[#f] for other server operations).

          The @scheme[relevant-info] contains an alist of information  
          to this operation.  Currently, the hook is used in several  
          after an operation has completed.

          For example, here is a simple hook module that sends
          notification messages when users are created or their  
information has

            (module hook mzscheme
              (provide hook)
              (require (lib "sendmail.ss" "net"))
              (define (hook what session alist)
                (when (memq what '(user-create user-change))
                   "course-staff at university.edu"
                   (format "[server] ~a (~a)" what session)
                   '("course-staff at university.edu") '() '()
                   (map (lambda (key+val)
                          (apply format "~a: ~s" key+val))

     Changes to @filepath{config.ss} are detected, the file will be re- 
read, and
     options are reloaded.  A few options are fixed at startup time:
     port numbers, log file specs, and the @scheme[web-base-dir] are as
     configured at startup.  All other options will change the behavior
     of the running server (but things like @scheme[username-case- 
     it would be unwise to do so).  (For safety, options are not
     reloaded until the file parses correctly, but make sure that you
     don't save a copy that has inconsistent options: it is best to
     create a new configuration file and move it over the old one, or
     use an editor that does so and not save until the new contents is
     ready.)  This is most useful for closing & opening submissions

Posted on the users mailing list.