User:Furey/References to source code - Revision history

Furey: Notes about specific templates

2024-07-02T04:44:29Z

Notes about specific templates

Furey: Redo organization.

2024-06-22T23:40:16Z

Redo organization.

Furey: /* Case in point: acid hound */

2024-06-22T23:36:03Z

‎Case in point: acid hound

Furey: first draft.

2024-06-22T03:08:43Z

first draft.

Furey: first draft.

2024-06-22T02:59:50Z

first draft.

New page

= References to source code =

== 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:
* [[Source:NetHack 3.4.3/src/allmain.c]]
* [[Allmain.c]]
* [[Source:Allmain.c]]
* [[Source:Ref/moveloop]]
* <nowiki>{{refsrc|allmain.c}}</nowiki>
* <nowiki>{{refsrc|src/allmain.c|nnn}}</nowiki>
* <nowiki>{{sourcecode}}</nowiki>
* <nowiki>{{function}}</nowiki>
* <nowiki>{{reffunc}}</nowiki>
* ... and probably more ...

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: [[allmain.c]] ===

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

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:
* <nowiki>{{refsrc|allmain.c|137}}</nowiki>
* <nowiki>{{refsrc|allmain.c|147}}</nowiki>
* <nowiki>{{refsrc|allmain.c|119}}</nowiki>

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

← Older revision		Revision as of 04:44, 2 July 2024
Line 86:		Line 86:

	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.		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 =
		+
		+	<tt>refsrc</tt> is the best. it takes a <tt>nethack=</tt> argument, or even a <tt>version=</tt> argument for variant source. Also takes a ref=no argument which makes it behave like <tt>sourcecode</tt>. Can find both internal and external archives.
		+
		+	<tt>sourcecode</tt> is okay. If you see a <nowiki><ref>{{sourcecode\|...}</ref></nowiki> then change it to a <tt>refsrc</tt>.
		+
		+	<tt>function</tt> 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.
		+
		+	<tt>function_343</tt> is like <tt>function</tt> 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.
		+
		+	<tt>function_361</tt> does not exist yet but I will create it if and when I find use cases.
		+
		+	<tt>reffunc</tt> 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.
		+
		+	<tt>upcoming</tt> notes use a lot of <tt>commit</tt> messages rather than source file line numbers or source file function names. This is fine.

← Older revision		Revision as of 23:36, 22 June 2024
Line 30:		Line 30:

	This scheme has not worked.		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]] ===		=== Case in point: [[allmain.c]] ===

← Older revision		Revision as of 03:08, 22 June 2024
Line 66:		Line 66:
	Category:Pages with unversioned Function templates		Category:Pages with unversioned Function templates
	89 members (0 subcategories, 0 files) - 00:17, 27 January 2020		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.

@@ Line 1: / Line 1: @@
-= References to source code =
+{{tocright}}
-== Timeline ==
+= Timeline =
 : [[NetHack 3.4.3]] released.
@@ Line 25: / Line 25: @@
 These were fine as long as there was only one THE source.
-== The new multiversion world ==
+= 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.
@@ Line 31: / Line 31: @@
 This scheme has not worked.
-=== Case in point: [[acid hound]] ===
+== 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".
@@ Line 37: / Line 37: @@
 This is likely a problem for many monster definitions in variants.
-=== Case in point: [[allmain.c]] ===
+== Case in point: [[allmain.c]] ==
 Consider [[Source:NetHack 3.4.3/src/allmain.c]] itself. The second sentence of the article reads:
@@ Line 44: / Line 44: @@
 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]] ===
+== 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:
@@ Line 53: / Line 53: @@
 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 ===
+== 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 ==
+= Statistics =
 Some of our templates track unversioned usage. Statistics as of June 21, 2024.
@@ Line 73: / Line 73: @@
 members (0 subcategories, 0 files) - 00:17, 27 January 2020
-== Proposal ==
+= Proposal =
 In one sentence: