Difference between revisions of "Help talk:Style"

From ArchWiki
Jump to: navigation, search
(Make discussion pages part more visible: Remove closed discussion.)
m (Styling configuration paths: removed closed discussion)
 
(704 intermediate revisions by 24 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]].
+
 
 +
Thank you for reading this notice and for contributing to the ArchWiki! -- [[ArchWiki:Administrators|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.}}
 +
__TOC__
 +
== Change Edit Summary label and possibility to make it mandatory ==
 +
 
 +
All edits to articles should be accompanied by some words in the summary filed, answering the question "'''Why''' did you edit the article?". "What", "where", "when" and "how" are self-explained by the diff itself, it's redundant to add them. An explanation is not mandatory in talk pages, where the "why" should be already evident. Remember that links are allowed in the summary field, so it is allowed to point to an existing discussion. -- [[User:Kynikos|Kynikos]] 09:32, 3 May 2011 (EDT)
 +
 
 +
Maybe we could submit a bug to request the change of the word "Summary:" to "Reason for editing:" next to the input in the edit page itself? -- [[User:Kynikos|Kynikos]] 11:33, 3 May 2011 (EDT)
 +
:+1
 +
:Would it go directly upstream? The Polish wiki has something like ''Summarize the changes [you've made to the        article]''. Wikipedia has ''Edit summary <sub>(Briefly describe the changes you have made)</sub>''. They all deal with what is being changed, not '''why''' - we need to fix this :-) -- [[User:Karol|Karol]] 12:04, 3 May 2011 (EDT)
 +
::Done: {{Bug|24075}}, remember you can vote it. -- [[User:Kynikos|Kynikos]] 12:57, 3 May 2011 (EDT)
 +
:::Any wiki admin can change this message (aside: can you view [[Special:AllMessages]]?) I think it might be more fitting to include this as an addendum to the copyright notice instead (text above the summary field). Perhaps we should also consider making the edit summary mandatory (i.e. prevent saving with a blank summary). -- [[User:Pointone|pointone]] 22:55, 4 May 2011 (EDT)
 +
::::Nice, I can see that page, I didn't know that ^^ Maybe I should close the bug request then. Anyway I'm quite sure that ''only'' appending this recommendation to the copyright notice would make people start ignoring it very soon (as it happens with road signs eheh): I'm still in favour of changing the word "Summary", as it's misleading. Making the field mandatory could be a great idea instead, but for what I've seen until now, if the edit page returns an error, it forgets about the editing done, and it would be quite annoying (the textarea could be easily repopulated echoing $_POST['...'] instead of recovering the text back from the database; I have only tested this when trying to edit a page that has been edited by somebody else meanwhile). -- [[User:Kynikos|Kynikos]] 06:15, 5 May 2011 (EDT)
 +
::::(Well, doing it in javascript would solve the problem, though using JS is not very wiki-style it seems) -- [[User:Kynikos|Kynikos]] 06:17, 5 May 2011 (EDT)
 +
:::::When saving an edit that conflicts with another, your changes ''are'' saved. MediaWiki presents you with two text areas: one contains the page contents and the other contains your edit.
 +
:::::Either way, a quick Google search reveals [http://commons.wikimedia.org/wiki/User:DieBuche/forcesummary.js User:DieBuche/forcesummary.js] and [[Wikipedia:Wikipedia:WikiProject User scripts/Scripts/Force edit summary]] as two possible solutions. There also is a user preference option under '''Editing''' > '''Advanced options''' > '''Prompt me when entering a blank edit summary''' -- I wonder whether we can enable this option by default as a less-intrusive solution.
 +
:::::-- [[User:Pointone|pointone]] 09:16, 5 May 2011 (EDT)
 +
::::::Uhm it always looked like I lost my changes everytime I had edit conflicts (always easily recovered with the back button), anyway it could be that I didn't look well.
 +
::::::About the main topic, I would first try just to change the Summary text, anyway if you want to go the JS way immediately, do it in a way that the user understands that he has to answer the question "why", not "what", otherwise all edit summaries would probably be filled with "added section", "corrected code", "deleted section" and so on (well, those ''are'' summaries in the end, and that's what the form requests literally atm). -- [[User:Kynikos|Kynikos]] 11:07, 5 May 2011 (EDT)
 +
:::::::I think it's also OK to combine 'what' with 'why' e.g. '[https://wiki.archlinux.org/index.php?title=Arch_Based_Distributions_(Active)&diff=prev&oldid=139695 removed '''outdated''' links]'. I'm not a native English speaker, but it sounds more natural than 'links were outdated'. -- [[User:Karol|Karol]] 11:50, 6 May 2011 (EDT)
 +
::::::::Of course it's also ok, anyway I'm not a native speaker either, but if a label says "Reason for editing" it comes more natural to me to write "links were outdated". This system should also exploit a bit of psychology afterall. -- [[User:Kynikos|Kynikos]] 12:56, 6 May 2011 (EDT)
 +
:::::::::<facepalm> Of course you are absolutely right ... I - ummm - forgot that we wanted to change 'Summary' to 'Reason for editing'. Sorry about that. -- [[User:Karol|Karol]] 19:58, 8 May 2011 (EDT)
 +
:::Since the bug got closed as 'Upstream', do we go upstream with this? -- [[User:Karol|Karol]] 19:58, 8 May 2011 (EDT)
 +
::::I am curious whether this has been discussed upstream already... I have no problem with making the change on our end, since every wiki handles summary policy differently (as pointed-out above in examples). -- [[User:Pointone|pointone]] 22:46, 8 May 2011 (EDT)
 +
:::::Well you are the one in charge here, you can decide what to do now ;) -- [[User:Kynikos|Kynikos]] 05:53, 9 May 2011 (EDT)
 +
::::::The style part of this discussion has been implemented in the guide. I'd still be interested in changing "Summary" to "Reason for editing", anybody else? -- [[User:Kynikos|Kynikos]] 15:32, 21 September 2011 (EDT)
 +
:::::::Going upstream would benefit more that just our wiki, as mediawiki is a pretty popular piece of software. +1 from me. -- [[User:Karol|Karol]] 16:45, 21 September 2011 (EDT)
 +
::::::::The relevant system message is [[MediaWiki:Summary]]. I would suggest that the word "Summary" itself remain, as it is referenced in other locations and the documentation. My vote is for addition of an explanatory subtext à la Wikipedia. (Summary: <sub>(Briefly describe the changes you have made)</sub>). -- [[User:Pointone|pointone]] 13:50, 22 September 2011 (EDT)
 +
:::::::::Cooool, that's the way to go! +1000 XD
 +
:::::::::Some ideas:
 +
:::::::::*<sub>Briefly explain the reason for the changes you have made</sub>
 +
:::::::::*<sub>Briefly explain the reason for your edit</sub>
 +
:::::::::*<sub>Briefly explain the reason for your changes</sub>
 +
:::::::::*<sub>Briefly explain the reason why you edited the page</sub>
 +
:::::::::-- [[User:Kynikos|Kynikos]] 15:55, 22 September 2011 (EDT)
 +
::::::::::I think a combination of using explanatory text (I like something such as "<sub>Briefly explain the reason for your changes</sub>" from your suggestions), and investigating how to set "Prompt me when entering a blank edit summary" user option by default would make it more noticeable and be a great start here.  [[User:Emiralle|Emiralle]] 12:56, 15 October 2011 (EDT)
 +
:::::::::::I'd like to make the edit summary strictly mandatory (meaning that a blank summary field won't allow submitting the edit): pointone mentioned some possible methods for doing this in the first part of the discussion, I'm just adding some more references as reminders (don't know exactly what to do with them yet... :P ): [http://www.mediawiki.org/wiki/Manual:$wgDefaultUserOptions] (see "forceeditsummary"), [http://www.mediawiki.org/wiki/Manual:Parameters_to_index.php#Optional_additional_data], [http://www.mediawiki.org/wiki/Wikia_code/includes/EditPage.php]. -- [[User:Kynikos|Kynikos]] 15:01, 20 October 2011 (EDT)
 +
::::::::::::For the moment I've changed the label to:
 +
:::::::::::::[[Help:Style#Edit summary|'''Summary''']] <small>('''what''' you did and '''why''')</small>:
 +
::::::::::::as you can see when opening a page for edit, I hope it's ugly and annoying enough to be noticed by many >;)
 +
::::::::::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:37, 11 July 2013 (UTC)
 +
:::::::::::::The edit box has been moved to the right, so it's easy to spot that something's different. I like it, good job, Kynikos. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 19:14, 12 July 2013 (UTC)
 +
:::About making the ''Prompt me when entering a blank edit summary'' option enabled by default, this is what has to be done:
 +
:::# Have {{Bug|35545}} implemented
 +
:::# Edit [[MediaWiki:Missingsummary]] and make it more visible and formative
 +
:::# Add the {{ic|forceeditsummary}} option to the default user preferences as described in [[mw:Manual:$wgDefaultUserOptions]]
 +
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:06, 13 July 2013 (UTC)
 +
 
 +
::::I went ahead and submitted a feature request ({{Bug|46190}}), with even ''better'' technical solution. Let's see how this goes... -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 3 September 2015 (UTC)
  
 
==Article summary templates==
 
==Article summary templates==
 
See [[Help talk:Style/Article summary templates]].
 
See [[Help talk:Style/Article summary templates]].
  
==Migration to new Code formatting templates==
+
== Better structuring ==
See [[Help talk:Style/Migration to new Code formatting templates]].
+
  
==Category pages - tree or otherwise?==
+
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]])
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)
+
: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)
: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)
+
::> ..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)
  
::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.
+
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)
:: 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).
+
:::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.
+
:::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...
+
:::-- [[User:Kynikos|Kynikos]] 12:59, 27 October 2011 (EDT)
+
  
==Style vs. Usability ==
+
: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).
Commenting on: [[Help:Style#Daemon_operations]] and [[Help:Style#Official_packages]]
+
: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)
  
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.
+
== Related links ==
  
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.
+
=== See also or Related in Article Summary? ===
  
This would be fine if the action involved wasn't so important, or if the linked information was either:
+
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.
* 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)
+
See also [[#Article summary templates]].
:''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.
+
-- [[User:Kynikos|Kynikos]] 15:15, 21 September 2011 (EDT)
  
::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)
+
: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)
:::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.
+
: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)
:::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)
+
:::[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)
+
::::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.   
+
'''Advantages of links in See also:'''
: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!
+
*There is more space for link descriptions
: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.
+
*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 articleIt 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)
: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 :)
+
*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)
:-- [[User:Kynikos|Kynikos]] 09:35, 11 January 2012 (EST)
+
*:Especially for people used to Wikipedia, which uses the same wiki software. [[User:Vadmium|Vadmium]] 11:12, 26 October 2011 (EDT).
: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)
+
*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)
::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)
+
*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)
:::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)
+
*More formatting options here than in summary. [[User:Emiralle|Emiralle]] 13:12, 15 October 2011 (EDT)
::::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)
+
*More inclined to put external, or less closely related stuff here. [[User:Emiralle|Emiralle]] 13:12, 15 October 2011 (EDT)
:::::"''...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.
+
*''See also'' section would not be skipped if you start reading the main text sequentially from the top. [[User:Vadmium|Vadmium]].
:::::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.
+
*''[add more advantages...]''
:::::-- [[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:
+
'''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...]''
  
  $ pacman -S package1 package2
