User:Furey/References to source code

From NetHackWiki
Jump to navigation Jump to search

Timeline

2003: NetHack 3.4.3 released.

2005: NetHackWiki created.

2015: NetHack 3.6.0 released.

During the time between 2005 and 2015, there was one vanilla source code, plus SLASH'EM 0.0.7E7F2 source code, plus an abortive attempt at SLASH'EM 0.0.7E7F3 source code (only 5 files were uploaded). So there was one source, THE source.

Editors wrote many different features to reference THE source:

These were fine as long as there was only one THE source.

The new multiversion world

After the release of NetHack 3.6.0, things changed. Some of the methods for making source code references grew a new parameter to specify the version. The new parameter had to be optional, and it had to default to NetHack 3.4.3 so that legacy references would continue to work. This scheme relies on editors conscientiously choosing the right source version when referring to source code.

This scheme has not worked.

Case in point: acid hound

Contains two calls to Template:monster. The first call defines "acid hound pup" with refline=580. The second call defines "acid hound' with refline=622. The two reflines resolve to https://nethackwiki.com/wiki/Source:NetHack_3.6.1/src/monst.c , which of course does not have any acid hounds. Line 580 is inside the definition of "large mimic", and line 622 is inside the definition of "hobgoblin".

This is likely a problem for many monster definitions in variants.

Case in point: allmain.c

Consider Source:NetHack 3.4.3/src/allmain.c itself. The second sentence of the article reads: To link to a particular line, write [[allmain.c#line123]], for example.

Wrong. allmain.c used to redirect to Source:NetHack 3.4.3/src/allmain.c, but in December 2015, someone changed the redirect to Source:NetHack 3.6.1/src/allmain.c. This was a quiet change, and it broke callers. It also means anyone using allmain.c today has to remember that this is a 3.6.1 file. Is it going to be a 3.7.0 file in 2026? Nobody knows.

Case in point: speed

Consider https://nethackwiki.com/index.php?title=Speed&oldid=171493 , a historical version from right before I fixed it. Here are three references from the article:

  • {{refsrc|allmain.c|137}}
  • {{refsrc|allmain.c|147}}
  • {{refsrc|allmain.c|119}}

When I followed these line numbers, the results were nonsense. The problem is that the unversioned refsrc defaults to NetHack 3.4.3, but the editor who wrote the article provided line numbers from NetHack 3.6.7. This problem is endemic in our articles.

Case in point: Template:monster

Consider titan. The infobox for monster data shows a source code reference of monst.c#line1438. This resolves to NetHack 3.6.1, and in the 3.6.1 version of src/monst.c, line 1438 is 5 lines away from the actual line that defines MON("titan", ...). A five line version skew is not much but it will get a lot worse when NetHack 3.7.0 releases.

Statistics

Some of our templates track unversioned usage. Statistics as of June 21, 2024.

https://nethackwiki.com/index.php?search=unversioned 

Page title matches
Category:Pages with unversioned Sourcecode templates
119 members (0 subcategories, 0 files) - 00:19, 27 January 2020
Category:Pages with unversioned Refsrc templates
258 members (0 subcategories, 0 files) - 00:19, 27 January 2020
Category:Pages with unversioned Reffunc templates
85 members (0 subcategories, 0 files) - 00:18, 27 January 2020
Category:Pages with unversioned Function templates
89 members (0 subcategories, 0 files) - 00:17, 27 January 2020

Proposal

In one sentence:

Every reference to source code must explicitly specify a version number.

Yeah, yeah, that's nice. But it has a lot of implications.

  • Hundreds of existing articles must be fixed.
  • We must change our templates to give errors if a version number is not specified.
    • Relying on people to choose to specify a version number has not worked.
  • Popular templates such as monster and object will need all of their callers changed.

This will be a hard sell, because someone will propose a default that is convenient for them, predicated on the assumption that people will follow their rules about how the default behaves. And then other people will produce mis-matched references like the examples cited above. At that point there will be enormous numbers of worthless source references in our article base, which taint the trustworthiness of all the source references. That is where we are today.

Notes about specific templates

refsrc is the best. it takes a nethack= argument, or even a version= argument for variant source. Also takes a ref=no argument which makes it behave like sourcecode. Can find both internal and external archives.

sourcecode is okay. If you see a <ref>{{sourcecode|...}</ref> then change it to a refsrc.

function looks nice but is limited. It takes a version argument but then ignores its value. It always resolves to a local article name that matches its filename. In the past, these articles were redirectors to 3.4.3; as of July 2024, they are redirectors to 3.6.1,; and there is no guarantee where they will resolve in the future. I usually change these to refsrc's.

function_343 is like function but is hard coded for NetHack 3.4.3. This is a feature. Good for references in articles about 3.4.3, 3.4.3 based variants, 3.4.3 patches, talk pages from the 3.4.3 era, and so on. Very easy and safe edit.

function_361 does not exist yet but I will create it if and when I find use cases.

reffunc I have not used.

As of July 2024, line-based references do not work on source files with __MIXEDSYNTAXHIGHLIGHT__, which is most source files for NetHack 3.4.3, NetHack 3.6.0, and NetHack 3.6.1.

Function-based references do not work on source files hosted on GitHub, which is NetHack 3.6.2 and later versions.

upcoming notes use a lot of commit messages rather than source file line numbers or source file function names. This is fine.

Retrieved from "https://nethackwiki.com/index.php?title=User:Furey/References_to_source_code&oldid=173659"