[racket] Module docs

From: Mark Carter (mcturra2000 at yahoo.co.uk)
Date: Tue Aug 30 13:02:58 EDT 2011

----- Original Message -----
> From: Matthew Flatt <mflatt at cs.utah.edu>
> To: Mark Carter <mcturra2000 at yahoo.co.uk>
> Cc: "users at racket-lang.org" <users at racket-lang.org>
> Sent: Tuesday, 30 August 2011, 15:07
> Subject: Re: [racket] Module docs
>T hanks for the details. I see that `raco setup' in a fresh install on
> Windows does bad things, so I'm starting with that problem. When that's
> fixed, I'll continue checking what happens with your files.

Many thanks. There does seem to be a bug in raco itself, where it generates the "duplicate tag" warnings. I found a help page in DrRacket that explains how to set up module documentation, and my collection layout wasn't in conformity. For example, I discovered that my carali.scrbl should have the header
#lang scribble/manual
and info.rkt should have the header
#lang setup.infotab

Things can get confusing for a newbie like me, because there tends to be settings all over the place, and it's difficult to figure out what does what. Also, people who write collections for the Planet seem to have different styles, which again tends to make things confusing.

It seems that typing 
raco setup
now does work, although there are still "duplicate tag" warnings, and it does take quote some time, as it seems to want to do a lot of compiling work, including reconstructing the racket.exe itself - which seems OTT considering that all I'm really trying to do is construct my module documentation.

I love the whole documentation concept, BTW. I often forget how my functions should work, and what's available, so documentation linked under F1 is a very neat idea. Plus, of course, for people browsing Planet, it allows them to read the documentation in advance to decide whether it's likely to be suitable for their purposes.

Once again, thanks for your help.

Posted on the users mailing list.