+
=== 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)
  
NTPd can be [[pacman|installed]] with the package {{pkg|ntp}}, available in the [[Official Repositories]].
+
=== 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]])
  
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?
+
== Application name capitalization ==
  
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)
+
Which are the rules of capitalization of certain names? For LibreOffice there is no doubt, but for example is it 'bash' or 'Bash'? Probably the documented one is the preferable, so 'bash', 'Bash' when starts a sentence, aria2c everywhere. For zsh neither man pages are coherent. -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 18:00, 19 May 2013 (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!).
+
:This topic is rather interesting: it's quite natural that we should follow the capitalization used in the upstream documentation, and this guide should probably mention it. I'd also like to remark whether the name should be always capitalized at the beginning of a sentence or not: honestly my position would be to still follow what the upstream documentation does.
 +
:In case the documentation is not coherent, I guess there's nothing we can suggest, except for being consistent throughout the article, _and_, if the application is mentioned in other articles, capitalization should be consistently based on the main article for that application (e.g. [[Bash]]).
 +
:Note that Bash is always capitalized in http://www.gnu.org/software/bash/
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 15:00, 22 May 2013 (UTC)
 +
::so Bash is written wrong in [[Help:Style#Shells]], (lol, forgive me :) ) -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 10:29, 3 June 2013 (UTC)
 +
:::Ahah perfection is unreachable, you will always find something to report... Anyway in this case "bash" _would_be_ written "wrong" in [[Help:Style#Shells]] only if the above had already been enforced as a rule ;) (but I'll forgive you for this blunder, don't worry :P ) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:32, 3 June 2013 (UTC)
  
:::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/.
+
::::I like the way the Git project uses both "Git" and "git" in their documentation based on what the author is referring to. They use "Git" when talking about the project/software generally, and they use "git" when referring to the ''compiled program used when running commands'' [https://github.com/git/git/blob/master/Documentation/CodingGuidelines#L313]. This style makes it quite easy to know whether to use "Bash" or "bash", etc.
 +
::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 02:42, 11 January 2014 (UTC)
  
:::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.
+
:::::That is certainly logical, with [[Help:Style/Formatting_and_Punctuation]] applied it would be "Git" (plain text, first letter uppercase) and "''git''" (italic, all lowercase). I believe that with proper context it would not be confusing, but for the controversial cases it's probably best to place a note with some explanation into the talk page, as it has been done for [[Btrfs]]: [https://wiki.archlinux.org/index.php?title=Talk:Btrfs&diff=291780&oldid=291779]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:09, 31 January 2014 (UTC)
  
:::''Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime.''
+
::::::In my view Git makes its spelling convention look more complicated than it is: IMHO it just says "always use 'Git', except when talking about the executable, which is a lower-case filename and couldn't be run otherwise". Anyway we could indeed enforce such a convention, but only for applications that A) don't have an official or common capitalization convention and B) are commonly run through an executable that has the same name as the application itself. This would of course settle Bash and Btrfs cases though. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:50, 1 February 2014 (UTC)
  
:::- [[User:Thestinger|thestinger]] 21:21, 18 January 2012 (EST)
+
==List of Applications and See also==
::::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 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.
  
::::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?
+
-- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 18:00, 19 May 2013 (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)
+
: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.
:::::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?
+
:About 3. I don't understand what you mean, can you be more specific?
:::::-- [[User:Kynikos|Kynikos]] 08:33, 19 January 2012 (EST)
+
: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)
  
:::::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)
+
== 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)
  
:::::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)
+
== Prefer linking to the article than to the package ==
 +
''When mentioning an application, prefer linking to its article, if existing, rather than directly to the package.'' -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:24, 28 May 2013 (UTC)
 +
:+1, apart from the standard "Download {{ic|foo}} from the official repos" and similar. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 13:27, 28 May 2013 (UTC)
  
:::::::Completely agree. Also, I think, color should be different from one of interwiki links. --[[User:AlexanderR|AlexanderR]] 23:54, 29 January 2012 (EST)
+
== git/vcs/source builds ==
  
::::::::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).
+
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:
::::::::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.
+
* of course you can build application on your own, there is no need to say that.
::::::::-- [[User:Kynikos|Kynikos]] 07:11, 31 January 2012 (EST)
+
* 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)
  
:::::::::>> Do you mean of a completely different color?
+
== Distinguish fragment identifier interwiki links? ==
:::::::::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?
+
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:
:::::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==
+
# 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
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''}}.
+
# 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 propose the following style rule to be added under [[Help:Style#Title]] (as the first point):
+
I'd vote for the second, it seems to be the most universal. Or does anybody have some other suggestion?
  
* Titles should be capitalized using '''title case''', as in "How to Install Arch Linux on a Toaster."
+
(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.)
  
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)?
+
Sorry if this has already been discussed somewhere else, I don't have the time to search it right now.
  
-- [[User:Pointone|pointone]] 16:37, 19 January 2012 (EST)
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:41, 7 October 2013 (UTC)
  
: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).
+
:Talking of distinguishing links, external https links are not distinguished either:
: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].
+
::[http://foobar.org http]
:I don't think it's necessary to explicitly contrast this rule with that for section headings.
+
::[https://foobar.org https]
:-- [[User:Kynikos|Kynikos]] 07:16, 20 January 2012 (EST)
+
:Perhaps a bug?
: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)
+
: -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:10, 10 October 2013 (UTC)
  
==Reducing formatting bloat==
+
::About the little icons next to links, I guess we could do it easily with CSS attribute selectors in the skin files.
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)
+
::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.
: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:
+
::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 :)
:{{Tip|You can run rm -rf / as root to free some space on your hdd.}}
+
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:53, 10 October 2013 (UTC)
: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 ===
+
:::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].
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?
+
:::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)
  
-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
+
::::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)
  
==== Bold ====
+
:::::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)
:{{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)
+
::::::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)
  
:* ''Highly questionable:'' single file names
+
:::::::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)
::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):
+
::::::::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)
::'''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
+
== Problem with keyboard keys style ==
::ensure that '''radeonfb''' is blacklisted
+
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
  
:* important part of file/command line contents:
+
I could use some help with [[Keyboard Shortcuts]]:
::{{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
+
<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>
::'''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)
+
Also, what would be the preferred style for showing multiple shortcuts for some modifier combination?:
  
::::>> so this rule could just add bloat for nothing
+
* {{ic|Alt}}+{{ic|.}}or{{ic|_}}
::::Maybe, but for some reason cited HTML5 developers, authors of many articles in this Wiki and even http://www.archlinux.org/ webmaster believe this to be "conventional typographic presentation". This, however, does not oblige us to support such case of usage here.
+
* {{ic|Ctrl}}+{{ic|Alt}}+{{ic|+}}/{{ic|-}}
::::>> I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead.
+
* {{ic|Ctrl}}+{{ic|Alt}}+{{ic|F1}}, {{ic|F2}}, {{ic|F3}}, ...
::::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)
+
  
