NetHackWiki talk:Style guide

Formality

So when can we start calling this the official style guide? --ZeroOne 18:34, 27 June 2006 (UTC)

I think that the style guide still needs more work. The style guide makes some assumptions that I fail to understand, and even makes recommendations that I might want to disagree with.

The good thing about this style guide is that when someone wants to know the best way to cite source code in footnotes, or to make pretty tables, or which templates to use, then we can refer them here.

The things that might or might not need changing: (1) the recommendation against ==Introduction== at the start, because maybe we want the TOC at the top of some pages. (2) the Wikipedia-Memory-Alpha-et-cetera "{{disambig}}" feature, which seems unnecessary to me. (3) the general principles which defer to Wikipedia, because this wiki is not part of Wikipedia. (4) possibly something else. --Kernigh 20:24, 27 June 2006 (UTC)

I used {{disambig}} on Fire, which seems appropriate. Wikipedia isn't perfect, but I do think it is, in general, sane enough to be better than nothing. Please do feel free to modify this guide. I hesitated to call this a formal/official style guide, since this wiki is still young and doesn't need an excess of rules just yet. --Jayt 21:59, 28 June 2006 (UTC)

Actually {{disambig}} looks good for pages that need to be like redirects, but to more than one page. Like fire is now. Later maybe someone will write a longer document about fire, and it might not be a "{{disambig}}". Interestingly, there is also a Special:Disambiguations page, but I do not seem to understand it yet. --Kernigh 03:28, 29 June 2006 (UTC)

I added Template:otheruses a few days ago... it seems to be pretty useful. GreyKnight 05:11, 13 August 2006 (UTC)

Templates

Should the "name" section of a template include the item type? For example, potion of object detection lists "potion of object detection" as the item name, and scroll of genocide lists "genocide" as the item name. I'd prefer the latter because the item names can get pretty long and make the template table wide. --Eidolos 23:39, 13 August 2006 (UTC)

I'd prefer the latter too. Perhaps replacing "Name" with "Potion"/"Scroll"/"Wand"/etc. would help. --Jayt 17:43, 14 August 2006 (UTC)

Should "Cost" be renamed to "Base cost" or "Base price"? The internal field name (cost) can obviously stay, but should the output remain an unqualified "Cost"? --Eidolos 23:39, 13 August 2006 (UTC)

I see what you're saying. We don't want to get into the details of buying vs selling prices. Calling it "Base cost" should be enough of a prompt to make the reader think "Hmm, is cost not constant? Perhaps I should look for an article on cost". So yes, I think it should be renamed "Base cost".--Jayt 17:43, 14 August 2006 (UTC)

Or we could keep it as "cost" but make it a link, Cost. --ZeroOne 18:02, 14 August 2006 (UTC)

That too. I don't have a strong preference either way. Perhaps the number ("300zm"), which currently links to Zm, should link to Cost. I think the table would look funny with only one heading being a link. --Jayt 20:23, 14 August 2006 (UTC)

Yeah, that's an option too. Or we could make the rest of the headings links, too. --ZeroOne 20:31, 14 August 2006 (UTC)

[[Aleax]]es vs [[Aleax|Aleaxes]] vs redirect

I think the header says it all, really. [[Aleax]]es is the quickest to type, and is nicer to read in the source. On the other hand, [[Aleax|Aleaxes]] is nicer to read on the page. On the gripping hand, we could just create redirects every time we come across a situation like this. My personal preference is the second one ([[Aleax|Aleaxes]]), but what does everybody else think? GreyKnight 03:04, 19 August 2006 (UTC)

Uh, [[Aleax]]es looks just like [[Aleax|Aleaxes]] to the end user (without looking at the source, which is which? Aleaxes / Aleaxes). I'm all in favor of [[Aleax]]es over the other two. --Eidolos 04:21, 19 August 2006 (UTC)

Hmm, I see mediawiki automatically "gobbles up" the rest of the word in such a case... I hadn't known it did that, so I guess this invalidates that part of the question. GreyKnight 04:29, 19 August 2006 (UTC)

