[plt-scheme] testing scrbl work-in-progress in local svn area

> > If it's the latter, then you can run setup-plt with PLTCOLLECTS  
> > pointing at your own directory, for example
> >  PLTCOLLECTS=":/Users/gknauth/test/plt/collects" setup-plt
> 
> I tried that, with one small change (extra plt in my dev-path):
> 
>    PLTCOLLECTS=":/Users/gknauth/test/plt/plt/collects" setup-plt
> 
> I discovered a few things before I got things to work.
> 
> I had been working in:
>    ~/test/plt/plt/collects/parser-tools
> porting doc.txt to doc/manual.ss and doc/info.ss
> 
> When I ran setup-plt your way, I noticed all the .scrbl files that  
> were processed were either in (a) or (b):
> (a) collects/module-name/module-name.scrbl
> (b) collects/scribblings/module-name/module-name.scrbl
> 
> and they were ALL in /usr/local/plt, not in my dev directory.

Since your PLTCOLLECTS setting starts with ":", and since a
"parser-tools" collection was found in the default collection
directory, then the "parser-tools" directory in
"~/test/plt/plt/collects" wasn't used. That is, PLTCOLLECTS only
splices at the collection level, not at the level of individual files.


You could do something like this:

 cd /tmp
 mkdir doc-collects
 ln -s ~/test/plt/plt/collects/parser-tools doc-collects/doc-parser-tools
 PLTCOLLECTS=":/tmp/doc-collects" setup-plt

and then your "parser-tools.scrbl" would get built as part of a new
"doc-parser-tools" collection. (The documentation would be written to a
"doc" subdirectory next to "parser-tools.scrbl", not in the main
installation's "doc" directory.)


The underlying design is that Setup PLT globally resolves
cross-references among documents. To do that, it needs to know all the
documents, and each one needs a fixed identity; the collection is used
as part of the document's identity. That's why every document has to be
in a collection (or planet package) for Setup PLT to handle it.

Naturally, `scribble' itself does not require documents to be in
collections --- but `scribble' also needs you to tell it about all the
other documents that you might link to. That's why Yavuz suggested
running `scribble' to get rough output without hyperlinks.

But if you want to work on collection-library documentation without
working in the main collection tree and without replacing any of the
collections there, then you have to either add a new collection
somehow.

Matthew