Help talk:Style

Read this first

Help:Style is an official document of the ArchWiki, and it is actively monitored for malicious, unapproved, or poor quality edits. This is necessary to ensure sufficient stability over time, since frequent, undiscussed changes to its rules would defeat the purpose of the guide itself.

It is probably needless to say that the active supervision of the article makes this very talk page the most important and effective place for discussing every possible improvement to the guide, from the correction of small typos to major changes like the introduction of new rules. Every report or discussion is welcome and will be answered as soon as possible. However, if an existing style rule is under dispute, its current state remains enforced until it is changed, if that ever happens.

This guide was born after several months of discussions among the administrators and the most active contributors at the time, and it is a compromise among their ideas and those of who has been contributing until now. While new ideas and proposals that are coherent with the guide will probably be accepted and implemented, it is also likely that the requests that aim to radically change the way a particular style issue is already addressed will be discarded. We all must acknowledge the fact that it is reasonably unrealistic to think that all the ArchWiki users will ever completely agree over all the style rules, that is why it becomes necessary that final decisions be made by the administrators: we hope that this concept will be peacefully accepted by everybody, so that we can all collaborate in a more constructive way.

Thank you for reading this notice and for contributing to the ArchWiki! -- The ArchWiki Administrators 21:27, 14 January 2012 (EST)

Tip: A way to speed up the addition or modification of style rules is to provide some text that, if approved, can be directly copy-pasted in the guide, just like patches work for bug reports.

Better structuring

IMHO, many parts of article can be safely moved to descriptions of corresponding templates. For example, information about Template:Keypress actually belongs to template itself rather than this style guidelines. I believe, most people look at template page before using it. What do you think? --AlexanderR (talk)

Actually this idea would overlap with a larger project I've had in mind for some time now: merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with. However I'd like to plan this carefully in advance, as it involves several pages, otherwise we risk increasing the mess instead of reducing it. -- Kynikos (talk) 10:04, 14 May 2012 (UTC)

> ..merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with.

Sounds good. Note, that moving part of current content to templates can reduce overall size of all involved articles and possibly simplify further work. --AlexanderR (talk)

See also #Help:Talk. -- Kynikos (talk) 16:11, 25 December 2012 (UTC)

I was wondering, why the style guidelines are kept in the Help: namespace? I think that ArchWiki: would suit the rules better, then Help: could be reserved for examples, recommendations and guides (not guidelines). -- Lahwaacz (talk) 20:30, 23 August 2014 (UTC)

But with that reasoning nothing would be left in Category:Help ^^ I know you're making the comparison with Wikipedia:Wikipedia:MoS, I'm not aware of Wikipedia's policy about the scope of the two namespaces (but I've seen many Wikipedia:... articles under the Help category there, either directly or under a descendant, while Category:Wikipedia seems to contain articles that talk about Wikipedia in an encyclopedic way, and they're not in the Wikipedia's namespace).

In our wiki, I think we tend to have a correspondence (or redundancy) between the Help and ArchWiki namespaces and categories: Help is more for articles that are meant to show editors the proper way to contribute (and so yes, for coherence I'd move ArchWiki:Contributing there instead), and ArchWiki is more for articles that are about the wiki itself (not Arch Linux), including the pages that are used by the staff to ease maintenance. Also note that Category:Help is a child of Category:ArchWiki.

In short, I'd leave Style where it is, and maybe I'd improve the correspondence between namespaces and categories, thus moving Table of contents under ArchWiki:, together with ArchWiki Translation Team, and then there are also some uncategorized titles in Special:PrefixIndex/ArchWiki:, we could consider categorizing them.

-- Kynikos (talk) 10:20, 25 August 2014 (UTC)

Related links

See also or Related in Article Summary?

I think we'd better be coherent whether to keep links, references etc. either in a "See also" section at the bottom of the article, or in one (or more) boxes under the Article Summary at the top right of the article.

See also #Article summary templates.

-- Kynikos 15:15, 21 September 2011 (EDT)

This is more a reminder than other, but I'm starting to like the idea of adding the rule to keep related ArchWiki articles in the Article Summary box only, and external links in See also sections only. Well, this way the "See also" default may even be changed (with bots, don't worry!) to a non-imperative, descriptive title like "Additional resources", "External links" or something like that. -- Kynikos 07:06, 14 December 2011 (EST)

Also remember that many external links in summaries can be found with Special:WhatLinksHere/Template:Article_summary_link. -- Kynikos 07:41, 24 January 2012 (EST)

Advantages of links in See also:

• There is more space for link descriptions
• It is likely one will read or skim the article before actively looking for additional reading material. This naturally leaves the reader at the end of the article. It is convenient for the reader in this case if links are at the end of the article. James Eder 00:29, 22 September 2011 (EDT)
• It seems more common (elsewhere) to have links at the end of articles (when they are not inline with the rest of the text). Following common convention it may be better from a usability perspective. James Eder 00:29, 22 September 2011 (EDT)

  Especially for people used to Wikipedia, which uses the same wiki software. Vadmium 11:12, 26 October 2011 (EDT).

• I am not sure how much we care about this but it having the links at the end could be more friendly to small form factor screens and screen readers. James Eder 00:29, 22 September 2011 (EDT)
• As a section, "See also" gets its own TOC entry granting easy access from near the top of the article. Alternatively one may press the END key. James Eder 00:29, 22 September 2011 (EDT)
• More formatting options here than in summary. Emiralle 13:12, 15 October 2011 (EDT)
• More inclined to put external, or less closely related stuff here. Emiralle 13:12, 15 October 2011 (EDT)
• See also section would not be skipped if you start reading the main text sequentially from the top. Vadmium.
• [add more advantages...]

Advantages of links in Article Summary:

• Immediately visible
• Beyond some minor editing inconvenience, is there any real disadvantage of having the most interesting links in both locations? It could be advantageous for the reader to have some links in both locations. James Eder 00:29, 22 September 2011 (EDT)
• I think putting very closely related links in the summary gives the topic more cohesion, and as James Eder said, they could be included at the bottom as well. Emiralle 13:12, 15 October 2011 (EDT)
• It would theoretically be more effective in preventing duplication of content within the wiki, as (unexperienced) editors would have a clearer view of the articles where related content could already exist (true especially with series (or "rings") of articles on the same subject). -- Kynikos (talk) 02:46, 29 September 2013 (UTC)
• [add more advantages...]

Lists

Inspired by [1], I was wondering if related links in "See also" sections or article summaries should be avoided if already present in the body of the article. I'd prefer having complete lists of related articles even if that implies duplicating some of them. -- Kynikos (talk) 11:09, 16 May 2012 (UTC)

> I'd prefer having complete lists of related articles even if that implies duplicating some of them

I'd prefer this way as well. Sadly listing all related articles may occupy most of vertical space, so there should be clear guidelines regarding choise of related links. And editors often don't have time to read even Help:Style... On the other hand, defining simple rule like "only links not present in text" can eliminate the very requirement for any additional rules. --AlexanderR (talk)

"only links not present in text" is too strict I think. Related links make some page more "visible" to readers. For example, I often click on them to learn more info about the same topic. But to be honest, I rarely click on the "in page links" even the links shown clearly in "See Also". They are much harder to be found and clicked. -- Fengchao (talk) 04:50, 19 May 2012 (UTC)

Definition

Inspired by [2], I was wondering if we needed a definition of what are the conditions under which an article can be considered related to another one. Honestly I can't think of something suitable at the moment, if somebody has good ideas, they're welcome here. -- Kynikos (talk) 11:09, 16 May 2012 (UTC)

Few ideas:

• Alternatives to software, described in article
• Methods and techniques alternative to ones described in article
• Software <-> it's use case
• software/technique <-> it's developer

--AlexanderR (talk)

List of Applications and See also

1. I suggest for lists like List_of_Applications/Multimedia to use capital letter for the first letter of the description, NO dots at the end (this behaviour seems to be preminent in Wikipedia) and to avoid totally articles ('A ..' is annoying). Is it ok?
2. In the same list it may be fair to put {{Grp|group}} beside items that have their one.
3. The See also section should be treated as above lists.

-- Flu (talk) 18:00, 19 May 2013 (UTC)

I support 1. and 2. except for the dots at the end of descriptions, which I would require instead, since sometimes the App template has long descriptions, even made of several sentences, and including all the puntuation only omitting the final dot would look weird to me.

About 3. I don't understand what you mean, can you be more specific?

However I'm also wondering if these rules should be hosted here (if they refer to the use of Template:App) or in Talk:List of Applications (if they refer only to List of Applications and subpages).

-- Kynikos (talk) 12:23, 26 May 2013 (UTC)

About 3: I just mean that a section like Aria2#See_also must have capitalized letters and no dots (or whatever the standard would be).

About the hosting place: page like CD_Burning#Burning_CDs_with_a_GUI or Conky#AUR_packages are not directly related to List of Applications, so I think it is worth to host a rule here. Plus this rule would apply also to any other list, like E4rat#Process --Flu (talk) 16:53, 26 May 2013 (UTC)

Still about 3: I see, usually See-also links have much shorter descriptions, in that case I would apply a no-dot policy. Still open to more opinions though.

Hosting place: a rule about lists of applications would probably best fit in Template:App, also in light of my plans to decentralize style rules in general. A rule about See also sections would instead fit this guide indeed, at least for the moment.

-- Kynikos (talk) 13:17, 28 May 2013 (UTC)

One link to the package in a paragraph is enough

Do we need multiple links to the same package, wiki article etc. in the same paragraph? I understand that if the article is very long, the links may be used in different sections, but isn't "In the past, Arch used SysVinit as the init process. Now on new installs, Systemd is used by default. Existing SysVinit users are recommended to switch to systemd." with 2 links to SysVinit and 2 links to systemd a bit too much? -- Karol (talk) 23:15, 21 May 2013 (UTC)

First thing, probably in the title you mean links to articles in general, not only packages, right?

However, I definitely agree, I guess we could extend the rule to the same section or even the whole article, but I'd like to exclude some cases, like "See also" sections (see #Lists of related links), and to make the rule compatible with Help:Style#Official packages and similar.

-- Kynikos (talk) 15:11, 22 May 2013 (UTC)

Just a reminder: this is affected by Help:Style/Formatting_and_Punctuation#First_instances, not sure if it sould be mentioned directly on Help:Style. -- Lahwaacz (talk) 16:35, 1 September 2013 (UTC)

git/vcs/source builds

In some article there are source build instruction like Jumanji#Method_2:_From_Source and [3] or AUR git references like [4]. I think they are pointless because:

• of course you can build application on your own, there is no need to say that.
• there is plenty of git/patched/vcs variants in AUR. One can decide to install them by their choice.

What about a rule to forbid git/source references unless they are the only chance?

(oh no, another time) -- Flu (talk) 21:15, 2 June 2013 (UTC)

IMHO 'make && make install' instructions should go.

I have nothing against describing different AUR packages, whether VCS or not. PKGBUILDs are sometimes pretty complex and it's not obvious what's the difference between the various AUR versions of a package - if any.

Please sign your talk page edits Help:Discussion#Join_a_discussion. -- Karol (talk) 20:21, 2 June 2013 (UTC)

Yes, manual compilation instructions can be removed, but only when an AUR package is available. A rule may be added for this.

No, please don't remove links to "alternative" versions of packages in AUR; treat every AUR package as the others, there are not AUR packages more "official" than others: if they all install the same application, they _can_ (i.e. not _must_) be mentioned in the same article.

-- Kynikos (talk) 05:05, 3 June 2013 (UTC)

Just mentioning a recent related example, [5], that I consider perfectly reasonable. -- Kynikos (talk) 08:10, 12 June 2013 (UTC)

Distinguish fragment identifier interwiki links?

Similarly to #Visited_links_color, can we distinguish fragment identifier interwiki links (those written as [[#foo]]) from other interwiki links (generally pointing to some other page)? I find something like [[#PolicyKit authorization|PolicyKit authorization]] [6] kind of confusing, it should be clear that the link points to a section on current page and not to separate page. Possibilities:

1. prefer [[#foo]] instead of [[#foo|foo]] - this does not solve something like [[#Run daemon|run the daemon]], also note that the fragment is case-sensitive
2. add some icon (superscript?) in front of/behind the link, I was thinking about the arrow shown in history pages (but without the link to the section)
3. use some other color

I'd vote for the second, it seems to be the most universal. Or does anybody have some other suggestion?

(Looking at the second link in this post, something similar could be done for links to Wikipedia. In this case, I propose adding superscript W behind the link.)

Sorry if this has already been discussed somewhere else, I don't have the time to search it right now.

-- Lahwaacz (talk) 19:41, 7 October 2013 (UTC)

Talking of distinguishing links, external https links are not distinguished either:

http

https

Perhaps a bug?

-- Lahwaacz (talk) 06:10, 10 October 2013 (UTC)

About the little icons next to links, I guess we could do it easily with CSS attribute selectors in the skin files.

About the https icon in particular, it looks it was disabled on purpose for some reason: [7] (line 67) I'd be curious to know why.

Of course to implement all this, a bug report should be opened and very likely patches should be prepared, so if you think you have the time to work on it, the project is at [8] with links to clone the repo. I'd be interested in giving a hand of course :)

-- Kynikos (talk) 09:53, 10 October 2013 (UTC)

Thanks for pointing me to the right direction, here's the commit about the https links: [9].

Let's see if I can get to this again this weekend...

-- Lahwaacz (talk) 15:05, 10 October 2013 (UTC)

I sent an email to Pierre about the commit in November and did not receive any reply, so I submitted a bug report: FS#38769 - hopefully it won't be missed. -- Lahwaacz (talk) 16:00, 2 February 2014 (UTC)

We'll see, I've submitted a patch, but unfortunately wiki bugs, even if easy to fix, have a long life... -- Kynikos (talk) 10:17, 3 February 2014 (UTC)

Interesting, the https links are now sometimes equipped with a lock icon. It seems that some domains are excluded by the following CSS (which I got with the help of Firebug):

#bodyContent a.external[href^="http://archlinux.org"],
#bodyContent a.external[href^="http://www.archlinux.org"],
#bodyContent a.external[href^="http://wiki.archlinux.org"],
#bodyContent a.external[href^="http://aur.archlinux.org"],
#bodyContent a.external[href^="http://bbs.archlinux.org"],
#bodyContent a.external[href^="http://bugs.archlinux.org"],
#bodyContent a.external[href^="https://archlinux.org"],
#bodyContent a.external[href^="https://www.archlinux.org"],
#bodyContent a.external[href^="https://wiki.archlinux.org"],
#bodyContent a.external[href^="https://aur.archlinux.org"],
#bodyContent a.external[href^="https://bbs.archlinux.org"],
#bodyContent a.external[href^="https://bugs.archlinux.org"] {
    background: none repeat scroll 0 0 rgba(0, 0, 0, 0);
    padding-right: 0;
}

Another interesting thing about this is that I could not find the snippet anywhere in the git...

-- Lahwaacz (talk) 08:44, 14 December 2014 (UTC)

Eheh maybe you should have looked at Special:RecentChanges :) (still working on it, this may have numerous applications/consequences) -- Kynikos (talk) 08:51, 14 December 2014 (UTC)

Well that is the last place I would search in, mystery solved. Thanks for testing the workaround, you surely got me on that one. -- Lahwaacz (talk) 09:35, 14 December 2014 (UTC)

Problem with keyboard keys style

I could use some help with Keyboard Shortcuts:

According to Help:Style#Keyboard_keys, Ctrl+Alt++ should be Ctrl+Alt++, but is that clear enough? (see Keyboard_Shortcuts#X11)

Also, what would be the preferred style for showing multiple shortcuts for some modifier combination?:

• Alt+.or_
• Ctrl+Alt++/-
• Ctrl+Alt+F1, F2, F3, ...

(note: someone used ⇑ Shift on that page, the arrow looks really funny :D )

Edit: the Ctrl+Alt++ shortcut was either dropped from X or is specific to NVIDIA, so I've removed it from the list of standard shortcuts. The only references I found were about 6 years old, the original is probably this.

-- Lahwaacz (talk) 22:22, 16 December 2013 (UTC)

