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

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?

Jay

>
> (I don't know the answer to your second question, though.)
>
> Ryan
>
>
>
>> 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