David Vallner
1/12/2006 1:19:00 PM
On Thu, 12 Jan 2006 14:03:05 +0100, Greg Lorriman <temp@lorriman.com>
wrote:
> Hello persons,
>
> ri's help is very handy, but there are no cross-references to related
> classes/methods other than by chance mention in the text of the
> method's/class's docs. This is especially important when trying to find
> a method/class whose name one doesn't know (particularly as a beginner,
> or with unfamiliar libraries). This would also aid a more organic
> discovery of ruby libraries.
>
> Perhaps such a feature is only really possible in professional tools.
> However I have so often felt the pain of this situation that I thought
> to pose the possibility of such a feature to the Ruby community.
>
> All that is needed is a list of classes/methods at the end of the
> normal documentation. For example Numeric#truncate could have a list at
> the end mentioning floor, ceil and Float#round.
>
> I have noticed in the Borland world that though Borland specified a
> format for help files for professional documentation purposes (such as
> for professional component writers), that this format had no explicit
> support for cross-referencing. The result was that although Borland's
> own online help was properly cross-referenced no 3rd party online help
> bothered cross-referencing either within itself or referencing
> Borland's libraries. When I wrote my own, once upon a long time ago, it
> never occurred to me to cross-reference despite having made great use
> of Borland's cross-referencing efforts (and microsoft's).
>
> If the Ruby community were to eventually decide to encourage
> cross-referenced documentation then I reckon that this would be much
> aided by support within ri itself. For example ri might recognise a
> suitably marked list of method names as a cross-reference, and
> therefore be able to enforce usability conventions (ie. positioning the
> cross references at the end, or beginning or something, or even
> numbering them so that they can be drilled into via ri 3, for example).
>
>
> Perhaps even the ability to take the cross-references and apply them in
> reverse (to that which is cross-referenced). But maybe that is too
> exciting (and risky?). The latter idea would even allow the standard
> library to recieve cross-referencing via a 3rd party without touching
> the original docs. Perhaps even support for inherited
> cross-referencing, to remove redundancy (but maybe that is too
> complicated, and slow 'though it could be indexed).
>
> any takers?
>
> Greg
>
>
Wouldn't a "See also" section with method name forms in the method
comments / module synopsis already get parsed by rdoc and generate
cross-references (links) for the html backend, possibly highlighted text
for the ri one?
ri is meant to be a simple documentation search / viewing tool, not a
documentation browser. For advanced use, using HTML documentation, or a
texinfo backend to rdoc seem like more concise and easier to implement
alternatives than reinventing the wheel with Yet Another Manual Browser.
David Vallner