[racket] Unified docs on info.rkt?

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 <dyoo at 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 <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://teammccarthy.org/jay

"The glory of God is Intelligence" - D&C 93