Help talk:Style

From ArchWiki
Jump to: navigation, search

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)

Application name capitalization

Which are the rules of capitalization of certain names? For LibreOffice there is no doubt, but for example is it 'bash' or 'Bash'? Probably the documented one is the preferable, so 'bash', 'Bash' when starts a sentence, aria2c everywhere. For zsh neither man pages are coherent. -- Flu (talk) 18:00, 19 May 2013 (UTC)

This topic is rather interesting: it's quite natural that we should follow the capitalization used in the upstream documentation, and this guide should probably mention it. I'd also like to remark whether the name should be always capitalized at the beginning of a sentence or not: honestly my position would be to still follow what the upstream documentation does.
In case the documentation is not coherent, I guess there's nothing we can suggest, except for being consistent throughout the article, _and_, if the application is mentioned in other articles, capitalization should be consistently based on the main article for that application (e.g. Bash).
Note that Bash is always capitalized in http://www.gnu.org/software/bash/
-- Kynikos (talk) 15:00, 22 May 2013 (UTC)
so Bash is written wrong in Help:Style#Shells, (lol, forgive me :) ) -- Flu (talk) 10:29, 3 June 2013 (UTC)
Ahah perfection is unreachable, you will always find something to report... Anyway in this case "bash" _would_be_ written "wrong" in Help:Style#Shells only if the above had already been enforced as a rule ;) (but I'll forgive you for this blunder, don't worry :P ) -- Kynikos (talk) 12:32, 3 June 2013 (UTC)
I like the way the Git project uses both "Git" and "git" in their documentation based on what the author is referring to. They use "Git" when talking about the project/software generally, and they use "git" when referring to the compiled program used when running commands [3]. This style makes it quite easy to know whether to use "Bash" or "bash", etc.
-- Jstjohn (talk) 02:42, 11 January 2014 (UTC)
That is certainly logical, with Help:Style/Formatting_and_Punctuation applied it would be "Git" (plain text, first letter uppercase) and "git" (italic, all lowercase). I believe that with proper context it would not be confusing, but for the controversial cases it's probably best to place a note with some explanation into the talk page, as it has been done for Btrfs: [4]. -- Lahwaacz (talk) 16:09, 31 January 2014 (UTC)
In my view Git makes its spelling convention look more complicated than it is: IMHO it just says "always use 'Git', except when talking about the executable, which is a lower-case filename and couldn't be run otherwise". Anyway we could indeed enforce such a convention, but only for applications that A) don't have an official or common capitalization convention and B) are commonly run through an executable that has the same name as the application itself. This would of course settle Bash and Btrfs cases though. -- Kynikos (talk) 04:50, 1 February 2014 (UTC)

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)

Prefer linking to the article than to the package

When mentioning an application, prefer linking to its article, if existing, rather than directly to the package. -- Kynikos (talk) 13:24, 28 May 2013 (UTC)

+1, apart from the standard "Download foo from the official repos" and similar. -- Karol (talk) 13:27, 28 May 2013 (UTC)

git/vcs/source builds

In some article there are source build instruction like Jumanji#Method_2:_From_Source and [5] or AUR git references like [6]. 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, [7], 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]] [8] 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: [9] (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 [10] 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: [11].
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 [12]? -- 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 [13]. – 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. [14] ;) -- 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 &mdash;), 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)

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: [15], [16]

-- 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)

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)

Formatting of references to man pages

