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