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
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
