[plt-scheme] Some More Scribble Questions

I finally have the science collection documentation converted to Scribble,
but have some warnings I'd like to get rid of.

The problem is that I am using sub-collections and have some interdependent
sets of functionality (specifically, gamma, psi, and zeta functions) that
are in a single module, but documented in separate sections.  Let me give a
simplified example.

main.scrbl
...
@include-section["section.scrbl"]
...

section.scrbl
...
@defmodule[(planet williams/main/section)]
...
@section{Section One}
...
@defmodule[(planet williams/main/section/shared)]
...
@section{Section Two}
...
@defmodule[(planet williams/main/section/shared)]
...

Note that the first defmodule is for the entire sub-collection - it requires
and provides all of the modules in the subcollection.  But, the user can
also just require the modules they are using, if they want - for example the
shared module above.

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?  [The warning is visible to the user
when they first require the package from PLaneT and it is downloaded and
built.]

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)?  [There are a
lot of defmodules in the documentation and I've notice that I can mistype
planet references and not get an error, so there might be one lingering
somwhere.  Warning don't give any source location information, so it can be
hard to tell where they originate.]

---

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?

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.  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?

---

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.

---

And, some general comments and kudos.

I was pleasantly surprised that the @math{} functionality was as developed
as it is.  The documentation says that _ and ^ may be added in the future.
Well, apparently I downloaded through a time warp, because they work - at
least for many cases (and I could use @subscript and @superscript in the
others).  I assume it's still a work in progress, but I was able to render
many of the mathematical equations directly.

One nice feature would be something like @equation{...} that takes a TeX
equation and renders it to an image.  That's probably a bit too deep into
the Scribble code for me to attempt, but it would be a great feature if
someone wanted to tackle it.  [Doing that manually is how I did the more
advanced equations - integrals, summations, etc - that @math couldn't
handle.]

I'm very happy with how the science documentation looks in scribble.

Thanks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20080921/595cdcee/attachment.html>