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

When I've run into this prolem, I've made up a dummy module that is
located with the documentation to supply a binding, and then declared
the dummy module with `declare-exporting'. But even though
`declare-exporting' doesn't publicize the dummy module name as loudly
as `defmodule', the dummy name is still visible in various ways.

So, I think it would be better to have a way to say "not from a
module", and I'll work on that in the morning.

Matthew

At Wed, 13 Feb 2008 16:26:52 -0800, John Clements wrote:
> 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))])
>                    void?]
> 
>           @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- 
> connect],
>             @indexed-scheme['user-create],  @indexed-scheme['user- 
> change],  @indexed-scheme['login],
>             @indexed-scheme['submission-received],  @indexed- 
> scheme['submission-committed],
>             @indexed-scheme['submission-retrieved], @indexed- 
> scheme['status-login],
>             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  
> relevant
>           to this operation.  Currently, the hook is used in several  
> places
>           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
>           changed:
> 
> @schemeblock[
>             (module hook mzscheme
>               (provide hook)
>               (require (lib "sendmail.ss" "net"))
>               (define (hook what session alist)
>                 (when (memq what '(user-create user-change))
>                   (send-mail-message
>                    "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))
>                         alist)))))]
> 
>      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- 
> sensitive?]
>      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
>      directories.}}
> 
> 
> _________________________________________________
>   For list-related administrative tasks:
>   http://list.cs.brown.edu/mailman/listinfo/plt-scheme