Hacker News Reader

Comment by pm215 | Hacker News Reader

I've done the "reference the spec section" thing before -- the difficulty is that often section numbers or similar things get stale when a newer revision of the spec document is published; so it can work for a slow-moving thing like the C spec but is more awkward if the spec/manual gets a revision every six months.

View on HN

It's a good point. This is why for C the references are to a specific standard, i.e. C11. For D, I use named links, which we try to not change. The bugzilla numbers do not change, which is a feature of bugzilla.

Even so, the utility of the links far outweighs the possibility of needing to adjust them.

P.S. I've found using links to Microsoft documentation to be extremely frustrating, because not only does Microsoft move them around all the time, but will wholesale permanently delete vast swaths of reference material.

Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.

One way I’ve found is to quote the thing I’m citing. Context and length dependent, of course. This also has the advantage of showing how the doc looked when you write the code, so the comment rots less slowly (and if something changes, you can see by comparing the excerpts)

I've considered that, but was concerned about copyright issues.

Interesting. IANAL but is saying “we have to do this dumb workaround because of xyz” criticism under (US) fair use?

You're probably right, but I don't want to deal with a lawyer on this. It's not worth it.

> Notice that the github links are to line numbers. Line numbers are ephemeral, I don't know a way around that.

If you go to your link, under the button with 3 dots there's a "copy permalink option" that creates a link to the specific commit you're looking at, ensuring the line number doesn't get out of date. Example:

https://github.com/dlang/dmd/blob/9003e2ae7e11faed433638e9cb...

Perfect! Thanks!

Reply on news.ycombinator.com