(I don't wanna know where you've downloaded the font you're using with your browser... XD )

Oh well, even though Ctrl+Alt++ was (luckily?) outdated in that context, that's certainly a big flaw in the style rule... What do we want to do, switch to the Ctrl+Alt++ format? It would invalidate many of the style edits that have been done in the last months, but a bug is a bug ^^ Any better ideas?

About variable combinations, maybe we can just give some examples but leave the choice up to the editor?

-- Kynikos (talk) 13:48, 17 December 2013 (UTC)

I would not change the rule for just one shortcut (resp. two: Ctrl+Alt+-), converting it back would be really exhausting. If another instance appears, I'd create an exception for it. Or, even better, just link to an external documentation :P

Regarding the second problem I agree with leaving it up to the editor. Examples could be:

• press Alt+. or Alt+_
• press Ctrl+Alt+FN to switch to the N-th virtual console

i.e. basically use the full, expanded form or the pseudo-variables.

-- Lahwaacz (talk) 22:12, 18 December 2013 (UTC)

Well, let's just suspend this discussion until a similar problem is found again then, if ever. I'll think about closing it next time I'll come here to do some general clean up. -- Kynikos (talk) 10:25, 19 December 2013 (UTC)

Putting spaces around the + character would mitigate some of the confusion in the example Lahwaacz pointed out, but this would unfortunately require a lot of work to bring everything up to a new standard.

-- Jstjohn (talk) 02:32, 11 January 2014 (UTC)

Um... Ctrl + + doesn't look much clearer than Ctrl++ to me, if one day we'll need to change the rule for keys, we'll better do it the safest way, which probably is Ctrl++, since as you point out it's going to be "a lot of work" in any case. -- Kynikos (talk) 08:51, 12 January 2014 (UTC)

kbd tag

Huh, what about [10]? -- Lahwaacz (talk) 08:02, 10 August 2016 (UTC)

I remember discussing whether to favor the html rendering correctness to the detriment of wiki syntax Simplicity or vice versa, I think it was something about indentation, I don't have the time to search for the discussion but IIRC we decided to keep the wiki syntax simple and be less strict with the html output, so I endorse [11]. – Kynikos (talk) 11:27, 10 August 2016 (UTC)

Grammar errors throughout Help:Style

I've found a large amount of grammar errors throughout Help:Style, and it would be quite tedious to list a before and after for each one here in order to get them fixed. Would it be possible to either temporarily unlock Help:Style for editing (and closely monitor it for unauthorized changes), or if you don't want to unlock it for editing, should I just provide a pastebin with the revised wiki markup that you can copy/paste into the locked page? The downside to the latter option is that one really large change can be a pain to sort through in the history due to the lack of more verbose comments; although, if it's mostly simple grammar fixes, I guess this wouldn't be too big of a problem, as the change comments would likely be quite minimal.

-- Jstjohn (talk) 03:41, 11 January 2014 (UTC)

It would be awesome if you could fix those errors, it will also be a good chance for me to improve my English: the article is unlocked now. Just make sure not to alter the explicit and implicit meaning of rules, e.g. [12] ;) -- Kynikos (talk) 05:16, 12 January 2014 (UTC)

I have a general question: what are the rules for using mdash ("—") vs. ndash ("–") in English literature? Is there supposed to be a space around them or not?

(I did not intend to challenge your work, I'm just curious - the rule is very likely to be different from those used in Czech...)

-- Lahwaacz (talk) 20:57, 11 February 2014 (UTC)

There is not supposed to be a full space around the em dash ("—") or the en dash ("–"). Ideally, the em and en dashes will be surrounded with a hair space, which is just wide enough to put a one pixel space between the dash and the adjacent characters, which makes it easier to read because the dash doesn't look like it's part of an adjacent character. I did not put hair spaces in my edits because I generally find it tedious to do.

As for when you should use the em dash vs. the en dash... the em dash is used for large pauses in speech or for side notes — notice the hair spaces around these em dashes — and the en dash is used for numeric ranges (e.g. 47 – 83).

The hyphen looks similar to the en dash ( - –  ← hyphen on the left, en dash on the right), but the hyphen is only supposed to be used between certain compound adjectives and nouns.

There's also the minus sign ("−"), which looks very much like an en dash ( − –  ← minus sign on the left, en dash on the right). It should only be used in mathematical formulas or when writing negative values (e.g. 47 − 83 = −36)

If you haven't noticed, I'm a bit of a typography geek. haha

-- Jstjohn (talk) 02:02, 13 February 2014 (UTC)

Thanks for this nice explanation! It is a shame that the wiki markup language does not have special syntax for this punctuation, entering the HTML codes is really PITA. There are some packages for LaTeX that translate "--" into en dash and "---" into em dash. But typographically, TeX is on completely different level than wiki. -- Lahwaacz (talk) 08:08, 13 February 2014 (UTC)

We could possibly add MediaWiki templates for the em dash and en dash. Adding a template for the minus sign seems like it might be overkill. For example, {{emdash}} or {{em dash}} would output &.#8202;&.mdash;&.#8202; (without the dots, of course)

-- Jstjohn (talk) 23:59, 18 February 2014 (UTC)

I say let's keep it simple, who would use those templates in practice? They would also go against our decision to e.g. use typewriter quotes instead of typographic, see Help:Style/Formatting_and_Punctuation#Quote_marks. As Lahwaacz mentioned, a wiki is not TeX, it's designed to keep source and rendered text similar, and punctuation templates would reduce readability of source text. MediaWiki takes care of translating source text characters into HTML entities when needed, and in my view we shouldn't try to bypass such feature except when really needed (see also Help:Template#HTML_entities). If you want to use some particular punctuation marks, IMHO you should enter them directly, possibly assigning them as special combinations to your keyboard map. -- Kynikos (talk) 06:00, 19 February 2014 (UTC)

Regarding source text readability, why not just input the unicode character itself — like this? (Notice that it works also for the hair spaces, though they are not very "hairy" in the source...) -- Lahwaacz (talk) 07:01, 19 February 2014 (UTC)

I would use those templates. :)

I agree that {{em dash}} would be less readable than a directly-entered "—" character; however, {{em dash}} is a lot more readable than &.#8202;&.mdash;&.#8202; (without the dots), which is why I support the idea. I feel that directly-entered em dashes with the surrounding hair spaces (using the Unicode characters directly) is less maintainable than {{em dash}} because subsequent edits may remove one or both of the hair spaces without editors realizing that they did so.

-- Jstjohn (talk) 01:14, 20 February 2014 (UTC)

Ok, I admit that to me all this seems overly complicated as in not Simple, however, as Help:Style/Formatting_and_Punctuation#General_rules says, "for cases not covered in this guide, Wikipedia:Wikipedia:Manual of Style is the authority reference", and to me it seems very sensible to stick with that rule instead of attempting to create our own punctuation guides. In particular, Wikipedia:Wikipedia:Manual_of_Style#Punctuating_a_sentence_.28em_or_en_dashes.29 says "do not use spaced em dashes", while they do have a {{spaced ndash}} template, so IMO that's what we should follow. -- Kynikos (talk) 14:21, 20 February 2014 (UTC)

If we decide for the templates way, which subset of the Wikipedia formatting and function templates should be used on ArchWiki?

I don't like the templates either, this had better be solved upstream (either directly in the parser core or via an extenasion. The only mention of upstream dealing with this I found is this rather old discussion, so it's probably going nowhere. (Extending the parser should not be that hard, a couple of regular expressions should do it for the dashes -- I'm surprised that it's not done yet...)

Suggestions so far: 1) use HTML entities (such as —), 2) use templates (such as {{em dash}}), 3) use the Unicode characters directly, 4) use some extension (none found yet), 5) drop the typography rules completely (use plain spaced hyphen " - " or commas) -- this could be called "wait for upstream to implement the necessary change" :P

-- Lahwaacz (talk) 16:43, 20 February 2014 (UTC)

Well, as I've said I'm for 3), with the possible advice of setting key combinations for the most frequent cases (e.g. AltGr + -^{I'm aware of 1} for the em dash). Just out of curiosity, _personally_ I tend to use ~5) because in my native language all the cases where English requires dashes are covered by commas or parentheses, so I'll be seen rarely, if ever, using dashes in my contributions.

Even if there was an extension to parse "--" and "---", we'd still find resistance for having it installed in our wiki... Maybe upstream they're just waiting for your patch! ;)

About Wikipedia's "formatting and function" templates, for sure we're discarding the "function" ones, and about the others I'd say let's create them one at a time whenever one is needed, but only if method 3) and method 1), in that order, would require too much typing effort for that case.

For completeness' sake, there's also a suggestion 6) to use a (theoretical) external editor that turns "--" and "---" into proper dashes before sending the text to the server, and does the opposite when retrieving a page for editing.

-- Kynikos (talk) 14:38, 21 February 2014 (UTC)

A little note, the Colemak layout already comes with en dash and em dash respectively preset to AltGr+- and AltGr+Shift+-. -- Kynikos (talk) 13:49, 10 June 2014 (UTC)

References

Rule suggestion: reference links

First of all, sorry if there is already some similar rule about this, I don't know (yet) what I've forgotten since last year :/

The suggestion:

"When adding troubleshooting sections to new problems, always add reference links into the article, whenever such links are available."

(There is (at least) one implied meaning: "...and not just in the edit summary" :) )

These links will be mostly links to our bug tracker or the forums. The rule should probably include some examples.

The reason behind this is quite obvious: the users (and maintainers) will easily know if the problem is still valid or already fixed.

Finally, some reference links for completeness: [13], [14]

-- Lahwaacz (talk) 21:48, 11 February 2014 (UTC)

The style guide should be currently freely editable, even though discussing any changes beforehand is a must (so thank you for doing it). You can go ahead and add a few examples, with the only recommendation to be as synthetic as possible, in accordance with the rest of the guide. -- Kynikos (talk) 07:09, 12 February 2014 (UTC)

Citations and reasoning

Currently we have the following clauses on referencing content:

• Help:Style#Language register: Remember not only to answer how, but also why. Explanatory information always goes further toward imparting knowledge than does instruction alone.
• Help:Style#"Known issues" sections: If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.
• Help:Style#"Troubleshooting" sections: You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
• Help:Style#Hypertext metaphor: If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.

