Is there a way to portably create a 'link:' ?

[thinkerbot]

I often want to link to other files (licenses, help docs, etc) in my RDoc. In RDoc 1.0 such links can be made using something like:

{file}[link:files/file_name_ext.html]

But as pointed out in an issue regarding YARD and rubydoc.info, this syntax assumes the location of the file. Obviously the links break between RDoc/YARD, but I found they also break between RDoc 1.0 and RDoc 3.8. It also breaks on GitHub... rendered .rdoc files have links that don't link to the intended files.

Maybe nothing can be done for everywhere, but is there a way to write portable links between RDoc 1.0 and RDoc 3.8? I'd like these links to work when people install the RDoc via Rubygems and I don't think I can assume RDoc 3.8 has been installed. If there is one, I plan on submitting a pull request to the GitHub markup library so that links can work on GitHub (it may involve a little gsub to reference the file in the repo but who knows they may go for it).

This gist illustrates the issue: https://gist.github.com/1097310 Generate with:

rdoc --main README.rdoc README.rdoc file.txt

When you use RDoc 1.0 you get a working link and a file like 'doc/files/file_txt.html'. When you use RDoc 3.8 you get a broken link and a file like 'doc/file_txt.html'.

[drbrain]

The directory layout of generated documentation changed between RDoc 1 and RDoc 3. Poking through the code I don't see an easy way to make the link: scheme portable between the two versions.

RDoc will link a plain file name, so:

Here is a reference to the file.txt

In README.rdoc will create a link to file.txt. It's not as pretty but it is a workaround

For forward compatibility I could add an rdoc: scheme that links to the correct place for use in friendly links in case the directory structure changes. For example:

{RDoc driver}[rdoc:RDoc::RDoc] would link to RDoc/RDoc.html
{README}[rdoc:README.txt] would link to README_txt.html

How does this sound?

[thinkerbot]

So would the plan be to add the rdoc: scheme to both RDoc 1 and RDoc 3? I think that would be a great solution. Do you have any idea how long it would take updates to RDoc 1 to propagate to the stdlib?

Regarding your workaround, RDoc 1.0.1 isn't creating a link for me using a plain file name. Am I on too old a version or does that only work with RDoc 3? Thanks for your quick response to this and other issues.

[drbrain]

It would not be added to RDoc 1. The 1.8.7 branch only accepts bug fixes for future patchlevels and there will be no 1.8.8 release to add the feature to. Unfortunately RDoc 1 (and Ruby 1.8) are officially dead.

The advantage of the rdoc: scheme is that it would create a correct link if the file structure changed in a future generator or incompatible version of RDoc.

I think you are right that the plain link doesn't work in RDoc 1… now that you mention it I seem to recall adding it.

[thinkerbot]

Darn, sounds like there isn't much that can be done for RDoc 1. Oh well, I guess you have to move forward at some point! Last question before I personally consider this issue closed - do you know when RDoc 3 is going to be a part of the 1.9 stdlib? Currently I have 1.9.2-p180 which looks like it comes with RDoc 2.5.8.

[drbrain]

The Ruby 1.9.3 branch currently contains RDoc 3.8 and I will be importing 3.9 today or tomorrow.

[drbrain]

I changed the scheme to rdoc-ref: