[racket-dev] Scribble - language/module documentation and declare-exporting

Based on some feedback from Robby, I'm trying to improve the way the
Web server's binding exports are documented.

I've been looking at the docs and some examples, but I can't find the
right thing to do and if it is even possible.

Here's the basic setup:

web-sever/http re-exports the bindings provided by web-server/http/xexpr
web-server/servlet re-exports the bindings provided by web-server/http
#lang web-server/insta re-exports the bindings from web-server/servlet
#lang web-server re-exports the bindings provided by web-server/http
and a bunch of other things

Right now what I do, is at the start of each section I say that, for
example, web-server/http exports every module "below" and then have
the documentation for each of the modules; and similarly in the case
of the languages, I have a list of what modules are exported.

This is fine for a prose reading, but it doesn't work very well with a
search, because if you search for 'extract-binding' it will only say
'web-server/http/bindings' and not the other modules, which you may
already be requiring.

My understanding is that it is possible for me to use

@defmodule*/no-declare[(web-server/http/xexpr)]{}

@declare-exporting[web-server/http/xexpr web-server/http]

to show that web-server/http/xexpr is re-exported by web-server/http

There are two problems with this:

First, it is non-modular because the *exported* module has to tie
itself to the *exporting* module, rather than the *exporting* module
looking like

@defmodule/dream-team[web-server/http #:exports (web-server/http/xexpr)]

Second, it does not appear possible to show that a module is
re-exported by a #lang and not a module. For example "#lang
web-server" and the "web-server" module are totally different, so

@declare-exporting[web-server/http/xexpr web-server]

is incorrect and misleading.

Similarly, I'd like

@defmodulelang/summer-lovin[web-server #:exports (web-server/http)]

--

Due to these two problems, I don't think it is feasible for me to
improve the Web server docs in this way because of the vast number of
re-exports that are going on.

Unfortunately, my understanding of how Scribble is implemented
suggests that this can't really work, because the indexing information
is computed during expansion from the label bindings and my dream @def
constructs wouldn't be able to propagate their information to the
existing index entries for the underlying modules.

Is there a better way to solve this problem? How feasible is it to
change Scribble to accommodate this if not?

Jay

-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93