Ri cross-referencing


#1

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


#2

On Thu, 12 Jan 2006 14:03:05 +0100, Greg L. removed_email_address@domain.invalid
wrote:

However I have so often felt the pain of this situation that I thought
own online help was properly cross-referenced no 3rd party online help
cross references at the end, or beginning or something, or even

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 V.


#3

On Jan 12, 2006, at 7:03 AM, Greg L. wrote:

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.

To be fair, there’s no way that rdoc can know what methods are
relevant to the current one unless they’re cited explicitly. If they
are, then use the html form of the documentation, rather than ri, and
you’ll find the inline references become hyperlinks to the other
method descriptions.

Cheers

Dave