[plt-scheme] Some More Scribble Questions

Thanks, Matthew.  It's in good enough shape now to release - which I have.
I'll move on to the simulation and inference collection documentation now.
I don't think they'll be as hard as the science collection was.

At some point in time - hopefully within a month or so - I'll revisit the
science collection documentation and code.  One thing I have noticed from
reading the PLT Scheme Reference Manual is the inclusion of exact integer
booleans- things like exact-non-negative integer?.  I assume these are the
right things to use in the contracts for any arguments that eventually are
used as vector indices, etc.  I also assume that contract error messages for
exact-nonnegative-integer? would give a more informative message than for
(and/c exact? natural-number/c?), etc.

It also seems that there is now a mismatch between how we specify arguments
and contracts in Scribble, which is very nice, and in the contracts in the
code.  The defproc format seems to be more intuitive.  I haven't revisited
the contracts section of the documentations yet - and probably should.

Anyway, thanks for answering all the questions I've had.

Doug

On Mon, Sep 22, 2008 at 7:27 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:

> At Sun, 21 Sep 2008 11:58:25 -0600, "Doug Williams" wrote:
> > I get a warning the it collected information multiple times on (mod-path
> > "(planet williams/main/section/shared)") and (index-entry (mod-path
> "(planet
> > williams/main/section/shared)")).  Is there an alternative to the second
> > defmodule that won't give the warning?
>
> `defmodule*/no-declare'.
>
> > I also get a warning that it collected information multiple times on
> > "(exporting-libraries #f)".  Is that likely from the same problem or a
> > different one (like a different defmodule problem elsewhere)?
>
> That's likely a `defproc' (or `defthing', etc.) inside a section that
> doesn't have a `defmodule' (either in the immediate section or an
> enclosing section).
>
> > Second question: I am including (require (for-label (planet
> > ../science-with-graphics.ss")) in each of the scribble files, but I'm not
> > sure it it's necessary if I have the defmodules.  I assume it is used to
> > resolve references for hyperlinking, but do the defprocs, etc provide the
> > same information?
>
> You need both, currently. The `defmodule's determine the hyperlink
> bindings created the `defproc's, etc. The `require .... for-label's
> determine uses of identifiers to be hyperlinked. The same bit of text
> naming a function in a `defproc' both serves as a hyperlink target and
> is hyperlinked to itself. (Of course, hyperlinking to itself isn't
> really useful, but by "hyperlink" in this case I also mean getting the
> right text style, such as blue versus bold black.)
>
> > And, I guess a related question:  in my defmodules I am using the planet
> > reference, but I used the relative reference in the for-label.  It seems
> > logical to me to do that since the defmodule renders into something the
> user
> > sees - and they know about the planet collection, while the for-label is
> > internal to the scribble files and not visible to the user.
>
> Right.
>
> > Does the planet
> > deference in defmodule refer to the copy in the planet repository (on my
> > machine) or to the source code being used to build it?  That is, do I
> have
> > to have already built a .plt and fileinjected it for the defmodule to
> work?
>
> Yes, or you need to have a development link. This is definitely a place
> to improve in the future.
>
> > One last question:  How can I include an appendix (or at least an
> unnumbered
> > section-include?  I have the GNU Free Documentation License I need to
> > include with the documentation, but would rather it wasn't a numbered
> > section.
>
> You can use `make-unnumbered-part'. There doesn't seem to be a style on
> `section' (or anything like that) to write the start of an unnumbered
> section more directly. We should add something, or maybe unnumberedness
> should have been a style instead of a different structure type.
>
>
> Matthew
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20080922/c4dd6231/attachment.html>