From: Greg Lorriman <temp@...>
Date: 2006-01-12T22:03:05+09:00
Subject: ri cross-referencing

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