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

At Wed, 13 Feb 2008 19:55:37 -0700, Matthew Flatt wrote:
> 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.

The dummy module still seems to be necessary to connect references to
`hook' with the definition of `hook'. So, create

  collects/handin-server/scribblings/hook-dummy.ss

that provides a `hook' export, and then in the documentation:

  @(require (for-label handin-server/scribblings/hook-dummy))


  @declare-exporting[#:use-sources (handin-server/scribblings/hook-dummy)]

  @defproc[(hook ....) ....]{....}

The `#:use-sources' keyword in `declare-exporting' means that
documented identifiers should be keyed on the combination of the
`handin-server/scribblings/hook-dummy' module path and the documented
identifier. Normally, though, a module path precedes `#:use-sources',
and the typeset documentation advertises the documented binding as
exported from the preceding module path.

The new feature of `declare-exporting' --- now commited in SVN --- is
that you can omit the module path before `#:use-sources', and then the
documentation doesn't advertise the biding as being from any particular
module.

For an example, see the web-server documentation, sections 2.1 and 3.1.

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
> _________________________________________________
>   For list-related administrative tasks:
>   http://list.cs.brown.edu/mailman/listinfo/plt-scheme