If we must have redirections, I'd only have them for monsters that pluralize with some modification to the base word (such as elf -> elves, or violet fungus -> violet fungi) so we don't have to use the pipe link form at all (just say [[elves]] and it'll redirect you to elf, BUT not for, say, [[quantum mechanics]]). But redirecting only a subset of the plural monster names could lead to problems and would be inconsistent. --Eidolos 04:21, 19 August 2006 (UTC)

May I be so bold to ask why singular names are preferred? It might be usefull to have a plural name when talking about the entire species and singular name when being specific. E.g Liches can be about all 4 liches and Lich about only the lowest L. Elf can be about the race, Elves about the enemy class. Not that it's really important, just got confused by this. --BlackShift 05:42, 29 August 2006 (UTC)

It's mostly a matter of convention, but one good reason for having singular article names is that if the article is at [[orc]], you can easily link to [[orc]] or [[orc]]s , but if the article is at [[orcs]], then you have to use [[orcs|orc]], or a redirect. Again, there's nothing wrong with redirects (other than creating more potential double redirects), but if we are going to choose between singular or plural (and we should, for consistency), then I think singular is best.

Of course there are some naturally plural articles: Liches and Elves might be good. If so, Lich should redirect to Liches as the whole point of Liches would be to collect all relevant information in one place. For the Elf race, we should have Elf (race). --Jayt 11:41, 29 August 2006 (UTC)

Variants

SLASH'EM (old section)

However, this is a NetHack wiki, so consider twice whether SLASH'EM-only articles are worth creating.

I think they are: (a) SLASH'EM is not just another roguelike or hacklike - it's a close fork, meaning code occasionally comes back to vanilla NetHack (the wizard patch being the major example) and this symbiotic relationship is acknowledged in the NetHack souce, (b) SLASH'EM is considered on-topic in RGRN, so why not here?, (c) people are going to add SLASH'EM articles anyway (it's already happened), so they may as well do it in a way that minimises the interference with vanilla articles. --Jayt 10:58, 1 September 2006 (UTC)

OK, as long as the emphasis is still on creating articles about vanilla NetHack. :) --ZeroOne 16:17, 1 September 2006 (UTC)

Yes, of course :-) This wiki's primary objective should be to document NetHack, and NetHack should always take priority when there is potential for confusion. --Jayt 16:04, 2 September 2006 (UTC)

2018 revisiting

12 years later, and the variant scene has exploded far beyond SLASH'EM. But the wiki still hasn't settled on an appropriate set of rules for handling all these variants. I swear that I've participated in some previous discussion on the subject, but I can't seem to find it either here or in IRC logs. Oh well.

To address the above discussion, yes, it's clear by now that the wiki is THE definitive source for NetHack-related information, more so than any one person writing up spoilers, and variants are not so separate from NetHack that their documentation needs to go live somewhere else. For the most part, this is fine since variant specific stuff can go on its own pages (e.g. Air dash), or if necessary "Foo (Variant X)" and "Foo (Variant Y)" pages, or have a bunch of pages as subpages of the variant like dNetHack does. The main issue is how to handle variant discussion of some thing on a vanilla page about that thing.

There are four offenders I've noticed, thankfully none of them very common:

1. Multiple variants change something and they all do so differently, so the page starts to obtain multiple level-two sections (with the == syntax) all describing how that variant changes something. The problem is that the table of contents quickly becomes unwieldy after even two variants have had their say.
2. A variant section grows out of control and becomes a substantial fraction of the page. A good example of this would be the SLASH'EM Valkyrie strategy guide, which up until recently lived on the Valkyrie page and was half as large as the vanilla one until it was chopped out into its own page.
3. Variant information is scattered into the regular sections of the article, either as subsections or sometimes as one-line sentences. This makes the information both easier to miss and more muddled for vanilla readers.
4. A variant makes a small or insubstantial change to something, and the page for that thing is given a variant section containing one sentence or barely relevant chunk of strategy which the page doesn't really need.

With that in mind, here's my proposal for dealing with variant information on vanilla pages (much of which is already followed, but we're talking about putting it in the style guide):

• If there is a substantial change made by the variant with a notable impact on strategy, then it's fair game to put on the page; if not, just put it on the main page for that variant.
• All variant information should go in a level-two ==Variants== section near the bottom of the page (but above the encyclopedia entry), which should be broken up into subsections for each relevant variant. Avoid having chunks of variant information in the main sections of the page, even if it seems to be organized better into those sections.
  • The one exception to this rule is if there is only one variant, in which case the level-two section can just be titled after that variant; e.g. ==SLASH'EM== or ==UnNetHack==. But if a second variant is ever added, both variants should become level-three sections under a Variants section.
