[lnkForumImage]
TotalShareware - Download Free Software

Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

ri cross-referencing

Greg Lorriman

1/12/2006 1:01:00 PM

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 Answers

David Vallner

1/12/2006 1:19:00 PM

0

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



Dave Thomas

1/13/2006 4:35:00 AM

0


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

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

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