[plt-scheme] Some More Scribble Questions

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