:* I don't know if we should use bold or what else when using pseudo-variables like:
+
(note: someone used {{ic|&uArr; Shift}} on that page, the arrow looks really funny :D )
::{{bc|# modprobe '''module_name'''}}
+
::{{bc|# modprobe ''module_name''}}
+
::{{bc|# modprobe <module_name>}}
+
::{{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.
+
'''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].
:::''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 ====
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:22, 16 December 2013 (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)
+
:(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)
  
:* Cites from external sources:
+
::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
::''All your data belongs to us'' &ndash; Google
+
::Regarding the second problem I agree with leaving it up to the editor. Examples could be:
::--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
::* 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)
  
:::...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)
+
:::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)
  
::::This is matter of punctuation, not formatting. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
::::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)
  
:* Inline templates (IMHO, those with italic formatting look much better than ones with bold formatting):
+
:::::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)
::{{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)
+
== Grammar errors throughout Help:Style ==
  
::::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)
+
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.
  
=== Quoting and underlining ===
+
-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 03:41, 11 January 2014 (UTC)
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.
+
: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)
  
-- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
: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)
  
==== Quoting and double quoting ====
+
::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.
Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
::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)
  
==== Underlining ====
+
:::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)
:{{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)
+
::::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)
  
== Daemons and modules wording ==
+
:::::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)
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.
+
  
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.
+
::::::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)
  
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):
+
::::::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)
  
*"[[Daemons#Performing daemon actions manually|Start]] the {{ic|foobar}} daemon."
+
:::::::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)
*"[[Kernel Modules#Loading|Load]] the {{ic|foobar}} module."
+
*"Add the {{ic|foobar}} daemon to the [[Daemons#Starting on Boot|DAEMONS]] array."
+
*"Add the {{ic|foobar}} module to the [[Rc.conf#Hardware|MODULES]] array."
+
*"[[Daemons#Performing daemon actions manually|Start]] the {{ic|foobar}} daemon and add it to the [[Daemons#Starting on Boot|DAEMONS]] array."
+
*"[[Kernel Modules#Loading|Load]] the {{ic|foobar}} module and add it to the [[Rc.conf#Hardware|MODULES]] array."
+
  
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>}}.
+
::::::::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)
  
-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
+
:::::::::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.
:* I moved this part to the separate section as this discussion is not directly related to "formatting bloat" but rather to unification of phrasing.
+
:::::::::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! ;)
:* Exact formatting depends on results of [[#Bold and italic]] discussion, so I propose to finish it before continuing this one.
+
:::::::::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.
:>> objections to the whole idea are still taken into consideration
+
:::::::::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.
: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:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:38, 21 February 2014 (UTC)
:--[[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==
+
:::::::::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)
The style of &lt;tt>, &lt;code> and &lt;pre> has recently been adjusted in the CSS to match that of code formatting templates.
+
  
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.
+
== Rule suggestion: reference links ==
  
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:30, 4 May 2012 (UTC)
+
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 :/
  
:"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]])
+
The suggestion:
 +
:"When adding troubleshooting sections to new problems, always add reference links into the article, whenever such links are available."
  
== Better structuring ==
+
(There is (at least) one implied meaning: "...and not just in the edit summary" :) )
  
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]])
+
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.
: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)
+
  
== Is it suggested to use Template:AUR for links? ==
+
The reason behind this is quite obvious: the users (and maintainers) will easily know if the problem is still valid or already fixed.
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]])
+
: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.
+
: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 ==
+
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]
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 ==
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:48, 11 February 2014 (UTC)
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:
+
: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)
:* Alternatives to software, described in article
+
 
:* Methods and techniques alternative to ones described in article
+
== Slashes in titles ==
:* Software <-> it's use case
+
 
:* software/technique <-> it's developer
+
It should be made clear that {{ic|/}} in page titles will create a subpage, even if the parent page does not exist. Different wording (which ''must'' exist) should be used in cases where the subpage is not desired. While everything is working OK on the web interface, missing this detail will make alternative interfaces, e.g. {{Pkg|arch-wiki-docs}}, quite confusing.
:--[[User:AlexanderR|AlexanderR]] ([[User talk:AlexanderR|talk]])
+
 
 +
Some infamous pages suffering from this issue:
 +
 
 +
* [[:Category:Audio/Video]]
 +
* [https://wiki.archlinux.org/index.php//dev/shm /dev/shm] (no idea why [[/dev/shm]] does not work here, it does in [[XFCE simple Network Monitor applet#Prerequisites]])
 +
 
 +
Additionally, I don't like the use of {{ic|/}} even in section titles, it just looks wrong: [https://wiki.archlinux.org/index.php?title=List_of_applications&oldid=301902#Scans.2FImage List of applications#Scans/Image].
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:42, 21 March 2014 (UTC)
 +
 
 +
:Umm, technically what I just said is wrong - subpages are disabled in the Main namespace. See for yourself: add {{ic|<nowiki>{{SUBPAGENAME}}</nowiki>}} to [[systemd/User]] and preview, it will return "systemd/User" and not "User". (Also notice the small navigation link below the title in [[Help:Style/Formatting_and_punctuation]]) [[mw:Manual:$wgNamespacesWithSubpages|$wgNamespacesWithSubpages]] is probably set to default value in Arch Wiki configuration.
 +
:See also [[wikipedia:Help:Subpages#Slashes_in_article_titles]].
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:56, 22 March 2014 (UTC)
 +
 
 +
::Yes, subpages are disabled in the Main namespace. [[:/dev/shm]] works in [[XFCE simple Network Monitor applet]] because that article is in the Main namespace and slashes are not specially interpreted there, while they are interpreted as relative (to the current page) links in the other namespaces like Help_talk, hence the red link since [[Help_talk:Style/dev]] doesn't exist. You must prefix a link like that with a colon in order to turn it into an "absolute" link, like {{ic|<nowiki>[[:/dev/shm]]</nowiki>}}.
 +
::That said, do you still support mentioning subpages in the guide? And how exactly? Also, would you forbid slashes in section titles? (I wouldn't, but I'm open for discussing as always)
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 17:11, 22 March 2014 (UTC)
 +
 
 +
:::Well, we should either enable subpages ''everywhere'' (or just the Main namespace in addition to those currently enabled?), or avoid using the term "subpage" altogether: [[Help:Style#Title]], [[Help:Style#Kernel module operations]], ..., [[Talk:Arch systemd container]], [[Talk:Dm-crypt]], ... Is there too much harm in having [[S/KEY Authentication]] a subpage of [[S]]? Is there a way to disable the 'subpage' feature on specific articles? Alternatively, would it be even more confusing to rename the page to [[S KEY Authentication]]?
 +
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:32, 23 March 2014 (UTC)
 +
 
 +
::::I tend to be against real subpages in the Main namespace, as they would prevent the normal usage of slashes in titles, as you note too. Wikipedia has the same configuration by the way (but http://wiki.gentoo.org uses subpages).
 +
::::I understand that using the term "subpage" can be confusing if taken literally, but how would you call the practice of naming articles like "Beginners' guide/*", "List of applications/*" and so on?
 +
::::[[S/KEY Authentication]] as a subpage of [[S]] would create a confusing link at the top of the page, under the title (IMHO more confusing than the current usage of the "subpage" term).
 +
::::If there was a way to disable subpages per-page, it would be through [[mw:Help:Magic_words]], but it looks like there's nothing for that (yet?).
 +
::::Renaming articles like [[S KEY Authentication]] would mean enforcing the rule of avoiding slashes in titles, which is something I would be against... Unless we make use of DISPLAYTITLE to display the correct titles?
 +
::::Finally, I refuse to open a report to change the configuration of the wiki before {{Bug|35545}} is implemented >:( (Please, anybody reading here, vote for it)
 +
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 21:54, 23 March 2014 (UTC)
 +
 
 +
:::::Interesting, [http://wiki.gentoo.org/wiki/Boost/How_build_systems_find_boost] does not show the link below the title. Maybe because the parent page does not exist? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 22:51, 23 March 2014 (UTC)
 +
 
 +
::::::Very interesting indeed, I've done a test here and the link does not appear if the super-page doesn't exist. This actually turns my preference towards enabling subpages also in the Main namespace. However we should patch LocalSettings.php for that, and {{Bug|35545}} is a blocker unfortunately. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 18:21, 24 March 2014 (UTC)
 +
 
 +
:::::::I have misunderstood [[metawikipedia:Help:Link#Subpage_feature|Meta-Wiki]] entry yesterday; today I found the information in [[mw:Help:Link#Subpage_feature|MediaWiki]] too, but Meta-Wiki adds an interesting detail about breaking the breadcrumb links sequence on first non-existent page.
 +
:::::::[[Wikipedia:Help:Subpages#History_of_subpages|Wikipedia]] describes that they originally used subpages, but then switched to the disambiguation system, which probably lead to disabling subpages by default. We don't use disambiguations, so I don't see any further reason why the Main namespace should behave differently.
 +
:::::::{{Bug|35545}} is the blocker, but we won't get anywhere without submitting another bug - it could be the necessary catalyst. (About [https://wiki.archlinux.org/index.php?title=User:Kynikos&diff=306809&oldid=286042]: you've won two votes since yesterday :)
 +
:::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:31, 24 March 2014 (UTC)
 +
 
 +
::::::::You're absolutely right, I'll let you open the report since the idea and the research are yours; it would be better if you could restate the supporting arguments there instead of linking here, and finally emphasize the fact that a patch will be provided if {{Bug|35545}} is implemented first (if we manage to have it fixed, it will be very very useful in the future).
 +
::::::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 18:08, 26 March 2014 (UTC)
 +
 
 +
:::::::::Reported in {{Bug|39668}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 00:03, 29 March 2014 (UTC)
 +
 
 +
::::::::::Added my vote. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:30, 30 March 2014 (UTC)
 +
 
 +
=== 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)
 +
 
 +
== Formatting of references to man pages ==
 +
 
 +
''[Moved from [[Help talk:Style/Formatting and punctuation#Formatting of references to man pages]] -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:24, 29 June 2014 (UTC)]''
 +
 
 +
How should references to manpages be formatted? Possible formats:
 +
# {{ic|pacman}}(8)
 +
# {{ic|pacman(8)}}
 +
# ''pacman(8)''
 +
# .....see ''pacman'' manual.....
 +
#:or even maybe
 +
# {{ic|man 8 pacman}}
 +
[[User:Axper|axper]] ([[User talk:Axper|talk]]) 16:53, 28 June 2014 (UTC)
 +
 
 +
:Ok, let's standardize this, I think the clearest is "... see {{ic|man pacman}} for details ...": the formatting complies with [[Help:Style/Formatting and Punctuation#CLI lines]] where it's already used as an example. I would leave the section number optional, it's quite rare that the same name is in two different sections, so we can recommend to specify it only in cases of ambiguity.
 +
:Let's read more opinions. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:34, 29 June 2014 (UTC)
 +
 
 +
::I am ok with {{ic|man pacman}}.
 +
::Pros:
 +
::* Newbies who haven't encountered manpages yet (which I think is rare) can simply run the command and not wonder what pacman(8) is.
 +
::Cons:
 +
::* It implies that manpages should be read via {{ic|man}}. There are some great alternatives out there or may appear in the future. Of course users of these alternatives can run the equivalent command, but still.
 +
::Other thoughts: For popular manpage it's not very rare when one with same name is in different sections (crontab, man, intro, kill, link, locale, passwd, time, write, hostname). When a section isn't specified, this is the search priority:
 +
::* 1 or 8 - executables or system executables
 +
::* 3 - library calls
 +
::* 2 - kernel calls
 +
::* 5 - file formats
 +
::* 4 - special files (/dev)
 +
::* 6 - games
 +
::* 7 - misc
 +
::So we should be a bit careful when not specifying the section number.  Though this shouldn't be a problem as the author has probably ran the command himself and means the first one in the priority list.
 +
::EDIT: If the user is using one of the alternative viewers and section number isn't specified, that can cause problems for multi-section pages. [[User:Axper|axper]] ([[User talk:Axper|talk]]) 07:08, 29 June 2014 (UTC)
 +
 
 +
:::It is good to consider users with alternative viewers as you do, but using one is an explicit choice. Hence, it seems fair to imply the user knows how to use it as a {{ic|man}} replacement. From the alternatives referencing the section in brackets only those having the section bracket outside the {{ic|ic tag}} would be workable. However, we generally want to give the man reference prominence and for that a "see {{ic|man passwd}} for options" is more prominent than a "see passwd(1) for options". That said, I'd personally like the non-ic version because it is a better textflow in my view. Plus the prominence the ic-tag gives is watered down the more it is used for peripheral commands.
 +
:::For the reason you give regarding the author (the editor deciding whether {{ic|man 5 passwd}} or {{ic|man 1 passwd}} is referenced) it seems safe to leave it optional like Kynikos suggests.
 +
:::To add another thought: In special cases it may even be helpful to reference it externally, e.g. like [http://linux.die.net/man/5/passwd passwd's manpage], particularly when it can be assumed the user has no access to it yet on the system itself. For example: we frequently have man references in the article preface, but referencing a package's man page at that early point (before the installation section) is not particularly reader friendly. The problem with external links is of course consistency, i.e. there are too many outdated external references. But most editors are well aware of that, I'd say.
 +
:::So, with the exception of special cases, I am +1 to Kynikos' suggestion if a rule is made, but like to add that I don't feel a need for it to be standardised. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:44, 29 June 2014 (UTC)
 +
 
 +
::::Good point Indigo, we can't assume the manpage's package is installed. I'd say we can allow two versions of references to manpages:
 +
::::* If the package is probably not installed, use "see ''pacman'''s [https://www.archlinux.org/pacman/pacman.8.html manual] for details" with the recommendation to prefer linking to the official web representation of the manpage, if available.
 +
::::* If the package is probably installed, use "see {{ic|man 8 pacman}} for details", with the possibility to omit the section number when not ambiguous.
 +
::::* If the manpage is linked in a See also section, use the normal See also style instead (discussed in [[#Manpages in "See also" sections]]).
 +
::::Do you like it? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:19, 30 June 2014 (UTC)
 +
 
 +
:::::Oh, fine with me. Thanks for working it out. I particularly like the recommendation towards referencing official package's web manpages too; very beneficial for content overall & software rolling forward. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:14, 30 June 2014 (UTC)
 +
 
 +
::::::[https://wiki.archlinux.org/index.php?title=Mount&diff=330649&oldid=330646 This] is one of the reasons why external links for man pages can be harmful - some distributions may provide patched packages including patched man pages. As Arch provides mostly vanilla packages, the link should lead to upstream's page, which should be the most up to date version (also third-party sites may become outdated after some time). Perhaps this should be mentioned as well. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:59, 16 August 2014 (UTC)
 +
 
 +
I think the prior style discussion conflicts with the philosophy behind the entire [[Help:Style#Package_management_instructions|Package management instructions]] section. Man page usage, like pacman, AUR, and systemd usage, should be an essential skill picked up by every Arch user and shouldn't need to be described with explicit commands for every man page reference on every page. Explanations of man usage (including where to find man pages online) can be consolidated in the [[man page]] article, and references can link to that. I would advocate for a style like "see the passwd(1) [[man page]]". --[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 19:59, 16 September 2014 (UTC)
 +
 
 +
:You certainly have a point here, linking to [[man page]] would indeed be more consistent with our style philosophy, thanks for bringing this up.
 +
:Maybe my proposal above could be changed to:
 +
:* In the article's body, use "see the pacman(8) [[man page]]", where the link is {{ic|<nowiki>[[man page]]</nowiki>}}. In this case I think we should require the section number, and I'd avoid using italics because the number and the link should be enough to emphasize the reference.
 +
:* If the manpage is officially maintained in an online version, it can be linked from the See also section, using the normal See also style (discussed in [[#Manpages in "See also" sections]]).
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:20, 18 September 2014 (UTC)
 +
 
 +
::I saw that link to [[#Manpages in "See also" sections]] a few times in the prior discussion, but it doesn't go anywhere for me. Was that style discussion removed at some point?
 +
::[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 15:24, 20 September 2014 (UTC)
 +
 
 +
:::Yep, closed & removed. Here is the [https://wiki.archlinux.org/index.php?title=Help_talk:Style&oldid=323290#Local_Manpages_in_.22See_also.22_sections permalink], found in the history of this talk page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:57, 20 September 2014 (UTC)
 +
 
 +
::I also agree to your reasoning & it is certainly a great idea to crosslink to [[man page]] in a number of articles, but I'd be against using it as a general style rule. I'd argue just ''because'' reading and interpreting man pages can be considered an essental skill, it is unnecessary to crosslink to [[man page]] in every man page reference of any article (excepting Arch beginner content, where we should use the crosslink often, yes). We don't crosslink every mention of ''systemd'' in the text either. "man pages" is a much too common term for it. I'd say it even is too general to consider crosslinking the first instance of it in an article.
 +
::A link itself is emphasized in the layout and I'd find that emphasis inapppropriate for crosslinking to 'essential skills' general knowledge - distracting from the content.
 +
::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:36, 20 September 2014 (UTC)
 +
 
 +
Another matter is linking to ''specific'' sections of man pages. In cases upstream provides an indexed page (like the [https://i3wm.org/docs/userguide.html i3 user guide]) it's straightforward, but this is more exception than rule. See [[Midnight_Commander#Usage]] for a poor way to tackle this. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:07, 13 June 2015 (UTC)
 +
 
 +
:Unfortunately many man2html converters don't generate the toc and the man sections don't even have an anchor to allow manual links to sections, so there is no other way than this "poor wording". -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:29, 13 June 2015 (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)
 +
 
 +
== 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)
 +
 
 +
== 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)
 +
 
 +
: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:
 +
 
 +
::In {{ic|~/.config/nautilus/accels}}, replace:
 +
::{{bc|; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")}}
 +
::with:
 +
::{{bc|(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]].
 +
:-- [[User:Kynikos|Kynikos]] ([[User talk: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 {{ic|<Actions>/DirViewActions/Trash}} with the key {{ic|Delete}} e.g.
 +
{{hc|~/.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. --[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 17:28, 8 October 2014 (UTC)
 +
 
 +
== Links to redirects ==
 +
 
 +
I'd like to recommend avoiding links like {{ic|<nowiki>[[Xorg#Composite|AIGLX]]</nowiki>}} or {{ic|<nowiki>[[daemons|daemon]]</nowiki>}} and promote linking to redirects, e.g. {{ic|<nowiki>[[AIGLX]]</nowiki>}} or {{ic|<nowiki>[[daemon]]</nowiki>}}: this would have the advantage of:
 +
 
 +
# making the source text simpler and easier to read
 +
# keeping track of the particular "reason" why a link is made, also grouping the various links by "reason" in WhatLinksHere pages
 +
# allowing quickly updating link fragments in case of section renames
 +
 
 +
We may even encourage to create redirects like those when the alternative text could be used somewhere else.
 +
 
 +
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:09, 12 July 2014 (UTC)
 +
 
 +
:Exactly my thoughts, we've gotten too far in the "update link(s) (avoid redirect)" series of edits, which apparently set a bad example for others. Redirects are a feature and as such should not be avoided, except for the following cases (which I consider confusing):
 +
:# the titles differ only in capitalization
 +
:# the link is given in the 'Related articles' floating box
 +
:# two links to the same target are given next to each other, one of them goes over redirect
 +
:Also when a phrase {{ic|<nowiki>See [[Some page]] for details.</nowiki>}} is used, it should be a direct link, but this is not very confusing and likely depends on context, sometimes redirects might be desired even in this case.
 +
:There are also some tricks to save writing the anchor text in some cases, see for example [[Help:Editing#Pipe trick]]. Then there is the following syntax: {{ic|<nowiki>[[window manager]]s</nowiki>}}, which will result in [[window manager]]s, but this can be solved also with a redirect. (off-topic: does [[Wiki Monkey]] support this?)
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:21, 12 July 2014 (UTC)
 +
 
 +
::I agree with the exceptions. About {{ic|<nowiki>See [[Some page]] for details.</nowiki>}}, I'd still consider my points 2) and 3), and maybe at least don't explicitly list the case among the exceptions (we'll have to write this rule more as a recommendation than an obligation anyway, so the editors will be able to decide case by case). We could also recommend the pipe or the suffix trick over redirects when it's possible to use them. (OT: nope, [https://github.com/kynikos/wiki-monkey/issues/186 #186] [https://github.com/kynikos/wiki-monkey/issues/188 #188]) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:21, 13 July 2014 (UTC)
 +
 
 +
:::Considering that some of these rules are already being enforced then perhaps they should be added (in some form) to the page instead of hiding them on the talk-page?
 +
:::However, with redirects to sections being broken and no fix in sight, I would rather see explicit links to sections, i.e. {{ic|<nowiki>[[Xorg#Composite|AIGLX]]</nowiki>}}, being tolerated than to expect from the reader to figure out what the author meant when he placed the redirect to an article with a dozen sections, hundreds of lines and several thousand words. IMHO the cost of a slightly more verbose source is bearable in this case.
 +
:::[[User:Namarrgon|Namarrgon]] ([[User talk:Namarrgon|talk]]) 00:12, 3 March 2016 (UTC)
 +
 
 +
::::I agree to [[User:Namarrgon|Namarrgon]]'s above comment. We need a note in [[Help:Reading]] and [[Help:Style]] about this asap. Apart from the bugs (server&client side), requiring JavaScript is a severe limitation. Does anyone know, if these section redirects are the only feature used in ArchWiki that requires it for browsing? If yes, I would vote for eliminating them all. edit: IMO the JavaScript requirement results in what the [https://www.gnu.org/software/toutdoux/doc/user/fr/x522.html GDL] calls "opaque" (see resulting {{Pkg|arch-wiki-docs}}). -- [[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 08:49, 3 March 2016 (UTC)
 +
 
 +
:::::The bugs are indeed the reason why this recommendation has never made it into the main guidelines. Honestly in 2016 I wouldn't consider requiring JavaScript a "severe limitation" :) If I had to vote in a poll, I would still support using the redirects because IMO the 3 reasons I outlined in the OP outweigh the browsing issues that affect only a minority of users in those few cases when a JS-enabled browser isn't available. I don't see much room for compromises, maybe we really need a poll? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:36, 3 March 2016 (UTC)
 +
 
 +
::::::Well, with Chrome 48 and JS enabled it stopped working for me too... -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 11:38, 3 March 2016 (UTC)
 +
 
 +
::::::... same problem with {{Pkg|epiphany}} (gnome-web/gnome-shell has JS enabled). I have added {{Bug|48427}}, please vote for it. -- [[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:45, 3 March 2016 (UTC)
 +
 
 +
:::::::Redirects to sections seem to work normally with the latest Chromium or Epiphany on Wikipedia, which has already upgraded to MediaWiki 1.27, try any link from [[w:Category:Redirects_to_sections]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:37, 5 March 2016 (UTC)
 +
 
 +
::::::::Yes, I get the same results as you (tried chromium, epiphany), good news. Reading related info it seems to me all affected browsers are webkit based (which amount to ~50% browser base, unfortunately). I have added [https://wiki.archlinux.org/index.php?title=Help%3AReading&action=historysubmit&type=revision&diff=424044&oldid=423661] for now (please adjust as you deem to). Many thanks to Lahwaacz, who sprinted to fix {{Pkg|arch-wiki-docs}}. When I opened {{Bug|48427}}, I was thinking we may simply point to the package as a work-around, but with Chrome et al affected that's clearly not enough. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:43, 5 March 2016 (UTC)
 +
 
 +
:::::::::Thanks, I've [https://wiki.archlinux.org/index.php?title=Help%3AReading&type=revision&diff=424254&oldid=424044 reworded] the notes because reloading the page doesn't seem to work on browsers that attempt to remember the scroll state. – [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 02:50, 6 March 2016 (UTC)
 +
 
 +
Redirects to sections are affected by some bugs:
 +
# It depends on some JavaScript code, which is a MediaWiki bug: [[phabricator:T53736]]
 +
# Until MediaWiki 1.27, the JavaScript code responsible for redirects to sections behaves unreliably: [[phabricator:T110501]]. Consequently, some browsers will have trouble with opening the target page at the correct position: [https://github.com/The-Compiler/qutebrowser/issues/1190#issuecomment-167262664].
 +
There is nothing we can really do about this, we can only wait for the fix(es) upstream.
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:05, 2 March 2016 (UTC)
 +
 
 +
== Titles: singular or plural? ==
 +
 
 +
Currently we have [[daemons]], [[List of applications]], [[:Category:Proxy servers]]... but also [[window manager]], [[display manager]], [[:Category:Mail server]]... I'm for enforcing the plural version in all cases. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:26, 13 July 2014 (UTC)
 +
 
 +
:I agree, plurals sound better, it's also how Wikipedia does it:
 +
:* [[Wikipedia:Wikipedia:Naming_conventions_(plurals)#Exceptions]]
 +
:* [[Wikipedia:Wikipedia:Category_names#General_conventions]]
 +
:[[User:Axper|axper]] ([[User talk: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. -- [[User:Kynikos|Kynikos]] ([[User talk: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.
 +
:::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 16:38, 26 December 2014 (UTC)
 +
 
 +
::::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)
 +
 
 +
:::::See also [[ArchWiki:Requests#Renaming_of_categories]]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:12, 9 August 2014 (UTC)
 +
 
 +
=== Underscores vs. slashes in kernel module names ===
 +
 
 +
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]
 +
 
 +
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.
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 {{ic|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.
 +
:[[User:Axper|axper]] ([[User talk:Axper|talk]]) 06:04, 10 August 2014 (UTC)
 +
 
 +
::+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)
 +
 
 +
=== Alphabetical order ===
 +
 
 +
Example: [https://wiki.archlinux.org/index.php?title=Xorg&diff=prev&oldid=327850]
 +
 
 +
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?
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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. -- [[User:Alad|Alad]] ([[User talk: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. [[User:Axper|axper]] ([[User talk: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.
 +
:::-- [[User:Kynikos|Kynikos]] ([[User talk: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]] -- [[User:Kycok|Kycok]] ([[User talk: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.
 +
 
 +
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk: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 [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)
 +
 
 +
::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)
 +
 
 +
::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)
 +
 
 +
=== "as of version X.XX..." ===
 +
 
 +
Example: [https://wiki.archlinux.org/index.php?title=Core_utilities&diff=424410&oldid=424178]
 +
 
 +
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)
 +
 
 +
: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)
 +
 
 +
::+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)
 +
 
 +
:::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)
 +
 
 +
:::: 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)
 +
 
 +
::::: (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)
 +
 
 +
== Hypertext metaphor interpretation ==
 +
 
 +
Regarding [https://wiki.archlinux.org/index.php?title=Talk:VDR&diff=331548&oldid=331546], what is ok to duplicate and what not?
 +
 
 +
The relevant rules in [[Help:Style#Hypertext metaphor]] are:
 +
 
 +
:* Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
 +
:* If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.
 +
 
 +
''In my view'', the first one refers to internal articles only, so it doesn't apply here. The second should be regulating duplication of external sources. Now, I don't think we can consider https://wiki.debian.org/VDR as the "upstream documentation" for VDR, so I think duplicating the article here could be allowed, as Debian's wiki article (even if written by the same author) can't be considered a more reliable — or better maintained — source than this one.
 +
 
 +
I've posted here because I want to discuss the interpretation of those rules in general, and possibly end up improving them to make their meaning clearer.
 +
 
 +
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:57, 21 August 2014 (UTC)
 +
 
 +
:You are right that there is no rule to address the issue ''directly'', hence my reply in [[Talk:VDR]] is probably an overstatement. Sometimes I link to [[Help:Style#Hypertext metaphor]] just so that the user gets the general idea.
 +
:To the interpretation of "Hypertext metaphor": IMV, "upstream/official documentation" in the second aforementioned rule ''can be'' "any external resource the editor is currently working with". For some projects, the notion of upstream/official documentation is pretty clear (e.g. [[i3]] with their [http://i3wm.org/docs/userguide.html userguide]), some projects have multiple high-quality "official documentations" (developers' blog posts, manpages, READMEs...), and some projects have none. In the last case it shouldn't matter if the source is hosted on some other distro's wiki or not, they should all have the same priority.
 +
:Regarding maintenance, [[VDR]] is not maintained [https://wiki.archlinux.org/index.php?title=VDR&diff=312049&oldid=239286 since 2012], while [https://wiki.debian.org/VDR Debian's] article has a [https://wiki.debian.org/VDR?action=info stable maintainer] (probably the same person as [[User:Cdwijs]]). This could be a reason both for and against porting the Debian's article here, but maintaining a single article is surely easier than maintaining two.
 +
:It is also questionable if porting an article from MoinMoin (used by Debian's wiki) to MediaWiki syntax can be called a duplication, but I still think it is useless from the reader's point of view.
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:07, 21 August 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)
  
==Request to change recommended package installation style==
+
::It looks like I forgot what was written above ... -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:30, 5 November 2015 (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.
+
== File types ==
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:
+
File types are formatted as per [[Help:Style#Code formatting]], right?:  
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.
+
:* ''Use {{ic|<nowiki>{{ic|code}}</nowiki>}} for short lines of code, file names, command names, variable names and the like to be represented inline [..]''
: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. :)
+
Does it need mentioning?:  
::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.
+
:* ''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: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.
+
'''<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)
::::If we can create some good redirects for common searches like that, would your concerns be addressed (or at least partly)?
+
::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 23:03, 18 June 2012 (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. 
+
: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)
:::::  -- [[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.
+
:: 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)
::::::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?
+
== Some style/grammar guidelines ==
:::::::I'm going to create a redirect for [[install package]] and [[install packages]] now.
+
:::::::-- [[User:Jstjohn|Jstjohn]] ([[User talk:Jstjohn|talk]]) 13:58, 21 June 2012 (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:
+
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:
::::::::{{bc|[[pacman|Install]] the package {{Pkg|xmonad}} from the [[Official Repositories|official repositories]].}}
+
* 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."
::::::::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.
+
* 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''".
::::::::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:
+
[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 20:13, 4 March 2016 (UTC)
::::::::{{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 ==
+
:[[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.
I'd like to suggest you / we add wording & style suggestions for systemd daemon operations to [[Help:Style#Daemon_operations]]. --[[User:Stefanwilkens]]
+
: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)
  
:Agreed, can you start with an example of suggestions? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:58, 3 October 2012 (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?
::Considering that giving direct examples that can be copy pasted is deprecated, I would suggest something like this:
+
::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
::Use [[Systemd#Using_Units|systemctl]] to enable <servicename> with <servicefile> during boot.
+
:::''It is also recommended to disable password logins entirely. This will greatly increase security.''
::{{Note|Use [[Systemd#Using_Units|systemctl]] to enable GDM with {{ic|gdm.service}} during boot.}}
+
::That's fine, but it reads just as well like so:
::Or the more to the point:
+
:::''Disabling password logins entirely greatly increases security.''
::<Action> <servicename> with <servicefile> using [[Systemd#Using_Units|systemctl]].
+
::Greatly increasing security is obviously good, so recommending it doesn't really add anything.
::{{Note|Start GDM with {{ic|gdm.service}} using [[Systemd#Using_Units|systemctl]].}}
+
::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.
::{{Note|Enable GDM at boot time with {{ic|gdm.service}} using [[Systemd#Using_Units|systemctl]].}}
+
::[[User:Silverhammermba|Silverhammermba]] ([[User talk:Silverhammermba|talk]]) 06:52, 5 March 2016 (UTC)
::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 ==
+
:::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.
 +
:::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:29, 6 March 2016 (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.
+
::::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)
  
* Introduction
+
:::::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.
** What is a discussion page.  
+
:::::Also +1 for the second part about recommendations.
** What kind of content should be added.
+
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:58, 6 March 2016 (UTC)
** 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]].
+
::::::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.
:Finally I'm mentioning also here that this project can be considered part of [[Help talk:Style#Better structuring]].
+
::::::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]]) 16:10, 25 December 2012 (UTC)
+
::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:20, 7 March 2016 (UTC)

Latest revision as of 11:25, 4 June 2016

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.

Change Edit Summary label and possibility to make it mandatory

All edits to articles should be accompanied by some words in the summary filed, answering the question "Why did you edit the article?". "What", "where", "when" and "how" are self-explained by the diff itself, it's redundant to add them. An explanation is not mandatory in talk pages, where the "why" should be already evident. Remember that links are allowed in the summary field, so it is allowed to point to an existing discussion. -- Kynikos 09:32, 3 May 2011 (EDT)

Maybe we could submit a bug to request the change of the word "Summary:" to "Reason for editing:" next to the input in the edit page itself? -- Kynikos 11:33, 3 May 2011 (EDT)

+1
Would it go directly upstream? The Polish wiki has something like Summarize the changes [you've made to the article]. Wikipedia has Edit summary (Briefly describe the changes you have made). They all deal with what is being changed, not why - we need to fix this :-) -- Karol 12:04, 3 May 2011 (EDT)
Done: FS#24075, remember you can vote it. -- Kynikos 12:57, 3 May 2011 (EDT)
Any wiki admin can change this message (aside: can you view Special:AllMessages?) I think it might be more fitting to include this as an addendum to the copyright notice instead (text above the summary field). Perhaps we should also consider making the edit summary mandatory (i.e. prevent saving with a blank summary). -- pointone 22:55, 4 May 2011 (EDT)
Nice, I can see that page, I didn't know that ^^ Maybe I should close the bug request then. Anyway I'm quite sure that only appending this recommendation to the copyright notice would make people start ignoring it very soon (as it happens with road signs eheh): I'm still in favour of changing the word "Summary", as it's misleading. Making the field mandatory could be a great idea instead, but for what I've seen until now, if the edit page returns an error, it forgets about the editing done, and it would be quite annoying (the textarea could be easily repopulated echoing $_POST['...'] instead of recovering the text back from the database; I have only tested this when trying to edit a page that has been edited by somebody else meanwhile). -- Kynikos 06:15, 5 May 2011 (EDT)
(Well, doing it in javascript would solve the problem, though using JS is not very wiki-style it seems) -- Kynikos 06:17, 5 May 2011 (EDT)
When saving an edit that conflicts with another, your changes are saved. MediaWiki presents you with two text areas: one contains the page contents and the other contains your edit.
Either way, a quick Google search reveals User:DieBuche/forcesummary.js and Wikipedia:Wikipedia:WikiProject User scripts/Scripts/Force edit summary as two possible solutions. There also is a user preference option under Editing > Advanced options > Prompt me when entering a blank edit summary -- I wonder whether we can enable this option by default as a less-intrusive solution.
-- pointone 09:16, 5 May 2011 (EDT)
Uhm it always looked like I lost my changes everytime I had edit conflicts (always easily recovered with the back button), anyway it could be that I didn't look well.
About the main topic, I would first try just to change the Summary text, anyway if you want to go the JS way immediately, do it in a way that the user understands that he has to answer the question "why", not "what", otherwise all edit summaries would probably be filled with "added section", "corrected code", "deleted section" and so on (well, those are summaries in the end, and that's what the form requests literally atm). -- Kynikos 11:07, 5 May 2011 (EDT)
I think it's also OK to combine 'what' with 'why' e.g. 'removed outdated links'. I'm not a native English speaker, but it sounds more natural than 'links were outdated'. -- Karol 11:50, 6 May 2011 (EDT)
Of course it's also ok, anyway I'm not a native speaker either, but if a label says "Reason for editing" it comes more natural to me to write "links were outdated". This system should also exploit a bit of psychology afterall. -- Kynikos 12:56, 6 May 2011 (EDT)
<facepalm> Of course you are absolutely right ... I - ummm - forgot that we wanted to change 'Summary' to 'Reason for editing'. Sorry about that. -- Karol 19:58, 8 May 2011 (EDT)
Since the bug got closed as 'Upstream', do we go upstream with this? -- Karol 19:58, 8 May 2011 (EDT)
I am curious whether this has been discussed upstream already... I have no problem with making the change on our end, since every wiki handles summary policy differently (as pointed-out above in examples). -- pointone 22:46, 8 May 2011 (EDT)
Well you are the one in charge here, you can decide what to do now ;) -- Kynikos 05:53, 9 May 2011 (EDT)
The style part of this discussion has been implemented in the guide. I'd still be interested in changing "Summary" to "Reason for editing", anybody else? -- Kynikos 15:32, 21 September 2011 (EDT)
Going upstream would benefit more that just our wiki, as mediawiki is a pretty popular piece of software. +1 from me. -- Karol 16:45, 21 September 2011 (EDT)
The relevant system message is MediaWiki:Summary. I would suggest that the word "Summary" itself remain, as it is referenced in other locations and the documentation. My vote is for addition of an explanatory subtext à la Wikipedia. (Summary: (Briefly describe the changes you have made)). -- pointone 13:50, 22 September 2011 (EDT)
Cooool, that's the way to go! +1000 XD
Some ideas:
  • Briefly explain the reason for the changes you have made
  • Briefly explain the reason for your edit
  • Briefly explain the reason for your changes
  • Briefly explain the reason why you edited the page
-- Kynikos 15:55, 22 September 2011 (EDT)
I think a combination of using explanatory text (I like something such as "Briefly explain the reason for your changes" from your suggestions), and investigating how to set "Prompt me when entering a blank edit summary" user option by default would make it more noticeable and be a great start here. Emiralle 12:56, 15 October 2011 (EDT)
I'd like to make the edit summary strictly mandatory (meaning that a blank summary field won't allow submitting the edit): pointone mentioned some possible methods for doing this in the first part of the discussion, I'm just adding some more references as reminders (don't know exactly what to do with them yet... :P ): [1] (see "forceeditsummary"), [2], [3]. -- Kynikos 15:01, 20 October 2011 (EDT)
For the moment I've changed the label to:
Summary (what you did and why):
as you can see when opening a page for edit, I hope it's ugly and annoying enough to be noticed by many >;)
-- Kynikos (talk) 11:37, 11 July 2013 (UTC)
The edit box has been moved to the right, so it's easy to spot that something's different. I like it, good job, Kynikos. -- Karol (talk) 19:14, 12 July 2013 (UTC)
About making the Prompt me when entering a blank edit summary option enabled by default, this is what has to be done:
  1. Have FS#35545 implemented
  2. Edit MediaWiki:Missingsummary and make it more visible and formative
  3. Add the forceeditsummary option to the default user preferences as described in mw:Manual:$wgDefaultUserOptions
-- Kynikos (talk) 03:06, 13 July 2013 (UTC)
I went ahead and submitted a feature request (FS#46190), with even better technical solution. Let's see how this goes... -- Lahwaacz (talk) 15:21, 3 September 2015 (UTC)

Article summary templates

See Help talk:Style/Article summary templates.

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

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

Application name capitalization

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

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

List of Applications and See also

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

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

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

One link to the package in a paragraph is enough

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

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

Prefer linking to the article than to the package

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

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

git/vcs/source builds

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

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. [15] ;) -- Kynikos (talk) 05:16, 12 January 2014 (UTC)
I have a general question: what are the rules for using mdash ("—") vs. ndash ("–") in English literature? Is there supposed to be a space around them or not?
(I did not intend to challenge your work, I'm just curious - the rule is very likely to be different from those used in Czech...)
-- Lahwaacz (talk) 20:57, 11 February 2014 (UTC)
There is not supposed to be a full space around the em dash ("—") or the en dash ("–"). Ideally, the em and en dashes will be surrounded with a hair space, which is just wide enough to put a one pixel space between the dash and the adjacent characters, which makes it easier to read because the dash doesn't look like it's part of an adjacent character. I did not put hair spaces in my edits because I generally find it tedious to do.
As for when you should use the em dash vs. the en dash... the em dash is used for large pauses in speech or for side notes — notice the hair spaces around these em dashes — and the en dash is used for numeric ranges (e.g. 47 – 83).
The hyphen looks similar to the en dash ( - –  ← hyphen on the left, en dash on the right), but the hyphen is only supposed to be used between certain compound adjectives and nouns.
There's also the minus sign ("−"), which looks very much like an en dash ( − –  ← minus sign on the left, en dash on the right). It should only be used in mathematical formulas or when writing negative values (e.g. 47 − 83 = −36)
If you haven't noticed, I'm a bit of a typography geek. haha
-- Jstjohn (talk) 02:02, 13 February 2014 (UTC)
Thanks for this nice explanation! It is a shame that the wiki markup language does not have special syntax for this punctuation, entering the HTML codes is really PITA. There are some packages for LaTeX that translate "--" into en dash and "---" into em dash. But typographically, TeX is on completely different level than wiki. -- Lahwaacz (talk) 08:08, 13 February 2014 (UTC)
We could possibly add MediaWiki templates for the em dash and en dash. Adding a template for the minus sign seems like it might be overkill. For example, {{emdash}} or {{em dash}} would output &.#8202;&.mdash;&.#8202; (without the dots, of course)
-- Jstjohn (talk) 23:59, 18 February 2014 (UTC)
I say let's keep it simple, who would use those templates in practice? They would also go against our decision to e.g. use typewriter quotes instead of typographic, see Help:Style/Formatting_and_Punctuation#Quote_marks. As Lahwaacz mentioned, a wiki is not TeX, it's designed to keep source and rendered text similar, and punctuation templates would reduce readability of source text. MediaWiki takes care of translating source text characters into HTML entities when needed, and in my view we shouldn't try to bypass such feature except when really needed (see also Help:Template#HTML_entities). If you want to use some particular punctuation marks, IMHO you should enter them directly, possibly assigning them as special combinations to your keyboard map. -- Kynikos (talk) 06:00, 19 February 2014 (UTC)
Regarding source text readability, why not just input the unicode character itself — like this? (Notice that it works also for the hair spaces, though they are not very "hairy" in the source...) -- Lahwaacz (talk) 07:01, 19 February 2014 (UTC)
I would use those templates. :)
I agree that {{em dash}} would be less readable than a directly-entered "—" character; however, {{em dash}} is a lot more readable than &.#8202;&.mdash;&.#8202; (without the dots), which is why I support the idea. I feel that directly-entered em dashes with the surrounding hair spaces (using the Unicode characters directly) is less maintainable than {{em dash}} because subsequent edits may remove one or both of the hair spaces without editors realizing that they did so.
-- Jstjohn (talk) 01:14, 20 February 2014 (UTC)
Ok, I admit that to me all this seems overly complicated as in not Simple, however, as Help:Style/Formatting_and_Punctuation#General_rules says, "for cases not covered in this guide, Wikipedia:Wikipedia:Manual of Style is the authority reference", and to me it seems very sensible to stick with that rule instead of attempting to create our own punctuation guides. In particular, Wikipedia:Wikipedia:Manual_of_Style#Punctuating_a_sentence_.28em_or_en_dashes.29 says "do not use spaced em dashes", while they do have a {{spaced ndash}} template, so IMO that's what we should follow. -- Kynikos (talk) 14:21, 20 February 2014 (UTC)
If we decide for the templates way, which subset of the Wikipedia formatting and function templates should be used on ArchWiki?
I don't like the templates either, this had better be solved upstream (either directly in the parser core or via an extenasion. The only mention of upstream dealing with this I found is this rather old discussion, so it's probably going nowhere. (Extending the parser should not be that hard, a couple of regular expressions should do it for the dashes -- I'm surprised that it's not done yet...)
Suggestions so far: 1) use HTML entities (such as &mdash;), 2) use templates (such as {{em dash}}), 3) use the Unicode characters directly, 4) use some extension (none found yet), 5) drop the typography rules completely (use plain spaced hyphen " - " or commas) -- this could be called "wait for upstream to implement the necessary change" :P
-- Lahwaacz (talk) 16:43, 20 February 2014 (UTC)
Well, as I've said I'm for 3), with the possible advice of setting key combinations for the most frequent cases (e.g. AltGr + -I'm aware of 1 for the em dash). Just out of curiosity, _personally_ I tend to use ~5) because in my native language all the cases where English requires dashes are covered by commas or parentheses, so I'll be seen rarely, if ever, using dashes in my contributions.
Even if there was an extension to parse "--" and "---", we'd still find resistance for having it installed in our wiki... Maybe upstream they're just waiting for your patch! ;)
About Wikipedia's "formatting and function" templates, for sure we're discarding the "function" ones, and about the others I'd say let's create them one at a time whenever one is needed, but only if method 3) and method 1), in that order, would require too much typing effort for that case.
For completeness' sake, there's also a suggestion 6) to use a (theoretical) external editor that turns "--" and "---" into proper dashes before sending the text to the server, and does the opposite when retrieving a page for editing.
-- Kynikos (talk) 14:38, 21 February 2014 (UTC)
A little note, the Colemak layout already comes with en dash and em dash respectively preset to AltGr+- and AltGr+Shift+-. -- Kynikos (talk) 13:49, 10 June 2014 (UTC)

Rule suggestion: reference links

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

The suggestion:

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

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

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

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

Finally, some reference links for completeness: [16], [17]

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

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

Slashes in titles

It should be made clear that / in page titles will create a subpage, even if the parent page does not exist. Different wording (which must exist) should be used in cases where the subpage is not desired. While everything is working OK on the web interface, missing this detail will make alternative interfaces, e.g. arch-wiki-docs, quite confusing.

Some infamous pages suffering from this issue:

Additionally, I don't like the use of / even in section titles, it just looks wrong: List of applications#Scans/Image.

-- Lahwaacz (talk) 19:42, 21 March 2014 (UTC)

Umm, technically what I just said is wrong - subpages are disabled in the Main namespace. See for yourself: add {{SUBPAGENAME}} to systemd/User and preview, it will return "systemd/User" and not "User". (Also notice the small navigation link below the title in Help:Style/Formatting_and_punctuation) $wgNamespacesWithSubpages is probably set to default value in Arch Wiki configuration.
See also wikipedia:Help:Subpages#Slashes_in_article_titles.
-- Lahwaacz (talk) 08:56, 22 March 2014 (UTC)
Yes, subpages are disabled in the Main namespace. /dev/shm works in XFCE simple Network Monitor applet because that article is in the Main namespace and slashes are not specially interpreted there, while they are interpreted as relative (to the current page) links in the other namespaces like Help_talk, hence the red link since Help_talk:Style/dev doesn't exist. You must prefix a link like that with a colon in order to turn it into an "absolute" link, like [[:/dev/shm]].
That said, do you still support mentioning subpages in the guide? And how exactly? Also, would you forbid slashes in section titles? (I wouldn't, but I'm open for discussing as always)
-- Kynikos (talk) 17:11, 22 March 2014 (UTC)
Well, we should either enable subpages everywhere (or just the Main namespace in addition to those currently enabled?), or avoid using the term "subpage" altogether: Help:Style#Title, Help:Style#Kernel module operations, ..., Talk:Arch systemd container, Talk:Dm-crypt, ... Is there too much harm in having S/KEY Authentication a subpage of S? Is there a way to disable the 'subpage' feature on specific articles? Alternatively, would it be even more confusing to rename the page to S KEY Authentication?
-- Lahwaacz (talk) 08:32, 23 March 2014 (UTC)
I tend to be against real subpages in the Main namespace, as they would prevent the normal usage of slashes in titles, as you note too. Wikipedia has the same configuration by the way (but http://wiki.gentoo.org uses subpages).
I understand that using the term "subpage" can be confusing if taken literally, but how would you call the practice of naming articles like "Beginners' guide/*", "List of applications/*" and so on?
S/KEY Authentication as a subpage of S would create a confusing link at the top of the page, under the title (IMHO more confusing than the current usage of the "subpage" term).
If there was a way to disable subpages per-page, it would be through mw:Help:Magic_words, but it looks like there's nothing for that (yet?).
Renaming articles like S KEY Authentication would mean enforcing the rule of avoiding slashes in titles, which is something I would be against... Unless we make use of DISPLAYTITLE to display the correct titles?
Finally, I refuse to open a report to change the configuration of the wiki before FS#35545 is implemented >:( (Please, anybody reading here, vote for it)
-- Kynikos (talk) 21:54, 23 March 2014 (UTC)
Interesting, [18] does not show the link below the title. Maybe because the parent page does not exist? -- Lahwaacz (talk) 22:51, 23 March 2014 (UTC)
Very interesting indeed, I've done a test here and the link does not appear if the super-page doesn't exist. This actually turns my preference towards enabling subpages also in the Main namespace. However we should patch LocalSettings.php for that, and FS#35545 is a blocker unfortunately. -- Kynikos (talk) 18:21, 24 March 2014 (UTC)
I have misunderstood Meta-Wiki entry yesterday; today I found the information in MediaWiki too, but Meta-Wiki adds an interesting detail about breaking the breadcrumb links sequence on first non-existent page.
Wikipedia describes that they originally used subpages, but then switched to the disambiguation system, which probably lead to disabling subpages by default. We don't use disambiguations, so I don't see any further reason why the Main namespace should behave differently.
FS#35545 is the blocker, but we won't get anywhere without submitting another bug - it could be the necessary catalyst. (About [19]: you've won two votes since yesterday :)
-- Lahwaacz (talk) 19:31, 24 March 2014 (UTC)
You're absolutely right, I'll let you open the report since the idea and the research are yours; it would be better if you could restate the supporting arguments there instead of linking here, and finally emphasize the fact that a patch will be provided if FS#35545 is implemented first (if we manage to have it fixed, it will be very very useful in the future).
-- Kynikos (talk) 18:08, 26 March 2014 (UTC)
Reported in FS#39668. -- Lahwaacz (talk) 00:03, 29 March 2014 (UTC)
Added my vote. -- Kynikos (talk) 14:30, 30 March 2014 (UTC)

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)

Formatting of references to man pages

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

How should references to manpages be formatted? Possible formats:

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

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

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

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

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

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

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

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: [20]. The edit clearly breaks the (future) rule "Do not use lists if a passage is read easily as plain paragraphs.", so the problem is reduced to usage of manual numbering - is it acceptable or do we tolerate HTML tags in such cases?

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

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

{{Note|bla-bla}}

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

See also links

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

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

I vote for the first style. It's compact and IIRC already more popular than the other styles. axper (talk) 16:00, 1 July 2014 (UTC)
Agreed with axper, +1 to the first style. --Alad (talk) 18:28, 1 July 2014 (UTC)
I like the first style too. Also, I think this is how the Wikipedia does it. -- Karol (talk) 20:35, 1 July 2014 (UTC)
I'd prefer the first style too, but I forgot that links in See also section can be accompanied by descriptions, these are some examples of how the style can vary: Core utilities#See also, Secure Shell#See also, Systemd#See also, KDE#See also (funny), Xfce#See also, List of applications#See also. I haven't made up my mind yet. -- Kynikos (talk) 06:48, 5 July 2014 (UTC)
Meahwhile I've run into a non-standard section in Cursor Themes and I've changed it like this. -- Kynikos (talk) 03:01, 6 July 2014 (UTC)
+1 for the first style. Yet the examples show how useful a description can be, I vote for making it optional. Having an optional description behind the link looks much neater as well imo, rather than trying to use the link title to transport it in those cases.
Focussing on the links in Systemd#See also: some are indeed a little dated (already), but it would be a pity to loose them. I was wondering for a moment whether it would make sense to foster grouping them, e.g.
But then again there are few cases with that many links and the description can be useful/enough to transport that information too. Some sort of grouping happens automatically by editors keeping relevant links together and ordering most relevant (e.g. project home pages) first.
In my view the whole could be clarified by just appending some examples to Help:Style#.22See_also.22_sections ala:
Examples:
--Indigo (talk) 18:28, 11 August 2014 (UTC)

Preferred subpage method

Options:

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

I think, current method (number one) is good. The third one is bad (for example, it's very bad for List of applications Utilities). You can add another method with colon symbol: Page:subpage. But I'm ok with the first one -- Kycok (talk) 07:56, 4 July 2014 (UTC)
As subpages are a feature of MediaWiki, the only way to have a full subpage experience is the first option. Unfortunately, it is currently disabled in the Main: namespace on Arch wiki (see #Slashes in titles). Until it is enabled, all options have equal weight, but using anything different than slashes does not make sense if we want to eventually switch to them. -- Lahwaacz (talk) 08:20, 4 July 2014 (UTC)
As Lahwaacz says, using the slash form is the way to go for forward compatibility, do we want to write a rule and already start changing the existing non-compliant titles (e.g. pacman tips)? The problem is that without the little navigation links under the title, it's not immediate to understand the meaning of the slash, especially for short titles, which at the moment look neater with a simple space. -- Kynikos (talk) 06:59, 5 July 2014 (UTC)
My vote goes for option #4 (using sections like Wikipedia):
  1. Doesn't to pollute the "Related articles" column with number_of_subpages2 lines (or equivalent) with added complexity of maintaining all that
  2. Doesn't pollute the category pages
  3. It's easier to find information (i.e. Ctrl+f or / or by looking at TOC)
  4. No confusion caused by non-existent separator character
  5. Is just simple. Remember KISS? :)
axper (talk) 16:08, 8 July 2014 (UTC)
OK, let's compare us to Wikipedia (see wikipedia:Wikipedia:Subpages for reference). Basically, it forbids using subpages in the Main: namespace. The history section states, that subpages were once used to create hierarchies of articles, but then it was superseded by categories and disambiguations. On Arch wiki, the hierarchy of categories was designed as a tree (although in practice with some "converging branches", see #Category pages - tree or otherwise?) and we don't use disambiguations at all. Unlike Wikipedia, so far this system works quite well on Arch wiki, which I think is mainly due to the type of content, amount of content and greater devotion and attention to detail of the Maintenance Team :)
Sometimes an article is too long to be kept on just one page, and the easiest solution is to split some section into a separate article, which will effectively create a subpage. I don't really see how this could be avoided without completely rewriting it, disambiguations or categories won't help here.
But I could agree that the usage of subpages should be regulated, for example PulseAudio/Troubleshooting would be good, while Kernels/Compilation/Traditional would be wrong (see the Wikipedia case). I don't know yet about Color Bash Prompt and something like Bash/Color prompt.
-- Lahwaacz (talk) 09:00, 9 July 2014 (UTC)
Well, solution #4 would be ideal, but in practice I think we can't really help splitting articles, both for length issues and because it's hard to understand when to stop merging articles back to their "parents". Take for example dm-crypt: it has several quite long subpages, would an article that merges all of them be clearer to read? I wouldn't see it as an improvement. And then why not merge dm-crypt and the others back to Disk encryption?
A subpage system is much more manageable, especially from the point of view of the maintainers, rather than the readers, so we just have to stick with it and make it as efficient and organized as possible.
@Lahwaacz How would you rename Kernels/Compilation/Traditional? Kernels/Compilation is the only child of Kernels (and currently only a redirect), so probably all those subpages could be moved to Kernels/Traditional compilation and so on. Maybe we could limit the depth of subpages to just 1 in general?
About Color Bash Prompt, I think its natural subpage version would be more Bash/Prompt color, or, considering the actual content of the article, Bash/Prompt customization (I think we're using the AE spelling everywhere, but that's something else that's not regulated yet), Bash/Prompt style or similar.
-- 09:57, 10 July 2014 (UTC)
Yes, Kernels/Traditional compilation looks good. About Color Bash Prompt, I think that "color" is either a verb (as in "colorize") or an adjective, so I used it the same. But your alternatives are better. -- Lahwaacz (talk) 12:21, 10 July 2014 (UTC)
Thanks, what about limiting the depth of subpages to 1? -- Kynikos (talk) 04:13, 12 July 2014 (UTC)
I wouldn't mind more levels, provided that the first/previous level is wide enough. -- Lahwaacz (talk) 08:49, 12 July 2014 (UTC)

OK to put category pages in related articles list?

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

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

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

My first thought when reading this was "when the article is not included in the given category and it is still relevant, it should be included, otherwise not". On second thought, if the category is relevant enough, the article can be simple put into that category. The big problem is that related articles are at the top and related categories at the bottom.
We can either 1) leave pages at the top and categories at the bottom, 2) include every category into the 'Related articles' box at the top, 3) move the list of categories to the top (how?), 4) move the 'Related articles' box to the bottom (merge into 'See also' again).
Yep, so far I don't like either one of them for some reason or another...
-- Lahwaacz (talk) 19:25, 10 July 2014 (UTC)
About axper's proposed amendment, I agree, if a group of articles don't have a generic overview (e.g. unlike window managers), then linking to the category that groups them can be useful, if the edited article is not part of such category. Of course if the article itself is part of the category, there's the problem of duplicating the category link in the source text. This reminds me of an old idea of mine that I explained in [21]: translated to the "modern" wiki, it could mean replacing the normal categorization system with a Template:Category to be added to the Related articles box, when present, so that the article gets categorized under some categories, but their links are also shown somehow in the floated box. For example:
Current system
[[Category:Foo]]
[[Category:Bar]]
{{Related articles start}}
{{Related|link}}
{{Related articles end}}

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

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

Convention on added/removed text in Hc Templates

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

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

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

Nope, there's no policy on that (yet?). Your version is certainly an improvement, compared to the previous -+ system, although in my opinion there's no need to add italic to the stricken line (keep it simple). What I think I've seen around more often, though, is a more verbose:
In ~/.config/nautilus/accels, replace:
; (gtk_accel_path "<Actions>/DirViewActions/Trash" "<Primary>Delete")
with:
(gtk_accel_path "<Actions>/DirViewActions/Trash" "Delete")
Your version has the advantage of using Template:hc, thus making it visually clearer that those lines are two versions of the same line, and belong to the same file. The "verbose" version has the advantage of giving clearer written instructions about what has to be done.
Replacing lines doesn't seem to be very frequent in articles, maybe standardizing this would be too much. If we decided to use the "stricken" version, it would probably be worth adding a note in Help:Reading#Append, create, edit and source.
-- Kynikos (talk) 15:30, 11 July 2014 (UTC)

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

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

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

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

Links to redirects

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

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

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

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

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

Redirects to sections are affected by some bugs:

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

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

-- Lahwaacz (talk) 18:05, 2 March 2016 (UTC)

Titles: singular or plural?

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

I agree, plurals sound better, it's also how Wikipedia does it:
axper (talk) 07:35, 13 July 2014 (UTC)
As there are no objections, let's try to implement this; the problem is that it's not easy to find a good formulation. For Help:Style#Title I was thinking of something like:
  • By default, the topic name in titles should be in the singular form; it should be in the plural form if it represents a group or class of something and is a countable noun or perceived as such.
For Help:Style#Category pages:
  • By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe one of its members ("set" categories).
Do you think they are clear enough? Alternatively we could just link to the Wikipedia conventions that Axper pasted above. -- Kynikos (talk) 02:40, 26 December 2014 (UTC)
I think that your formulation provides the general idea, Wikipedia could provide some examples and peculiarities.
Edit: OK, the peculiarities of Wikipedia may not be wanted, because they include disambiguation pages or focus on content not applicable to ArchWiki.
-- Lahwaacz (talk) 16:38, 26 December 2014 (UTC)
Thanks for the feedback, rules merged with [24]. 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: [25] vs. [26]

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

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

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.[31] -- Lahwaacz (talk) 21:46, 6 March 2016 (UTC)
+1. For [32] see also [33]. Another missing features example is [34]. Such is difficult to track for readers who may have encountered the issue in the past and, in this case, perhaps used a different boot loader just because of it. Perhaps one could say "as of notes" are less useful to keep for missing features in the "Installation" sections, but the further down in the article they are (e.g. in a "troubleshooting" section) the more useful they are for awareness of updates. --Indigo (talk) 09:48, 7 March 2016 (UTC)
Yes, to generalize, I'd say that "as of" notes are indeed useful next to information that is expected (or maybe reasonably wished/feared) to change in the future. Certainly, added features don't fall in that category, so I agree with the Core utilities, GDM and makepkg edits, but I would undo the Python edit, and, as noted by Indigo, check the SSH keys edit against Talk:SSH_keys#PuTTY_elliptic_curve_support. Since we are in the talk page of the style guide, is there a proposal for the addition of a new rule to discuss? — Kynikos (talk) 07:53, 8 March 2016 (UTC)
I think a possible style rule could be that adding edits about when changes to a program occurred is mostly appropriate when it's about a bug, or about a product in heavy development that's expected to change soon. Just listing off when features were added to a stable program adds noise and should be avoided. Rdeckard (talk) 02:24, 19 March 2016 (UTC)
(Welcome to the team, Rdeckard!). Yes, though, take the putty example: it's long a missing feature, putty is not really what one would call heavy development. When the feature finally hits stable, an "as of" might help (an ssh client is an application where I would expect a lot users prefer to use stable and wait). Maybe it is easier to suggest a time-period, i.e. "as of notices" older than (half) a year after a bug or missing feature (which has been tagged as such in the content) has been fixed can safely be removed because of the rolling repos Arch uses.
As for the place to put it: we actually have Help:Style#.22Known issues.22 sections in the guide, but it is rarely used - which is understandable in my view, because mentioning a bug where the related configuration or features are described makes sense. Question is whether we need this style section at all (then an "as of" addition could be added to it), or it should be removed entirely and integrated into the more commonly used Help:Style#.22Troubleshooting.22_sections. (+1)
--Indigo (talk) 07:26, 19 March 2016 (UTC)

Hypertext metaphor interpretation

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

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

  • Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.
  • If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.

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

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

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

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

Citations and reasoning

Currently we have the following clauses on referencing content:

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

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

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

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

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

File types

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

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

Does it need mentioning?:

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

Dettalk 00:36, 6 October 2015 (UTC)

There is Help:Style/Formatting_and_punctuation#File_extensions. Some reorganization and/or cross-referencing would be in order... Lahwaacz (talk) 06:20, 6 October 2015 (UTC)
I've missed that completely. I fixed my edit in Wayland. —Dettalk 23:38, 8 October 2015 (UTC)

Some style/grammar guidelines

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

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

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

Help:Style#Language register says: "Articles should be written using formal, professional, and concise language." It is certainly possible to make the writing formal and professional enough (at least for this wiki) using second or third person, but recommending to use one over another is too strong, because the best wording usually depends on context. If the whole page is already written in second person, the next modifications usually also use second person to blend in, and vice versa.
The text should be professional, but also feel natural. For example, the Linux Containers page excessively uses "users" to refer to the reader: "Users may use other programs to achieve the same results." Simply using "you" instead of "users" might look better, but I'd write "Other programs may be used to achieve the same results."
As for recommendations, there is nothing wrong with them - they only have to stay objective, expressing personal preference is not allowed (also as per the Language register). In your examples, "It is recommended that you do foo in order to enable bar on your system" would be fine if it was followed by an explanation of why it is recommended.
-- Lahwaacz (talk) 21:22, 4 March 2016 (UTC)
Actually Linux Containers contains a random mix of second and third person. At a glance you've got "Install the...", "Verify that...", "Users may...", "Users are..." "Disable the...". You even have weird sentences that combine them "For users already using netctl to manage an adapter, simply switch-to it" (I guess you're switching on behalf of the users?). I agree that certain situations require third person, but this is clearly a case of different authors following different writing styles, resulting in strange repeated switching of perspectives. Considering that this problem is present on a lot of articles and we both agree that each article should maintain a consistent perspective, there are a lot of edits to be done. I was just figuring that while we're doing all of these edits, why not make them all consistent across articles?
Let me try to better convey my point about recommendations. I agree that recommendations are fine as long as you explain why, but they are also usually unnecessary if you explain why. For example, Secure Shell says
It is also recommended to disable password logins entirely. This will greatly increase security.
That's fine, but it reads just as well like so:
Disabling password logins entirely greatly increases security.
Greatly increasing security is obviously good, so recommending it doesn't really add anything.
But still, there are certainly exceptions. I suppose that's the case with all of my suggestions: they aren't hard and fast rules, they're more like guidelines that should be kept in mind. If that's not the kind of stuff we want in the style guide, I understand.
Silverhammermba (talk) 06:52, 5 March 2016 (UTC)
In this case I have to say I generally tend to agree with Silverhammermba: IMHO adding guidelines on these issues would still help resolve possible (minor) edit wars in the future; of course they wouldn't mean that non-complying edits would be rejected, like with all the other rules, but if e.g. two users disagree about the way to phrase something, we have something to resolve the dispute.
About the first problem, though, I tend to prefer third-person or passive-voice writing, and if "Users may use other programs to achieve the same results." doesn't sound as good as when using "You...", I do think that "Other programs could be used to achieve the same results." would sound even better. But I wouldn't generalize, since for example most of the very rules in this guide are better put with an imperative (i.e. second-person) form. For this reason I'd propose to add, in Help:Style#Language register:
  • When editing content, be consistent with the style used in the rest of the article. For example, if the reader is always addressed using the second person, this style should be adopted by the added content; the same goes if third person or passive voice are clearly dominant throughout the article.
And about recommendations, even though I'm surely guilty of giving many in my edits, I agree that a rule like the following could belong in the style guide:
  • When offering a choice among different options (pieces of software, methods to do something, etc.) do not explicitly recommend one over the others, but objectively describe the advantages and disadvantages of each, thus helping the reader to make the best decision for his personal case.
Kynikos (talk) 03:29, 6 March 2016 (UTC)
About "be consistent with the style...", in my experience w:Mirroring (psychology) is a strong phenomenon among editors, so I'm unsure if an explicit mention is needed in Help:Style.
About "objectively describe", +1 from me. -- Alad (talk) 03:56, 6 March 2016 (UTC)
Recommending mirroring would avoid the mixtures such as Linux Containers, but also conserve the (bad) style on other pages. Mirroring is a good fallback solution for situations when you have no idea, but I think the guidelines have to state what is right.
Also +1 for the second part about recommendations.
-- Lahwaacz (talk) 13:58, 6 March 2016 (UTC)
I remember writing this even when we were developing this page 5 years ago: this guide is only in theory aimed at teaching contributors what is the recommended style for the wiki; in practice, only a tiny minority of them reads any part of it, and it is indeed mirroring what accounts for the majority of the style-compliant edits (regarding any style rule, not only these ones). The real, practical aim of this guide is to solve disputes, as I said, and to give an official justification to the style-fixing edits made by the wiki staff and the other proactive users.
That is why explicitly defining what is good and what is wrong, whenever an issue is presented, is always pertinent here. I have added the two new clauses: perhaps that's not the most suitable section, if somebody wants to move them somewhere else, please go ahead, otherwise the next one who agrees can close the discussion :)
Kynikos (talk) 03:20, 7 March 2016 (UTC)