[plt-scheme] Re: Some More Scribble Questions

To partially answer my own e-mail:

For the multiple defmodules, I removed all by one of the defmodules for
shared and replaced the last ones with @scheme[(require (planet
williams/main/section/shared))].  This eliminated the warnings and pretty
much looks the same in the documentation.  [The require line isn'toutlined
in a pastel pinkish box, but I don't think anyone will notice.]

There is one warning/message that I get now when I initially download and
install the collection.  It says it is removing the .zo for the GFDL.scrbl
file.  I'm not sure why that one file is different than any of the other
@include-sections.  It has no code references to it since it is just text is
all.

I have released the package update to PLaneT with the new documentation.

Doug

On Sun, Sep 21, 2008 at 11:58 AM, Doug Williams <
m.douglas.williams at gmail.com> wrote:

> 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/20080922/50de610d/attachment.html>