• There should be no level-four or lower subsections, to keep the table of contents clean. If an editor feels that the variant section needs multiple subsections, then that may indicate that it's getting long enough to warrant its own page.
• Variant articles that have or are moved to their own pages can be linked from the main page in the top level ==Variants== section (that is, it doesn't need a whole subsection just for one link to the main page).

--Phol ende wodan (talk) 10:37, 18 August 2018 (UTC)

This seems to be the standard for several pages that have information on multiple variants, and should be on the style guide. Luxidream (talk) 14:02, 18 August 2018 (UTC)

I also completely agree. Admittedly I did it wrong in the early days of SLEX where I scattered SLEX-specific stuff into main articles, but if I stumble over that now, I'll move it in the variants section (and I also agree that there should only be one "Variants" section if an article mentions several) :) A bunch of SLEX-specific pages are in my userspace specifically to avoid clogging up the rest of the wiki, too. --Bluescreenofdeath (talk) 14:09, 18 August 2018 (UTC)

Added it to the style guide. --Phol ende wodan (talk) 17:47, 29 August 2018 (UTC)

Suggested new section - Internals

For source-divers, it can be useful to know which code macro/function is related to which function. This is not always clear – e.g. M2_STALK is the macro that determines whether monsters follow.

On the other hand, putting this in the main body of the article could be extremely distracting for the many wiki readers who do not source dive.

I have started adding an "Internals" section to provide such information, where I believe it may be useful. This helps source-divers reconcile the code to the spoilers without unduly distracting non-source-divers. This would be in addition to annotating the source itself.

I propose this is added to the style guide.

--Rogerb-on-NAO 20:51, 15 July 2008 (UTC)

agreed. -Tjr 22:31, February 19, 2010 (UTC)

{{subst:unsigned}}

Why does this say {{unsigned}} and {{unsigned2}} must be substituted? IMHO this makes the talk pages rather less readable; also there is no technical requirement (as in, without subst: they would not work) forcing them to be substituted (in fact, most uses of them I've observed don't use subst: for them, but still work fine; see also Special:WhatLinksHere/Template:Unsigned).

wikipedia:Wikipedia:Substitution mentions that templates in signatures (which seem similar to {{unsigned}} in a way, as it basically acts as a replacement signature) can cause server strain when updated; I don't know whether this applies to a wiki like NetHackWiki (which doesn't have nearly as many pages and users as Wikipedia), but I wonder why Template:Unsigned would need to be changed at all. --Bcode (talk) 03:53, 13 November 2012 (UTC)

These two Wikipedia articles say that they should always be substituted: Wikipedia:Template:Unsigned and Wikipedia:WP:UNSIGNED. I do not know the reasoning. --99.239.147.0 04:38, 13 November 2012 (UTC)

That's Wikipedia, though. What is valid for them might not apply here, which is why I ask here. (FWIW, the page about substitutions also seems to say it is debatable whether this template should be substituted. Obviously, current policy there is to substitute it, though.) --Bcode (talk) 04:44, 13 November 2012 (UTC)

sigs

are there any guidelines as to what may or may not be in a user's sig? i would say (and who am i?) that the purpose of a sig should be to discretely identify a user in a way that is useful to the reader. if a user were to, say, use colour in such a way that it obscured the text (picking as a random example black on dark purple) would there be any sanction? or if they included a dumb joke clever reference instead of their username would someone with authority object? i include some of the guidelines from Wikipedia, which some some editors think is pretty good.

When customizing your signature, please keep the following in mind: A distracting, confusing, or otherwise unsuitable signature may adversely affect other users. For example, some editors find that long formatting disrupts discourse on talk pages, or makes working in the edit window more difficult. Complicated signatures contain a lot of code ("markup") that is revealed in the edit window, and can take up unnecessary amounts of narrative space, which can make both reading and editing harder. The WMF's "Flow" project (which will replace the current Wikipedia talk page system) probably won't support custom signature formatting (details). Your signature must not blink, scroll, or otherwise inconvenience or annoy other editors.

