[racket] Fw: Building docs

At Sat, 27 Aug 2011 21:37:39 +0100 (BST), Mark Carter wrote:
> > I'm puzzled by the warnings, where the same collection is named in two
> > ways. Can you show the command line that produced this output?
> 
> raco setup carali

That makes sense, but now I realize that I need to know previous
command lines, if you have them.

By the time you ran `raco setup carali', the installation had become
confused about "scribblings/main/user\search.scrbl" and
"scribblings\main\user\search.scrbl" being the same document (i.e.,
there's some path-normalization problem).


> Actually, you can visit the root of the project at this link:
> https://github.com/blippy/tacc/tree/master/scheme/carali
> That will probably help a lot to see how things are structured.

That looks like a fine organization overall.

Instead of

 (module <filename> racket
   ...)

most of us use just

 #lang racket


> Also, what is the point of the of the second argument in module? For example, 
> in access.rkt, the top of my file reads:
> (module access racket
> ... )
> "access" names my module. What does "racket" do? I've never figured that one 
> out. Should I even be using modules in my packages?

Hopefully the `#lang racket' form is more suggestive: It indicates that
the module is implemented in the `racket' language, as opposed to
`typed/racket' or `scribble/manual' or any number of other languages.


> To be honest, I'm a bit puzzled overall about how best to structure files. I 
> conceive of carali as a package that I use often, split into various files 
> logically. I'm not really sure if it's a good idea to put rkt files in 
> modules, or not. The way things should be laid out in my head is a bit vague, 
> so I'm generally just "having a stab" at things the best way I can.

Putting code into module is definitely the right approach.


> Am I right in thinking that "info.rkt" is a reserved file that is used by 
> Racket to generate documentation?

Yes, `raco setup' and other tools consult "info.rkt" for
meta-information about a library collection, such as how to build its
documentation.

> And that "main.rkt" is a reserved file used by Racket to define a package's 
> structure?

No, "main.rkt" is special only in that it enables a shorthand. Use it
when a main library makes sense for a collection, so that `(require
carali)' can be used as a shorthand for `(require carali/main)'.