With an ever increasing number of edits, as well as the suggested deprecation of ArchWiki:Reports, I think it is time to revisit and generalize this topic. I see following issues with the present set of rules:

• It assumes editors already know how to properly create and explain content. While linking to bug reports indeed qualifies as a necessity (further motivated in Help:Style#"Troubleshooting") editors should understand to not blindly copy information contained within.
• The presence of an explanation is alone not enough, it should also provide a clear relation between cause and symptom of the issue at hand.
• The reference to upstream documentation should be more explicit; for example, only linking to it for "general information" does not imply the understanding needed to write Arch-specific adaptations.

Considering the scope of this rule I would consider a separate section; we can draft it below. Related discussion: ArchWiki_talk:Administrators#Cite_extension -- Alad (talk) 15:04, 7 June 2015 (UTC)

So, to put it in other words, is your proposal to aggregate all the bits from the 4 linked sections above into a unified section (I guess "Citations and reasoning" would also be the title you have in mind) and expand it with your last 3 points? I do support elaborating on this very important style issue, but wouldn't the new section overlap too much with Help:Style#Hypertext metaphor? Maybe we could more simply expand that, or split its items into subsections? Also I think that it still makes sense to keep reminding to link to bug reports directly in Help:Style#"Known issues" sections and Help:Style#"Troubleshooting" sections, so perhaps those sections should display a link to the new centralized guidelines.

If I haven't interpreted correctly what you had in mind, I'll wait for your initial draft below to understand better.

— Kynikos (talk) 03:03, 8 June 2015 (UTC)

For Troubleshooting, I propose to simply expand Help:Style#Hypertext metaphor with a paragraph on involving upstream, or invonvovled Arch projects. We've been encouraging this for some time, and it seems to works well enough. See below. -- Alad (talk) 20:26, 5 November 2015 (UTC)

It looks like I forgot what was written above ... -- Alad (talk) 20:30, 5 November 2015 (UTC)

Positioning of numbered external links

See Help talk:Style/Formatting and punctuation#Positioning of numbered external links.

Slashes in titles

Localized subpages

If FS#39668 is implemented, we should probably rethink the rule for localized subpages in Help:I18n#Article_titles. The problem is that with Title/Sub-page (Language) the breadcrumb links below the title will point to the English page instead of the localized one. Title (Language)/Sub-page makes more sense wrt file system hierarchy anyway, so I would do it anyway. Alternatively we may go the language namespaces way, which should also solve this problem. -- Lahwaacz (talk) 19:30, 4 April 2014 (UTC)

My original intention behind the Title/Sub-page (Language) style was to make it safer for Wiki Monkey to detect the language of an article by just looking at the end of the title, but I guess I might as well look for the tag anywhere in the title, and realistically it wouldn't give any troubles, so when FS#39668 is implemented we can indeed change the rule and rename the affected articles. The language namespaces way is still my long-term-preferred solution though. -- Kynikos (talk) 01:40, 5 April 2014 (UTC)

The Title (Language)/Sub-page format will not work with interlanguage links. See for example Help:Style/White space and its link to the Russian page. -- Lahwaacz (talk) 16:05, 30 August 2015 (UTC)

FS#39668 now status implemented. Closed by Doug Newgard (Scimmia) Sunday, 24 July 2016, 05:43 GMT. -- PiroXiline (talk) 17:14, 22 September 2016 (UTC)

Preferred subpage method

Options:

• Page/subpage (examples: Perl Background Rotation/Tips, List of applications/Utilities)
• Page - subpage (ex: Btrfs - Tips and tricks
• Page subpage (ex: GNOME tips, pacman tips)
• No subpages (using sections instead)

See also: #Slashes_in_titles --Alad (talk) 12:16, 2 July 2014 (UTC)

I think, current method (number one) is good. The third one is bad (for example, it's very bad for List of applications Utilities). You can add another method with colon symbol: Page:subpage. But I'm ok with the first one -- Kycok (talk) 07:56, 4 July 2014 (UTC)

As subpages are a feature of MediaWiki, the only way to have a full subpage experience is the first option. Unfortunately, it is currently disabled in the Main: namespace on Arch wiki (see #Slashes in titles). Until it is enabled, all options have equal weight, but using anything different than slashes does not make sense if we want to eventually switch to them. -- Lahwaacz (talk) 08:20, 4 July 2014 (UTC)

As Lahwaacz says, using the slash form is the way to go for forward compatibility, do we want to write a rule and already start changing the existing non-compliant titles (e.g. pacman tips)? The problem is that without the little navigation links under the title, it's not immediate to understand the meaning of the slash, especially for short titles, which at the moment look neater with a simple space. -- Kynikos (talk) 06:59, 5 July 2014 (UTC)

My vote goes for option #4 (using sections like Wikipedia):

1. Doesn't to pollute the "Related articles" column with number_of_subpages² lines (or equivalent) with added complexity of maintaining all that
2. Doesn't pollute the category pages
3. It's easier to find information (i.e. Ctrl+f or / or by looking at TOC)
4. No confusion caused by non-existent separator character
5. Is just simple. Remember KISS? :)

axper (talk) 16:08, 8 July 2014 (UTC)

OK, let's compare us to Wikipedia (see wikipedia:Wikipedia:Subpages for reference). Basically, it forbids using subpages in the Main: namespace. The history section states, that subpages were once used to create hierarchies of articles, but then it was superseded by categories and disambiguations. On Arch wiki, the hierarchy of categories was designed as a tree (although in practice with some "converging branches", see #Category pages - tree or otherwise?) and we don't use disambiguations at all. Unlike Wikipedia, so far this system works quite well on Arch wiki, which I think is mainly due to the type of content, amount of content and greater devotion and attention to detail of the Maintenance Team :)

Sometimes an article is too long to be kept on just one page, and the easiest solution is to split some section into a separate article, which will effectively create a subpage. I don't really see how this could be avoided without completely rewriting it, disambiguations or categories won't help here.

But I could agree that the usage of subpages should be regulated, for example PulseAudio/Troubleshooting would be good, while Kernels/Compilation/Traditional would be wrong (see the Wikipedia case). I don't know yet about Color Bash Prompt and something like Bash/Color prompt.

-- Lahwaacz (talk) 09:00, 9 July 2014 (UTC)

Well, solution #4 would be ideal, but in practice I think we can't really help splitting articles, both for length issues and because it's hard to understand when to stop merging articles back to their "parents". Take for example dm-crypt: it has several quite long subpages, would an article that merges all of them be clearer to read? I wouldn't see it as an improvement. And then why not merge dm-crypt and the others back to Disk encryption?

A subpage system is much more manageable, especially from the point of view of the maintainers, rather than the readers, so we just have to stick with it and make it as efficient and organized as possible.

@Lahwaacz How would you rename Kernels/Compilation/Traditional? Kernels/Compilation is the only child of Kernels (and currently only a redirect), so probably all those subpages could be moved to Kernels/Traditional compilation and so on. Maybe we could limit the depth of subpages to just 1 in general?

About Color Bash Prompt, I think its natural subpage version would be more Bash/Prompt color, or, considering the actual content of the article, Bash/Prompt customization (I think we're using the AE spelling everywhere, but that's something else that's not regulated yet), Bash/Prompt style or similar.

-- 09:57, 10 July 2014 (UTC)

Yes, Kernels/Traditional compilation looks good. About Color Bash Prompt, I think that "color" is either a verb (as in "colorize") or an adjective, so I used it the same. But your alternatives are better. -- Lahwaacz (talk) 12:21, 10 July 2014 (UTC)

Thanks, what about limiting the depth of subpages to 1? -- Kynikos (talk) 04:13, 12 July 2014 (UTC)

I wouldn't mind more levels, provided that the first/previous level is wide enough. -- Lahwaacz (talk) 08:49, 12 July 2014 (UTC)

Lists, colons, indentation

As a continuation of Block quotations, let's clarify our position to multi-line blocks inside lists and indentation (definition lists without definition terms). I have slightly mentioned this in the previous discussion, and I'd like to finish it here.

The markup lists are designed to be simple, and apparently are unsuitable for more complex lists, e.g. with multi-line blocks inside. Wikipedia says: "Do not use lists if a passage is read easily as plain paragraphs." I think that most of the "incorrectness" on Arch wiki comes from disobeying this quote. We should probably recommend using the lists only in simple cases, one or two paragraphs in each item at most (use <br> tags to separate them).

Other common case, unfortunately falling into the non-simple category regarding markup, is that a note or tip is presented inside a list. The "common" syntax has been

* some text
: {{Note|text to note}}

but I've recently seen a number of edits changing it to

* some text {{Note|text to note}}

which is something I don't like, because even though the latter renders correct HTML, it makes the wikitext unreadable. As much as we don't like it, definition lists without definition terms are a feature, and the MediaWiki's manual is full of such tricks. To achieve a fully correct HTML output only with markup syntax, we would need to fix the parser/renderer anyway, so I think we should focus more on wikitext readability.

The only way to achieve correct HTML, is to use HTML tags in wikitext, which brings me to the next problem: [15]. The edit clearly breaks the (future) rule "Do not use lists if a passage is read easily as plain paragraphs.", so the problem is reduced to usage of manual numbering - is it acceptable or do we tolerate HTML tags in such cases?

-- Lahwaacz (talk) 08:11, 29 June 2014 (UTC)

I agree, look at this page broken by a "Translateme" template inside a list. axper (talk) 08:30, 29 June 2014 (UTC)

I've used the * some text {{Note|text to note}} trick several times myself, but after reading Lahwaacz's reasoning I won't anymore (when I'll remember), as I agree completely: we should aim for the cleanest source text that results in the wanted appearance of the page. If the generated HTML is not correct it's indeed a problem of MediaWiki, we shouldn't try to work around it.

Yes, we should encourage preferring paragraphs or even subsections to lists with long/complex items. About ordered lists, manual numbering looks quite ugly to me, and I feel the same about mixing HTML and wiki markup: I think most (hopefully all) of the cases where it would be needed are better solved in some other way. For example in the QEMU case reported above, the items of that list don't need to be numbered, bullets or subsections should be used. Another notable example is Arch_packaging_standards#Submitting_packages_to_the_AUR, where bullet points would be more appropriate.

-- Kynikos (talk) 10:49, 30 June 2014 (UTC)

Maybe we can create a template for items? I mean something like this:

* First item
* Second item
* {{Template_name|
Third item

{{Note|bla-bla}}

Bla-bla-bla
}}
*Fourth item

And there will be a good readability of wikitext as well as correct indentations

-- Kycok (talk) 07:47, 4 July 2014 (UTC)

This still seems too complicated to me. -- Kynikos (talk) 06:15, 5 July 2014 (UTC)

I don't think such template is possible, the blank lines would still break the list (test it for Template:bc without <nowiki> tags). All the templates for lists on Wikipedia work the other way, template arguments are turned into list items. See for example wikipedia:Template:Ordered list, but it relies on Lua scripting, which is not available on Arch wiki. -- Lahwaacz (talk) 09:42, 5 July 2014 (UTC)

See also links

This is a low priority discussion, more of a reminder, however I'd like to recommend a unified style for external links in See also sections, because at the moment the various articles are inconsistent about that. These are some options:

• Arch Linux home page
• Arch Linux home page: https://www.archlinux.org/
• Arch Linux home page — https://www.archlinux.org/
• https://www.archlinux.org/ — Arch Linux home page

-- Kynikos (talk) 15:36, 1 July 2014 (UTC)

I vote for the first style. It's compact and IIRC already more popular than the other styles. axper (talk) 16:00, 1 July 2014 (UTC)

Agreed with axper, +1 to the first style. --Alad (talk) 18:28, 1 July 2014 (UTC)

I like the first style too. Also, I think this is how the Wikipedia does it. -- Karol (talk) 20:35, 1 July 2014 (UTC)

I'd prefer the first style too, but I forgot that links in See also section can be accompanied by descriptions, these are some examples of how the style can vary: Core utilities#See also, Secure Shell#See also, Systemd#See also, KDE#See also (funny), Xfce#See also, List of applications#See also. I haven't made up my mind yet. -- Kynikos (talk) 06:48, 5 July 2014 (UTC)

Meahwhile I've run into a non-standard section in Cursor Themes and I've changed it like this. -- Kynikos (talk) 03:01, 6 July 2014 (UTC)

+1 for the first style. Yet the examples show how useful a description can be, I vote for making it optional. Having an optional description behind the link looks much neater as well imo, rather than trying to use the link title to transport it in those cases.

Focussing on the links in Systemd#See also: some are indeed a little dated (already), but it would be a pity to loose them. I was wondering for a moment whether it would make sense to foster grouping them, e.g.

• systemd tips and tricks:
  • systemd FAQ
  • systemd tips and tricks
  • Fedora's SysVinit to systemd cheatsheet
• systemd project information:
  • Lennart's blog story - on the motivation to create systemd
  • ...
  • systemd status update 3 — (April 2012)

But then again there are few cases with that many links and the description can be useful/enough to transport that information too. Some sort of grouping happens automatically by editors keeping relevant links together and ordering most relevant (e.g. project home pages) first.

In my view the whole could be clarified by just appending some examples to Help:Style#.22See_also.22_sections ala:

Examples:

• Arch Linux home page
• man Xcursor — for more information about cursors in X (supported directories, formats, compatibility, etc.).
• systemd status update 3 — (April 2012)

--Indigo (talk) 18:28, 11 August 2014 (UTC)

OK to put category pages in related articles list?

Recently I made some edits which replaced links to multiple articles with a single link to a category page. That category page contains all those articles.

• Category:Hypervisors
• Category:Network managers

Are people OK with this? If so, maybe edit Help:Style#Related_articles_box here to instead say:

• Provides a simple list of related internal pages.
• Optionally included right below categories (or interlanguage links, or Article status templates, if present).
• It can only be made of Template:Related articles start, Template:Related and Template:Related articles end. See also the guidelines in those pages.
• Non-English pages can make use of Template:Related2 for translating the anchor text.
• Use the "See also" section for a more complete and detailed list that also includes link descriptions and interwiki or external links.

(change the word "article" to "page") axper (talk) 16:33, 10 July 2014 (UTC)

My first thought when reading this was "when the article is not included in the given category and it is still relevant, it should be included, otherwise not". On second thought, if the category is relevant enough, the article can be simple put into that category. The big problem is that related articles are at the top and related categories at the bottom.

We can either 1) leave pages at the top and categories at the bottom, 2) include every category into the 'Related articles' box at the top, 3) move the list of categories to the top (how?), 4) move the 'Related articles' box to the bottom (merge into 'See also' again).