• Avoid markup such as <big> and <font size="3">(or more) tags (which produce big text), or line breaks (<br /> tags), since they disrupt the way that surrounding text displays. The use of non-breaking spaces to ensure that the signature displays on one line is recommended.
• Be sparing with superscript or subscript. In some cases, this type of script can also affect the way that surrounding text is displayed.
• Do not make your signature so small that it is difficult to read.
• As some users have vision problems, be sparing with color. If you insist on using different colors in your signature, please ensure that the result will be readable by people with color blindness, defective color vision, and other visual disabilities.
• Do not include horizontal rules (----).

--194.116.198.185 13:21, 24 January 2014 (UTC)

Personally I'd go even further and ban colors and font tricks in sigs altogether. Also I don't get why you'd want to change your login name to some other text in your sig... --paxed (talk) 13:47, 24 January 2014 (UTC)

I agree with paxed in spirit. But I'm a bit reluctant to make a lot of rules that should be common sense. --Tjr (talk) 19:55, 24 January 2014 (UTC)

Oxford comma

Continuing the discussion on American versus British (international) English, I'm curious if there's a rule on the use of the Oxford comma on this wiki. I ask because I'm noticing a lot of people omit the comma (by the international convention) and I've already corrected it a few times as part of larger grammar correction edits. I ask because, while I'm not going to go out of my way to correct the omitted comma anyway, I think it could be annoying to other users if grammar edits continuously remove or replace a comma in an article.

It seems reasonable to me to assume that the American convention would be ideal, since NetHack is a game largely produced in America, but its international appeal brings this reasoning into question. I should point out that the Wikipedia style guide suggests that the Oxford comma be used or omitted on a case-by-case basis to avoid ambiguity. Any thoughts? Crawldragon (talk|nao|wiki) 16:33, 19 October 2014 (UTC)

I'd argue the Oxford comma as matter of style isn't something you'd need to "correct" either way, except to conform with style guidelines, the absence of which you did seem to correctly point out.

IMHO, it probably needs no special rule, either: keep it however it is in current articles unless adjusting it helps resolve ambiguity. It's not as if a little inconsistency here and there could ruin the world :) —bcode ^{talk | mail} 17:14, 19 October 2014 (UTC)

Beatitude vs "BUC status"

We have an English word "beatitude" that describes the blessed-ness of an object. Many places in the wiki use beatitude, many use "BUC status." There should perhaps be a consistent use? I would prefer the word, for several reasons:

1. "Beatitude" is an actual word, already present in our language.
2. "BUC status" is fairly cumbersome to both read and speak.
3. We might expand the vocabulary of people by one word if we use it more often.
4. "Beatitude" is a really cool word to use.

--lilmouse

Personally I vastly favor "beatitude" as well. As devil's advocate, there are two arguments in favor of BUC that I can see: first, the minor one that technically its definition only means blessedness, and could be ambiguous about curses; and second, the term "BUC-identified" is way more prevalent than anything else. "Beatitude-identified" is clunkier, "bknown" only makes sense if you source dive, "curse-tested" is ambiguous since it can mean just cursed/noncursed, and I can't think of any other contenders. I was recently making some edits to the BUC page and thinking if it would be worth it to move it to Beatitude and set up the redirect from BUC, but held off because the various BUC-identifieds in the page wouldn't have made that much sense otherwise.

Maybe that is the best thing to do, to swap the page and the redirect, and have the de facto standard be "beatitude" for most uses and "BUC-identified" where appropriate? (In a lot of cases a sentence containing it could probably be reworded anyway.) --Phol ende wodan (talk) 22:15, 17 August 2018 (UTC)

Gender style guidelines: "he or she" vs "they"

There are articles which sometimes fail to keep gender neutral language (often using "he"). We should specify either using "he or she" in all cases or use the singular "they."

Wikipedia does not have a preference (but does require using either "he or she" or "they" and not "he") - https://en.wikipedia.org/wiki/Wikipedia:Gender-neutral_language

I would prefer using "they"/etc.

1. It has a history of use as a singular gender neutral pronoun (as noted in https://www.merriam-webster.com/words-at-play/singular-nonbinary-they). (Given players in NetHack have either a masculine or feminine gender, using "they" as a non-binary pronoun isn't important to the game.)
2. It's widely used in modern language and easy for people to use.
3. It's a lot shorter to type than "he or she" and less cumbersome.