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

On 04/13/2012 10:55 AM, Jay McCarthy wrote:
> On Fri, Apr 13, 2012 at 10:28 AM, Ryan Culpepper<ryan at cs.utah.edu>  wrote:
>> On 04/12/2012 11:27 AM, Jay McCarthy wrote:
>>>
>>> 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)]
>>
>>
>> It seems like this could be done with a couple macros and a compile-time
>> table or two. For example,
>>
>>   @declare-re-exports[web-server/http (web-server/http/xexpr)]
>>
>> could enter the relationship in the table(s),
>>
>>   @defmodule/dream-team[web-server/http]
>>
>> could discover that web-server/http includes web-server/http/xexpr, if you
>> wanted to produce a paragraph that mentions every module that it re-exports,
>> and
>>
>>   @defmodule/dream-team[web-server/http/xexpr]
>>
>> could discover that web-server/http/xexpr is re-exported by web-server/http
>> and automatically produce the declare-exporting declarations.
>
> This compile-time table strategy wouldn't work if they were in
> different Scribble files though, right?

The declaration forms would have to be in a module required by all 
Scribble files that depended on the relationships that they declared.

Actually, it looks like 'declare-exporting' doesn't have any important 
compile-time behavior, so if you're willing to poke around in the 
Scribble internals (ie, use '*declare-exporting' directly) you could use 
a run-time table instead. (See scribble/private/manual-mod.)

Ryan