Yep, so far I don't like either one of them for some reason or another...

-- Lahwaacz (talk) 19:25, 10 July 2014 (UTC)

About axper's proposed amendment, I agree, if a group of articles don't have a generic overview (e.g. unlike window managers), then linking to the category that groups them can be useful, if the edited article is not part of such category. Of course if the article itself is part of the category, there's the problem of duplicating the category link in the source text. This reminds me of an old idea of mine that I explained in [16]: translated to the "modern" wiki, it could mean replacing the normal categorization system with a Template:Category to be added to the Related articles box, when present, so that the article gets categorized under some categories, but their links are also shown somehow in the floated box. For example:

Current system

[[Category:Foo]]
[[Category:Bar]]
{{Related articles start}}
{{Related|link}}
{{Related articles end}}

Body

New system

{{Related articles start}}
{{Category|Foo}}
{{Category|Bar}}
{{Related|link}}
{{Related articles end}}

Body

-- Kynikos (talk) 04:33, 12 July 2014 (UTC)

The problem is that it involves more writing when there are no related articles (it is necessary to add {{Related articles start}} and {{Related articles end}} around the cats). Or would we use the current system for such pages? -- Lahwaacz (talk) 08:40, 12 July 2014 (UTC)

I was just brainstorming, I'm not sure, maybe we could start using the RA box on every article? Wiki Monkey should have all the libraries needed to automate the migration, both for articles with an RA box and for those without, so the "extra writing" disadvantage wouldn't really apply. -- Kynikos (talk) 05:24, 13 July 2014 (UTC)

Convention on added/removed text in Hc Templates

I just used the following way to clarify removed/added text in Nautilus#Use delete key to move to trash in Nautilus 3.6 and above:

~/.config/nautilus/accels

; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")

Is there already a policy on this? --Det^talk 23:29, 10 July 2014 (UTC)

Nope, there's no policy on that (yet?). Your version is certainly an improvement, compared to the previous -+ system, although in my opinion there's no need to add italic to the stricken line (keep it simple). What I think I've seen around more often, though, is a more verbose:

In ~/.config/nautilus/accels, replace:

; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")

with:

(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")

Your version has the advantage of using Template:hc, thus making it visually clearer that those lines are two versions of the same line, and belong to the same file. The "verbose" version has the advantage of giving clearer written instructions about what has to be done.

Replacing lines doesn't seem to be very frequent in articles, maybe standardizing this would be too much. If we decided to use the "stricken" version, it would probably be worth adding a note in Help:Reading#Append, create, edit and source.

-- Kynikos (talk) 15:30, 11 July 2014 (UTC)

I disagree with both of the previously suggested styles as neither explains what is changed and why. They're both barely better than telling someone to paste some sed command in their terminal as they rely on the current content of the file (which can change with updates) and they don't immediately convey what needs to be done. My preferred approach depends a lot on the context, but for this case I would do something like:

Create a shortcut to the action <Actions>/DirViewActions/Trash with the key Delete e.g.

~/.config/nautilus/accels

...
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
...

This is more broadly informative. If the keyboard shortcut format changes in some way or if the commented line is removed, it will still be clear what needs to be done. --Silverhammermba (talk) 17:28, 8 October 2014 (UTC)

Titles: singular or plural?

Currently we have daemons, List of applications, Category:Proxy servers... but also window manager, display manager, Category:Mail server... I'm for enforcing the plural version in all cases. -- Kynikos (talk) 07:26, 13 July 2014 (UTC)

I agree, plurals sound better, it's also how Wikipedia does it:

• Wikipedia:Wikipedia:Naming_conventions_(plurals)#Exceptions
• Wikipedia:Wikipedia:Category_names#General_conventions

axper (talk) 07:35, 13 July 2014 (UTC)

As there are no objections, let's try to implement this; the problem is that it's not easy to find a good formulation. For Help:Style#Title I was thinking of something like:

• By default, the topic name in titles should be in the singular form; it should be in the plural form if it represents a group or class of something and is a countable noun or perceived as such.

For Help:Style#Category pages:

• By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe one of its members ("set" categories).

Do you think they are clear enough? Alternatively we could just link to the Wikipedia conventions that Axper pasted above. -- Kynikos (talk) 02:40, 26 December 2014 (UTC)

I think that your formulation provides the general idea, Wikipedia could provide some examples and peculiarities.

Edit: OK, the peculiarities of Wikipedia may not be wanted, because they include disambiguation pages or focus on content not applicable to ArchWiki.

-- Lahwaacz (talk) 16:38, 26 December 2014 (UTC)

Thanks for the feedback, rules merged with [17]. I too think that linking to Wikipedia wouldn't add anything useful.

I guess we'll leave this discussion open as a reminder to mass-rename the non-compliant pages.

-- Kynikos (talk) 03:09, 27 December 2014 (UTC)

See also ArchWiki:Requests#Renaming_of_categories. -- Lahwaacz (talk) 19:40, 26 July 2015 (UTC)

Questionable edits

There are several kinds of questionable edits made almost regularly to the wiki. They are not breaking any rules (yet?), I just find them useless, counter-productive, or even annoying. I'd like to discuss them to see how others feel. Of course feel free to add a section of your own. -- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)

Underscores vs. slashes in kernel module names

Example: [18] vs. [19]

From modprobe(8): "there is no difference between _ and - in module names (automatic underscore conversion is performed)". Not only the naming is inconsistent across the wiki, this could lead to edit wars.

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)

Let's just pick one style and go with it. I vote for undescores, since that's how lsmod prints them, consistency would be nice.

I wouldn't consider these 2 edits questionable, rather it's lack of Help:Style rules about this particular subject.

axper (talk) 06:04, 10 August 2014 (UTC)

+1 for regulating this with underscores as per axper's lsmod argument. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)

Alphabetical order

Example: [20]

Unless in lists (such as List of applications), alphabetical sorting of sections or other items is useless, I'd even say wrong. Alphabetical sorting is good for finding things, but we have full-text searching nowadays. Even chronological sorting (assuming that new sections are added to the bottom) is more useful for Troubleshooting sections.

Also, have you ever read a book with chapters sorted alphabetically?

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)

I think as long as the sorted sections are equivalent (as in, alphabetical order does not break logical order), you could probably make an argument for both. Should a rule for chronological sorting be found useful, however, I wouldn't object to it. -- Alad (talk) 18:41, 9 August 2014 (UTC)

Yes, I'd expect a section about a new bug I am looking a solution for to be at the end of the article. axper (talk) 06:20, 10 August 2014 (UTC)

First, the example edit should have been split (i.e. one section moved at a time).

About the issue, I don't think that alphabetical order can make sense in Troubleshooting or Tips and tricks sections, since the first word of the headings is often incomparable (can be an article, a noun, etc.); chronological order would be better, for example a rule could recommend adding sections at the bottom (or top) of such section groups, unless some similar ones already exist, and in that case I guess keeping similar sections next to each other would be preferable.

-- Kynikos (talk) 09:13, 10 August 2014 (UTC)

+1, Lahwaacz is right. And one example for keeping similar sections next to each other: GNOME#Extensions -- Kycok (talk) 12:21, 20 August 2014 (UTC)

Concision

(without example)

Several times recently I was amazed as to how can be a concise article made even more concise. I think that we need more precision over concision. I think that the good wiki pages are usually verbose, as the topic is usually too complex to be described concisely. As tempting as it may be, having an expert making it more concise is not helpful for the majority of others.

-- Lahwaacz (talk) 17:12, 9 August 2014 (UTC)

I think there's a difference between concision in style and concision in content. Former is a matter of correct writing (convey information that helps understanding, not make it difficult); see [21] for a simple example. Latter should be avoided, and flagged (for example [22]) where appropriate. -- Alad (talk) 18:24, 9 August 2014 (UTC)

We can indeed put some recommendation like that in the guide, but this is something that the wiki staff will always have to keep an eye on, because experience is the only way to judge, case by case, what's too verbose and what's too concise. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)

Thanks for this hint. I've never recognized concision as a term and always associated it only with removing of content, either large parts or nuances that might have been intended by the previous editor. Although the language should be concise, let's not take it too far. And especially watch out for the nuances. -- Lahwaacz (talk) 14:08, 10 August 2014 (UTC)

"as of version X.XX..."

Example: [23]

For some reason users really want to put in when a feature was added to a program. I find this useless because an Arch system always uses the latest version. I think these comments are more appropriate for the talk page or even the user forums. For me the wiki shouldn't be a changelog. I do think it could be appropriate to use when its clear there are issues that are buggy and in progress, but once they are resolved, the note should be removed. Rdeckard (talk) 20:22, 6 March 2016 (UTC)

I agree that it is useless for features. But I think it is very important for bugs and perhaps even missing features.[24] -- Lahwaacz (talk) 21:46, 6 March 2016 (UTC)

+1. For [25] see also [26]. Another missing features example is [27]. Such is difficult to track for readers who may have encountered the issue in the past and, in this case, perhaps used a different boot loader just because of it. Perhaps one could say "as of notes" are less useful to keep for missing features in the "Installation" sections, but the further down in the article they are (e.g. in a "troubleshooting" section) the more useful they are for awareness of updates. --Indigo (talk) 09:48, 7 March 2016 (UTC)

Yes, to generalize, I'd say that "as of" notes are indeed useful next to information that is expected (or maybe reasonably wished/feared) to change in the future. Certainly, added features don't fall in that category, so I agree with the Core utilities, GDM and makepkg edits, but I would undo the Python edit, and, as noted by Indigo, check the SSH keys edit against Talk:SSH_keys#PuTTY_elliptic_curve_support. Since we are in the talk page of the style guide, is there a proposal for the addition of a new rule to discuss? — Kynikos (talk) 07:53, 8 March 2016 (UTC)

I think a possible style rule could be that adding edits about when changes to a program occurred is mostly appropriate when it's about a bug, or about a product in heavy development that's expected to change soon. Just listing off when features were added to a stable program adds noise and should be avoided. Rdeckard (talk) 02:24, 19 March 2016 (UTC)

(Welcome to the team, Rdeckard!). Yes, though, take the putty example: it's long a missing feature, putty is not really what one would call heavy development. When the feature finally hits stable, an "as of" might help (an ssh client is an application where I would expect a lot users prefer to use stable and wait). Maybe it is easier to suggest a time-period, i.e. "as of notices" older than (half) a year after a bug or missing feature (which has been tagged as such in the content) has been fixed can safely be removed because of the rolling repos Arch uses.

As for the place to put it: we actually have Help:Style#.22Known issues.22 sections in the guide, but it is rarely used - which is understandable in my view, because mentioning a bug where the related configuration or features are described makes sense. Question is whether we need this style section at all (then an "as of" addition could be added to it), or it should be removed entirely and integrated into the more commonly used Help:Style#.22Troubleshooting.22_sections. (+1)

--Indigo (talk) 07:26, 19 March 2016 (UTC)

Restarting this discussion because I just did a bunch of "as of" edits. It is a tricky issue because there definitely isn't a simple policy that always applies. That being said I think that most "as of"s should probably go. Here are the main use cases that I've observed:

1. noting when a feature was added/removed
2. noting when a default option was changed
3. noting when a bug was introduced/fixed
4. noting when the editor last verified the information (workaround was effective, desired feature was missing, etc.)

