handling broken links in documentation

Broken links are a problem for CRAN submission, so they are really not worth the risk and cost. (Why cost? I mean cost in developer time and also cost for CRAN members who might look at the submission.)

At one point, I thought the mechanism of linking to the web was a very good thing. It meant that users could just click a highlighted URL in the docs. But, really, how much harder is it to copy the URL and paste it into a browser? Not much.

My policy is as follows, whenever a local URL test or a test in a remote build cannot find a link.

1. Check the link myself. If it works, try it again. If that fails, go to step 2.
2. Change the link to fixed-width font, e.g. changing \doi{something} to DOI something.

That's it. At one point, I was making lists of problematic links, so that I could check again a day after I saw something was broken. Now, I just don't see the point. If CRAN is going to flag broken links, I want oce to have as few broken links as possible. In theory what you can do is to put into the CRAN notes some text saying that the link is broken sometimes but not always. But do we really want to impose upon CRAN maintainers to read such things and try links themselves? No.

In baseball terms, one strike and you're out.