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
on 2006-01-12 15:04
on 2006-01-12 15:19
On Thu, 12 Jan 2006 14:03:05 +0100, Greg L. <firstname.lastname@example.org> 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.
on 2006-01-13 06:37
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