Number 4 is easy: "as of" is unnecessary. First of all it is redundant since the article history shows when the information was added (and thus verified). Secondly it adds very little value to the reader of the article. If I'm having a problem and a troubleshooting section has a potential solution it doesn't matter if it was working "as of" 100 years ago, I'm going to give it a shot (and then update the article if it no longer works). Lastly it encourages useless edits. If I see an old "as of" and check that it is still the case, does it really add value to the article if I just update the date to show that it still works? Where do we draw the line for that? Should we go around adding "as of" to every single thing that we verify as working? "As of March 3, 2017 sudo can be installed via sudo."

Number 3 is also easy: "as of" is unnecessary. In almost every case it is more useful to simply link to the bug report (ours or upstream). The obvious advantage being that upstream bug reports often include all the information the reader may want: when it was reported, what versions it affects, potential workarounds/solutions, if/when the bug was fixed, etc. Adding "as of" in this case is just sparing the reader an extra click, which goes against the hypertext metaphor.

Number 2 is a little tricky. If it is the case where the option change might require user intervention (e.g. a breaking change in config) then the "as of" is needed. However in most cases I've seen it is still not used well in the article. You'll see something like "As of version X the default is blah ...much later in the article... if you are upgrading from an older version, you may need to...". I think the "as of" is misplaced here: users who installed after the change likely don't care about the new default since they don't have to worry about breakage. In this case the "as of" should be placed in the later section dealing with the issue: "The default is blah ...much later in the article... if you are upgrading from version X, you may need to...". If the default change requires no intervention, I see no need for the "as of": users who run the default likely don't care and users who do not use the defaults are likely unaffected.

Number 1 is also difficult. I think feature removal is slightly easier because if the removal was an intentional design decision by the developers (i.e. not a bug) then the "as of" is not needed. Arch doesn't support users who want to keep old software around, so it is sufficient for the article to simply say that the feature was removed (not when). Because it was an upstream design decision, users reading the article can safely assume that the software will no longer support that feature. For feature addition I think the same logic as number 2 applies. If the new feature might change how upgrading users use the software it should be mentioned in the relevant section.

The only rule of thumb that I think applies in all of these cases is that often an editor adds an "as of" when there is actually something more specific they are trying to communicate: "as of X the default was changed so if you upgrade you have to...", "as of X this feature was removed so instead you may need to install...". By all means keep the the more specific information, ditch the "as of" if possible.

Silverhammermba (talk) 19:14, 3 March 2017 (UTC)

Very good. One comment: I think a regular case is that someone put a work-around/troubleshooting item into the wiki for a missing feature/default. Later the feature/default is added/changed. I think procedure should be to put a Template:Remove to the workaround first, so that users who might have implemented it get info. Then purge it later. (Obviously, there may be simple cases too.)

Two questions. 1: Do you think we should put a "as of" style suggestion with good/bad examples of usage into the style guide? If yes, where?

Question 2: Look at the above SSH keys#ECDSA example. Coincidentally, the referred to putty package finally gained the feature two weeks ago. How would you handle that, taking into account implementing the feature took a couple of years.

--Indigo (talk) 20:47, 3 March 2017 (UTC)

I think the "as of" there is needed, but again I think it is misused. Right now it is an example of case 4 i.e. "when I edited this article in March 2016 the feature wasn't there yet". This is redundant and not very useful. A much better "as of" would be to mention that ECDSA support has actually been in the development snapshot since November 2014! That is much more useful. Silverhammermba (talk) 23:19, 3 March 2017 (UTC)

I agree, somewhat. The "feature not there" info was useful in so far, as there will be users who configure their Arch openssh server (defaulting to ECDSA) but may latter want to connect via another platform's client (i.e. useful to avoid the pitfall with putty as a common client failing to support the server default). Of course it would have been even more useful with the development version info being merged over from the talk page, or the info moved/crosslinked from putty. But ok. My question was for the new status quo: How would you phrase it now, with the new stable version supporting ECDSA? Keep the note with an "as of putty 0.68 (Feb 2017) ECDSA is available", or simply drop it because it does not matter anymore? --Indigo (talk) 02:36, 4 March 2017 (UTC)

Putty is an exceptional case because there we have to deal with compatibility with other OSes (where the always up-to-date assumption does not apply). So the "as of" there is useful, again as long as it actually mentions when the feature was added.

Also, regarding "as of" in the style guide I think it sufficient to mention the two clear-cut cases: do not use "as of" if you are just noting the last time you personally checked something and do not use "as of" for bug reports, just link to the report itself.Silverhammermba (talk) 18:37, 4 March 2017 (UTC)

I've handled the Putty example with [28] and [29] I agree it could be done the other way too. --Indigo (talk) 21:29, 6 March 2017 (UTC)

Great write up above. I'm in agreement that we should tell users not to note the date, time, or program version in their edits if they are just telling us the last time everything worked for them. I also like the idea of encouraging users to link to bug reports instead of giving specific versions. We also need to use the "Known Issues" more often in our articles. -- Rdeckard (talk) 21:11, 4 March 2017 (UTC)

To make a start with mentioning "as of", I put in [30] and [31] (the latter addition may be a bit sublime). Perhaps you have an idea to make it more prominent or concise along above. --Indigo (talk) 21:29, 6 March 2017 (UTC)

File types

File types are formatted as per Help:Style#Code formatting, right?:

• Use {{ic|code}} for short lines of code, file names, command names, variable names and the like to be represented inline [..]

Does it need mentioning?:

• Use {{ic|code}} for short lines of code, file names and types, command names, variable names and the like to be represented inline [..]

〜Det^talk 00:36, 6 October 2015 (UTC)

There is Help:Style/Formatting_and_punctuation#File_extensions. Some reorganization and/or cross-referencing would be in order... Lahwaacz (talk) 06:20, 6 October 2015 (UTC)

I've missed that completely. I fixed my edit in Wayland. —Det^talk 23:38, 8 October 2015 (UTC)

Some style/grammar guidelines

I have noticed that most, but not all, articles follow these guidelines. I'm somewhat surprised that they are not mentioned here (maybe I just can't find them)? Anyway:

• Write in second person rather than third. For example "It is recommended that you do foo in order to enable bar on your system" is preferred over "It is recommended that users do foo in order to enable bar on their systems."
• If possible, do not "recommend" anything. Arch users are expected to read and understand instructions, not follow them blindly; everything on the wiki is implicitly "recommended" and can be ignored by savvy users. If a choice is involved simply explain why users might want to make a choice. So "If you need baz, do foo in order to enable bar on your system." is preferred over "It is recommended that you do foo in order to enable bar on your system". Recommendations are only needed in situations where the choice may be unclear and it is easy to choose poorly (and then a Template:Warning might be in order).
• Write in an active voice. For example "foo modifies bar" is preferred over "foo is used to modify bar".

Silverhammermba (talk) 20:13, 4 March 2016 (UTC)

Help:Style#Language register says: "Articles should be written using formal, professional, and concise language." It is certainly possible to make the writing formal and professional enough (at least for this wiki) using second or third person, but recommending to use one over another is too strong, because the best wording usually depends on context. If the whole page is already written in second person, the next modifications usually also use second person to blend in, and vice versa.

The text should be professional, but also feel natural. For example, the Linux Containers page excessively uses "users" to refer to the reader: "Users may use other programs to achieve the same results." Simply using "you" instead of "users" might look better, but I'd write "Other programs may be used to achieve the same results."

As for recommendations, there is nothing wrong with them - they only have to stay objective, expressing personal preference is not allowed (also as per the Language register). In your examples, "It is recommended that you do foo in order to enable bar on your system" would be fine if it was followed by an explanation of why it is recommended.

-- Lahwaacz (talk) 21:22, 4 March 2016 (UTC)

Actually Linux Containers contains a random mix of second and third person. At a glance you've got "Install the...", "Verify that...", "Users may...", "Users are..." "Disable the...". You even have weird sentences that combine them "For users already using netctl to manage an adapter, simply switch-to it" (I guess you're switching on behalf of the users?). I agree that certain situations require third person, but this is clearly a case of different authors following different writing styles, resulting in strange repeated switching of perspectives. Considering that this problem is present on a lot of articles and we both agree that each article should maintain a consistent perspective, there are a lot of edits to be done. I was just figuring that while we're doing all of these edits, why not make them all consistent across articles?

Let me try to better convey my point about recommendations. I agree that recommendations are fine as long as you explain why, but they are also usually unnecessary if you explain why. For example, Secure Shell says

It is also recommended to disable password logins entirely. This will greatly increase security.

That's fine, but it reads just as well like so:

Disabling password logins entirely greatly increases security.

Greatly increasing security is obviously good, so recommending it doesn't really add anything.

But still, there are certainly exceptions. I suppose that's the case with all of my suggestions: they aren't hard and fast rules, they're more like guidelines that should be kept in mind. If that's not the kind of stuff we want in the style guide, I understand.

Silverhammermba (talk) 06:52, 5 March 2016 (UTC)

