This same kind of problems comes up for documenting things like struct properties, match expanders, require/provide syntax, what is a sequence, what is a dict, etc. I think there is probably a single solution to them all.
Jay On Wed, Oct 6, 2010 at 1:27 PM, Danny Yoo <d...@cs.wpi.edu> wrote: > 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? > _________________________________________________ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/users > -- Jay McCarthy <j...@cs.byu.edu> Assistant Professor / Brigham Young University http://teammccarthy.org/jay "The glory of God is Intelligence" - D&C 93 _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/users
