[racket] Unified docs on info.rkt?

From: Danny Yoo (dyoo at cs.wpi.edu)
Date: Wed Oct 6 15:27:40 EDT 2010

Despite the Racket documentation being a quite a bit better than
before, it still needs work.  I was having a hard time finding the
documentation for info.rkt files this afternoon.  info.rkt is funny
because it's a fairly generic file format, and other parts of Racket
take advantage of its open file format.  The documentation to
info.rkt, consequently, is really spread out across several sections.

I was trying to figure out how to get a collection's compilation to
ignore certain directories.  I know I'd done this in the past, but I
was blanking out on the exact name and type of the info.rkt
configuration option.  As an experiment, I put myself in the mindset
of someone who doesn't yet know the system, to see if I could find it
anyway.

 I searched the documentation for 'info.rkt', and found three hits:

     http://docs.racket-lang.org/raco/running.html?q=info.rkt#(part._setup-info)

     http://docs.racket-lang.org/planet/Developing_Packages_for_PLaneT.html?q=info.rkt#(part._.Create_an__info_rkt__.File__.Optional_)

    http://docs.racket-lang.org/raco/info_rkt.html?q=info.rkt

I looked through all of this, but none of it pointed to the option I
was looking for.  I gave up after that, and just resorted to grepping
through my old source trees to finally come across a reference to
compile-omit-paths.   I then searched for compile-omit-paths:

http://docs.racket-lang.org/raco/API_for_Raw_Compilation.html?q=omit#(idx._(gentag._41._(lib._scribblings/raco/raco..scrbl)))

The somewhat infuriating result is that the documentation for
compile-omit-paths does have a literal "back-reference" link to
info.rkt in its description, but the search is not picking that up.

The experiment's results are: I would not have been able to discover
'compile-omit-paths in the current documentation.  I wonder: would it
be effective to adjust the search engine's indexer to include the kind
of back-references that characterize open systems such as the info.rkt
documentation?


Posted on the users mailing list.