[racket-dev] Scribble in-source documentation documentation

Greetings.

Section 4.5 of the Scribble docs, 'In-Source Documentation' refers to the file/gif.rkt source as a useful example of this practice.  However, probably due to version changes, that file now looks different from what's described in the section it purportedly exemplifies.

Namely (noting docs -> gif.rkt):

  * '#reader scribble/reader' -> '#lang at-exp scheme/base'

  * '(require/doc scribble/base scribble/manual)' -> '(require/doc scheme/base scribble/manual)'

----

Separately, the documentation for proc-doc/names shows the structure of the form as

    (proc-doc/names id contract ((arg-id ...) ((arg-id default-expr) ...)) desc-expr)

I read that as requiring two subforms within the third proc-doc/names argument, even if there are zero (arg-id default-expr) forms.  Thus this seems to suggest that a procedure with one mandatory and no optional arguments would be declared as 

    (proc-doc/names foo (-> type type) ((arg1) ()) @{Description})

I appreciate there isn't really a formal grammar here, but adding a further exemplar line without the default-expr forms might be clearer -- is there perhaps a missing template

    (proc-doc/names id contract (arg-id ...) desc-expr)

As it was, it took some grepping through collects/* before I worked out why I was getting errors with my first attempt (no tragedy, of course, but it slows one down...).

----

Separately (again), the discussion in section 4.5.2 might benefit from some attention.  The description of provide-extracted mentions that "the documentation is packaged and exported as exported, instead of left inline."  I think I can see the intention here, but the phrase 'exported as exported' seems terribly important without being at all transparent as to meaning.  This paragraph suggests that provide-extracted should go in the scribble file, while the next one seems to suggest that it should instead go in the module file.  Then I look around and find framework/main.scrbl, which refers to main-extracts.ss, and ... I'm starting to get a bit confused.  I think I may now see which (third!) file the provide-extracted form should go into, but it's definitely getting a bit voodoo, now.

I can't just flail around and experiment, because the module I'm trying to document doesn't appear to work in an expected way with include-extracted.  In my scribble file I have 

% cat rdf.scrbl
#lang scribble/manual
@(require scribble/extract)
@title{The rdf library, wrapping librdf.org}
If you give a mouse a cookie, he's going to ask for a glass of milk.
@(include-extracted "../src/build/rdf.ss")
%

In the rdf.ss I have a line '(require "librdf-extn.rkt")', and in ../src/build I have rdf.ss and compiled/native/i386-macosx/3m/librdf-extn_rkt.dylib (ie, an extension, with no associated .rkt or .ss file).  Running scribble then gives:

% scribble --html rdf.scrbl
default-load-handler: cannot open input file: "/checkouts/me/code/plt-librdf/doc/librdf-extn.rkt" (No such file or directory; errno=2)

 === context ===
/Data/LocalApplications/Racket/Racket v5.0/collects/racket/private/map.rkt:18:11: map
/Data/LocalApplications/Racket/Racket v5.0/collects/scribble/run.rkt: [running body]
% pwd
/checkouts/me/code/plt-librdf/doc
%

That is, the processing of include-extracted seems to be searching for required modules in an unexpected way.

Thanks for any illumination.  Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk