Bug #14743: Some links broken in README

• Status: Closed
• Assignee: -
• Target version: -
• ruby -v: trunk
• Backport: 2.3: UNKNOWN, 2.4: UNKNOWN, 2.5: UNKNOWN
• Tags: notbug, doc

[znz (Kazuhiro NISHIYAMA)]

Some links broken in README is original issue.
And I tried to fix links, but some problems occur.

1. Current README.md's link is [win32/README.win32](win32/README.win32) and it works on github, but rdoc generates broken link.
2. Using rdoc-ref suggested in Convert links to local files in markdown, it works rdoc generated html, but it does not work on github.
3. Plain filename becomes link on rdoc generated html, but it does not become link on github.

• Sample site: https://md-link-test-2018.netlify.com/
• Source: https://github.com/znz/md-link-test-2018

Which is better?
Is there other better solution?

[shevegen (Robert A. Heiler)]

I can't answer your two questions, but for what it's worth,
aycabta commented on the linked/associated github issue:

I think that GitHub's UI isn't important for Ruby. And,
I don't want to optimize RDoc for GitHub.

I personally am not hugely active on github, but I am very
active on rubygems.org. There, I do try to have my README.md
files work, bcause end users may want to read it. (I actually
autogenerated these .md files, through ruby, via a README.gen
template).

I use only very plain markdown rules; rdoc-ref would seem
way too complex for me to use. :D

IMO, many people use github to browse and read source code
and I think that many more people do so these days, as
compared to reading a .md file locally/offline, so I personally
think that github UI is also important, simply because people
make use of it a lot.

I don't know of a solution that works for both, but I think
rdoc could be fixed more easily. If aycabta does not want to
do so that is fine; perhaps someone else has an idea, or we
may have a solution that works on both. At any rate, that is
just my 2 cc.

• Status changed from Open to Closed

Applied in changeset git|2898805535104c330e1e5c64c8065a108f1f2895.

---

Use rdoc-ref to fix a few links in the README

This may break linking on GitHub, but it's more important for the
links to work in the documentation generated by rdoc.

Fixes [Bug #14743]