[Moved from Help talk:Style/Formatting and punctuation#Formatting of references to man pages -- Kynikos (talk) 03:24, 29 June 2014 (UTC)]

How should references to manpages be formatted? Possible formats:

  1. pacman(8)
  2. pacman(8)
  3. pacman(8)
  4. .....see pacman manual.....
    or even maybe
  5. man 8 pacman

axper (talk) 16:53, 28 June 2014 (UTC)

Ok, let's standardize this, I think the clearest is "... see man pacman for details ...": the formatting complies with Help:Style/Formatting and Punctuation#CLI lines where it's already used as an example. I would leave the section number optional, it's quite rare that the same name is in two different sections, so we can recommend to specify it only in cases of ambiguity.
Let's read more opinions. -- Kynikos (talk) 03:34, 29 June 2014 (UTC)
I am ok with man pacman.
Pros:
  • Newbies who haven't encountered manpages yet (which I think is rare) can simply run the command and not wonder what pacman(8) is.
Cons:
  • It implies that manpages should be read via man. There are some great alternatives out there or may appear in the future. Of course users of these alternatives can run the equivalent command, but still.
Other thoughts: For popular manpage it's not very rare when one with same name is in different sections (crontab, man, intro, kill, link, locale, passwd, time, write, hostname). When a section isn't specified, this is the search priority:
  • 1 or 8 - executables or system executables
  • 3 - library calls
  • 2 - kernel calls
  • 5 - file formats
  • 4 - special files (/dev)
  • 6 - games
  • 7 - misc
So we should be a bit careful when not specifying the section number. Though this shouldn't be a problem as the author has probably ran the command himself and means the first one in the priority list.
EDIT: If the user is using one of the alternative viewers and section number isn't specified, that can cause problems for multi-section pages. axper (talk) 07:08, 29 June 2014 (UTC)
It is good to consider users with alternative viewers as you do, but using one is an explicit choice. Hence, it seems fair to imply the user knows how to use it as a man replacement. From the alternatives referencing the section in brackets only those having the section bracket outside the ic tag would be workable. However, we generally want to give the man reference prominence and for that a "see man passwd for options" is more prominent than a "see passwd(1) for options". That said, I'd personally like the non-ic version because it is a better textflow in my view. Plus the prominence the ic-tag gives is watered down the more it is used for peripheral commands.
For the reason you give regarding the author (the editor deciding whether man 5 passwd or man 1 passwd is referenced) it seems safe to leave it optional like Kynikos suggests.
To add another thought: In special cases it may even be helpful to reference it externally, e.g. like passwd's manpage, particularly when it can be assumed the user has no access to it yet on the system itself. For example: we frequently have man references in the article preface, but referencing a package's man page at that early point (before the installation section) is not particularly reader friendly. The problem with external links is of course consistency, i.e. there are too many outdated external references. But most editors are well aware of that, I'd say.
So, with the exception of special cases, I am +1 to Kynikos' suggestion if a rule is made, but like to add that I don't feel a need for it to be standardised. --Indigo (talk) 09:44, 29 June 2014 (UTC)
Good point Indigo, we can't assume the manpage's package is installed. I'd say we can allow two versions of references to manpages:
  • If the package is probably not installed, use "see pacman's manual for details" with the recommendation to prefer linking to the official web representation of the manpage, if available.
  • If the package is probably installed, use "see man 8 pacman for details", with the possibility to omit the section number when not ambiguous.
  • If the manpage is linked in a See also section, use the normal See also style instead (discussed in #Manpages in "See also" sections).
Do you like it? -- Kynikos (talk) 10:19, 30 June 2014 (UTC)
Oh, fine with me. Thanks for working it out. I particularly like the recommendation towards referencing official package's web manpages too; very beneficial for content overall & software rolling forward. --Indigo (talk) 18:14, 30 June 2014 (UTC)
This is one of the reasons why external links for man pages can be harmful - some distributions may provide patched packages including patched man pages. As Arch provides mostly vanilla packages, the link should lead to upstream's page, which should be the most up to date version (also third-party sites may become outdated after some time). Perhaps this should be mentioned as well. -- Lahwaacz (talk) 18:59, 16 August 2014 (UTC)

I think the prior style discussion conflicts with the philosophy behind the entire Package management instructions section. Man page usage, like pacman, AUR, and systemd usage, should be an essential skill picked up by every Arch user and shouldn't need to be described with explicit commands for every man page reference on every page. Explanations of man usage (including where to find man pages online) can be consolidated in the man page article, and references can link to that. I would advocate for a style like "see the passwd(1) man page". --Silverhammermba (talk) 19:59, 16 September 2014 (UTC)

You certainly have a point here, linking to man page would indeed be more consistent with our style philosophy, thanks for bringing this up.
Maybe my proposal above could be changed to:
  • In the article's body, use "see the pacman(8) man page", where the link is [[man page]]. In this case I think we should require the section number, and I'd avoid using italics because the number and the link should be enough to emphasize the reference.
  • If the manpage is officially maintained in an online version, it can be linked from the See also section, using the normal See also style (discussed in #Manpages in "See also" sections).
-- Kynikos (talk) 04:20, 18 September 2014 (UTC)
I saw that link to #Manpages in "See also" sections a few times in the prior discussion, but it doesn't go anywhere for me. Was that style discussion removed at some point?
Silverhammermba (talk) 15:24, 20 September 2014 (UTC)
Yep, closed & removed. Here is the permalink, found in the history of this talk page. -- Lahwaacz (talk) 19:57, 20 September 2014 (UTC)
I also agree to your reasoning & it is certainly a great idea to crosslink to man page in a number of articles, but I'd be against using it as a general style rule. I'd argue just because reading and interpreting man pages can be considered an essental skill, it is unnecessary to crosslink to man page in every man page reference of any article (excepting Arch beginner content, where we should use the crosslink often, yes). We don't crosslink every mention of systemd in the text either. "man pages" is a much too common term for it. I'd say it even is too general to consider crosslinking the first instance of it in an article.
A link itself is emphasized in the layout and I'd find that emphasis inapppropriate for crosslinking to 'essential skills' general knowledge - distracting from the content.
--Indigo (talk) 20:36, 20 September 2014 (UTC)

Another matter is linking to specific sections of man pages. In cases upstream provides an indexed page (like the i3 user guide) it's straightforward, but this is more exception than rule. See Midnight_Commander#Usage for a poor way to tackle this. -- Alad (talk) 11:07, 13 June 2015 (UTC)

Unfortunately many man2html converters don't generate the toc and the man sections don't even have an anchor to allow manual links to sections, so there is no other way than this "poor wording". -- Lahwaacz (talk) 13:29, 13 June 2015 (UTC)

Template

Wikipedia has a template for man pags: w:Template:Man. It also includes a list of upstream man page providers, which should handle the mentioned risk of distribution-specific man pages. I'd suggest to go with man7.org, as it includes specific references where the documentation was retrieved from, as well as a table of contents. -- Alad (talk) 16:21, 23 July 2016 (UTC)

See User:Alad/Installation_guide for what this would look like in practice. -- Alad (talk) 21:04, 23 July 2016 (UTC)
The new Template:Man also supports linking to man page sections. The numbers of man pages on man7.org is comparatively small (I've sent a request for including the man pages from pacman, netctl and mkinitcpio), but it should address most of the points raised above. Any further comments? -- Alad (talk) 12:19, 24 July 2016 (UTC)
Is using the Template:ic around the link necessary? It conflicts with Help:Style/Formatting_and_punctuation#Links and looks somewhat odd. -- Lahwaacz (talk) 19:02, 24 July 2016 (UTC)
Indeed, I think a plain link is just fine, other than that I'm ok for using it, even though in some cases html versions of the man pages are published and maintained by the upstream projects directly, e.g. pacman's, and this template wouldn't link to them.
If we get control of interwiki links with the dedicated extension, maybe this kind of shortcuts would be better handled that way rather than a template.
— Kynikos (talk) 22:09, 24 July 2016 (UTC)
Using code text is consistent with wikipedia, but I mainly did so to easily distinguish between wiki links and man pages links. It's a quick reminder that you can get the same manual text by typing man foo in a terminal (though it's true that the command text in the template can't be taken literally).
I do agree that using interwiki links eventually is the way going forward. -- Alad (talk) 22:16, 24 July 2016 (UTC)
With interwiki you would need 8 prefixes for each section and write something like [[man1:intro|intro(1)]], so I don't mind the single template... -- Lahwaacz (talk) 22:27, 24 July 2016 (UTC)
I proposed interwiki links as a way to keep it simple, since representing man pages with links like man1:intro (just [[man1:intro]]) would be just another equally meaningful convention than intro(1) in my view.
Anyway, regarding the template text formatting, if we really want to use monospace I suggest to at least style Template:Man like Template:Pkg, i.e. intro(1) (no background).
Kynikos (talk) 09:36, 26 July 2016 (UTC)
Added [17] -- Alad (talk) 10:00, 26 July 2016 (UTC)
How about adding a title text to the link with the appropriate man command. See [18] –– nl6720talk 08:26, 25 July 2016 (UTC)
Uh, smart, I like it :) — Kynikos (talk) 09:39, 26 July 2016 (UTC)
Added [19] -- Alad (talk) 10:00, 26 July 2016 (UTC)
Regarding edits like [20], I'm not sure (tendentially against) if it's ok to override the rule to always prefer linking to an internal article, e.g. replacing fdisk with fdisk(8). — Kynikos (talk) 09:47, 26 July 2016 (UTC)
The idea is that the Installation guide is one of the first pages a new Arch user sees, and reading the upstream documentation first may lead to more meaningful contributions to wiki articles (cf. [21]).
Secondary considerations are that man pages are a bit easier to access from the installation environment, and how some wiki articles like netctl have tangential content (this should be probably be fixed in those articles... others like fdisk and locale do much better on this regard).
An alternative could be to have a "dual" template which links to both article and man page. Not sure if this is desirable or even possible. -- Alad (talk) 10:11, 26 July 2016 (UTC)
I agree netctl is tangenial, but not en toto. In particular the beginning netctl#Installation (optional dependencies) is very important for anyone following the install guide. IMHO linking to its man pages in this case clearly makes it harder for new users.
I would not like a "dual" template. Even if possible, it probably gets as complicated to use as Template:App and would promote more uniform, disconnected content. It would disconnect the wiki content somewhat because it would suggest an article is meant as alternative to a man page - which is the opposite to what we want. I think it's better to continue using more and more direct crosslinks to sections and working towards them being unpiped; to get content on focus.
Other than that, I like this new template a lot; awesome! --Indigo (talk) 21:05, 26 July 2016 (UTC)
About the "dual" template, I too think it would be too complicated.
I think in general we should teach new readers our Help:Style#Hypertext metaphor, i.e. that they shouldn't expect to find everything they need on the same page, but they must learn to follow links to get information. In my view man pages should be linked from the most specific article that we have about that program, which could default to articles like Installation guide if we don't have a more specific article. I don't know if "reading the upstream documentation first may lead to more meaningful contributions to wiki articles", because the wiki article is bypassed in this way, which could give the impression that we don't rely too much on it.
Kynikos (talk) 09:08, 27 July 2016 (UTC)
Another point is how the installation guide looks in install.txt for Archiso; manual templates remain useful, while there is no difference between wiki links and plain text. See Talk:Installation_guide#Small_suggestion. -- Alad (talk) 20:10, 9 August 2016 (UTC)
We could also change the way install.txt is generated and create the difference ;) Lahwaacz (talk) 20:23, 9 August 2016 (UTC)
The 08.2016 ISO and those before it use lynx --dump, what would you suggest instead? -- Alad (talk) 11:14, 23 August 2016 (UTC)
We could take the plain wikicode instead, or add some grep/sed/awk magic to strip things like the categories and language links at the top or add fixed line length wrapping. After all, the installation guide should be one of the exemplary works regarding style, so the source should be nicely readable as well. -- Lahwaacz (talk) 14:44, 25 August 2016 (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: [22]. 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:

-- 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.
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:
--Indigo (talk) 18:28, 11 August 2014 (UTC)

Preferred subpage method

Options:

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_subpages2 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)

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.

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

(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 [23]: 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? --Dettalk 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)

Links to redirects

I'd like to recommend avoiding links like [[Xorg#Composite|AIGLX]] or [[daemons|daemon]] and promote linking to redirects, e.g. [[AIGLX]] or [[daemon]]: this would have the advantage of:

  1. making the source text simpler and easier to read
  2. keeping track of the particular "reason" why a link is made, also grouping the various links by "reason" in WhatLinksHere pages
  3. allowing quickly updating link fragments in case of section renames

We may even encourage to create redirects like those when the alternative text could be used somewhere else.

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

Exactly my thoughts, we've gotten too far in the "update link(s) (avoid redirect)" series of edits, which apparently set a bad example for others. Redirects are a feature and as such should not be avoided, except for the following cases (which I consider confusing):
  1. the titles differ only in capitalization
  2. the link is given in the 'Related articles' floating box
  3. two links to the same target are given next to each other, one of them goes over redirect
Also when a phrase See [[Some page]] for details. is used, it should be a direct link, but this is not very confusing and likely depends on context, sometimes redirects might be desired even in this case.
There are also some tricks to save writing the anchor text in some cases, see for example Help:Editing#Pipe trick. Then there is the following syntax: [[window manager]]s, which will result in window managers, but this can be solved also with a redirect. (off-topic: does Wiki Monkey support this?)
-- Lahwaacz (talk) 08:21, 12 July 2014 (UTC)
I agree with the exceptions. About See [[Some page]] for details., I'd still consider my points 2) and 3), and maybe at least don't explicitly list the case among the exceptions (we'll have to write this rule more as a recommendation than an obligation anyway, so the editors will be able to decide case by case). We could also recommend the pipe or the suffix trick over redirects when it's possible to use them. (OT: nope, #186 #188) -- Kynikos (talk) 07:21, 13 July 2014 (UTC)
Considering that some of these rules are already being enforced then perhaps they should be added (in some form) to the page instead of hiding them on the talk-page?
However, with redirects to sections being broken and no fix in sight, I would rather see explicit links to sections, i.e. [[Xorg#Composite|AIGLX]], being tolerated than to expect from the reader to figure out what the author meant when he placed the redirect to an article with a dozen sections, hundreds of lines and several thousand words. IMHO the cost of a slightly more verbose source is bearable in this case.
Namarrgon (talk) 00:12, 3 March 2016 (UTC)
I agree to Namarrgon's above comment. We need a note in Help:Reading and Help:Style about this asap. Apart from the bugs (server&client side), requiring JavaScript is a severe limitation. Does anyone know, if these section redirects are the only feature used in ArchWiki that requires it for browsing? If yes, I would vote for eliminating them all. edit: IMO the JavaScript requirement results in what the GDL calls "opaque" (see resulting arch-wiki-docs). -- Indigo (talk) 08:49, 3 March 2016 (UTC)
The bugs are indeed the reason why this recommendation has never made it into the main guidelines. Honestly in 2016 I wouldn't consider requiring JavaScript a "severe limitation" :) If I had to vote in a poll, I would still support using the redirects because IMO the 3 reasons I outlined in the OP outweigh the browsing issues that affect only a minority of users in those few cases when a JS-enabled browser isn't available. I don't see much room for compromises, maybe we really need a poll? — Kynikos (talk) 09:36, 3 March 2016 (UTC)
Well, with Chrome 48 and JS enabled it stopped working for me too... -- Alad (talk) 11:38, 3 March 2016 (UTC)
... same problem with epiphany (gnome-web/gnome-shell has JS enabled). I have added FS#48427, please vote for it. -- Indigo (talk) 12:45, 3 March 2016 (UTC)
Redirects to sections seem to work normally with the latest Chromium or Epiphany on Wikipedia, which has already upgraded to MediaWiki 1.27, try any link from w:Category:Redirects_to_sections. — Kynikos (talk) 04:37, 5 March 2016 (UTC)
Yes, I get the same results as you (tried chromium, epiphany), good news. Reading related info it seems to me all affected browsers are webkit based (which amount to ~50% browser base, unfortunately). I have added [24] for now (please adjust as you deem to). Many thanks to Lahwaacz, who sprinted to fix arch-wiki-docs. When I opened FS#48427, I was thinking we may simply point to the package as a work-around, but with Chrome et al affected that's clearly not enough. --Indigo (talk) 09:43, 5 March 2016 (UTC)
Thanks, I've reworded the notes because reloading the page doesn't seem to work on browsers that attempt to remember the scroll state. – Kynikos (talk) 02:50, 6 March 2016 (UTC)

Redirects to sections are affected by some bugs:

  1. It depends on some JavaScript code, which is a MediaWiki bug: phabricator:T53736
  2. Until MediaWiki 1.27, the JavaScript code responsible for redirects to sections behaves unreliably: phabricator:T110501. Consequently, some browsers will have trouble with opening the target page at the correct position: [25].

There is nothing we can really do about this, we can only wait for the fix(es) upstream.

-- Lahwaacz (talk) 18:05, 2 March 2016 (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:
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 [26]. 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: [27] vs. [28]

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: [29]

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 [30] for a simple example. Latter should be avoided, and flagged (for example [31]) 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: [32]

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.[33] -- Lahwaacz (talk) 21:46, 6 March 2016 (UTC)
+1. For [34] see also [35]. Another missing features example is [36]. 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)

Hypertext metaphor interpretation

Regarding [37], what is ok to duplicate and what not?

The relevant rules in Help:Style#Hypertext metaphor are:

  • Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
  • 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.

In my view, the first one refers to internal articles only, so it doesn't apply here. The second should be regulating duplication of external sources. Now, I don't think we can consider https://wiki.debian.org/VDR as the "upstream documentation" for VDR, so I think duplicating the article here could be allowed, as Debian's wiki article (even if written by the same author) can't be considered a more reliable — or better maintained — source than this one.

I've posted here because I want to discuss the interpretation of those rules in general, and possibly end up improving them to make their meaning clearer.

-- Kynikos (talk) 03:57, 21 August 2014 (UTC)

You are right that there is no rule to address the issue directly, hence my reply in Talk:VDR is probably an overstatement. Sometimes I link to Help:Style#Hypertext metaphor just so that the user gets the general idea.
To the interpretation of "Hypertext metaphor": IMV, "upstream/official documentation" in the second aforementioned rule can be "any external resource the editor is currently working with". For some projects, the notion of upstream/official documentation is pretty clear (e.g. i3 with their userguide), some projects have multiple high-quality "official documentations" (developers' blog posts, manpages, READMEs...), and some projects have none. In the last case it shouldn't matter if the source is hosted on some other distro's wiki or not, they should all have the same priority.
Regarding maintenance, VDR is not maintained since 2012, while Debian's article has a stable maintainer (probably the same person as User:Cdwijs). This could be a reason both for and against porting the Debian's article here, but maintaining a single article is surely easier than maintaining two.
It is also questionable if porting an article from MoinMoin (used by Debian's wiki) to MediaWiki syntax can be called a duplication, but I still think it is useless from the reader's point of view.
-- Lahwaacz (talk) 09:07, 21 August 2014 (UTC)

Sentences about non-existent articles contradict each-other

Here sentences contradict each other.

Help:Style#Hypertext_metaphor

Only link to a new article after creating it. In general, do not create links to non-existent articles.

Sentence forbids link to non-existent articles.

Help:Editing#Internal_links

You can add links to existing titles, and also to titles you think ought to exist in future.

Sentence encourages links to non-existent articles. - PiroXiline (talk) 18:57, 10 September 2016 (UTC)

Eagle eye, I think we just don't read Help:Editing anymore :D fixed. — Kynikos (talk) 01:42, 11 September 2016 (UTC)

Idea about interlinks

Yes please, it would help a lot if you withdrew this whole discussion to your talk page and only proposed small incremental changes one by one. – Kynikos (talk) 14:31, 23 September 2016 (UTC)
Moved to User_talk:PiroXiline#Idea_about_interlinks. – PiroXiline (talk) 00:26, 24 September 2016 (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)

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 [..]

Dettalk 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. —Dettalk 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)

Clarity of the article

Am I the only one who thinks this page is a big detail mess that's in a dire need of at least subheadings? It can't be that all those 1.1 - 1.26 have nothing in common, except that they are "Article pages". E.g. PKGBUILD is a good example of what would help me alot. --Dettalk 10:45, 13 September 2016 (UTC)

No, see #Better structuring. -- Lahwaacz (talk) 11:12, 13 September 2016 (UTC)

File editing requests

Help:Style#File_editing_requests mentions:

"Do not use implicit commands to request text file edits, unless strictly necessary. "

What does "strictly necessary" mean, exactly? Does e.g. Installation_guide#Configure_the_system fall under this or not? -- Alad (talk) 13:53, 13 September 2016 (UTC)

Worded like that it doesn't mean anything, but we can fix it here :)
Personally I'd always avoid redirection from echo, and let Help:Reading suggest it as a shortcut. However I think that "strictly necessary" covers the commands that are designed to be used with redirection, e.g. genfstab or wpa_passphrase. For this reason I'd replace:
Do not use implicit commands to request text file edits, unless strictly necessary. For example...
with:
Do not use echo redirections to request text file edits. For example...
Maybe at the bottom we can clarify that redirecting the output of other commands is fine.
Kynikos (talk) 10:24, 14 September 2016 (UTC)
That's too specific, there might be similar commands using tee, sed, nano, vim or any $EDITOR instead of echo. (I know, $EDITORs only open the file, but such commands occur nonetheless.)
Plus, there is a difference between editing ~/anything and /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor.
-- Lahwaacz (talk) 15:58, 14 September 2016 (UTC)
Indeed, but what is your position regarding the "strictly necessary" clause, and this rule in general?
About scaling_governor in CPU frequency scaling#Scaling governors, I'm coherent with my taste and I'd like to see:
Alternatively it is possible to activate a governor manually for each CPU by directly editing its name in the /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor files.
Then maybe that tee trick can be added in Help:Reading#Append, add, create, edit as an example to edit multiple files at the same time, so it's also useful for other articles.
For the moment, in reply to your comment this is my new proposal for the rule:
  • In general, do not use implicit commands to request text file edits. For example, $ echo -e "clear\nreset" >> ~/.bash_logout should be:
Append the following lines to ~/.bash_logout:
clear
reset
A common exception are commands whose output is specifically designed to be redirected to files, for example genfstab -U /mnt >> /mnt/etc/fstab.
Where it might be helpful, a link to Help:Reading#Append, add, create, edit can be added.
Kynikos (talk) 10:25, 15 September 2016 (UTC)
As for the scaling governors, "editing its name in ..." is wrong wording since there are only couple of valid values and anything else won't work. Also, if this error occurs, only echo and tee give meaningful warning (like echo: write error: Invalid argument), vim gives E667: Fsync failed and e.g. python gives nothing. So let's say that I just found an example for the "strictly necessary" clause :P
To your proposal: first of all, "implicit commands" should be "explicit commands". Another problem is that "output specifically designed to be redirected to files" is a catch-all term, it could be argued even for echo or cat. After all, redirection is one of the greatest unix features and everything is a file, even stdout and stderr.
I think that we don't like the echo et al. instructions because they don't generate any new output other than what the user gives them, so it makes no difference if the user writes the text into command line or an open editor. I propose to replace the exception clause in your new proposal above with the follwing:
A common exception are commands which involve generating a complex, system-specific output, for example genfstab -U /mnt >> /mnt/etc/fstab.
-- Lahwaacz (talk) 16:47, 22 September 2016 (UTC)
True about the errors.
About "implicit/explicit" it depends on how you see it: I use "implicit" because to me the "explicit" instruction is to edit a file; if you use a command to do it, the explicit instruction becomes to execute the command, which only implicitly edits the file. This is also the main reason why I consider this less educational than simply (explicitly) instructing to edit the file.
Nonetheless I like and agree with your explanation why "we don't like the echo et al.", and have no problems with using your exception clause in place of mine.
Kynikos (talk) 14:44, 23 September 2016 (UTC)