Difference between revisions of "Help talk:Style"

From ArchWiki
Jump to: navigation, search
m (Implicit links: avoid repetition)
(Rule about optional dependency: Re.)
 
(870 intermediate revisions by 28 users not shown)
Line 1: Line 1:
'''Read this first'''
+
==Read this first==
:[[Help:Style]] is an official document of the ArchWiki, and is protected so that only users with administrator privileges can edit it. This is necessary to ensure sufficient stability over time, since frequent, undiscussed changes to its rules would defeat the purpose of the guide itself.
+
[[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 protection 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! -- [[ArchWiki:Administrators|The ArchWiki Administrators]] 21:27, 14 January 2012 (EST)
 
  
==Edit summary==
+
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.
See [[Help talk:Style/Edit summary]].
 
  
==Package installation==
+
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.
See [[Help talk:Style/Package installation]].
 
  
==Article summary templates==
+
Thank you for reading this notice and for contributing to the ArchWiki! -- [[ArchWiki:Administrators|The ArchWiki Administrators]] 21:27, 14 January 2012 (EST)
See [[Help talk:Style/Article summary templates]].
 
  
==Migration to new Code formatting templates==
+
{{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.}}
See [[Help talk:Style/Migration to new Code formatting templates]].
+
__TOC__
 +
== 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? --[[User:AlexanderR|AlexanderR]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk: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. --[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
 +
:See also [[#Help:Talk]]. -- [[User:Kynikos|Kynikos]] ([[User 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). -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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.
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk: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]].
 +
 
 +
-- [[User:Kynikos|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. -- [[User:Kynikos|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]]. -- [[User:Kynikos|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. [[User:James Eder|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. [[User:James Eder|James Eder]] 00:29, 22 September 2011 (EDT)
 +
*:Especially for people used to Wikipedia, which uses the same wiki software. [[User:Vadmium|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. [[User:James Eder|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.  [[User:James Eder|James Eder]] 00:29, 22 September 2011 (EDT)
 +
*More formatting options here than in summary. [[User:Emiralle|Emiralle]] 13:12, 15 October 2011 (EDT)
 +
*More inclined to put external, or less closely related stuff here. [[User:Emiralle|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. [[User:Vadmium|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. [[User:James Eder|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. [[User:Emiralle|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). -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 02:46, 29 September 2013 (UTC)
 +
*''[add more advantages...]''
 +
 
 +
=== Lists ===
 +
Inspired by [https://wiki.archlinux.org/index.php?title=Sound_system&curid=10626&diff=201543&oldid=197917], 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. -- [[User:Kynikos|Kynikos]] ([[User talk: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. --[[User:AlexanderR|AlexanderR]] ([[User talk: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.  -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 04:50, 19 May 2012 (UTC)
 +
 
 +
=== Definition ===
 +
Inspired by [https://wiki.archlinux.org/index.php?title=Boot_Debugging&diff=prev&oldid=201554], 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. -- [[User:Kynikos|Kynikos]] ([[User talk: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
 +
:--[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
 +
 
 +
==List of Applications and See also==
 +
# 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?
 +
# In the same list it may be fair to put <nowiki>{{Grp|group}}</nowiki> beside items that have their one.
 +
# The '''See also''' section should be treated as above lists.
 +
 
 +
-- [[User:Flu|Flu]] ([[User talk: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).
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk: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]] --[[User:Flu|Flu]] ([[User talk: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.
 +
:::-- [[User:Kynikos|Kynikos]] ([[User talk: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 "[[Arch_Boot_Process#Init_process|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? -- [[User:Karol|Karol]] ([[User talk: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.
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk: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]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:35, 1 September 2013 (UTC)
 +
 
 +
== git/vcs/source builds ==
 +
 
 +
In some article there are source build instruction like [[Jumanji#Method_2:_From_Source]] and [https://wiki.archlinux.org/index.php?title=Logitech_Unifying_Receive&direction=prev&oldid=260677#From_AUR] or AUR git references like [https://wiki.archlinux.org/index.php?title=Bumblebee&oldid=259841#Installation]. 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) -- [[User:Flu|Flu]] ([[User talk: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]]. -- [[User:Karol|Karol]] ([[User talk: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.
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:05, 3 June 2013 (UTC)
 +
::Just mentioning a recent related example, [https://wiki.archlinux.org/index.php?title=Isync&diff=262333&oldid=253631], that I consider perfectly reasonable. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:10, 12 June 2013 (UTC)
 +
 
 +
== Distinguish fragment identifier interwiki links? ==
 +
 
 +
Similarly to [[#Visited_links_color]], can we distinguish [[Wikipedia:Fragment identifier|fragment identifier]] interwiki links (those written as {{ic|<nowiki>[[#foo]]</nowiki>}}) from other interwiki links (generally pointing to some other page)? I find something like {{ic|<nowiki>[[#PolicyKit authorization|PolicyKit authorization]]</nowiki>}} [https://wiki.archlinux.org/index.php?title=Libvirt&diff=next&oldid=274533] kind of confusing, it should be clear that the link points to a section on current page and not to separate page. Possibilities:
 +
 
 +
# prefer {{ic|<nowiki>[[#foo]]</nowiki>}} instead of {{ic|<nowiki>[[#foo|foo]]</nowiki>}} - this does not solve something like {{ic|<nowiki>[[#Run daemon|run the daemon]]</nowiki>}}, also note that the fragment is case-sensitive
 +
# add some icon (superscript?) in front of/behind the link, I was thinking about the arrow shown in [https://wiki.archlinux.org/index.php?title=Help_talk:Style&action=history history pages] (but without the link to the section)
 +
# 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 {{ic|W}} behind the link.)
 +
 
 +
Sorry if this has already been discussed somewhere else, I don't have the time to search it right now.
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 7 October 2013 (UTC)
 +
 
 +
:Talking of distinguishing links, external https links are not distinguished either:
 +
::[http://foobar.org http]
 +
::[https://foobar.org https]
 +
:Perhaps a bug?
 +
: -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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: [https://projects.archlinux.org/vhosts/wiki.archlinux.org.git/tree/skins/archlinux/arch.css] (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 [https://projects.archlinux.org/vhosts/wiki.archlinux.org.git/] with links to clone the repo. I'd be interested in giving a hand of course :)
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:53, 10 October 2013 (UTC)
 +
 
 +
:::Thanks for pointing me to the right direction, here's the commit about the https links: [https://projects.archlinux.org/vhosts/wiki.archlinux.org.git/commit/skins/archlinux/archlinux.css?id=e8b7a08c663a0fb392a24c67ec1dea59057f480a].
 +
:::Let's see if I can get to this again this weekend...
 +
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:05, 10 October 2013 (UTC)
 +
 
 +
::::I sent an email to [[User:Pierre|Pierre]] about the commit in November and did not receive any reply, so I submitted a bug report: {{Bug|38769}} - hopefully it won't be missed. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 [https://bugs.archlinux.org/task/35545 long life]... -- [[User:Kynikos|Kynikos]] ([[User talk: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): {{bc|<nowiki>
 +
#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;
 +
}
 +
</nowiki>}}
 +
::::::Another interesting thing about this is that I could not find the snippet anywhere in the [https://projects.archlinux.org/vhosts/wiki.archlinux.org.git/ git]...
 +
::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:51, 14 December 2014 (UTC)
 +
 
 +
::::::::Well that is the last place I would search in, mystery solved. Thanks for testing the [[MediaWiki:Archlinux.css|workaround]], you surely got me on that one. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:35, 14 December 2014 (UTC)
 +
 
 +
== Problem with keyboard keys style ==
 +
 
 +
I could use some help with [[Keyboard Shortcuts]]:
 +
 
 +
<s>According to [[Help:Style#Keyboard_keys]], {{ic|Ctrl}}+{{ic|Alt}}+{{ic|+}} should be {{ic|Ctrl+Alt++}}, but is that clear enough? (see [[Keyboard_Shortcuts#X11]])</s>
 +
 
 +
Also, what would be the preferred style for showing multiple shortcuts for some modifier combination?:
 +
 
 +
* {{ic|Alt}}+{{ic|.}}or{{ic|_}}
 +
* {{ic|Ctrl}}+{{ic|Alt}}+{{ic|+}}/{{ic|-}}
 +
* {{ic|Ctrl}}+{{ic|Alt}}+{{ic|F1}}, {{ic|F2}}, {{ic|F3}}, ...
 +
 
 +
(note: someone used {{ic|&uArr; Shift}} on that page, the arrow looks really funny :D )
 +
 
 +
'''Edit:''' the {{ic|Ctrl+Alt++}} shortcut was either dropped from X or is specific to NVIDIA, so I've [https://wiki.archlinux.org/index.php?title=Keyboard_Shortcuts&diff=288958&oldid=288082 removed it] from the list of standard shortcuts. The only references I found were about 6 years old, the original is probably [http://ubuntuforums.org/showthread.php?t=83973 this].
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 {{ic|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 {{ic|Ctrl}}+{{ic|Alt}}+{{ic|+}} 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?
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:48, 17 December 2013 (UTC)
 +
 
 +
::I would not change the rule for just one shortcut (resp. two: {{ic|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 {{ic|Alt+.}} or {{ic|Alt+_}}
 +
::* press {{ic|Ctrl+Alt+F''N''}} to switch to the {{ic|''N''}}-th virtual console
 +
::i.e. basically use the full, expanded form or the [[Help:Style/Formatting_and_Punctuation#Pseudo-variables_in_file.2Fcommand_line_contents|pseudo-variables]].
 +
::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:25, 19 December 2013 (UTC)
 +
 
 +
::::Putting spaces around the {{ic|+}} 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.
 +
::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 02:32, 11 January 2014 (UTC)
 +
 
 +
:::::Um... {{ic|Ctrl + +}} doesn't look much clearer than {{ic|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 {{ic|Ctrl}}+{{ic|+}}, since as you point out it's going to be "a lot of work" in any case. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:51, 12 January 2014 (UTC)
 +
 
 +
=== kbd tag ===
 +
 
 +
Huh, what about [https://wiki.archlinux.org/index.php?title=Kernel_parameters&diff=next&oldid=445462]? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 [https://wiki.archlinux.org/index.php?title=Kernel_parameters&diff=next&oldid=446131]. – [[User:Kynikos|Kynikos]] ([[User talk: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.
 +
 
 +
-- [[User:Jstjohn|Jstjohn]] ([[User talk: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. [https://wiki.archlinux.org/index.php?title=Help:Style&diff=178056&oldid=178055] ;) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:16, 12 January 2014 (UTC)
 +
 
 +
:I have a general question: what are the rules for using mdash ("&mdash;") vs. ndash ("&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...)
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:57, 11 February 2014 (UTC)
 +
 
 +
::There is not supposed to be a ''full'' space around the em dash ("&mdash;") or the en dash ("&ndash;"). Ideally, the [https://en.wikipedia.org/wiki/Space_(punctuation)#Hair_spaces_around_dashes 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&#8202;&mdash;&#8202;notice the hair spaces around these em dashes&#8202;&mdash;&#8202;and the en dash is used for numeric ranges (e.g. 47&#8202;&ndash;&#8202;83).
 +
::The hyphen looks similar to the en dash (&nbsp;- &ndash;&nbsp;&nbsp;&larr; 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 ("&minus;"), which looks very much like an en dash (&nbsp;&minus; &ndash;&nbsp;&nbsp;&larr; 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 &minus; 83 = &minus;36)
 +
::If you haven't noticed, I'm a bit of a typography geek. haha
 +
::-- [[User:Jstjohn|Jstjohn]] ([[User talk: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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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, <nowiki>{{emdash}}</nowiki> or <nowiki>{{em dash}}</nowiki> would output {{ic|&.#8202;&.mdash;&.#8202;}} (without the dots, of course)
 +
::::-- [[User:Jstjohn|Jstjohn]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk: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...) -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:01, 19 February 2014 (UTC)
 +
 
 +
::::::I would use those templates. :)
 +
::::::I agree that <nowiki>{{em dash}}</nowiki> would be less readable than a directly-entered "—" character; however, <nowiki>{{em dash}}</nowiki> is a ''lot'' more readable than {{ic|&.#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 <nowiki>{{em dash}}</nowiki> because subsequent edits may remove one or both of the hair spaces without editors realizing that they did so.
 +
::::::-- [[User:Jstjohn|Jstjohn]] ([[User talk: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 <nowiki>{{spaced ndash}}</nowiki> template, so IMO that's what we should follow. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:21, 20 February 2014 (UTC)
 +
 
 +
::::::::If we decide for the templates way, which subset of the [[Wikipedia:Category:Wikipedia_formatting_and_function_templates|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 [https://meta.wikimedia.org/wiki/MediaWiki_feature_request_and_bug_report_discussion/Archive#.22Incorrect.22_quotes 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 {{ic|&amp;mdash;}}), 2) use templates (such as {{ic|<nowiki>{{em dash}}</nowiki>}}), 3) use the Unicode characters directly, 4) use some extension (none found yet), 5) drop the typography rules completely (use plain spaced hyphen "{{ic| - }}" or commas) -- this could be called "wait for upstream to implement the necessary change" :P
 +
::::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. {{ic|AltGr}} + {{ic|-}}<sup>I'm aware of [[#Problem_with_keyboard_keys_style|1]]</sup> 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.
 +
:::::::::-- [[User:Kynikos|Kynikos]] ([[User talk: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 {{ic|AltGr+-}} and {{ic|AltGr+Shift+-}}. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:49, 10 June 2014 (UTC)
 +
 
 +
== References ==
 +
 
 +
=== Rule suggestion: reference links ===
 +
 
 +
First of all, sorry if there is already some similar rule about this, I don't know (yet) what I've forgotten since last year :/
 +
 
 +
The suggestion:
 +
:"When adding troubleshooting sections to new problems, always add reference links into the article, whenever such links are available."
 +
 
 +
(There is (at least) one implied meaning: "...and not just in the edit summary" :) )
 +
 
 +
These links will be mostly links to our [https://bugs.archlinux.org/ bug tracker] or the [https://bbs.archlinux.org/ 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: [https://wiki.archlinux.org/index.php?title=Chromium&diff=296005&oldid=295185], [https://wiki.archlinux.org/index.php?title=MPlayer&diff=296894&oldid=296809]
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:09, 12 February 2014 (UTC)
 +
 
 +
=== Citations and reasoning ===
 +
 
 +
Currently we have the following clauses on referencing content:
 +
* [[Help:Style#Language register]]: Remember not only to answer how, but also why. Explanatory information always goes further toward imparting knowledge than does instruction alone.
 +
* [[Help:Style#"Known issues" sections]]: If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.
 +
* [[Help:Style#"Troubleshooting" sections]]: You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
 +
* [[Help:Style#Hypertext metaphor]]: If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
 +
With an ever increasing number of edits, as well as the [[ArchWiki_talk:Maintenance_Team#Reorganization|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]]
 +
-- [[User:Alad|Alad]] ([[User talk: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.
 +
:— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:03, 8 June 2015 (UTC)
 +
 
 +
::<s>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.</s> -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:26, 5 November 2015 (UTC)
 +
 
 +
::It looks like I forgot what was written above ... -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:30, 5 November 2015 (UTC)
 +
 
 +
=== Positioning of numbered external links ===
 +
 
 +
See [[Help talk:Style/Formatting and punctuation#Positioning of numbered external links]].
 +
 
 +
== Slashes in titles ==
 +
 
 +
=== Localized subpages ===
 +
 
 +
If {{Bug|39668}} is implemented, we should probably rethink the rule for localized subpages in [[Help:I18n#Article_titles]]. The problem is that with {{ic|Title/Sub-page (Language)}} the breadcrumb links below the title will point to the English page instead of the localized one. {{ic|Title (Language)/Sub-page}} makes more sense wrt file system hierarchy anyway, so I would do it anyway. Alternatively we may go the [[Help_talk:I18n#Language_namespace.28s.29_in_place_of_suffixes.3F|language namespaces]] way, which should also solve this problem. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:30, 4 April 2014 (UTC)
 +
 
 +
:My original intention behind the {{ic|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 {{Bug|39668}} is implemented we can indeed change the rule and rename the affected articles. The [[Help_talk:I18n#Language_namespace.28s.29_in_place_of_suffixes.3F|language namespaces]] way is still my long-term-preferred solution though. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 01:40, 5 April 2014 (UTC)
 +
 
 +
::The {{ic|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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:05, 30 August 2015 (UTC)
 +
 
 +
:::{{Bug|39668}} now status implemented. Closed by Doug Newgard (Scimmia) Sunday, 24 July 2016, 05:43 GMT. -- [[User:PiroXiline|PiroXiline]] ([[User talk:PiroXiline|talk]]) 17:14, 22 September 2016 (UTC)
 +
 
 +
=== Preferred subpage method ===
 +
 
 +
Options:
 +
 
 +
* Page/subpage (examples: [[Perl Background Rotation/Tips]], [[List of applications/Utilities]])
 +
* Page - subpage (ex: [[Btrfs - Tips and tricks]]
 +
* Page subpage (ex: [[GNOME tips]], [[pacman tips]])
 +
* No subpages (using sections instead)
 +
 
 +
See also: [[#Slashes_in_titles]] --[[User:Alad|Alad]] ([[User talk: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 -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 07:56, 4 July 2014 (UTC)
 +
 
 +
::As [[mw:Help:Subpages|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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:59, 5 July 2014 (UTC)
 +
 
 +
::::My vote goes for option #4 (using sections like Wikipedia):
 +
::::# Doesn't to pollute the "Related articles" column with number_of_subpages<sup>2</sup> lines (or equivalent) with added complexity of maintaining all that
 +
::::# Doesn't pollute the category pages
 +
::::# It's easier to find information (i.e. {{ic|Ctrl+f}} or {{ic|/}} or by looking at TOC)
 +
::::# No confusion caused by non-existent separator character
 +
::::# Is just simple. Remember KISS? :)
 +
::::[[User:Axper|axper]] ([[User talk: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 [https://wiki.archlinux.org/index.php?title=Help_talk:Style&oldid=324150#Category_pages_-_tree_or_otherwise.3F #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 [[ArchWiki:Maintenance Team|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]].
 +
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 [https://wiki.archlinux.org/index.php?title=Special%3APrefixIndex&prefix=Kernels%2F&namespace=0 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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:21, 10 July 2014 (UTC)
 +
 
 +
::::::::Thanks, what about limiting the depth of subpages to 1? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:13, 12 July 2014 (UTC)
 +
 
 +
:::::::::I wouldn't mind more levels, provided that the first/previous level is wide enough. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:49, 12 July 2014 (UTC)
 +
 
 +
== Lists, colons, indentation ==
 +
 
 +
As a continuation of [https://wiki.archlinux.org/index.php?title=Help_talk:Style&oldid=316593#Block_quotations 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:Wikipedia:Manual_of_Style/Lists#Bulleted_and_numbered_lists|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 &lt;br> tags to separate them).
 +
 
 +
Other common case, unfortunately falling into the non-simple category regarding markup, is that a [[template:note|note]] or [[template:tip|tip]] is presented inside a list. The "common" syntax has been
 +
{{bc|<nowiki>
 +
* some text
 +
: {{Note|text to note}}
 +
</nowiki>}}
 +
but I've recently seen a number of edits changing it to
 +
{{bc|<nowiki>* some text {{Note|text to note}}</nowiki>}}
 +
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 [[mw:Help:Lists|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: [https://wiki.archlinux.org/index.php?title=QEMU&diff=next&oldid=321689]. 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?
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:11, 29 June 2014 (UTC)
 +
 
 +
:I agree, look at [https://wiki.archlinux.org/index.php?title=Compiz_%28Espa%C3%B1ol%29&oldid=273960 this page broken by a "Translateme" template inside a list]. [[User:Axper|axper]] ([[User talk:Axper|talk]]) 08:30, 29 June 2014 (UTC)
 +
 
 +
::I've used the {{ic|<nowiki>* some text {{Note|text to note}}</nowiki>}} trick several times myself, but after reading Lahwaacz's reasoning I won't anymore <small><small>(when I'll remember)</small></small>, 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.
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:49, 30 June 2014 (UTC)
 +
 
 +
:Maybe we can create a template for items? I mean something like this:
 +
:{{bc|<nowiki>* First item
 +
* Second item
 +
* {{Template_name|
 +
Third item
 +
 
 +
{{Note|bla-bla}}
 +
 
 +
Bla-bla-bla
 +
}}
 +
*Fourth item
 +
</nowiki>}}
 +
:And there will be a good readability of wikitext as well as correct indentations
 +
:-- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 07:47, 4 July 2014 (UTC)
 +
 
 +
::This still seems too complicated to me. -- [[User:Kynikos|Kynikos]] ([[User talk: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 &lt;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 [[mw:Extension:Scribunto|Lua scripting]], which is not available on Arch wiki. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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:
 +
 
 +
* [https://www.archlinux.org/ Arch Linux home page]
 +
* Arch Linux home page: https://www.archlinux.org/
 +
* Arch Linux home page — https://www.archlinux.org/
 +
* https://www.archlinux.org/ — Arch Linux home page
 +
 
 +
-- [[User:Kynikos|Kynikos]] ([[User talk: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. [[User:Axper|axper]] ([[User talk:Axper|talk]]) 16:00, 1 July 2014 (UTC)
 +
 
 +
::Agreed with axper, +1 to the first style. --[[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:28, 1 July 2014 (UTC)
 +
 
 +
:::I like the first style too. Also, I think this is how the Wikipedia does it. -- [[User:Karol|Karol]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk: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 [https://wiki.archlinux.org/index.php?title=Cursor_Themes&diff=323541&oldid=323304 like this]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:01, 6 July 2014 (UTC)
 +
 
 +
:::::+1 for the first style. Yet the examples show how useful a description can be, I vote for making it optional. Having an optional description behind the link looks much neater as well imo, rather than trying to use the link title to transport it in those cases.
 +
:::::Focussing on the links in [[Systemd#See also]]: some are indeed a little dated (already), but it would be a pity to loose them. I was wondering for a moment whether it would make sense to foster grouping them, e.g.
 +
::::::* systemd tips and tricks:
 +
::::::** [http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions systemd FAQ]
 +
::::::** [http://www.freedesktop.org/wiki/Software/systemd/TipsAndTricks systemd tips and tricks]
 +
::::::** [http://fedoraproject.org/wiki/SysVinit_to_Systemd_Cheatsheet Fedora's SysVinit to systemd cheatsheet]
 +
::::::* systemd project information:
 +
::::::** [http://0pointer.de/blog/projects/systemd.html Lennart's blog story] - on the motivation to create systemd
 +
::::::** ...
 +
::::::** [http://0pointer.de/blog/projects/systemd-update-3.html systemd status update 3] — (April 2012)
 +
:::::But then again there are few cases with that many links and the description can be useful/enough to transport that information too. Some sort of grouping happens automatically by editors keeping relevant links together and ordering most relevant (e.g. project home pages) first.
 +
:::::In my view the whole could be clarified by just appending some examples to [[Help:Style#.22See_also.22_sections]] ala:
 +
::::::Examples:
 +
::::::* [https://www.archlinux.org/ Arch Linux home page]
 +
::::::* [http://www.x.org/releases/current/doc/man/man3/Xcursor.3.xhtml man Xcursor] — for more information about cursors in X (supported directories, formats, compatibility, etc.).
 +
::::::* [http://0pointer.de/blog/projects/systemd-update-3.html systemd status update 3] — (April 2012)
 +
:::::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:28, 11 August 2014 (UTC)
 +
 
 +
== OK to put category pages in related articles list? ==
 +
 
 +
Recently I made some edits which replaced links to multiple articles with a single link to a category page. That category page contains all those articles.
 +
* [[:Category:Hypervisors]]
 +
* [[:Category:Network managers]]
 +
 
 +
Are people OK with this? If so, maybe edit [[Help:Style#Related_articles_box]] here to instead say:
 +
 
 +
{{META Box||
 +
* Provides a simple list of related internal pages.
 +
* Optionally included right below categories (or interlanguage links, or Article status templates, if present).
 +
* It can only be made of [[Template:Related articles start]], [[Template:Related]] and [[Template:Related articles end]]. See also the guidelines in those pages.
 +
* Non-English pages can make use of [[Template:Related2]] for translating the anchor text.
 +
* Use the [[#"See also" sections|"See also" section]] for a more complete and detailed list that also includes link descriptions and interwiki or external links.
 +
}}
 +
 
 +
(change the word "article" to "page")
 +
[[User:Axper|axper]] ([[User talk: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...
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 [https://wiki.archlinux.org/index.php?title=Help_talk:Style/Article_summary_templates&oldid=287617#A_crazy_idea_.28about_Summary_templates.2C_Overview_templates_and_categories.29]: 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:
 +
{{hc|Current system|<nowiki>
 +
[[Category:Foo]]
 +
[[Category:Bar]]
 +
{{Related articles start}}
 +
{{Related|link}}
 +
{{Related articles end}}
 +
 
 +
Body
 +
</nowiki>}}
 +
 
 +
{{hc|New system|<nowiki>
 +
{{Related articles start}}
 +
{{Category|Foo}}
 +
{{Category|Bar}}
 +
{{Related|link}}
 +
{{Related articles end}}
 +
 
 +
Body
 +
</nowiki>}}
 +
 
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk: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 <nowiki>{{Related articles start}}</nowiki> and <nowiki>{{Related articles end}}</nowiki> around the cats). Or would we use the current system for such pages? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:24, 13 July 2014 (UTC)
 +
 
 +
== Convention on added/removed text in Hc Templates ==
 +
 
 +
I just [https://wiki.archlinux.org/index.php?title=Nautilus&diff=prev&oldid=324433 used] the following way to clarify removed/added text in [[Nautilus#Use delete key to move to trash in Nautilus 3.6 and above]]:
 +
 
 +
{{hc|~/.config/nautilus/accels|
 +
''<s>; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")</s>''
 +
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
 +
}}
 +
 
 +
Is there already a policy on this? --'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<span style="color:gold">D</span><span style="color:orange">e</span><span style="color:red">t</span>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 23:29, 10 July 2014 (UTC)
  
==Category pages - tree or otherwise?==
+
:Nope, there's no policy on that (yet?). Your version is certainly an improvement, compared to the previous {{ic|-+}} 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:
The ArchWiki category tree was originally designed as just that: a [[Wikipedia:Tree (data structure)|tree]]. I disagree with the point: ''A category can be categorized under more than one category, provided one is not ancestor of the others.'' I believe that categories should themselves be categorized under only a single category. Non-overlapping categories should be devised in cases where one category could belong to many. Related categories can be listed on the category page itself. -- [[User:Pointone|pointone]] 10:39, 23 September 2011 (EDT)
 
:As noted at the top of [[Table of Contents]], [[:Category:Secure Shell]] is a good example: if we can solve it we can really try to avoid categories with multiple parents in general, which is something that I don't like either. The problem is that Security could hardly be child of Networking, and vice versa, so either we put Secure Shell only under one of them, or for example we split Security in two categories, one under Networking, the other not, and put Secure Shell under Networking->Security. Of course we could also split Networking instead, but it would probably be less natural. -- [[User:Kynikos|Kynikos]] 11:43, 23 September 2011 (EDT)
 
  
::Is there any decision on this? I would like to add [[:Category:Package development]] as a subcategory of [[:Category:Package management]]. Currently it is only a subcategory of [[:Category:Arch development]]. But there is no point in me doing that if it is just going to be undone. Otherwise I would add a manual link from ''Package management'' (which may have helped me find what I was originally looking for) and probably a reciprocal one back the other way. But I feel that is more work than necessary and when looking for information on the wiki I expect the categories to work this way instead.
+
::In {{ic|~/.config/nautilus/accels}}, replace:
:: Why were the Arch wiki’s categories originally designed as a tree? Why do you prefer that categories only have a single parent category, especially when article pages do not have to? [[User:Vadmium|Vadmium]] 10:52, 26 October 2011 (EDT).
+
::{{bc|; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")}}
:::No decision yet, the current style rules allow multiple parents also for categories, so you can implement your idea, don't worry now whether it will be undone or not in the future. Just remember to update [[Table of Contents]] or [[Talk:Table of Contents]] (I don't remember which one is the most up-to-date) and to link to this discussion from the Edit Summary.
+
::with:
:::In general, a tree-like structure is the "ideal goal" because it looks simpler and tidier than having "converging branches", thus helping organizing the articles in a more natural way and also making maintenance easier. However it may be hard to put into practice indeed, so this discussion is probably going to last long...
+
::{{bc|(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")}}
:::-- [[User:Kynikos|Kynikos]] 12:59, 27 October 2011 (EDT)
 
  
==Style vs. Usability ==
+
: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.
Commenting on: [[Help:Style#Daemon_operations]] and [[Help:Style#Official_packages]]
+
: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]].
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 15:30, 11 July 2014 (UTC)
  
Deprecating installation instructions and the method of adding deamons to the DAEMON array is causing a higher than normal amount of questions on how to do this in the IRC channel. Perhaps this can be reconsidered, or at least be reconsidered for critical articles like the beginner's guide, the dbus article, the official installation guide, the various graphics driver pages (ATI /NVIDIA) etc etc. These are often browsed from CLI during installation and should thus be as complete as possible, having to follow links around and back from a CLI browser is no fun.
+
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:
  
And in general: Having to look up the method of applying a change mid-article kills the flow of the article, users have to browse around to find a system-critical method on a different page.
+
Create a shortcut to the action {{ic|<Actions>/DirViewActions/Trash}} with the key {{ic|Delete}} e.g.
 +
{{hc|~/.config/nautilus/accels|
 +
...
 +
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
 +
...}}
  
This would be fine if the action involved wasn't so important, or if the linked information was either:
+
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. --[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 17:28, 8 October 2014 (UTC)
* a small non-critical note
 
* a large block of text requiring separate attention
 
  
but these actions are system critical. We don't want to create confusion in guide-nature articles. --[[User:Stefanwilkens|stefanwilkens]] 18:18, 10 January 2012 (EST)
+
== Titles: singular or plural? ==
:''All'' newcomers should read [[Beginners%27_Guide]]. Is there anything missing from that article or is anything not clear and easy to understand? It tells you how to add a daemon and install packages. -- [[User:Karol|Karol]] 18:19, 10 January 2012 (EST)
 
  
::That page is in such a proper state because the policies in [[Help:Style#Daemon_operations]] and [[Help:Style#Official_packages]] haven't been applied there. The flow would be broken if they were. I'm trying to point out that applying these policies to all our articles would needlessly complicate things for the users reading these articles.  
+
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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:26, 13 July 2014 (UTC)
  
::TLDR; an article telling you where to find how to do something rather than telling you how to do something within the article itself is incomplete, confusing and doesn't flow.--[[User:Stefanwilkens|stefanwilkens]] 18:43, 10 January 2012 (EST)
+
:I agree, plurals sound better, it's also how Wikipedia does it:
:::I'm a fan of [http://en.wikipedia.org/wiki/Don%27t_repeat_yourself DRY] so -1 for your suggested changes. People can't be bother to RTFM, nothing new.
+
:* [[Wikipedia:Wikipedia:Naming_conventions_(plurals)#Exceptions]]
:::Both [[Daemon]] and [[pacman]] articles should have the info you (the people you're trying to help) need. -- [[User:Karol|Karol]] 18:55, 10 January 2012 (EST)
+
:* [[Wikipedia:Wikipedia:Category_names#General_conventions]]
:::[https://wiki.archlinux.org/index.php/Help:Style#Hypertext_metaphor This part of the wiki styleguide] tells you explicitly ''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.'' -- [[User:Karol|Karol]] 19:39, 10 January 2012 (EST)
+
:[[User:Axper|axper]] ([[User talk:Axper|talk]]) 07:35, 13 July 2014 (UTC)
::::DRY is a philosophy originally intended for software development to prevent code duplication. While it is applied to documentation, surely applying DRY over article clarity isn't a good thing.
 
::::I refer you to random articles on other distro wikis out there:
 
::::* Gentoo's wiki articles [http://wiki.gentoo.org/wiki/GRUB2#Installation Grub2], [http://wiki.gentoo.org/wiki/Dracut Dracut], [http://wiki.gentoo.org/wiki/Syslinux_Bootloader syslinux]
 
::::* Ubuntu wiki articles [https://help.ubuntu.com/community/BinaryDriverHowto/Nvidia maintain the same method] despite [https://help.ubuntu.com/11.10/ their extensive core installation documentation]
 
::::* Debian wiki articles [http://wiki.debian.org/NvidiaGraphicsDrivers#Installation nvidia], [http://wiki.debian.org/fr/Clementine#Installation clementine]
 
::::It is standard practice in distro documentation land to include installation instructions in every article, and for good reason. It works, it's obvious and it's clear to the reader without having to find '''more''' documentation to explain the documentation he's reading at the moment. Your argument that they should have read other documentation makes sense and is sound, but we shouldn't forget that these articles are written with the single purpose of clarification. Where does one draw the line between preventing rehashing of information and sacrificing article sanity?
 
::::I do agree that rehashing complete articles of information is pointless, a good example of referring to external information is the [[nvidia]], [[ati]] and [[Desktop_Environment]] articles that had their content removed from the [[Beginner%27s_Guide]] and the [[xorg]] articles. This is useful because a user following links to those external articles will likely have to follow the extent of it, it flows well to do so. That and the silly amount of information that was essentially duplicated between the articles made for sound reasons to link rather than rehash.
 
:::: 
 
::::Forcing people to look up one-line information in large external articles is just silly, especially if that information is core to the system. You're not reducing the article's complication, you're not reducing the article's size in a significant way and you're complicating the flow.
 
:::::This is basic info and knowing how to install packages or add daemons is covered in the wiki in the places you'd expect: in the beginners' guide and in daemons and pacman article respectively. How can the lack of this info be a problem for any Arch user? -- [[User:Karol|Karol]] 06:38, 11 January 2012 (EST)
 
:::::The current initscripts (2012.01.2-1) have manual page for rc.conf. It's the first incarnation so it may need some work e.g. in the daemons section. Users of course have pacman and pacman.conf manual pages at their disposal.
 
:::::I understand that you're asking for just a one-line change here or there, but it's like having each pedal in a manual transmission car marked 'clutch', 'break' and 'acceleration' respectively. I see no reason users shouldn't be expected to know this stuff. -- [[User:Karol|Karol]] 07:07, 11 January 2012 (EST)
 
::::: As for "look up one-line information in large external articles", it is not the goal of providing an external link. When a user want to use Arch and install software, he should/must read all [[pacman]], learn all about it and remember most often used command "pacman -S ...". Then he will never need to follow these external link any more. And his mind will never be distract by a command which is right in the memory. [[User:Fengchao|Fengchao]] 20:49, 11 January 2012 (EST)
 
:::::: Yup, we should think about experienced users too - I don't think they want to read the same info over and over again :-) -- [[User:Karol|Karol]] 22:08, 11 January 2012 (EST)
 
::::::: But who is the target audience of this documentation? Surely it's easier for an advanced user to skip information he / she does not require than for a less advanced user to have to refer to other articles. The likes or dislikes of users shouldn't affect the documentation and it most definitely should not be a argument to make the documentation less accessible, which is pretty much what this comes down to.
 
::::::: Unless the hand-holding and increased accessibillity of our documentation to less-experienced users is a goal here. I know we don't strive to support the mentally challenged here, but we should prevent this from influencing the documentation? Two-sided coin I suppose. --[[User:Stefanwilkens|stefanwilkens]] 15:51, 17 January 2012 (EST)
 
  
:''"Deprecating installation instructions and the method of adding deamons to the DAEMON array is causing a higher than normal amount of questions on how to do this in the IRC channel."'' I believe that if an Arch user cannot remember how to install a package (pacman -S package) or to edit a text file (rc.conf) then it's even more important that he takes the time to read [[pacman]], [[rc.conf]] and [[Daemon]], because those articles are among the foundations of an Arch Linux system, and there's no way their content can be ignored. Arch users can't be made to think that an Arch system can be administered like more user-friendly distros such as Ubuntu, openSUSE and similar, the average Archer is required to be more aware of how his system works than the average Ubuntu user, that's by Arch's design in the first place. 
+
::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:
:That said, the [[Beginners' Guide]] is the only article that is exempt from the rules about installation and daemons. I'm taking note that this exemption is not explicitly stated and I'll fix that asap!
+
::* 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.
:The current style guide was discussed for several months (see the history of its talk pages) among the administrators and the main contributors at that time, and it's a compromise among all the different ideas and opinions we expressed during its development. We agreed that a style guide enforced by the admins is necessary since there's no way that all users will ever find a common point of agreement over all the style rules, and this very discussion, (although very welcome, like every discussion ^^ ) is just an example of that consideration.
+
::For [[Help:Style#Category pages]]:
:I'm sorry but I have to reject your proposal, since it wouldn't be an improvement of the style guide, but a change in its direction, and that would require a much larger discussion, considering that all the current active administrators support it the way it is now :)
+
::* 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).
:-- [[User:Kynikos|Kynikos]] 09:35, 11 January 2012 (EST)
+
::Do you think they are clear enough? Alternatively we could just link to the Wikipedia conventions that Axper pasted above. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 02:40, 26 December 2014 (UTC)
:Maybe one thing that could be evaluated, if some users are really ignoring links to those articles, is using more explicit links like "Install<sup>[[pacman#Installing_packages|how?]]</sup> the {{pkg|xyz}} package, available in the [[Official Repositories]]" as was proposed by James Eder on 3 June 2011 (see history). The {{ic|<nowiki><sup>[[pacman#Installing_packages|how?]]</sup></nowiki>}} part could be included with a specific template (we couldn't include also the rest of the sentence because it must be adaptable to package lists, groups and more possible particular situations). Something similar could be done for daemons and kernel modules. However this would be a compromise, I still prefer the implicit link in the word "install". -- [[User:Kynikos|Kynikos]] 12:30, 11 January 2012 (EST)
 
::The style suggested by the guide for installation of packages is unnecessarily verbose. '''The ArchWiki must be as concise and as usable as possible.''' If users want more in-depth documentation, they can consult a manpage or the project's official documentation. The instructions {{Box||{{bc|# pacman -S ntp}}}} are far clearer and more effective than {{Box||NTPd can be [[pacman|installed]] with the package {{pkg|ntp}}, available in the [[Official Repositories]].}} [[User:KerrickStaley|KerrickStaley]] 11:26, 12 January 2012 (EST)
 
:::I have only read the last two responses to this section, but I wanted to make a more general point. Far too much online documentation is dumb, meaning it tells the reader what to do, without explaining the underlying concepts. I believe the use of a sentence instead of a command helps the reader understand package installation more broadly. Many users are too quick to add commands and scripts to the Wiki without explanation. The switch from the {{ic|pacman -S <package>}} to the aforementioned sentence will hopefully be the first step in encouraging more thorough explanation. Commands should be used sparingly. ~ [[User:Filam|Filam]] 17:45, 12 January 2012 (EST)
 
::::We can get the best-of-both worlds if we first give instructions on exactly what to do, and follow those instructions with explanation. That's what I always strive to do when writing articles, but when installing packages, there's really no explanation necessary; it's a task the user must have done several times before they can even be browsing the ArchWiki. <p> More generally, documentation that gets to the point instead of beating around the bush is better. Lay out the main points first, and then mention the fine details, exceptions, etc. </p><p> Also, if we're going to use a sentence rather than a command line to explain which packages need to be installed, then a fixed sentence with minimal verbiage is better: "Install &lt;package(s)&gt;, available in the Official Repositories". It's easy to tell at-a-glance which packages are needed. </p> [[User:KerrickStaley|KerrickStaley]] 22:22, 13 January 2012 (EST)
 
:::::"''...it's a task the user must have done several times before they can even be browsing the ArchWiki.''" Well, that problem can't be solved in the ArchWiki then. By the way the Beginners' Guide is exempted from the disputed rules, and now I've also stated that explicitly in the guide.
 
:::::The minimal verbiage is recommended, in fact it's the one used in the main examples in the guide, but installation requests do not always come at the beginning of articles in installation sections: sometimes they are in tips and tricks sections, or troubleshooting, or in general are part of a longer sentence and require a specifically adapted wording that we can't predict with a style rule.
 
:::::-- [[User:Kynikos|Kynikos]] 10:33, 14 January 2012 (EST)
 
::::::A couple points from my perspective:
 
::::::* The current style rule is more generic; for the same reasons why {{ic|yaourt -S package}} is discouraged, {{ic|pacman -S package}} should be too. Pacman may be the default package manager but not everyone needs to use it -- many AUR helpers also work with the official packages and other pacman wrappers exist (e.g. pacman-color). Further, some people may wish to compile their own packages with ABS before installing, etc.
 
::::::* Even if {{ic|pacman -S package}} is preferred, this doesn't really tell the whole story. Proper (complete) installation instructions should read:
 
::::::** Ensure the correct repositories are enabled: {{ic|nano /etc/pacman.conf}}
 
::::::** Ensure that a server (or two) is uncommented in the mirrorlist: {{ic|nano /etc/pacman.d/mirrorlist}} (check online for up-to-date mirrors)
 
::::::** Update your system and refresh your package lists if you have not yet done so today: {{ic|pacman -Syu}}
 
::::::** Install package: {{ic|pacman -S package}}
 
::::::-- [[User:Pointone|pointone]] 12:33, 15 January 2012 (EST)
 
  
This debate ended up very lively with strong arguments from both sides, I'd like to present a new side to the same argument. I much enjoyed the fact that the "old" method of signifying an installation action provided a clear optical action point; compare if you will:
+
:::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.
 +
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:38, 26 December 2014 (UTC)
  
$ pacman -S package1 package2
+
::::Thanks for the feedback, rules merged with [https://wiki.archlinux.org/index.php?title=Help%3AStyle&diff=353479&oldid=353475]. 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.
 +
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:09, 27 December 2014 (UTC)
  
NTPd can be [[pacman|installed]] with the package {{pkg|ntp}}, available in the [[Official Repositories]].
+
:::::See also [[ArchWiki:Requests#Renaming_of_categories]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:40, 26 July 2015 (UTC)
  
The "old" method clearly signifies action should be taken, the new method suggested in the style documentation is far easier to miss in a large document. Furthermore, this new method reads more as a tip or a notice than an action statement, is that desirable or recognizable?
+
== Questionable edits ==
  
I believe this is similar to what Kynikos suggested a few blocks up, on 12:30, 11 January 2012 (EST)--[[User:Stefanwilkens|stefanwilkens]] 15:42, 17 January 2012 (EST)
+
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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:12, 9 August 2014 (UTC)
:Yeah I suggested that only as a possible compromise, although I still prefer the current phrasing. You're perfectly right, those who are used to reading only the blue parts in the articles will miss the installation parts with these style rules. But do we really want to accomodate to their needs? Words, even if on a white background and in variable-width fonts, have a definite, most often useful meaning, they have not been put there for aesthetic matters or by mistake. I don't think your argument is convincing, but let's see if somebody else has something to add. -- [[User:Kynikos|Kynikos]] 16:39, 17 January 2012 (EST)
 
:: Accommodation to the needs of experienced users (dislike reading hand-holding articles) is brought up as an argument a few blocks up from here. Why accommodate one group over the other? This is likely a question of who the target audience is. Is there a guideline on this at all? Is our documentation intended to let the novice users successively install / operate Arch Linux and anything we may describe in our WiKi or do we set the guideline that we expect more?
 
:: I think I may have answered my own question as I wrote this, but for the sake of consistency. What is the target audience?
 
:: As for the style, I would be inclined to add indentation or something else to attract attention to these to-be-installed lines. Visited links on our style turn grey, the line really does blend in with the article if all links in it are visited previously. Would additional attention be acceptable?--[[User:Stefanwilkens|stefanwilkens]] 18:14, 18 January 2012 (EST)
 
:::The information is still available on the wiki and linked to when relevant. In my opinion, duplicating instructions everywhere doesn't help new users. Instead, it provides them with many sources of incomplete and often out-of-date/inaccurate information rather than directing them to an high-quality article.
 
  
:::I understand that there's a steep learning curve, but hand-holding instead of teaching just prolongs it. Arch was my first experience with Linux and I had zero command-line knowledge. I ended up doings '''''lots''''' of reading (mostly the wiki at first, eventually other documentation) and worked through the issues I encountered. At that point the Beginners' Guide was a huge mess because it had many step-by-step branches (instructions for installing a dozen DEs/WMs and mouse cursors/themes!).
+
=== Underscores vs. slashes in kernel module names ===
  
:::If we just provide copy-and-paste commands everywhere we don't provide much opportunity to learn, and just teach users to turn to the forums or #archlinux at the first sign of trouble (instead of relying on the community as a fallback when they've already done research and tried to figure it out for themselves). Relevant: http://slash7.com/2006/12/22/vampires/.
+
Example: [https://wiki.archlinux.org/index.php?title=USB_storage_devices&diff=next&oldid=328933] vs. [https://wiki.archlinux.org/index.php?title=Advanced_Linux_Sound_Architecture&diff=311976&oldid=310951]
  
:::Linking to well-written and maintained articles makes it much easier for someone to go from being a new user to an experienced one; you only have to learn how to install/remove/downgrade a package once (likely just when you need to do it) and then you're set forever. It ''will'' make it harder for people who don't want to read or learn and just enter commands copied from the wiki, but I don't think we should encourage that.
+
From {{ic|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.
  
:::''Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime.''
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:12, 9 August 2014 (UTC)
  
:::- [[User:Thestinger|thestinger]] 21:21, 18 January 2012 (EST)
+
:Let's just pick one style and go with it. I vote for undescores, since that's how {{ic|lsmod}} prints them, consistency would be nice.
::::This comments on the content and overall tone of the article. Both "old" and "new" suggested methods of displaying the information contain equal content, I don't think we're loosing content or significantly avoiding hand-holding behavior at all with this new style. I accept that my initial argument on the removal of terminal style installation instructions has passed, but that's not what I'm trying to talk about in this section.
+
:I wouldn't consider these 2 edits questionable, rather it's lack of [[Help:Style]] rules about this particular subject.
 +
:[[User:Axper|axper]] ([[User talk:Axper|talk]]) 06:04, 10 August 2014 (UTC)
  
::::My debate here is that of readability, how to best present this information to a reader. Regardless of article tone, what optical structure is best used to signify key action points in the article. See the example 4 blocks up and take note of the significantly reduced visibility of these actionable points (something your link talks about). If we are to write actionable documentation, should we then not make sure that the directly actionable sections of the documentation are prominent?
+
::+1 for regulating this with underscores as per axper's lsmod argument. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:13, 10 August 2014 (UTC)
  
::::Open up any textbook, examples are always provided in colored blocks, other fonts, indented notation or preceded by colored or otherwise optically attracting constructs. The suggested style blends in with an article, especially when the links in it are marked "visited" (grey) --[[User:Stefanwilkens|stefanwilkens]] 07:19, 19 January 2012 (EST)
+
=== Alphabetical order ===
:::::Changing the color of visited links has been in my todo list for some time, maybe it's time to submit a bug for that: I'd like to see a purplish color, I tried something like <span style="color:#606;">#606</span>, <span style="color:#70b;">#70b</span>, <span style="color:#74b;">#74b</span>. More ideas? Objections?
 
:::::-- [[User:Kynikos|Kynikos]] 08:33, 19 January 2012 (EST)
 
  
:::::Note that interwiki links already become purple (albeit still too greyish?) when visited: [[wikipedia:Main Page]] '''[[wikipedia:Main Page]]'''. -- [[User:Kynikos|Kynikos]] 15:25, 24 January 2012 (EST)
+
Example: [https://wiki.archlinux.org/index.php?title=Xorg&diff=prev&oldid=327850]
  
:::::I'd also like to request that links remain bold even when they are in indented paragraphs ({{ic|#bodyContent dd > a {font-weight:bold;} }}?) -- [[User:Kynikos|Kynikos]] 11:46, 29 January 2012 (EST)
+
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.
  
:::::::Completely agree. Also, I think, color should be different from one of interwiki links. --[[User:AlexanderR|AlexanderR]] 23:54, 29 January 2012 (EST)
+
Also, have you ever read a book with chapters sorted alphabetically?
  
::::::::Do you mean of a completely different color? Can you be more specific or give an example? In any case if there should be a difference in color among links, it should distinguish internal from external links (including interwiki).
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:12, 9 August 2014 (UTC)
::::::::However I think that black for normal text, blue for links (internal or external), purple for visited links and black on cyan for code may be already enough.
 
::::::::-- [[User:Kynikos|Kynikos]] 07:11, 31 January 2012 (EST)
 
  
:::::::::>> Do you mean of a completely different color?
+
: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. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:41, 9 August 2014 (UTC)
:::::::::No, a bit darker shade than <span style="color:#606;">#606</span> (or, maybe even a bit more rich) would be perfect. --[[User:AlexanderR|AlexanderR]] 00:29, 4 February 2012 (EST)
 
  
:::::More about visibility: we could <u>evaluate</u> (which means I'm not supporting yet this idea, i.e. I'm brainstorming) the possibility of adding a little inline package icon at the end of [[Template:Pkg]] and [[Template:AUR]] in a similar fashion to what happens with regular external links, that get a little arrow. Thoughts?
+
::Yes, I'd expect a section about a ''new'' bug I am looking a solution for to be at the end of the article. [[User:Axper|axper]] ([[User talk:Axper|talk]]) 06:20, 10 August 2014 (UTC)
:::::I'm strongly against indentation as it won't work with installation requests that are included in longer sentences.
 
:::::-- [[User:Kynikos|Kynikos]] 08:33, 19 January 2012 (EST)
 
:::::If the icon for official packages is different from the one for aur packages, this may also let us avoid always adding "available in the [[official repositories]]" and "available in the [[AUR]]". -- [[User:Kynikos|Kynikos]] 11:46, 29 January 2012 (EST)
 
::::::Well, if you find suitable icons. --[[User:AlexanderR|AlexanderR]] 23:54, 29 January 2012 (EST)
 
::::::'''Edit:''' and develop alternative presentation for text browsers --[[User:AlexanderR|AlexanderR]] 23:54, 29 January 2012 (EST)
 
  
==Title case==
+
:::First, the example edit should have been split (i.e. one section moved at a time).
As discovered in [[Talk:Common Applications#Improving the title]], the rule regarding title case is currently unclear (and absent from this style guide). [[Help:Editing#Creating pages]] states {{ic|Titles should be capitalized appropriately: ''Title for New Page''; not ''Title for new page''}}.
+
:::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.
 +
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:13, 10 August 2014 (UTC)
  
I propose the following style rule to be added under [[Help:Style#Title]] (as the first point):
+
::::+1, Lahwaacz is right. And one example for keeping similar sections next to each other: [[GNOME#Extensions]] -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 12:21, 20 August 2014 (UTC)
  
* Titles should be capitalized using '''title case''', as in "How to Install Arch Linux on a Toaster."
+
=== Concision ===
  
Any objections or suggestions before I add this? Do you think it is necessary to contrast with the rule for headings (which should use sentence case)?
+
(without example)
  
-- [[User:Pointone|pointone]] 16:37, 19 January 2012 (EST)
+
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.
  
:Of course we need a rule for title case. Referring to "Title Case" should work in the majority of cases, however I'd use "How to Easily Install Arch Linux on a Blue Toaster" or something like that as an example, just to include an adverb and an adjective (assuming I've capitalized them correctly).
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:12, 9 August 2014 (UTC)
:Then we should probably also mention the correct way to capitalize the application names that are officially written in lower case, and this would probably need a reference to [[Template:Lowercase title]], which by the way I wanted to mention at the first position in [[Help:Style#Layout]], together with some [http://www.mediawiki.org/wiki/Help:Magic_words#Behavior_switches behavior switches].
 
:I don't think it's necessary to explicitly contrast this rule with that for section headings.
 
:-- [[User:Kynikos|Kynikos]] 07:16, 20 January 2012 (EST)
 
:This topic has been touched on also in [[Talk:Article Naming Guidelines#Article title capitalization]], mentioning [[Wikipedia:Wikipedia:Article_titles#Article_title_format|Wikipedia's policy]] which seems to conflict with the "title case" idea. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:49, 5 July 2012 (UTC)
 
  
==Reducing formatting bloat==
+
: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 [https://wiki.archlinux.org/index.php?title=Skype&diff=prev&oldid=328283] for a simple example. Latter should be avoided, and flagged (for example [https://wiki.archlinux.org/index.php?title=PPTP_Server&curid=9499&diff=329500&oldid=329283]) where appropriate. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 18:24, 9 August 2014 (UTC)
I noticed that some articles tend to become almost unreadable after long editing &ndash; mostly due to extensive usage of bold/blue text and code formatting templates. Does anybody feel the same? To start with &ndash; here is my proposal: prohibit usage of [[Template:Ic]] inside [[Template:Note]], [[Template:Tip]] and other similar templates. Such templates already attract a lot of reader's attention, there is no need to bother one even more (and IMHO combination looks ugly). --[[User:AlexanderR|AlexanderR]] 03:39, 25 January 2012 (EST)
 
:Honestly I like how code formatting templates make code recognizable even at a glance in a block of text, even inside Notes, Warnings and Tips. Forbidding the use of Ic inside those templates would generate:
 
:{{Tip|You can run rm -rf / as root to free some space on your hdd.}}
 
:Instead of:
 
:{{Tip|You can run {{ic|rm -rf /}} as root to free some space on your hdd.}}
 
:I find the second template much more readable and clear than the first one.
 
:That said, it's worthy of mention the solution used in Python's official documentation (code inside Notes and Warnings gets a darker background than the surrounding background color), but we can't implement that here because we'd have to play with css classes.
 
:-- [[User:Kynikos|Kynikos]] 16:12, 25 January 2012 (EST)
 
::Nice tips. Nearly gave me a hear attack ;P -- [[User:Karol|Karol]] 16:50, 25 January 2012 (EST)
 
:[[User:AlexanderR|AlexanderR]], can you give some examples, which articles look bad to you? -- [[User:Karol|Karol]] 16:50, 25 January 2012 (EST)
 
::This is not whole article but IMHO still counts: [[MySQL]]. There are several instructions like this:
 
:::edit {{Ic|/etc/[[rc.conf]]}} and add {{Ic|mysqld}} to the {{Ic|DAEMONS}} array.
 
::Link to [[rc.conf]] is almost invisible and actually is not helpful for ones who do not remember what daemon is. For me this looks a bit better:
 
:::add '''mysqld''' to the [[daemon|list of daemons]] in {{Ic|/etc/rc.conf}}
 
::--[[User:AlexanderR|AlexanderR]] 00:12, 29 January 2012 (EST)
 
:::Link to rc.conf is perfectly visible for me - it's blue and underlined.
 
:::As for people "who forgot what XYZ is", they can always check it in the wiki, e.g. by searching for 'XYZ', but adding link to the [[daemons]] article seems reasonable. -- [[User:Karol|Karol]] 06:13, 29 January 2012 (EST)
 
::::In any case it's true that we're missing an official phrasing like those for installation requests. I like:
 
::::[[Daemon#Starting on Boot|Add]] {{ic|example}} to the {{ic|[[DAEMONS]]}} array in {{ic|/etc/[[rc.conf]]}}.
 
::::{{ic|<nowiki>[[Daemon#Starting on Boot|Add]] {{ic|example}} to the {{ic|[[DAEMONS]]}} array in {{ic|/etc/[[rc.conf]]}}.</nowiki>}}
 
::::We should probably start a poll after we have collected some ideas here. The same should be done for immediate starting/stopping/restarting of daemons, for adding kernel modules to the MODULES array and for immediate adding/removing of kernel modules.
 
::::@karol: internal links become gray with the default theme when visited, and I agree they lose a lot of visibility (unless you move the mouse over them) see one of my proposals at the bottom of [[#Style vs. Usability]].
 
::::-- [[User:Kynikos|Kynikos]] 11:32, 29 January 2012 (EST)
 
:::::>>[[Daemon#Starting on Boot|Add]] {{ic|example}} to the {{ic|[[DAEMONS]]}} array in {{ic|/etc/[[rc.conf]]}}.
 
:::::Does not look good for me. Three links in the single sentence? Two of them to the same article? How is [[rc.conf]] related to the entire concept of daemons? E.g. what is the purpose of linking to [[rc.conf]] in such phrase? Also mentioning {{Ic|DAEMONS}} array, {{Ic|/etc/rc.conf}} and other details would only become a disservice if implementation changes in future. Anyway, managing daemons autostart is more complicated process than just adding/removing entries within some array. Users should also be able to understand which daemons specific one depends on, how to perform lazy (parallel) loading etc. In other words, average Arch user should know contents of [[Daemons]] just like [[Pacman]] quite well and highlighting {{Ic|/etc/rc.conf}} together with single link to [[Daemon]] should be enough to trigger all required associations.
 
:::::About formatting: highlighting file names and random code lines by means of pale bluish background is already common in Wiki and looks really cool. But, IMHO, it would be nice to use bold text more intensively: for names of kernel modules, daemons, random executables. Note, that unlike [[Template:Ic]] bold formattiong works also in console browsers (at least [[Links]] and [[Lynx]] can render it noticeably).
 
:::::--[[User:AlexanderR|AlexanderR]] 23:44, 29 January 2012 (EST)
 
:::::Another example from [[PulseAudio]]:
 
:::::make sure the module {{ic|snd_pcm_oss}} is not in the {{ic|MODULES}} array in [[rc.conf|{{ic|/etc/rc.conf}}]]
 
:::::(is link to [[rc.conf]] visible for you?)
 
:::::--[[User:AlexanderR|AlexanderR]] 20:00, 30 January 2012 (EST)
 
::::::'''AlexanderR''', I fixed the link in the [[PulseAudio#ALSA]] example you gave. However, I understand what you mean. I often find that most authors prefer to just write commands without enough explanation. I have certainly done it myself. That can make the formatting stand out. I find the PulseAudio example far more reasonable than the MySQL example you gave earlier because there is more context around the formatting. ~ [[User:Filam|Filam]] 22:44, 30 January 2012 (EST)
 
:::::::In the My SQL example, that “Add” link is like Wikipedia’s [[WikiPedia:WP:easter egg|easter egg]] links, which I find annoying. Linking to [[Daemon]] and introducing the ''mysqld'' script should probably be done even earlier in the article; this snippet should just be explaining how to run that script at boot time.
 
:::::::In the OSS example, from a technical point of view, the link is hidden because its formatting is overridden by the inner <nowiki>{{ic}}</nowiki> template. If you add text around it ([[rc.conf|the {{ic | /etc/rc.conf}} file]]) it might be clearer why. It works if you put the link inside the code ({{ic | [[rc.conf|/etc/rc.conf]]}}) or if you use plain &lt;code&gt; tags ([[rc.conf|<code>/etc/rc.conf</code>]]). Personally I’d just go for a plain link ([[:/etc/rc.conf]]) because the formatting of the link is enough emphasis for me, but I understand many people wouldn’t agree. [[User:Vadmium|Vadmium]] 23:14, 30 January 2012 (EST).
 
::::::::Ok guys you surely have some points about this, I'd like to concentrate especially on two things that AlexanderR has rightly pointed out (I'm rewording them, please correct me if I got them wrong), so I'm splitting the discussion here:
 
::::::::#[[#Daemons and modules wording]]
 
::::::::#[[#Bold and italic]]
 
:::::::::I am personally against any formatting at all, at least where it can be avoided. IMHO, if we want formatting in articles to be meaningful and helpful for readers, it is necessary to completely deprecate it's usage except limited list of well-defined cases. Such lists would obviously tend to change, but at least this would help to prevent counterintuitiveness and inconsistency. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
 
  
=== Bold and italic ===
+
::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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:13, 10 August 2014 (UTC)
Currently the style guide completely ignores '''bold''' formatting, which instead could probably be used in some cases in place of [[Template:ic]]. Let's include also ''italic'' in the discussion. Is there the possibility to have well-defined rules (applicable in real articles) about when to use [[Template:ic]], when to use bold and when to use italics?
 
  
-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
+
::Thanks for this hint. I've never recognized concision as a [[wikipedia:Concision|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 [[Help:Style#Language register|language]] should be concise, let's not take it too far. And especially watch out for the nuances. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:08, 10 August 2014 (UTC)
  
==== Bold ====
+
=== "as of version X.XX..." ===
:{{Box||''The b element represents a span of text offset from its surrounding content without conveying any extra emphasis or importance, and for which the conventional typographic presentation is bold text; for example, keywords in a document abstract, or product names in a review.''<br>&ndash; {{Press-entry|author=W3C HTML5 draft (CVS version)|title=b – offset text conventionally styled in bold|source=dev.w3.org|date=2012-02-01|uri=http://dev.w3.org/html5/markup/b.html}}}}
 
  
:With respect to this Wiki specificity (and taking into account various precedents) I propose to limit usage of bold text to: --[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
Example: [https://wiki.archlinux.org/index.php?title=Core_utilities&diff=424410&oldid=424178]
  
:* ''Highly questionable:'' single file names
+
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. [[User:Rdeckard|Rdeckard]] ([[User talk:Rdeckard|talk]]) 20:22, 6 March 2016 (UTC)
::search for '''loop.ko''' in {{Ic|/lib/modules/''kernel_release''}}
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:* executables names (as executables in file system, not in command line):
+
:I agree that it is useless for features. But I think it is very important for bugs and perhaps even missing features.[https://wiki.archlinux.org/index.php?title=SSH_keys&diff=next&oldid=422817] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:46, 6 March 2016 (UTC)
::'''javaws''', which is in {{Pkg|icedtea-web-java7}}
 
::{{Box YELLOW|Clarification required:|should executable names be highlighted always, at first encounter or under other rules?}}
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:* kernel module names
+
::+1. For [https://wiki.archlinux.org/index.php?title=SSH_keys&diff=next&oldid=422817] see also [https://wiki.archlinux.org/index.php/Talk:SSH_keys#PuTTY_elliptic_curve_support]. Another missing features example is [https://wiki.archlinux.org/index.php?title=Solid_State_Drives/NVMe&curid=21993&diff=424474&oldid=417803]. 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. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:48, 7 March 2016 (UTC)
::ensure that '''radeonfb''' is blacklisted
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:* important part of file/command line contents:
+
:::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 [https://wiki.archlinux.org/index.php?title=Core_utilities&diff=424410&oldid=424178 Core utilities], [https://wiki.archlinux.org/index.php?title=GDM&diff=prev&oldid=424423 GDM] and [https://wiki.archlinux.org/index.php?title=Makepkg&diff=prev&oldid=424425 makepkg] edits, but I would undo the [https://wiki.archlinux.org/index.php?title=Python&diff=prev&oldid=424426 Python] edit, and, as noted by Indigo, check the [https://wiki.archlinux.org/index.php?title=SSH_keys&diff=next&oldid=422817 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? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:53, 8 March 2016 (UTC)
::{{bc|1=root=/dev/sda6 ro 5 radeon.modeset=1 '''vga=current''' logo.nologo quiet splash}}
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
:::This one can be acceptable. -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
 
  
:* name of application in the beginning of application-related article
+
:::: 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. [[User:Rdeckard|Rdeckard]] ([[User talk:Rdeckard|talk]]) 02:24, 19 March 2016 (UTC)
::'''Foo''' is the most popular Linux alternative to [[Wikipedia:Bar]].
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:::I don't know, usually the name of the application is also the title of the article, so this rule could just add bloat for nothing. I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead. If there's nothing to link, leave it in normal weight. -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
::::: (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)
 +
::::: --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 07:26, 19 March 2016 (UTC)
  
::::>> so this rule could just add bloat for nothing
+
:Restarting this discussion because I just did a bunch of "as of" edits. It is a tricky issue because there definitely isn't a simple policy that always applies. That being said I think that most "as of"s should probably go. Here are the main use cases that I've observed:
::::Maybe, but for some reason cited HTML5 developers, authors of many articles in this Wiki and even https://www.archlinux.org/ webmaster believe this to be "conventional typographic presentation". This, however, does not oblige us to support such case of usage here.
+
:# noting when a feature was added/removed
::::>> I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead.
+
:# noting when a default option was changed
::::This is neither consistent (there is often ''nothing to link'') nor intuitive &ndash; user can not see link destination without hovering cursor over it. As I [[Talk:Common_Applications#Ideas so far|said in discussion on "''See also'' visibility"]], links to Wikipedia article(s), application home page(s), application project(s) on code hostings etc. together with reliable summary are the only reasonable content for [[Writing_Article_Overviews|article summary template]] and should probably be placed in that single predefined place. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
:# noting when a bug was introduced/fixed
 +
:# noting when the editor last verified the information (workaround was effective, desired feature was missing, etc.)
 +
:Number 4 is easy: "as of" is unnecessary. First of all it is redundant since the article history shows when the information was added (and thus verified). Secondly it adds very little value to the reader of the article. If I'm having a problem and a troubleshooting section has a potential solution it doesn't matter if it was working "as of" 100 years ago, I'm going to give it a shot (and then update the article if it no longer works). Lastly it encourages useless edits. If I see an old "as of" and check that it is still the case, does it really add value to the article if I just update the date to show that it still works? Where do we draw the line for that? Should we go around adding "as of" to every single thing that we verify as working? "As of March 3, 2017 sudo can be installed via {{pkg|sudo}}."
 +
:Number 3 is also easy: "as of" is unnecessary. In almost every case it is more useful to simply link to the bug report (ours or upstream). The obvious advantage being that upstream bug reports often include all the information the reader may want: when it was reported, what versions it affects, potential workarounds/solutions, if/when the bug was fixed, etc. Adding "as of" in this case is just sparing the reader an extra click, which goes against the hypertext metaphor.
 +
:Number 2 is a little tricky. If it is the case where the option change might require user intervention (e.g. a breaking change in config) then the "as of" is needed. However in most cases I've seen it is still not used well in the article. You'll see something like "As of version X the default is blah ...''much later in the article''... if you are upgrading from an older version, you may need to...". I think the "as of" is misplaced here: users who installed after the change likely don't care about the new default since they don't have to worry about breakage. In this case the "as of" should be placed in the later section dealing with the issue: "The default is blah ...''much later in the article''... if you are upgrading from version X, you may need to...". If the default change requires no intervention, I see no need for the "as of": users who run the default likely don't care and users who do not use the defaults are likely unaffected.
 +
:Number 1 is also difficult. I think feature removal is slightly easier because if the removal was an intentional design decision by the developers (i.e. not a bug) then the "as of" is not needed. Arch doesn't support users who want to keep old software around, so it is sufficient for the article to simply say that the feature was removed (not when). Because it was an upstream design decision, users reading the article can safely assume that the software will no longer support that feature. For feature addition I think the same logic as number 2 applies. If the new feature might change how upgrading users use the software it should be mentioned in the relevant section.
 +
:The only rule of thumb that I think applies in all of these cases is that often an editor adds an "as of" when there is actually something more specific they are trying to communicate: "as of X the default was changed '''so if you upgrade you have to'''...", "as of X this feature was removed '''so instead you may need to install'''...". By all means keep the the more specific information, ditch the "as of" if possible.
 +
:[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 19:14, 3 March 2017 (UTC)
  
:* I don't know if we should use bold or what else when using pseudo-variables like:
+
::Very good. One comment: I think a regular case is that someone put a work-around/troubleshooting item into the wiki for a missing feature/default. Later the feature/default is added/changed. I think procedure should be to put a [[:Template:Remove]] to the workaround first, so that users who might have implemented it get info. Then purge it later. (Obviously, there may be simple cases too.)
::{{bc|# modprobe '''module_name'''}}
+
::Two questions. 1: Do you think we should put a "as of" style suggestion with good/bad examples of usage into the style guide? If yes, where?
::{{bc|# modprobe ''module_name''}}
+
::Question 2: Look at the above [[SSH keys#ECDSA]] example. Coincidentally, the referred to putty package finally gained the feature two weeks ago. How would you handle that, taking into account implementing the feature took a couple of years.
::{{bc|# modprobe <module_name>}}
+
::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:47, 3 March 2017 (UTC)
::{{bc|# modprobe [MODULE_NAME]}}
 
::(from [[Kernel Modules]]). -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
 
  
:::This conflicts with "important part of file/command line contents" part. As I said below, italic seems to be more appropriate.
+
:::I think the "as of" there is needed, but again I think it is misused. Right now it is an example of case 4 i.e. "when I edited this article in March 2016 the feature wasn't there yet". This is redundant and not very useful. A much better "as of" would be to mention that ECDSA support has actually been in the development snapshot since November 2014! That is much more useful. [[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 23:19, 3 March 2017 (UTC)
:::''Probably worse idea than just italic'': Another proposal &ndash;
 
:::{{bc|# modprobe <''module_name''>}}
 
:::This way pseudo-variables become highlighted and offset from surrounding text at the same time but in different way than "important part". --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
 
  
==== Italic ====
+
::::I agree, somewhat. The "feature not there" info was useful in so far, as there will be users who configure their Arch openssh server (defaulting to ECDSA) but may latter want to connect via another platform's client (i.e. useful to avoid the pitfall with putty as a common client failing to support the server default). Of course it would have been even more useful with the development version info being merged over from the talk page, or the info moved/crosslinked from [[putty]]. But ok. My question was for the new status quo: How would you phrase it now, with the new stable version supporting ECDSA? Keep the note with an "as of putty 0.68 (Feb 2017) ECDSA is available", or simply drop it because it does not matter anymore? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 02:36, 4 March 2017 (UTC)
:{{Box||''The i element represents a span of text offset from its surrounding content without conveying any extra emphasis or importance, and for which the conventional typographic presentation is italic text; for example, a taxonomic designation, a technical term, an idiomatic phrase from another language, a thought, or a ship name.''<br>&ndash; {{Press-entry|author=W3C HTML5 draft (CVS version)|title=i – offset text conventionally styled in italic|source=dev.w3.org|date=2012-02-01|uri=http://dev.w3.org/html5/markup/i.html}}}}
 
  
:I already noticed two kinds of italic usage in this Wiki, conventional enough to be proposed for this role (I am so lazy.. please add examples yourself if you want): --[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
:::::Putty is an exceptional case because there we have to deal with compatibility with other OSes (where the always up-to-date assumption does not apply). So the "as of" there is useful, again as long as it actually mentions when the feature was added.
 +
:::::Also, regarding "as of" in the style guide I think it sufficient to mention the two clear-cut cases: do not use "as of" if you are just noting the last time you personally checked something and do not use "as of" for bug reports, just link to the report itself.[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 18:37, 4 March 2017 (UTC)
  
:* Cites from external sources:
+
::::::: I've handled the Putty example with [https://wiki.archlinux.org/index.php?title=PuTTY&curid=15652&diff=469978&oldid=469692] and [https://wiki.archlinux.org/index.php?title=SSH_keys&curid=1156&diff=469983&oldid=468807] I agree it could be done the other way too. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:29, 6 March 2017 (UTC)  
::''All your data belongs to us'' &ndash; Google
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:::...or ''"All your data belongs to us"'' (w/ quotes)? (see e.g. [[Beginners'_Guide#The_Arch_Way]]) -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
::::::Great write up above. I'm in agreement that we should tell users not to note the date, time, or program version in their edits if they are just telling us the last time everything worked for them. I also like the idea of encouraging users to link to bug reports instead of giving specific versions. We also need to use the "Known Issues" more often in our articles. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 21:11, 4 March 2017 (UTC)
  
::::This is matter of punctuation, not formatting. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
::::::: To make a start with mentioning "as of", I put in [https://wiki.archlinux.org/index.php?title=Help%3AStyle&type=revision&diff=469988&oldid=469986] and [https://wiki.archlinux.org/index.php?title=Help:Style&diff=next&oldid=469988] (the latter addition may be a bit sublime). Perhaps you have an idea to make it more prominent or concise along above. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:29, 6 March 2017 (UTC)
  
:* Inline templates (IMHO, those with italic formatting look much better than ones with bold formatting):
+
== File types ==
::{{Ic|<nowiki>http://127.0.0.1:8080/index.jsp#</nowiki>''section_name''}}
 
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
  
:::I don't understand, you'd use always italic inside [[Template:ic]] regardless of the content? In that case I don't even like it aesthetically :) -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
File types are formatted as per [[Help:Style#Code formatting]], right?:  
  
::::This is exactly what you name "pseudo-variables" (your wording was better than mine, lets use it). Using bold in this case conflicts with "important part of file/command line contents" part; italic would also be more intuitive: we want to ''offset text from its surrounding content'' rather than attract additional users attention. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
:* ''Use {{ic|<nowiki>{{ic|code}}</nowiki>}} for short lines of code, file names, command names, variable names and the like to be represented inline [..]''
  
=== Quoting and underlining ===
+
Does it need mentioning?:
Also note that, although with less frequency, even <u>underlining</u>, 'quoting' and "double quoting" are used more or less commonly.
 
  
Let's go through this discussion treating one specific problem at a time, without rushing it, since this can be an enormous topic and with our current shortage of manpower there's not much we could do to correct the articles even if we managed to find a decent set of rules.
+
:* ''Use {{ic|<nowiki>{{ic|code}}</nowiki>}} for short lines of code, file names '''and types''', command names, variable names and the like to be represented inline [..]''
  
-- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
〜'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<span style="color:gold">D</span><span style="color:orange">e</span><span style="color:red">t</span>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 00:36, 6 October 2015 (UTC)
  
==== Quoting and double quoting ====
+
:There is [[Help:Style/Formatting_and_punctuation#File_extensions]]. Some reorganization and/or cross-referencing would be in order... [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:20, 6 October 2015 (UTC)
Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
 
  
==== Underlining ====
+
:: I've missed that completely. I fixed my [https://wiki.archlinux.org/index.php?title=Wayland&diff=403815&oldid=403559 edit] in [[Wayland]]. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<span style="color:gold">D</span><span style="color:orange">e</span><span style="color:red">t</span>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 23:38, 8 October 2015 (UTC)
:{{Box||''The u element represents a span of text with an unarticulated, though explicitly rendered, non-textual annotation, such as labeling the text as being a proper name in Chinese text (a Chinese proper name mark), or labeling the text as being misspelt.<br><br>In most cases, another element is likely to be more appropriate: for marking stress emphasis, the em element should be used; for marking key words or phrases either the b element or the mark element should be used, depending on the context; for marking book titles, the cite element should be used; for labeling text with explicit textual annotations, the ruby element should be used; for labeling ship names in Western texts, the i element should be used.''<br>&ndash; {{Press-entry|author=WHATWG|title=HTML Standard|source=WHATWG HTML5 draft|date=2012-02-04|uri=http://www.whatwg.org/specs/web-apps/current-work/#the-u-element}}}}
 
  
:As far as I know underlining is used relatively rarely in this Wiki. The only use case I can imagine is using in place of bold (e.g. for highlighting single words and sentences without pulling them out of context). If we decide to deprecate direct usage of bold text in order to fully utilize it for technical purposes, such replacement would be suitable. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
== Some style/grammar guidelines ==
  
== Daemons and modules wording ==
+
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:
We need a more generic standard phrasing when requesting to "add daemons to the DAEMONS array..." (even avoid making reference to rc.conf, since [[Daemons]] links there already?) in the vein of what's been done with installation instructions, and point more clearly to [[Daemons]]. Similar problem with kernel modules and the MODULES array. Also the instructions for starting/stopping daemons and for adding/removing modules could be merged in the sentence.
+
* 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''".
 +
[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 20:13, 4 March 2016 (UTC)
  
I'd like to start a brainstorming session here to find the right wording example(s) to put in the guide. Of course objections to the whole idea are still taken into consideration.
+
:[[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.
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:22, 4 March 2016 (UTC)
  
We probably need a standard phrasing for immediate starting/stopping/loading/removing only, another standard for adding to DAEMONS/MODULES only and a third one for the cases where both immediate and automated action are recommended. I'll start with (I repeat, this is a brainstorming session):
+
::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.
 +
::[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 06:52, 5 March 2016 (UTC)
  
*"[[Daemons#Performing daemon actions manually|Start]] the {{ic|foobar}} daemon."
+
:::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.
*"[[Kernel Modules#Loading|Load]] the {{ic|foobar}} module."
+
:::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]]:
*"Add the {{ic|foobar}} daemon to the [[Daemons#Starting on Boot|DAEMONS]] array."
+
::::* 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.
*"Add the {{ic|foobar}} module to the [[Rc.conf#Hardware|MODULES]] array."
+
:::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:
*"[[Daemons#Performing daemon actions manually|Start]] the {{ic|foobar}} daemon and add it to the [[Daemons#Starting on Boot|DAEMONS]] array."
+
::::* 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.
*"[[Kernel Modules#Loading|Load]] the {{ic|foobar}} module and add it to the [[Rc.conf#Hardware|MODULES]] array."
+
:::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:29, 6 March 2016 (UTC)
  
Note that if we solve the problem of links color and font-weight as explained at the bottom of [[#Style vs. Usability]], the links will always be blue/purple and bold, even in indented paragraphs. For now you can fake this effect by enclosing links in {{ic|<nowiki>'''</nowiki>}}.
+
::::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. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 03:56, 6 March 2016 (UTC)
  
-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
+
:::::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.
:* I moved this part to the separate section as this discussion is not directly related to "formatting bloat" but rather to unification of phrasing.
+
:::::Also +1 for the second part about recommendations.
:* Exact formatting depends on results of [[#Bold and italic]] discussion, so I propose to finish it before continuing this one.
+
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 6 March 2016 (UTC)
:>> objections to the whole idea are still taken into consideration
 
:Well, I have already understood reasons for deprecating installation instructions and modules loading at startup/daemons autostart. All this is performed only once and there are a lot of troubles with giving command line snippets for this. But what's wrong with starting/stopping daemons? I'd better suggest to allow usage of snippets for this purpose but only for other reasons than creation of whole "Starting xxx manually" section, containing only that single line of code. IMHO, it is usually enough to mention existence and purpose of daemon in given package and providing link to [[Daemon]]. All daemons behave similarly, interaction with them in Arch is really simple; there is simply no need for adding same sections with same contents for ''every'' article. If writing snippet is really required to maintain workflow of step-by-step guide, then there is probably no need for restricting it (the same for loading/unloading) modules.
 
:--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
 
::Eheh with "whole idea" I meant the idea expressed in the first paragraph, since I was asking for possible methods of applying it without apparently leaving room for objections. I admit it wasn't clear at all :) So, just to give you an answer, it would look a bit inconsistent to me to allow daemon starting/stopping instructions and not installation instructions, also because we should resort to using snippets like:
 
:::You must now start the '''whatever''' daemon:
 
:::{{bc|# rc.d start whatever}}
 
::Which looks redundant to me, unless you wanted to suggest something like:
 
:::Now run:
 
:::{{bc|# rc.d start whatever}}
 
::Which I like even less because it's not teaching anything, it just leads the inexperienced user to copy-paste the command, without thinking of what he's doing.
 
::If you had something different in mind, just give an example. -- [[User:Kynikos|Kynikos]] 18:20, 3 February 2012 (EST)
 
:::Again from [[PulseAudio]]:
 
:::{{Box||If the D-Bus system daemon is not already running, start it:{{bc|# rc.d start dbus}}<br>PulseAudio can be started with:{{bc|$ pulseaudio --start}}<br>Or if you use X11:{{bc|$ start-pulseaudio-x11}}}}
 
:::Lets break workflow:
 
:::{{Box||PulseAudio depends on '''dbus''' [[daemon]], so first run it.<br>PulseAudio can be started with:{{bc|$ pulseaudio --start}}<br>Or if you use X11:{{bc|$ start-pulseaudio-x11}}}}
 
:::What looks better? --[[User:AlexanderR|AlexanderR]] 00:37, 4 February 2012 (EST)
 
::::This argument seems rather circular. I fully support the last comment by Kynikos. And personally, I would combine the first two sentences in AlexanderR's second example to something like:
 
:::::Since PulseAudio depends on the {{ic|dbus}} daemon, [[Daemon|start]] dbus and then start PulseAudio:
 
::::~ [[User:Filam|Filam]] 22:43, 4 February 2012 (EST)
 
:::::Like this?
 
:::::{{Box||Since PulseAudio depends on the {{ic|dbus}} daemon, [[Daemon|start]] dbus and then start PulseAudio:{{bc|$ pulseaudio --start}}<br>Or if you use X11:{{bc|$ start-pulseaudio-x11}}}}
 
:::::[[Wikipedia:Looks|Looks]] nice, except usage of verb in link to [[daemon]] article: I [[Wikipedia:agree|agree]] with [[User:Vadmium]] about the fact that usage of such [[Wikipedia:WP:easter_egg|easter_egg]] links [[Wikipedia:can|can]] a bit annoying and sometimes even misleading.
 
:::::PS I am not going to challenge already reached agreement on deprecation of daemon instructions, so please consider adding something useful to [[#Quoting and underlining]] and [[#Bold and italic]] discussions, so that we can continue this one. --[[User:AlexanderR|AlexanderR]] 00:40, 5 February 2012 (EST)
 
  
==CSS updates==
+
::::::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.
The style of &lt;tt>, &lt;code> and &lt;pre> has recently been adjusted in the CSS to match that of code formatting templates.
+
::::::That is why explicitly defining what is good and what is wrong, whenever an issue is presented, is always pertinent here. I have [https://wiki.archlinux.org/index.php?title=Help%3AStyle&action=historysubmit&type=revision&diff=424477&oldid=423038 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 :)
 +
::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:20, 7 March 2016 (UTC)
  
I was wondering if now we should suggest using &lt;pre> and space-initial lines instead of [[Template:bc]] in order to avoid having to add numbered parameters or &lt;nowiki> tags when necessary. On the other hand, this may be seen as an incosistency since those hacks are still needed for its "sibling" templates ic, hc and keypress.
+
== Example usage ==
  
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:30, 4 May 2012 (UTC)
+
I recently removed a newly added example from [[Apple Keyboard]] ([https://wiki.archlinux.org/index.php?title=Apple_Keyboard&diff=470290&oldid=470270], [https://wiki.archlinux.org/index.php?title=Apple_Keyboard&diff=prev&oldid=470270], see also [[User_talk:Pypi#Apple_Keyboard]]).
 +
I generally prefer to avoid examples which I feel are covered elsewhere, since they can be prone to bit rot and linking to a page on the topic both encourages understanding and is more robust, however I can't find an "official" stand on this.
 +
Have I missed a section explaining proper usage of examples? If not, is there some other reasons for/against that kind of usage of examples? Would it be useful for the style guide to be adjusted to include some "rules of thumb" for dealing with examples?
 +
-- [[User:Pypi|Pypi]] ([[User talk:Pypi|talk]]) 21:17, 10 March 2017 (UTC)
  
:"Space-initial lines" are fine, but suggesting &lt;pre> usage after so much effort put into getting rid of it does not look logical. --[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
+
:You're right, we're not explicit about examples at the moment: I'd say currently the most related sections are [[Help:Style#Hypertext metaphor]] about content centralization, and [[Help:Style#Package management instructions]]/[[Help:Style#systemd units operations]] about examples only for those specific cases.
 +
:[[Help:Style#Hypertext metaphor]] allows (obviously) to write Arch-specific adaptations (examples?) of external generic documentation: by analogy (and coherence), this could be seen applicable to topic-specific adaptations (examples?) of instructions which are centrally (and generally) discussed in a "main" article. If we wrote a rule about examples, and perhaps we do need it, it should probably still be quite loose I think, and describe sort of a minimum level of complexity that the adaptation of generic instructions should have to be allowed in an article in addition to a link to the centralized article.
 +
:Regarding the specific reverted edit, I tend to agree with you, the example looked quite trivial, so I've tried to instead [https://wiki.archlinux.org/index.php?title=Apple_Keyboard&type=revision&diff=470393&oldid=470290 clarify] the paragraph.
 +
:— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:48, 11 March 2017 (UTC)
  
== Better structuring ==
+
==<s> Hypertext metaphor: Same-page section links </s>==
 +
 
 +
''[Moved from [[Talk:Python]] -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:38, 21 May 2017 (UTC)]''
  
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? --[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
+
Hmmm... I don't really want to correct ArchWiki admins, but I have a notice about [https://wiki.archlinux.org/index.php?title=Python&curid=5717&diff=477849&oldid=477841]. According to [[Help:Style#Hypertext metaphor]]:
: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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:04, 14 May 2012 (UTC)
+
* '''5th item:''' do not hide the {{ic|#}} symbol in same-page section links
::> ..merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with.
+
* '''9th item:''' we can see there a same-page section link in a middle of a sentence (last sentence in that item), and it's written as it is in section heading, starting with capital letter
::Sounds good. Note, that moving part of current content to templates can reduce overall size of all involved articles and possibly simplify further work. --[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
+
-- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 22:09, 20 May 2017 (UTC)
:See also [[#Help:Talk]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:11, 25 December 2012 (UTC)
 
  
== Is it suggested to use Template:AUR for links? ==
+
:My point was regarding the 3rd point of the same section: "...use a link label. Regular grammar rules apply..."
During checking [https://wiki.archlinux.org/index.php?title=Systemd&curid=10292&diff=201651&oldid=201634&rcid=283848 this edit] I have suddenly realized that I do not know whether usage of direct links to AUR is right or not. If yes, than why, if no &ndash; where is the official rule regarding this? --[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
+
:Anyway, this is a very blurry case so your nitpick is highly appreciated and we'll probably have to reformulate the rules to be less ambiguous.
:Actually this is the only rule proposed in [[Help talk:Style/Package installation]] that hasn't been enforced yet since we're still waiting for the resolution of {{Bug|28839}} which should hopefully be solved in the next AUR release.
+
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:45, 20 May 2017 (UTC)
:The particular case you've mentioned, though, is an implicit installation request, and should be subject to [[Help:Style#AUR packages]], with particular reference to the paragraph "You are granted the flexibility to adapt the wording to your specific article...".
 
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:52, 16 May 2012 (UTC)
 
  
== Lists of related links ==
+
::I think that the 5th point ("Do not hide the # symbol") only expands the 4th point and does not apply to the cases covered by the 3rd point. Historically, the 5th point [https://wiki.archlinux.org/index.php?title=Help:Style&diff=425124&oldid=424477 predates] both previous points, so the intention was slightly different. What do others think? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:49, 21 May 2017 (UTC)
Inspired by [https://wiki.archlinux.org/index.php?title=Sound_system&curid=10626&diff=201543&oldid=197917], 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. -- [[User:Kynikos|Kynikos]] ([[User talk: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. --[[User:AlexanderR|AlexanderR]] ([[User talk: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.  -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 04:50, 19 May 2012 (UTC)
 
  
== Definition of related link ==
+
:::Oh no, '''both''' 3rd and 4th items mean links to '''another''' acticles, not to the same one. 3rd is used when you mean some topic or term, otherwise 4th is used when you mean an article itself. So 5th item doesn't expand previous, it refers to the same article as opposed to 3rd and 4th.
Inspired by [https://wiki.archlinux.org/index.php?title=Boot_Debugging&diff=prev&oldid=201554], 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. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:09, 16 May 2012 (UTC)
+
:::Also I would like to say that it's a good solution not to hide {{ic|#}}, reasons are described in article. At the moment we must use capitalization like in section heading, there are two ways to resolve this:
:Few ideas:
+
:::* Make some changes in code so that we can use lowercase same-page section links even if section heading starts from capital letter, like it is for articles (ex. [[Python]] and [[python]])
:* Alternatives to software, described in article
+
:::* Leave it as is and use the same capitalization like it is in section heading, even if it will start from capital letter in the middle of a sentence
:* Methods and techniques alternative to ones described in article
+
:::While first option is more correct, I like second one too
:* Software <-> it's use case
+
:::-- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 14:02, 21 May 2017 (UTC)
:* software/technique <-> it's developer
 
:--[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
 
  
==Request to change recommended package installation style==
+
::::After discussing this a couple of hours with my lawyer, we decided that my preferred interpretation is the same as Lahwaacz (if I understood it right): points #3 and #4 also apply to same-page links, and therefore, after we introduced them, point #5 became only an extension of point #4. That said, I'm pretty sure that I've contradicted myself even very recently when adding or editing some same-page links.
 +
::::@Kycok: you can try to propose a patch to MediaWiki, but making same-page links first-letter-case-insensitive may be considered backward incompatible and thus rejected.
 +
::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:57, 22 May 2017 (UTC)
  
I find the existing recommended package installation instructions to be unsightly because of excessive blue links (see [[Help:Style#Package_management_instructions]]), and I feel that my proposed examples significantly boost readability of articles.
+
:::::(Besides, the MediaWiki code regarding section anchors is very ugly and [https://phabricator.wikimedia.org/T20431 broken for years]...) -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:49, 22 May 2017 (UTC)
I propose changing the official recommendation to the following:
 
Install {{pkg|package}} from the official repositories.
 
or my lesser preferred:
 
Install {{pkg|package}}, available in the official repositories.
 
The three primary changes are:
 
# removing the link to [[pacman]]
 
# removing the link to [[Official Repositories]]
 
# changing "Official Repositories" to lowercase
 
I see no reason why a link to [[pacman]] and [[Official Repositories]] is necessary on every article. If an administrator of an Arch box does not know how to install packages or know what the official repos are, then god help them and any other users on that box because they are in for a poor experience. The [[Beginners' Guide]] makes it very clear how to install packages and that the user must be familiar with pacman and how pacman operates.
 
  
For the [multilib] example on [[Help:Style]], I think it is important to continue mentioning that a package is in [multilib], and I still support linking to [[multilib|&#91;multilib&#93;]]. I propose the following for a [multilib] package:
+
:::::So what is right? For now Lahwaacz's edit is reverted [https://wiki.archlinux.org/index.php?title=Python&diff=477865&oldid=477849] by Silverhammermba -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 22:14, 25 May 2017 (UTC)
Install {{pkg|package}} from the official [[multilib|&#91;multilib&#93;]] repository.
 
-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 20:02, 15 June 2012 (UTC)
 
  
:As for the wording itself, "Install package from the official repositories" sounds indeed slightly better than the current one, so I think we can replace it. The same goes for the multilib example.
+
::::::I've done [https://wiki.archlinux.org/index.php?title=Help%3AStyle&action=historysubmit&type=revision&diff=478391&oldid=478266 this] and [https://wiki.archlinux.org/index.php?title=Python&type=revision&diff=478392&oldid=477884 that], thoughts? [https://wiki.archlinux.org/index.php?title=KDE&curid=1196&diff=478317&oldid=478177 This] other edit also caught my attention, note how the amended link is next to another pure section link. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:39, 27 May 2017 (UTC)
:About the capitalization of "[Oo]fficial [Rr]epositories" I'm completely neutral, so unless somebody has opposing arguments I'm updating it, although using one or the other form is still equally acceptable.
 
:The links are clearly the main topic of this discussion: actually none of them is explicitly mandatory yet, so, just as a start, I'd like to state that at least the link to the package is needed.
 
:About the links to [[pacman]] and the [[official repositories]], we could make them optional, but recommend to use them in pages that may be targeted to less experienced users (e.g. articles directly linked from the [[Beginners' Guide]] like [[Xorg]] and so on).
 
:As always, it would be helpful to read somebody else's opinion ^^
 
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:04, 16 June 2012 (UTC)
 
  
::I'd be fine with recommending that the links be used on pages linked from the [[Beginners' Guide]], etc. I just find it bothersome seeing links to [[pacman]] on every wiki article. :)
+
:::::::I think such rules is very confusing. Wiki-writers will be forced to '''loose some time''' to guess which one matches our rules. And absolutely right such rules are opposite to '''Keep it simple'''! -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 20:56, 29 May 2017 (UTC)
::And I fully support making [[Template:Pkg]] mandatory.
 
::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 02:02, 17 June 2012 (UTC)
 
  
:::We are indeed familiar with pacman so to most people who know how to use talk page, the [[pacman]] link is not needed. But we should remember lots of people can not remember all pacman installation instruction after reading [[Beginners' Guide]]. When Arch wiki change from {{ic|pacman -S <package name> }} to current style, many users did get lost and asking what to do even when the link is provided. Remove installation link will make Arch learning curve steeper.
+
::::::::How would you like to see it handled then? From your two options above, modifying the code is anything but easy and leaving it as it was is not less confusing at all, otherwise we would not be having this discussion. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:29, 30 May 2017 (UTC)
:::-- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 11:03, 18 June 2012 (UTC)
 
  
::::I understand your concern, but I honestly don't know how Arch users cannot remember such a simple and often used procedure. Users should know to reference the [[Beginners' Guide]] or the [[pacman]] wiki articles if they forget basic pacman operations. To mitigate this unfortunate situation, I'm strongly leaning towards making some redirects to the pacman article. Notably [[install]] and [[install package]], which I expect would be the most frequently used search terms if someone doesn't know how to install a package.
+
:::::::::Ok, I also like [https://wiki.archlinux.org/index.php?title=KDE&curid=1196&diff=478317&oldid=478177 this]. Let's simply just make it mandatory to '''show''' an anchor for same-page links. Examples:
::::If we can create some good redirects for common searches like that, would your concerns be addressed (or at least partly)?
+
:::::::::* See [[#Prefer linking to the article than to the package]] section ''(without label)''
::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 23:03, 18 June 2012 (UTC)
+
:::::::::* In most cases [[#Prefer linking to the article than to the package|#prefer linking to the article than to the package]] ''(with label having non-modified section heading, but lowercase)''
 +
:::::::::* Rather than linking a package, [[#Prefer linking to the article than to the package|#prefer linking to the article]] ''(with modified label, containing mandatory anchor)''
 +
:::::::::All my examples are very similar to Kynikos's edits, but [https://wiki.archlinux.org/index.php?title=Help%3AStyle&action=historysubmit&type=revision&diff=478391&oldid=478266 there] we must use {{ic|<nowiki>We have [[#Hypertext metaphor|#style rules]] for links</nowiki>}} rather than {{ic|<nowiki>We have [[#Hypertext metaphor|style rules]] for links</nowiki>}}. And, of course, [https://wiki.archlinux.org/index.php?title=Python&curid=5717&diff=477849&oldid=477841 that] one is OK but we must add an anchor into label.
 +
:::::::::-- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 11:11, 30 May 2017 (UTC)
  
::::: Adding redirects is a good idea. Add all Arch users indeed remember it because who can not remember them before finishing reading [[Beginners' Guide]] will turn to other distro. :)  I am not objecting here. However I did remember when change away from {{ic|# pacman -S}} command line, many people object and complain. Had you read [[#Style vs. Usability]] above yet? We had a hard time to find a balance between different concerns for this style. Change it will stir things up again.  
+
::::::::::What if for the moment we do explicitly mention the {{ic|<nowiki>[[#Anchor|#Label]]</nowiki>}} syntax, but only as ''optional'', and see if it catches on? Besides the example above, I don't remember ever seeing it before here. Since point #4 now has a subpoint #4.1, this suggestion could fit well in an analogous #3.1 subpoint. [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:41, 30 May 2017 (UTC)
:::::  -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 09:30, 19 June 2012 (UTC)
 
  
::::::Ok, I've reworded the section, but I've decided we can't really get rid of links to [[pacman]]: installation instructions have been a very controversial style topic, and the current solution is some kind of a compromise to which I think we should adapt for the sake of consistency.
+
:::::::::::Yup, you can do this. But I think it would be great to show {{ic|#}} each time link refers to the same-page section -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 14:59, 30 May 2017 (UTC)
::::::About those redirects, creating them can be helpful, even though there's a <u>little</u> (I guess negligible) chance that somebody following them is instead looking for an article on how to install Arch and not a single package.
 
::::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:48, 21 June 2012 (UTC)
 
  
:::::::Do we have the ability to make disambiguation pages, similar to Wikipedia, that we can use for the [[install]] redirect?
+
::::::::::::If you read "In most cases #prefer linking to the article than to the package", how do you pronounce the "#" token? Probably nowise, you just skip it, because it is not part of the grammatical structure of the sentence. On the contrary, in "See #Prefer linking to the article than to the package" the "#" token is not excess, it is part of the designation of the object that should be seen. It can also be read as "paragraph" or "section" -- in fact, [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Linking#Section_links Wikipedia] uses "§" instead of "#" in link labels via its convoluted templates.
:::::::I'm going to create a redirect for [[install package]] and [[install packages]] now.
+
::::::::::::I think that when it comes to the 3rd point, the "#" symbol is more distracting than enlightening. Also if the "#" symbol was shown everywhere as you propose, there wouldn't be much sense anymore to handle the capitalization and interwiki prefixes separately by points 3 and 4. Consequently the rules would be simpler, but I think it would not produce a simple markup nor well-readable text, which is the point of having the rules in the first place.
:::::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 13:58, 21 June 2012 (UTC)
+
::::::::::::Can't we resolve the situation by just adding a ''justification'' to points 3 and 4 to ease the understanding of the rules?
 +
::::::::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:07, 30 May 2017 (UTC)
  
::::::::Another complaint I have regarding the current package installation instructions is how much typing must be done simply to state "Install blah from the blah". It would be much easier/better, for several reasons, to create a package installation template which does this for us. I imagine it would function quite similarly to [[Template:Pkg]] except that it would put all of the verbiage around the package link. So, for example, using <nowiki>{{PkgInst|xmonad}}</nowiki> would produce the following auto-magically:
+
:::::::::::::Sure, adding a justification would help, that would be enough to close this discussion for me.
::::::::{{bc|[[pacman|Install]] the package {{Pkg|xmonad}} from the [[Official Repositories|official repositories]].}}
+
:::::::::::::However just to give you a reply, the "#" token would not be pronounced just like the arrow icon next to external links such as in "In most cases [[w:Prefer|prefer]] linking to the article", which is instead allowed (because automatic). Even if a #Label syntax was allowed (at user's discretion) or enforced, I think that regulating same-page links separately in points 3 and 4 would still make sense because it would make it clear that using a label when referring to the section itself (not the topic) isn't allowed.
::::::::I don't have much preference for this proposed template's name. I initially kept the name short (e.g. <nowiki>{{Pi|xmonad}}</nowiki>), but I didn't want people to confuse that with [[Wikipedia:Pi|pi]]. I went with <nowiki>{{PkgInst}}</nowiki> in my example because it is clearly different from [[Template:Pkg]], but the similarity to/inspiration from [[Template:Pkg]] is hopefully obvious.
+
:::::::::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:11, 31 May 2017 (UTC)
::::::::
 
::::::::Because this only deals with official packages, it should be appropriate to create one for AUR packages as well. I propose that <nowiki>{{AURInst|opennebula}}</nowiki> would produce the following:
 
::::::::{{bc|[[Arch_User_Repository#Installing_packages|Install]] the package {{AUR|opennebula}} from the [[Arch User Repository|AUR]].}}
 
::::::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 14:52, 21 June 2012 (UTC)
 
:::::::::Let's leave [[Install]] uncreated for the moment: somebody may use it in installation instructions ([[Install]] {{pkg|package}} ...) and it would be confusing if it pointed to a disambiguation page.
 
:::::::::About the installation template, it has been proposed already in the past, and just like other similar ideas (adding daemons to DAEMONS etc.) it has been discarded because it could be applied only in a subset of the cases that require the installation of packages: you couldn't use it when there's more than one package to install, you couldn't use it when the installation request has to be integrated in a longer, more complex sentence. Besides, writing an installation sentence is not something you have to do several times a day, and in any case it takes about 10 seconds to write it each time, I don't think it would give a noticeable advantage. Last thing - but this is just a <u>personal</u> feeling - it would give me a sense of unnecessary complication, not in the Arch Way :)
 
:::::::::This discussion is open, however, more ideas are welcome.
 
:::::::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:59, 24 June 2012 (UTC)
 
  
== Daemon operations ==
+
:::::::::Also let's expand ''Hypertext metaphor'' section's 3rd and 4th items like this:
I'd like to suggest you / we add wording & style suggestions for systemd daemon operations to [[Help:Style#Daemon_operations]]. --[[User:Stefanwilkens]]
+
:::::::::* If a link refers to the term or topic described on the target page '''(including same-page section links)'''
 +
:::::::::* If an internal/interwiki link '''(including same-page section links)''' refers to the target page
 +
:::::::::As you can see, it was not so clear for me ^_^
 +
:::::::::-- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 11:11, 30 May 2017 (UTC)
  
:Agreed, can you start with an example of suggestions? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:58, 3 October 2012 (UTC)
+
::::::::::Those rules are starting to be quite complex, I'd like to avoid adding a clarification in parentheses, what about [https://wiki.archlinux.org/index.php?title=Help%3AStyle&type=revision&diff=478670&oldid=478391 this]? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:41, 30 May 2017 (UTC)
::Considering that giving direct examples that can be copy pasted is deprecated, I would suggest something like this:
 
::Use [[Systemd#Using_Units|systemctl]] to enable <servicename> with <servicefile> during boot.
 
::{{Note|Use [[Systemd#Using_Units|systemctl]] to enable GDM with {{ic|gdm.service}} during boot.}}
 
::Or the more to the point:
 
::<Action> <servicename> with <servicefile> using [[Systemd#Using_Units|systemctl]].
 
::{{Note|Start GDM with {{ic|gdm.service}} using [[Systemd#Using_Units|systemctl]].}}
 
::{{Note|Enable GDM at boot time with {{ic|gdm.service}} using [[Systemd#Using_Units|systemctl]].}}
 
::Upon review of this, it seems that we may only have to adjust the references to rc.d and the old DAEMONS array from [[Help:Style#Daemon_operations]] and replace it with instructions fitting to systemd. For example:
 
:::'''Daemon operations'''
 
:::* The standard phrasing is a simple list of the daemons involved, possibly remarking dependencies or conflicts with other daemons, and a link to [[Daemon|Daemon]].
 
:::* If a required action is not covered in [[Daemon|Daemon.]], it is acceptable to provide an example. Such an example should make use of the {{ic|systemctl}} command and provide a listing of the service files involved.
 
:::* The Beginners' Guide and its subpages are the only exceptions to the rules above.
 
::Just suggestions to get the ball rolling, nothing is worse that outdated documentation. --[[User:Stefanwilkens|stefanwilkens]] ([[User talk:Stefanwilkens|talk]]) 18:25, 14 October 2012 (UTC)
 
  
== Help:Talk ==
+
:::::::::::It's OK -- [[User:Kycok|Kycok]] ([[User talk:Kycok|talk]]) 14:59, 30 May 2017 (UTC)
  
Here is a draft structure for [[Help:Talk]], it will include discussion information in both [[Help:Style]] and [[Help:Editing]]. Please give your advice.
+
::::::::::::+1. Is the lawyer still squatting on this case or can it be closed? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:19, 12 August 2017 (UTC)
  
* Introduction
+
:::::::::::::Technically there's the branch above still open, about an optional {{ic|<nowiki>[[#Anchor|#Label]]</nowiki>}} syntax, there's 1 vote to make it mandatory, 1 to only mention it as optional, and 1 against. I don't feel very strongly about it though, I'll close this, so there's 1 more week for somebody to reopen and state their opinion, otherwise things will stay as they are. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:15, 13 August 2017 (UTC)
** What is a discussion page.  
 
** What kind of content should be added.
 
** What kind of content should be avoided.
 
* Start new discussion
 
* Discussion guideline
 
* Close a discussion
 
* Remove a discussion
 
-- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 11:51, 25 December 2012 (UTC)
 
  
:Looks like a very good plan, go for it! Once the page is ready, the rules can be removed from [[Help:Style]] and [[Help:Editing]], and replaced with a link to [[Help:Talk]].
+
== Rule about optional dependency  ==
:Finally I'm mentioning also here that this project can be considered part of [[Help talk:Style#Better structuring]].
 
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:10, 25 December 2012 (UTC)
 
  
== Implicit links ==
+
{{Comment|A topic started in [[Talk:BackupPC]], the contributor want to mention another optional dependency in the page. Should we define the rule about it?
How would you like a rule similar to:
+
My opinion is that: Optional dependency should not be mentioned. Because it is hard to check and maintain in the wiki. Just read pacman log which is correct and current.--[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 23:50, 22 October 2017 (UTC)  }}
  
''Try to avoid implicit links when possible. For example prefer "See the [[systemd]] article for more information" instead of "See [[systemd|here]] for more information".
+
:True, we'd better regulate this, but it can get tricky... For example we mention lots of optional packages in [[File manager functionality]], maybe we can discourage simply systematically listing all optdepends but allow it if there's something more to say about them? I don't know right now... -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:49, 24 October 2017 (UTC)
  
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:41, 5 May 2013 (UTC)
+
:: OK, I think we can put it as not recommended but not forbiding it. --[[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 02:03, 25 October 2017 (UTC)

Latest revision as of 02:03, 25 October 2017

Read this first

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

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

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

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

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

Better structuring

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

Actually this idea would overlap with a larger project I've had in mind for some time now: merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with. However I'd like to plan this carefully in advance, as it involves several pages, otherwise we risk increasing the mess instead of reducing it. -- Kynikos (talk) 10:04, 14 May 2012 (UTC)
> ..merging editing and style guidelines consistently everywhere, and split them in several articles based on the various topics being dealt with.
Sounds good. Note, that moving part of current content to templates can reduce overall size of all involved articles and possibly simplify further work. --AlexanderR (talk)
See also #Help:Talk. -- Kynikos (talk) 16:11, 25 December 2012 (UTC)

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

But with that reasoning nothing would be left in Category:Help ^^ I know you're making the comparison with Wikipedia:Wikipedia:MoS, I'm not aware of Wikipedia's policy about the scope of the two namespaces (but I've seen many Wikipedia:... articles under the Help category there, either directly or under a descendant, while Category:Wikipedia seems to contain articles that talk about Wikipedia in an encyclopedic way, and they're not in the Wikipedia's namespace).
In our wiki, I think we tend to have a correspondence (or redundancy) between the Help and ArchWiki namespaces and categories: Help is more for articles that are meant to show editors the proper way to contribute (and so yes, for coherence I'd move ArchWiki:Contributing there instead), and ArchWiki is more for articles that are about the wiki itself (not Arch Linux), including the pages that are used by the staff to ease maintenance. Also note that Category:Help is a child of Category:ArchWiki.
In short, I'd leave Style where it is, and maybe I'd improve the correspondence between namespaces and categories, thus moving Table of contents under ArchWiki:, together with ArchWiki Translation Team, and then there are also some uncategorized titles in Special:PrefixIndex/ArchWiki:, we could consider categorizing them.
-- Kynikos (talk) 10:20, 25 August 2014 (UTC)

Related links

See also or Related in Article Summary?

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

See also #Article summary templates.

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

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

Advantages of links in See also:

  • There is more space for link descriptions
  • It is likely one will read or skim the article before actively looking for additional reading material. This naturally leaves the reader at the end of the article. It is convenient for the reader in this case if links are at the end of the article. James Eder 00:29, 22 September 2011 (EDT)
  • It seems more common (elsewhere) to have links at the end of articles (when they are not inline with the rest of the text). Following common convention it may be better from a usability perspective. James Eder 00:29, 22 September 2011 (EDT)
    Especially for people used to Wikipedia, which uses the same wiki software. Vadmium 11:12, 26 October 2011 (EDT).
  • I am not sure how much we care about this but it having the links at the end could be more friendly to small form factor screens and screen readers. James Eder 00:29, 22 September 2011 (EDT)
  • As a section, "See also" gets its own TOC entry granting easy access from near the top of the article. Alternatively one may press the END key. James Eder 00:29, 22 September 2011 (EDT)
  • More formatting options here than in summary. Emiralle 13:12, 15 October 2011 (EDT)
  • More inclined to put external, or less closely related stuff here. Emiralle 13:12, 15 October 2011 (EDT)
  • See also section would not be skipped if you start reading the main text sequentially from the top. Vadmium.
  • [add more advantages...]

Advantages of links in Article Summary:

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

Lists

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

> I'd prefer having complete lists of related articles even if that implies duplicating some of them
I'd prefer this way as well. Sadly listing all related articles may occupy most of vertical space, so there should be clear guidelines regarding choise of related links. And editors often don't have time to read even Help:Style... On the other hand, defining simple rule like "only links not present in text" can eliminate the very requirement for any additional rules. --AlexanderR (talk)
"only links not present in text" is too strict I think. Related links make some page more "visible" to readers. For example, I often click on them to learn more info about the same topic. But to be honest, I rarely click on the "in page links" even the links shown clearly in "See Also". They are much harder to be found and clicked. -- Fengchao (talk) 04:50, 19 May 2012 (UTC)

Definition

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

Few ideas:
  • Alternatives to software, described in article
  • Methods and techniques alternative to ones described in article
  • Software <-> it's use case
  • software/technique <-> it's developer
--AlexanderR (talk)

List of Applications and See also

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

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

I support 1. and 2. except for the dots at the end of descriptions, which I would require instead, since sometimes the App template has long descriptions, even made of several sentences, and including all the puntuation only omitting the final dot would look weird to me.
About 3. I don't understand what you mean, can you be more specific?
However I'm also wondering if these rules should be hosted here (if they refer to the use of Template:App) or in Talk:List of Applications (if they refer only to List of Applications and subpages).
-- Kynikos (talk) 12:23, 26 May 2013 (UTC)
About 3: I just mean that a section like Aria2#See_also must have capitalized letters and no dots (or whatever the standard would be).
About the hosting place: page like CD_Burning#Burning_CDs_with_a_GUI or Conky#AUR_packages are not directly related to List of Applications, so I think it is worth to host a rule here. Plus this rule would apply also to any other list, like E4rat#Process --Flu (talk) 16:53, 26 May 2013 (UTC)
Still about 3: I see, usually See-also links have much shorter descriptions, in that case I would apply a no-dot policy. Still open to more opinions though.
Hosting place: a rule about lists of applications would probably best fit in Template:App, also in light of my plans to decentralize style rules in general. A rule about See also sections would instead fit this guide indeed, at least for the moment.
-- Kynikos (talk) 13:17, 28 May 2013 (UTC)

One link to the package in a paragraph is enough

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

First thing, probably in the title you mean links to articles in general, not only packages, right?
However, I definitely agree, I guess we could extend the rule to the same section or even the whole article, but I'd like to exclude some cases, like "See also" sections (see #Lists of related links), and to make the rule compatible with Help:Style#Official packages and similar.
-- Kynikos (talk) 15:11, 22 May 2013 (UTC)
Just a reminder: this is affected by Help:Style/Formatting_and_Punctuation#First_instances, not sure if it sould be mentioned directly on Help:Style. -- Lahwaacz (talk) 16:35, 1 September 2013 (UTC)

git/vcs/source builds

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

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

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

(oh no, another time) -- Flu (talk) 21:15, 2 June 2013 (UTC)
IMHO 'make && make install' instructions should go.
I have nothing against describing different AUR packages, whether VCS or not. PKGBUILDs are sometimes pretty complex and it's not obvious what's the difference between the various AUR versions of a package - if any.
Please sign your talk page edits Help:Discussion#Join_a_discussion. -- Karol (talk) 20:21, 2 June 2013 (UTC)
Yes, manual compilation instructions can be removed, but only when an AUR package is available. A rule may be added for this.
No, please don't remove links to "alternative" versions of packages in AUR; treat every AUR package as the others, there are not AUR packages more "official" than others: if they all install the same application, they _can_ (i.e. not _must_) be mentioned in the same article.
-- Kynikos (talk) 05:05, 3 June 2013 (UTC)
Just mentioning a recent related example, [5], that I consider perfectly reasonable. -- Kynikos (talk) 08:10, 12 June 2013 (UTC)

Distinguish fragment identifier interwiki links?

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

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

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

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

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

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

Talking of distinguishing links, external https links are not distinguished either:
http
https
Perhaps a bug?
-- Lahwaacz (talk) 06:10, 10 October 2013 (UTC)
About the little icons next to links, I guess we could do it easily with CSS attribute selectors in the skin files.
About the https icon in particular, it looks it was disabled on purpose for some reason: [7] (line 67) I'd be curious to know why.
Of course to implement all this, a bug report should be opened and very likely patches should be prepared, so if you think you have the time to work on it, the project is at [8] with links to clone the repo. I'd be interested in giving a hand of course :)
-- Kynikos (talk) 09:53, 10 October 2013 (UTC)
Thanks for pointing me to the right direction, here's the commit about the https links: [9].
Let's see if I can get to this again this weekend...
-- Lahwaacz (talk) 15:05, 10 October 2013 (UTC)
I sent an email to Pierre about the commit in November and did not receive any reply, so I submitted a bug report: FS#38769 - hopefully it won't be missed. -- Lahwaacz (talk) 16:00, 2 February 2014 (UTC)
We'll see, I've submitted a patch, but unfortunately wiki bugs, even if easy to fix, have a long life... -- Kynikos (talk) 10:17, 3 February 2014 (UTC)
Interesting, the https links are now sometimes equipped with a lock icon. It seems that some domains are excluded by the following CSS (which I got with the help of Firebug):
#bodyContent a.external[href^="http://archlinux.org"],
#bodyContent a.external[href^="http://www.archlinux.org"],
#bodyContent a.external[href^="http://wiki.archlinux.org"],
#bodyContent a.external[href^="http://aur.archlinux.org"],
#bodyContent a.external[href^="http://bbs.archlinux.org"],
#bodyContent a.external[href^="http://bugs.archlinux.org"],
#bodyContent a.external[href^="https://archlinux.org"],
#bodyContent a.external[href^="https://www.archlinux.org"],
#bodyContent a.external[href^="https://wiki.archlinux.org"],
#bodyContent a.external[href^="https://aur.archlinux.org"],
#bodyContent a.external[href^="https://bbs.archlinux.org"],
#bodyContent a.external[href^="https://bugs.archlinux.org"] {
    background: none repeat scroll 0 0 rgba(0, 0, 0, 0);
    padding-right: 0;
}
Another interesting thing about this is that I could not find the snippet anywhere in the git...
-- Lahwaacz (talk) 08:44, 14 December 2014 (UTC)
Eheh maybe you should have looked at Special:RecentChanges :) (still working on it, this may have numerous applications/consequences) -- Kynikos (talk) 08:51, 14 December 2014 (UTC)
Well that is the last place I would search in, mystery solved. Thanks for testing the workaround, you surely got me on that one. -- Lahwaacz (talk) 09:35, 14 December 2014 (UTC)

Problem with keyboard keys style

I could use some help with Keyboard Shortcuts:

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

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

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

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

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

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

(I don't wanna know where you've downloaded the font you're using with your browser... XD )
Oh well, even though Ctrl+Alt++ was (luckily?) outdated in that context, that's certainly a big flaw in the style rule... What do we want to do, switch to the Ctrl+Alt++ format? It would invalidate many of the style edits that have been done in the last months, but a bug is a bug ^^ Any better ideas?
About variable combinations, maybe we can just give some examples but leave the choice up to the editor?
-- Kynikos (talk) 13:48, 17 December 2013 (UTC)
I would not change the rule for just one shortcut (resp. two: Ctrl+Alt+-), converting it back would be really exhausting. If another instance appears, I'd create an exception for it. Or, even better, just link to an external documentation :P
Regarding the second problem I agree with leaving it up to the editor. Examples could be:
  • press Alt+. or Alt+_
  • press Ctrl+Alt+FN to switch to the N-th virtual console
i.e. basically use the full, expanded form or the pseudo-variables.
-- Lahwaacz (talk) 22:12, 18 December 2013 (UTC)
Well, let's just suspend this discussion until a similar problem is found again then, if ever. I'll think about closing it next time I'll come here to do some general clean up. -- Kynikos (talk) 10:25, 19 December 2013 (UTC)
Putting spaces around the + character would mitigate some of the confusion in the example Lahwaacz pointed out, but this would unfortunately require a lot of work to bring everything up to a new standard.
-- Jstjohn (talk) 02:32, 11 January 2014 (UTC)
Um... Ctrl + + doesn't look much clearer than Ctrl++ to me, if one day we'll need to change the rule for keys, we'll better do it the safest way, which probably is Ctrl++, since as you point out it's going to be "a lot of work" in any case. -- Kynikos (talk) 08:51, 12 January 2014 (UTC)

kbd tag

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

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

Grammar errors throughout Help:Style

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

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

It would be awesome if you could fix those errors, it will also be a good chance for me to improve my English: the article is unlocked now. Just make sure not to alter the explicit and implicit meaning of rules, e.g. [12] ;) -- Kynikos (talk) 05:16, 12 January 2014 (UTC)
I have a general question: what are the rules for using mdash ("—") vs. ndash ("–") in English literature? Is there supposed to be a space around them or not?
(I did not intend to challenge your work, I'm just curious - the rule is very likely to be different from those used in Czech...)
-- Lahwaacz (talk) 20:57, 11 February 2014 (UTC)
There is not supposed to be a full space around the em dash ("—") or the en dash ("–"). Ideally, the em and en dashes will be surrounded with a hair space, which is just wide enough to put a one pixel space between the dash and the adjacent characters, which makes it easier to read because the dash doesn't look like it's part of an adjacent character. I did not put hair spaces in my edits because I generally find it tedious to do.
As for when you should use the em dash vs. the en dash... the em dash is used for large pauses in speech or for side notes — notice the hair spaces around these em dashes — and the en dash is used for numeric ranges (e.g. 47 – 83).
The hyphen looks similar to the en dash ( - –  ← hyphen on the left, en dash on the right), but the hyphen is only supposed to be used between certain compound adjectives and nouns.
There's also the minus sign ("−"), which looks very much like an en dash ( − –  ← minus sign on the left, en dash on the right). It should only be used in mathematical formulas or when writing negative values (e.g. 47 − 83 = −36)
If you haven't noticed, I'm a bit of a typography geek. haha
-- Jstjohn (talk) 02:02, 13 February 2014 (UTC)
Thanks for this nice explanation! It is a shame that the wiki markup language does not have special syntax for this punctuation, entering the HTML codes is really PITA. There are some packages for LaTeX that translate "--" into en dash and "---" into em dash. But typographically, TeX is on completely different level than wiki. -- Lahwaacz (talk) 08:08, 13 February 2014 (UTC)
We could possibly add MediaWiki templates for the em dash and en dash. Adding a template for the minus sign seems like it might be overkill. For example, {{emdash}} or {{em dash}} would output &.#8202;&.mdash;&.#8202; (without the dots, of course)
-- Jstjohn (talk) 23:59, 18 February 2014 (UTC)
I say let's keep it simple, who would use those templates in practice? They would also go against our decision to e.g. use typewriter quotes instead of typographic, see Help:Style/Formatting_and_Punctuation#Quote_marks. As Lahwaacz mentioned, a wiki is not TeX, it's designed to keep source and rendered text similar, and punctuation templates would reduce readability of source text. MediaWiki takes care of translating source text characters into HTML entities when needed, and in my view we shouldn't try to bypass such feature except when really needed (see also Help:Template#HTML_entities). If you want to use some particular punctuation marks, IMHO you should enter them directly, possibly assigning them as special combinations to your keyboard map. -- Kynikos (talk) 06:00, 19 February 2014 (UTC)
Regarding source text readability, why not just input the unicode character itself — like this? (Notice that it works also for the hair spaces, though they are not very "hairy" in the source...) -- Lahwaacz (talk) 07:01, 19 February 2014 (UTC)
I would use those templates. :)
I agree that {{em dash}} would be less readable than a directly-entered "—" character; however, {{em dash}} is a lot more readable than &.#8202;&.mdash;&.#8202; (without the dots), which is why I support the idea. I feel that directly-entered em dashes with the surrounding hair spaces (using the Unicode characters directly) is less maintainable than {{em dash}} because subsequent edits may remove one or both of the hair spaces without editors realizing that they did so.
-- Jstjohn (talk) 01:14, 20 February 2014 (UTC)
Ok, I admit that to me all this seems overly complicated as in not Simple, however, as Help:Style/Formatting_and_Punctuation#General_rules says, "for cases not covered in this guide, Wikipedia:Wikipedia:Manual of Style is the authority reference", and to me it seems very sensible to stick with that rule instead of attempting to create our own punctuation guides. In particular, Wikipedia:Wikipedia:Manual_of_Style#Punctuating_a_sentence_.28em_or_en_dashes.29 says "do not use spaced em dashes", while they do have a {{spaced ndash}} template, so IMO that's what we should follow. -- Kynikos (talk) 14:21, 20 February 2014 (UTC)
If we decide for the templates way, which subset of the Wikipedia formatting and function templates should be used on ArchWiki?
I don't like the templates either, this had better be solved upstream (either directly in the parser core or via an extenasion. The only mention of upstream dealing with this I found is this rather old discussion, so it's probably going nowhere. (Extending the parser should not be that hard, a couple of regular expressions should do it for the dashes -- I'm surprised that it's not done yet...)
Suggestions so far: 1) use HTML entities (such as &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)

References

Rule suggestion: reference links

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

The suggestion:

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

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

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

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

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

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

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

Citations and reasoning

Currently we have the following clauses on referencing content:

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

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

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

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

So, to put it in other words, is your proposal to aggregate all the bits from the 4 linked sections above into a unified section (I guess "Citations and reasoning" would also be the title you have in mind) and expand it with your last 3 points? I do support elaborating on this very important style issue, but wouldn't the new section overlap too much with Help:Style#Hypertext metaphor? Maybe we could more simply expand that, or split its items into subsections? Also I think that it still makes sense to keep reminding to link to bug reports directly in Help:Style#"Known issues" sections and Help:Style#"Troubleshooting" sections, so perhaps those sections should display a link to the new centralized guidelines.
If I haven't interpreted correctly what you had in mind, I'll wait for your initial draft below to understand better.
Kynikos (talk) 03:03, 8 June 2015 (UTC)
For Troubleshooting, I propose to simply expand Help:Style#Hypertext metaphor with a paragraph on involving upstream, or invonvovled Arch projects. We've been encouraging this for some time, and it seems to works well enough. See below. -- Alad (talk) 20:26, 5 November 2015 (UTC)
It looks like I forgot what was written above ... -- Alad (talk) 20:30, 5 November 2015 (UTC)

Positioning of numbered external links

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

Slashes in titles

Localized subpages

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

My original intention behind the Title/Sub-page (Language) style was to make it safer for Wiki Monkey to detect the language of an article by just looking at the end of the title, but I guess I might as well look for the tag anywhere in the title, and realistically it wouldn't give any troubles, so when FS#39668 is implemented we can indeed change the rule and rename the affected articles. The language namespaces way is still my long-term-preferred solution though. -- Kynikos (talk) 01:40, 5 April 2014 (UTC)
The Title (Language)/Sub-page format will not work with interlanguage links. See for example Help:Style/White space and its link to the Russian page. -- Lahwaacz (talk) 16:05, 30 August 2015 (UTC)
FS#39668 now status implemented. Closed by Doug Newgard (Scimmia) Sunday, 24 July 2016, 05:43 GMT. -- PiroXiline (talk) 17:14, 22 September 2016 (UTC)

Preferred subpage method

Options:

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)

Lists, colons, indentation

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

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

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

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

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

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

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

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

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

I agree, look at this page broken by a "Translateme" template inside a list. axper (talk) 08:30, 29 June 2014 (UTC)
I've used the * some text {{Note|text to note}} trick several times myself, but after reading Lahwaacz's reasoning I won't anymore (when I'll remember), as I agree completely: we should aim for the cleanest source text that results in the wanted appearance of the page. If the generated HTML is not correct it's indeed a problem of MediaWiki, we shouldn't try to work around it.
Yes, we should encourage preferring paragraphs or even subsections to lists with long/complex items. About ordered lists, manual numbering looks quite ugly to me, and I feel the same about mixing HTML and wiki markup: I think most (hopefully all) of the cases where it would be needed are better solved in some other way. For example in the QEMU case reported above, the items of that list don't need to be numbered, bullets or subsections should be used. Another notable example is Arch_packaging_standards#Submitting_packages_to_the_AUR, where bullet points would be more appropriate.
-- Kynikos (talk) 10:49, 30 June 2014 (UTC)
Maybe we can create a template for items? I mean something like this:
* First item
* Second item
* {{Template_name|
Third item

{{Note|bla-bla}}

Bla-bla-bla
}}
*Fourth item
And there will be a good readability of wikitext as well as correct indentations
-- Kycok (talk) 07:47, 4 July 2014 (UTC)
This still seems too complicated to me. -- Kynikos (talk) 06:15, 5 July 2014 (UTC)
I don't think such template is possible, the blank lines would still break the list (test it for Template:bc without <nowiki> tags). All the templates for lists on Wikipedia work the other way, template arguments are turned into list items. See for example wikipedia:Template:Ordered list, but it relies on Lua scripting, which is not available on Arch wiki. -- Lahwaacz (talk) 09:42, 5 July 2014 (UTC)

See also links

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

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

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 [16]: translated to the "modern" wiki, it could mean replacing the normal categorization system with a Template:Category to be added to the Related articles box, when present, so that the article gets categorized under some categories, but their links are also shown somehow in the floated box. For example:
Current system
[[Category:Foo]]
[[Category:Bar]]
{{Related articles start}}
{{Related|link}}
{{Related articles end}}

Body
New system
{{Related articles start}}
{{Category|Foo}}
{{Category|Bar}}
{{Related|link}}
{{Related articles end}}

Body
-- Kynikos (talk) 04:33, 12 July 2014 (UTC)
The problem is that it involves more writing when there are no related articles (it is necessary to add {{Related articles start}} and {{Related articles end}} around the cats). Or would we use the current system for such pages? -- Lahwaacz (talk) 08:40, 12 July 2014 (UTC)
I was just brainstorming, I'm not sure, maybe we could start using the RA box on every article? Wiki Monkey should have all the libraries needed to automate the migration, both for articles with an RA box and for those without, so the "extra writing" disadvantage wouldn't really apply. -- Kynikos (talk) 05:24, 13 July 2014 (UTC)

Convention on added/removed text in Hc Templates

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

~/.config/nautilus/accels
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")

Is there already a policy on this? --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)

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 [17]. I too think that linking to Wikipedia wouldn't add anything useful.
I guess we'll leave this discussion open as a reminder to mass-rename the non-compliant pages.
-- Kynikos (talk) 03:09, 27 December 2014 (UTC)
See also ArchWiki:Requests#Renaming_of_categories. -- Lahwaacz (talk) 19:40, 26 July 2015 (UTC)

Questionable edits

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

Underscores vs. slashes in kernel module names

Example: [18] vs. [19]

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

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

Let's just pick one style and go with it. I vote for undescores, since that's how lsmod prints them, consistency would be nice.
I wouldn't consider these 2 edits questionable, rather it's lack of Help:Style rules about this particular subject.
axper (talk) 06:04, 10 August 2014 (UTC)
+1 for regulating this with underscores as per axper's lsmod argument. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)

Alphabetical order

Example: [20]

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

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

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

I think as long as the sorted sections are equivalent (as in, alphabetical order does not break logical order), you could probably make an argument for both. Should a rule for chronological sorting be found useful, however, I wouldn't object to it. -- Alad (talk) 18:41, 9 August 2014 (UTC)
Yes, I'd expect a section about a new bug I am looking a solution for to be at the end of the article. axper (talk) 06:20, 10 August 2014 (UTC)
First, the example edit should have been split (i.e. one section moved at a time).
About the issue, I don't think that alphabetical order can make sense in Troubleshooting or Tips and tricks sections, since the first word of the headings is often incomparable (can be an article, a noun, etc.); chronological order would be better, for example a rule could recommend adding sections at the bottom (or top) of such section groups, unless some similar ones already exist, and in that case I guess keeping similar sections next to each other would be preferable.
-- Kynikos (talk) 09:13, 10 August 2014 (UTC)
+1, Lahwaacz is right. And one example for keeping similar sections next to each other: GNOME#Extensions -- Kycok (talk) 12:21, 20 August 2014 (UTC)

Concision

(without example)

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

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

I think there's a difference between concision in style and concision in content. Former is a matter of correct writing (convey information that helps understanding, not make it difficult); see [21] for a simple example. Latter should be avoided, and flagged (for example [22]) where appropriate. -- Alad (talk) 18:24, 9 August 2014 (UTC)
We can indeed put some recommendation like that in the guide, but this is something that the wiki staff will always have to keep an eye on, because experience is the only way to judge, case by case, what's too verbose and what's too concise. -- Kynikos (talk) 09:13, 10 August 2014 (UTC)
Thanks for this hint. I've never recognized concision as a term and always associated it only with removing of content, either large parts or nuances that might have been intended by the previous editor. Although the language should be concise, let's not take it too far. And especially watch out for the nuances. -- Lahwaacz (talk) 14:08, 10 August 2014 (UTC)

"as of version X.XX..."

Example: [23]

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

I agree that it is useless for features. But I think it is very important for bugs and perhaps even missing features.[24] -- Lahwaacz (talk) 21:46, 6 March 2016 (UTC)
+1. For [25] see also [26]. Another missing features example is [27]. Such is difficult to track for readers who may have encountered the issue in the past and, in this case, perhaps used a different boot loader just because of it. Perhaps one could say "as of notes" are less useful to keep for missing features in the "Installation" sections, but the further down in the article they are (e.g. in a "troubleshooting" section) the more useful they are for awareness of updates. --Indigo (talk) 09:48, 7 March 2016 (UTC)
Yes, to generalize, I'd say that "as of" notes are indeed useful next to information that is expected (or maybe reasonably wished/feared) to change in the future. Certainly, added features don't fall in that category, so I agree with the Core utilities, GDM and makepkg edits, but I would undo the Python edit, and, as noted by Indigo, check the SSH keys edit against Talk:SSH_keys#PuTTY_elliptic_curve_support. Since we are in the talk page of the style guide, is there a proposal for the addition of a new rule to discuss? — Kynikos (talk) 07:53, 8 March 2016 (UTC)
I think a possible style rule could be that adding edits about when changes to a program occurred is mostly appropriate when it's about a bug, or about a product in heavy development that's expected to change soon. Just listing off when features were added to a stable program adds noise and should be avoided. Rdeckard (talk) 02:24, 19 March 2016 (UTC)
(Welcome to the team, Rdeckard!). Yes, though, take the putty example: it's long a missing feature, putty is not really what one would call heavy development. When the feature finally hits stable, an "as of" might help (an ssh client is an application where I would expect a lot users prefer to use stable and wait). Maybe it is easier to suggest a time-period, i.e. "as of notices" older than (half) a year after a bug or missing feature (which has been tagged as such in the content) has been fixed can safely be removed because of the rolling repos Arch uses.
As for the place to put it: we actually have Help:Style#.22Known issues.22 sections in the guide, but it is rarely used - which is understandable in my view, because mentioning a bug where the related configuration or features are described makes sense. Question is whether we need this style section at all (then an "as of" addition could be added to it), or it should be removed entirely and integrated into the more commonly used Help:Style#.22Troubleshooting.22_sections. (+1)
--Indigo (talk) 07:26, 19 March 2016 (UTC)
Restarting this discussion because I just did a bunch of "as of" edits. It is a tricky issue because there definitely isn't a simple policy that always applies. That being said I think that most "as of"s should probably go. Here are the main use cases that I've observed:
  1. noting when a feature was added/removed
  2. noting when a default option was changed
  3. noting when a bug was introduced/fixed
  4. noting when the editor last verified the information (workaround was effective, desired feature was missing, etc.)
Number 4 is easy: "as of" is unnecessary. First of all it is redundant since the article history shows when the information was added (and thus verified). Secondly it adds very little value to the reader of the article. If I'm having a problem and a troubleshooting section has a potential solution it doesn't matter if it was working "as of" 100 years ago, I'm going to give it a shot (and then update the article if it no longer works). Lastly it encourages useless edits. If I see an old "as of" and check that it is still the case, does it really add value to the article if I just update the date to show that it still works? Where do we draw the line for that? Should we go around adding "as of" to every single thing that we verify as working? "As of March 3, 2017 sudo can be installed via sudo."
Number 3 is also easy: "as of" is unnecessary. In almost every case it is more useful to simply link to the bug report (ours or upstream). The obvious advantage being that upstream bug reports often include all the information the reader may want: when it was reported, what versions it affects, potential workarounds/solutions, if/when the bug was fixed, etc. Adding "as of" in this case is just sparing the reader an extra click, which goes against the hypertext metaphor.
Number 2 is a little tricky. If it is the case where the option change might require user intervention (e.g. a breaking change in config) then the "as of" is needed. However in most cases I've seen it is still not used well in the article. You'll see something like "As of version X the default is blah ...much later in the article... if you are upgrading from an older version, you may need to...". I think the "as of" is misplaced here: users who installed after the change likely don't care about the new default since they don't have to worry about breakage. In this case the "as of" should be placed in the later section dealing with the issue: "The default is blah ...much later in the article... if you are upgrading from version X, you may need to...". If the default change requires no intervention, I see no need for the "as of": users who run the default likely don't care and users who do not use the defaults are likely unaffected.
Number 1 is also difficult. I think feature removal is slightly easier because if the removal was an intentional design decision by the developers (i.e. not a bug) then the "as of" is not needed. Arch doesn't support users who want to keep old software around, so it is sufficient for the article to simply say that the feature was removed (not when). Because it was an upstream design decision, users reading the article can safely assume that the software will no longer support that feature. For feature addition I think the same logic as number 2 applies. If the new feature might change how upgrading users use the software it should be mentioned in the relevant section.
The only rule of thumb that I think applies in all of these cases is that often an editor adds an "as of" when there is actually something more specific they are trying to communicate: "as of X the default was changed so if you upgrade you have to...", "as of X this feature was removed so instead you may need to install...". By all means keep the the more specific information, ditch the "as of" if possible.
Silverhammermba (talk) 19:14, 3 March 2017 (UTC)
Very good. One comment: I think a regular case is that someone put a work-around/troubleshooting item into the wiki for a missing feature/default. Later the feature/default is added/changed. I think procedure should be to put a Template:Remove to the workaround first, so that users who might have implemented it get info. Then purge it later. (Obviously, there may be simple cases too.)
Two questions. 1: Do you think we should put a "as of" style suggestion with good/bad examples of usage into the style guide? If yes, where?
Question 2: Look at the above SSH keys#ECDSA example. Coincidentally, the referred to putty package finally gained the feature two weeks ago. How would you handle that, taking into account implementing the feature took a couple of years.
--Indigo (talk) 20:47, 3 March 2017 (UTC)
I think the "as of" there is needed, but again I think it is misused. Right now it is an example of case 4 i.e. "when I edited this article in March 2016 the feature wasn't there yet". This is redundant and not very useful. A much better "as of" would be to mention that ECDSA support has actually been in the development snapshot since November 2014! That is much more useful. Silverhammermba (talk) 23:19, 3 March 2017 (UTC)
I agree, somewhat. The "feature not there" info was useful in so far, as there will be users who configure their Arch openssh server (defaulting to ECDSA) but may latter want to connect via another platform's client (i.e. useful to avoid the pitfall with putty as a common client failing to support the server default). Of course it would have been even more useful with the development version info being merged over from the talk page, or the info moved/crosslinked from putty. But ok. My question was for the new status quo: How would you phrase it now, with the new stable version supporting ECDSA? Keep the note with an "as of putty 0.68 (Feb 2017) ECDSA is available", or simply drop it because it does not matter anymore? --Indigo (talk) 02:36, 4 March 2017 (UTC)
Putty is an exceptional case because there we have to deal with compatibility with other OSes (where the always up-to-date assumption does not apply). So the "as of" there is useful, again as long as it actually mentions when the feature was added.
Also, regarding "as of" in the style guide I think it sufficient to mention the two clear-cut cases: do not use "as of" if you are just noting the last time you personally checked something and do not use "as of" for bug reports, just link to the report itself.Silverhammermba (talk) 18:37, 4 March 2017 (UTC)
I've handled the Putty example with [28] and [29] I agree it could be done the other way too. --Indigo (talk) 21:29, 6 March 2017 (UTC)
Great write up above. I'm in agreement that we should tell users not to note the date, time, or program version in their edits if they are just telling us the last time everything worked for them. I also like the idea of encouraging users to link to bug reports instead of giving specific versions. We also need to use the "Known Issues" more often in our articles. -- Rdeckard (talk) 21:11, 4 March 2017 (UTC)
To make a start with mentioning "as of", I put in [30] and [31] (the latter addition may be a bit sublime). Perhaps you have an idea to make it more prominent or concise along above. --Indigo (talk) 21:29, 6 March 2017 (UTC)

File types

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

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

Does it need mentioning?:

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

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)

Example usage

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

You're right, we're not explicit about examples at the moment: I'd say currently the most related sections are Help:Style#Hypertext metaphor about content centralization, and Help:Style#Package management instructions/Help:Style#systemd units operations about examples only for those specific cases.
Help:Style#Hypertext metaphor allows (obviously) to write Arch-specific adaptations (examples?) of external generic documentation: by analogy (and coherence), this could be seen applicable to topic-specific adaptations (examples?) of instructions which are centrally (and generally) discussed in a "main" article. If we wrote a rule about examples, and perhaps we do need it, it should probably still be quite loose I think, and describe sort of a minimum level of complexity that the adaptation of generic instructions should have to be allowed in an article in addition to a link to the centralized article.
Regarding the specific reverted edit, I tend to agree with you, the example looked quite trivial, so I've tried to instead clarify the paragraph.
Kynikos (talk) 07:48, 11 March 2017 (UTC)

Hypertext metaphor: Same-page section links

[Moved from Talk:Python -- Lahwaacz (talk) 08:38, 21 May 2017 (UTC)]

Hmmm... I don't really want to correct ArchWiki admins, but I have a notice about [34]. According to Help:Style#Hypertext metaphor:

  • 5th item: do not hide the # symbol in same-page section links
  • 9th item: we can see there a same-page section link in a middle of a sentence (last sentence in that item), and it's written as it is in section heading, starting with capital letter

-- Kycok (talk) 22:09, 20 May 2017 (UTC)

My point was regarding the 3rd point of the same section: "...use a link label. Regular grammar rules apply..."
Anyway, this is a very blurry case so your nitpick is highly appreciated and we'll probably have to reformulate the rules to be less ambiguous.
-- Lahwaacz (talk) 22:45, 20 May 2017 (UTC)
I think that the 5th point ("Do not hide the # symbol") only expands the 4th point and does not apply to the cases covered by the 3rd point. Historically, the 5th point predates both previous points, so the intention was slightly different. What do others think? -- Lahwaacz (talk) 08:49, 21 May 2017 (UTC)
Oh no, both 3rd and 4th items mean links to another acticles, not to the same one. 3rd is used when you mean some topic or term, otherwise 4th is used when you mean an article itself. So 5th item doesn't expand previous, it refers to the same article as opposed to 3rd and 4th.
Also I would like to say that it's a good solution not to hide #, reasons are described in article. At the moment we must use capitalization like in section heading, there are two ways to resolve this:
  • Make some changes in code so that we can use lowercase same-page section links even if section heading starts from capital letter, like it is for articles (ex. Python and python)
  • Leave it as is and use the same capitalization like it is in section heading, even if it will start from capital letter in the middle of a sentence
While first option is more correct, I like second one too
-- Kycok (talk) 14:02, 21 May 2017 (UTC)
After discussing this a couple of hours with my lawyer, we decided that my preferred interpretation is the same as Lahwaacz (if I understood it right): points #3 and #4 also apply to same-page links, and therefore, after we introduced them, point #5 became only an extension of point #4. That said, I'm pretty sure that I've contradicted myself even very recently when adding or editing some same-page links.
@Kycok: you can try to propose a patch to MediaWiki, but making same-page links first-letter-case-insensitive may be considered backward incompatible and thus rejected.
Kynikos (talk) 11:57, 22 May 2017 (UTC)
(Besides, the MediaWiki code regarding section anchors is very ugly and broken for years...) -- Lahwaacz (talk) 13:49, 22 May 2017 (UTC)
So what is right? For now Lahwaacz's edit is reverted [35] by Silverhammermba -- Kycok (talk) 22:14, 25 May 2017 (UTC)
I've done this and that, thoughts? This other edit also caught my attention, note how the amended link is next to another pure section link. — Kynikos (talk) 07:39, 27 May 2017 (UTC)
I think such rules is very confusing. Wiki-writers will be forced to loose some time to guess which one matches our rules. And absolutely right such rules are opposite to Keep it simple! -- Kycok (talk) 20:56, 29 May 2017 (UTC)
How would you like to see it handled then? From your two options above, modifying the code is anything but easy and leaving it as it was is not less confusing at all, otherwise we would not be having this discussion. -- Lahwaacz (talk) 06:29, 30 May 2017 (UTC)
Ok, I also like this. Let's simply just make it mandatory to show an anchor for same-page links. Examples:
All my examples are very similar to Kynikos's edits, but there we must use We have [[#Hypertext metaphor|#style rules]] for links rather than We have [[#Hypertext metaphor|style rules]] for links. And, of course, that one is OK but we must add an anchor into label.
-- Kycok (talk) 11:11, 30 May 2017 (UTC)
What if for the moment we do explicitly mention the [[#Anchor|#Label]] syntax, but only as optional, and see if it catches on? Besides the example above, I don't remember ever seeing it before here. Since point #4 now has a subpoint #4.1, this suggestion could fit well in an analogous #3.1 subpoint. — Kynikos (talk) 14:41, 30 May 2017 (UTC)
Yup, you can do this. But I think it would be great to show # each time link refers to the same-page section -- Kycok (talk) 14:59, 30 May 2017 (UTC)
If you read "In most cases #prefer linking to the article than to the package", how do you pronounce the "#" token? Probably nowise, you just skip it, because it is not part of the grammatical structure of the sentence. On the contrary, in "See #Prefer linking to the article than to the package" the "#" token is not excess, it is part of the designation of the object that should be seen. It can also be read as "paragraph" or "section" -- in fact, Wikipedia uses "§" instead of "#" in link labels via its convoluted templates.
I think that when it comes to the 3rd point, the "#" symbol is more distracting than enlightening. Also if the "#" symbol was shown everywhere as you propose, there wouldn't be much sense anymore to handle the capitalization and interwiki prefixes separately by points 3 and 4. Consequently the rules would be simpler, but I think it would not produce a simple markup nor well-readable text, which is the point of having the rules in the first place.
Can't we resolve the situation by just adding a justification to points 3 and 4 to ease the understanding of the rules?
-- Lahwaacz (talk) 18:07, 30 May 2017 (UTC)
Sure, adding a justification would help, that would be enough to close this discussion for me.
However just to give you a reply, the "#" token would not be pronounced just like the arrow icon next to external links such as in "In most cases prefer linking to the article", which is instead allowed (because automatic). Even if a #Label syntax was allowed (at user's discretion) or enforced, I think that regulating same-page links separately in points 3 and 4 would still make sense because it would make it clear that using a label when referring to the section itself (not the topic) isn't allowed.
— Kynikos (talk) 12:11, 31 May 2017 (UTC)
Also let's expand Hypertext metaphor section's 3rd and 4th items like this:
  • If a link refers to the term or topic described on the target page (including same-page section links)
  • If an internal/interwiki link (including same-page section links) refers to the target page
As you can see, it was not so clear for me ^_^
-- Kycok (talk) 11:11, 30 May 2017 (UTC)
Those rules are starting to be quite complex, I'd like to avoid adding a clarification in parentheses, what about this? — Kynikos (talk) 14:41, 30 May 2017 (UTC)
It's OK -- Kycok (talk) 14:59, 30 May 2017 (UTC)
+1. Is the lawyer still squatting on this case or can it be closed? --Indigo (talk) 20:19, 12 August 2017 (UTC)
Technically there's the branch above still open, about an optional [[#Anchor|#Label]] syntax, there's 1 vote to make it mandatory, 1 to only mention it as optional, and 1 against. I don't feel very strongly about it though, I'll close this, so there's 1 more week for somebody to reopen and state their opinion, otherwise things will stay as they are. -- Kynikos (talk) 04:15, 13 August 2017 (UTC)

Rule about optional dependency

Comment: A topic started in Talk:BackupPC, the contributor want to mention another optional dependency in the page. Should we define the rule about it? My opinion is that: Optional dependency should not be mentioned. Because it is hard to check and maintain in the wiki. Just read pacman log which is correct and current.--Fengchao (talk) 23:50, 22 October 2017 (UTC)
True, we'd better regulate this, but it can get tricky... For example we mention lots of optional packages in File manager functionality, maybe we can discourage simply systematically listing all optdepends but allow it if there's something more to say about them? I don't know right now... -- Kynikos (talk) 10:49, 24 October 2017 (UTC)
OK, I think we can put it as not recommended but not forbiding it. --Fengchao (talk) 02:03, 25 October 2017 (UTC)