User:Bhaak/Refsrc

From NetHackWiki
Jump to navigation Jump to search

This template is used to create references to NetHack source code.

Ambiguous references

Many old references on NetHackWiki look something like this:

{{refsrc|allmain.c|42}}

which produces this footnote.[1] These references don't specify which version of NetHack they're referencing, nor which directory the file is in, and thus are somewhat ambiguous. The template will attempt to patch these problems up (via assuming NetHack 3.4.3, the statistically most common version at present, and consulting a list of filenames to determine the directory). However, please try to specify at least the version explicitly, to avoid problems with future NetHack versions (most likely, for new references you don't want to cite 3.4.3 anyway).

Good references

Good examples of references, including explicit versions and directoires:

{{refsrc|src/allmain.c|42|version=NetHack 3.4.3}}

will produce this,[2] and

{{refsrc|src/allmain.c|42|version=NetHack 3.6.0}}

will produce this.[3]

This is case-sensitive. Remember, no capital letters in "version", two capital letters in "NetHack".

Unlike the old ambiguous references, these references will not break as new versions of NetHack are released, and also make it easy to identify which articles are referenced to an old version (and thus may contain out-of-date information).

If a reference is to NetHack specifically, rather than a variant, you can abbreviate the reference, like this:

{{refsrc|src/allmain.c|42|nethack=3.6.0}}

which produces this.[4] This is not identical to specifying version=NetHack 3.6.0, but faster to write and saves space in the edit box. Alas, it would not eliminate the error message 'Page with an unversioned refsrc'. Again, as this is case-sensitive, "nethack" as a parameter name should have all small letters.

The directory part is technically optional as long as the filename is unambiguous and the file is in one of the major directories (src/, include/, or dat/) – the template will consult a list of filenames to resolve the ambiguity – but providing it anyway may help avoid confusion.

Referencing NetHack's variants

{{refsrc|allmain.c|42|version=SLASH'EM 0.0.7E7F2}}

SLASH'EM code is stored on this wiki without the use of subdirectories, so for the time being, you'll need to omit those when referencing SLASH'EM code. The above example looks like this.[5]

{{refsrc|src/mkroom.c|123|unnethack|commit=e38a891b9}}

{{refsrc|src/mkroom.c|123|unnethack=1406}}

UnNetHack allows you to link to a particular commit on GitHub or revision on SourceForge, rather than a particular version. It looks like this for the repository on GitHub[6] and like this for SourceForge[7]. You will need to specify the subdirectory explicitly, because there is no filename list available for UnNetHack.

Advanced usage

{{refsrc|src/monmove.c|219|version=NetHack 3.4.3|comment=fleeing monsters stop holding you}}

You can include a comment along with the reference, as shown here.[8]

You may also specify a name parameter so you can reference the same location in the code from multiple locations in the text, like this:

{{refsrc|src/engrave.c|814|version=NetHack 3.4.3|name=venom_letter}} [some other text...] <ref name='venom_letter'/>

This will produce output like the following:[9] [some other text...] [9]

See also

References