In this case I have to say I generally tend to agree with Silverhammermba: IMHO adding guidelines on these issues would still help resolve possible (minor) edit wars in the future; of course they wouldn't mean that non-complying edits would be rejected, like with all the other rules, but if e.g. two users disagree about the way to phrase something, we have something to resolve the dispute.

About the first problem, though, I tend to prefer third-person or passive-voice writing, and if "Users may use other programs to achieve the same results." doesn't sound as good as when using "You...", I do think that "Other programs could be used to achieve the same results." would sound even better. But I wouldn't generalize, since for example most of the very rules in this guide are better put with an imperative (i.e. second-person) form. For this reason I'd propose to add, in Help:Style#Language register:

• When editing content, be consistent with the style used in the rest of the article. For example, if the reader is always addressed using the second person, this style should be adopted by the added content; the same goes if third person or passive voice are clearly dominant throughout the article.

And about recommendations, even though I'm surely guilty of giving many in my edits, I agree that a rule like the following could belong in the style guide:

• When offering a choice among different options (pieces of software, methods to do something, etc.) do not explicitly recommend one over the others, but objectively describe the advantages and disadvantages of each, thus helping the reader to make the best decision for his personal case.

— Kynikos (talk) 03:29, 6 March 2016 (UTC)

About "be consistent with the style...", in my experience w:Mirroring (psychology) is a strong phenomenon among editors, so I'm unsure if an explicit mention is needed in Help:Style.

About "objectively describe", +1 from me. -- Alad (talk) 03:56, 6 March 2016 (UTC)

Recommending mirroring would avoid the mixtures such as Linux Containers, but also conserve the (bad) style on other pages. Mirroring is a good fallback solution for situations when you have no idea, but I think the guidelines have to state what is right.

Also +1 for the second part about recommendations.

-- Lahwaacz (talk) 13:58, 6 March 2016 (UTC)

I remember writing this even when we were developing this page 5 years ago: this guide is only in theory aimed at teaching contributors what is the recommended style for the wiki; in practice, only a tiny minority of them reads any part of it, and it is indeed mirroring what accounts for the majority of the style-compliant edits (regarding any style rule, not only these ones). The real, practical aim of this guide is to solve disputes, as I said, and to give an official justification to the style-fixing edits made by the wiki staff and the other proactive users.

That is why explicitly defining what is good and what is wrong, whenever an issue is presented, is always pertinent here. I have added the two new clauses: perhaps that's not the most suitable section, if somebody wants to move them somewhere else, please go ahead, otherwise the next one who agrees can close the discussion :)

— Kynikos (talk) 03:20, 7 March 2016 (UTC)

Example usage

I recently removed a newly added example from Apple Keyboard ([32], [33], see also User_talk:Pypi#Apple_Keyboard). I generally prefer to avoid examples which I feel are covered elsewhere, since they can be prone to bit rot and linking to a page on the topic both encourages understanding and is more robust, however I can't find an "official" stand on this. Have I missed a section explaining proper usage of examples? If not, is there some other reasons for/against that kind of usage of examples? Would it be useful for the style guide to be adjusted to include some "rules of thumb" for dealing with examples? -- Pypi (talk) 21:17, 10 March 2017 (UTC)

You're right, we're not explicit about examples at the moment: I'd say currently the most related sections are Help:Style#Hypertext metaphor about content centralization, and Help:Style#Package management instructions/Help:Style#systemd units operations about examples only for those specific cases.

Help:Style#Hypertext metaphor allows (obviously) to write Arch-specific adaptations (examples?) of external generic documentation: by analogy (and coherence), this could be seen applicable to topic-specific adaptations (examples?) of instructions which are centrally (and generally) discussed in a "main" article. If we wrote a rule about examples, and perhaps we do need it, it should probably still be quite loose I think, and describe sort of a minimum level of complexity that the adaptation of generic instructions should have to be allowed in an article in addition to a link to the centralized article.

Regarding the specific reverted edit, I tend to agree with you, the example looked quite trivial, so I've tried to instead clarify the paragraph.

— Kynikos (talk) 07:48, 11 March 2017 (UTC)

Rule about optional dependency

Comment: A topic started in Talk:BackupPC, the contributor want to mention another optional dependency in the page. Should we define the rule about it? My opinion is that: Optional dependency should not be mentioned. Because it is hard to check and maintain in the wiki. Just read pacman log which is correct and current.--Fengchao (talk) 23:50, 22 October 2017 (UTC)

True, we'd better regulate this, but it can get tricky... For example we mention lots of optional packages in File manager functionality, maybe we can discourage simply systematically listing all optdepends but allow it if there's something more to say about them? I don't know right now... -- Kynikos (talk) 10:49, 24 October 2017 (UTC)

OK, I think we can put it as not recommended but not forbiding it. --Fengchao (talk) 02:03, 25 October 2017 (UTC)

Long form of uncommon command

We mention as a sub-point about shortening "prefer using the long form of uncommon command options instead of their single-character counterpart."

Then I see sometimes: use -p1 (or --parameter1) and -p2 (or --parameter2)... this easily become quite heavy. Should we mention that if the long form is used, the corresponding short form does not need to be indicated?

Kewl (talk) 20:16, 9 January 2018 (UTC)

The correct form should be "use -p1/--parameter1 and -p2/--parameter2...". See Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties.... -- nl6720 (talk) 09:33, 10 January 2018 (UTC)

Ok sounds good, I think both forms should be presented if it adds something, this is what Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... probably already means with the "have to". -- Kewl (talk) 11:10, 10 January 2018 (UTC)

Shall we regroup all the comments on parameters in the same section Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... i.e. moving the point about "prefer using the long form of uncommon command options instead of their single-character counterpart" into Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... ? I would also add if one form is provided long for uncommon or short for common, it is better to stick to it and it is not necessary to indicate all the possible spelling of an option. -- Kewl (talk) 19:12, 10 January 2018 (UTC)

Both forms should be presented if you explain the option itself, like in your example. Command line examples usually use short forms except for the uncommon options, but nothing actually forbids the use of long forms.

I don't think moving "prefer using the long form of uncommon command options instead of their single-character counterpart" to Help:Style/Formatting and punctuation would be correct, since it's not about formatting or punctuation. How about simply adding a link in Help:Style#Spelling to Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties.... E.g. "In the same fashion, prefer using the long form of uncommon command options instead of their single-character counterpart. See also Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties...". -- nl6720 (talk) 15:23, 11 January 2018 (UTC)

It is a good idea it would have helped to know there was also a point about it in Help:Style/Formatting and punctuation#Configuration parameters, variables, options, properties... -- Kewl (talk) 16:07, 11 January 2018 (UTC)

Done. -- nl6720 (talk) 10:03, 13 January 2018 (UTC)

Great, thanks -- Kewl (talk) 10:05, 13 January 2018 (UTC)

Thanks guys, do you think we can clarify in a few words when it's ok to represent both the short and long forms of a command option, and explicitly discourage from doing it by default? Or perhaps we should simply discourage it in general? -- Kynikos (talk) 14:37, 13 January 2018 (UTC)

Yes this was my initial idea I can't imagine cases where this adds much value and this is quite heavy to read. Common we use the short form, uncommon the long form and it is not recommended to indicate the different possible variations of an option nor to switch from one form to another across the page. -- Kewl (talk) 14:50, 13 January 2018 (UTC)

I see no need to discourage presenting both forms, it's not that much harder to read. I think this should be separated by usage:

• in text use both (e.g. "... use -v/--verbose for ...")
• in command line use short options unless they could cause confusion (e.g. efibootmgr -l and -L) and be consistent in using only long or short options

-- nl6720 (talk) 15:55, 13 January 2018 (UTC)

Transclusion

[Moved from User talk:Lahwaacz#Transclusion -- Kynikos (talk) 05:37, 15 April 2018 (UTC)]

Special:Diff/517439 "transclusion is useless and visual duplication confusing"

I guess this should be mentioned in Help:Style.

What about Special:Diff/516574? --Larivact (talk) 18:40, 14 April 2018 (UTC)

IIRC we discussed transclusion at least during the Beginners' Guide merge, and we discarded it in general for lack of arguments in favor of it when compared with simple linking. I'm in favor of adding a style rule to forbid transclusion with the obvious exception for templates. -- Kynikos (talk) 05:37, 15 April 2018 (UTC)

Avoid using redirects for anchor links on the same page

Case in point: Special:Diff/536203. I think that links to sections on the same page should be direct and I don't see any benefit to unnecessarily redirecting readers.

--Larivact (talk) 12:35, 24 August 2018 (UTC)

I agree. -- nl6720 (talk) 12:39, 24 August 2018 (UTC)

Me too, though I wouldn't complicate the rules in Help:Style#Hypertext metaphor even more. Fixing the script should be enough. -- Lahwaacz (talk) 12:44, 24 August 2018 (UTC)

The script should be fixed with [34], so I'll close this... -- Lahwaacz (talk) 07:27, 27 August 2018 (UTC)