Difference between revisions of "Help talk:Style"

From ArchWiki
Jump to: navigation, search
(Commands with response)
m (File names: 1+)
Line 395: Line 395:
 
-- [[User:Kynikos|Kynikos]] 21:51, 29 September 2011 (CEST)
 
-- [[User:Kynikos|Kynikos]] 21:51, 29 September 2011 (CEST)
  
:[discuss here...]
+
:I think this would be both consistent with the other new templates and more readable with 'File' in the header. 1+ -- [[User:Roygbiv|Roygbiv]] 16:25, 6 October 2011 (EDT)
  
 
=====Command names=====
 
=====Command names=====

Revision as of 20:25, 6 October 2011

Discussing the guide itself

In this section you can discuss modification to the Style Guide itself.

Initial references

Style rules

This section is for discussing the addition or modification of style rules.

Edit summary

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)

Proper use of "This is a minor edit"

I know it is mentioned in Help:Editing#Editing (with a link to Wikipedia:Help:Minor_edit) but is it worth mentioning on the style guide as well? It seems at least as relevant as Help:Style#Edit summary. James Eder 15:32, 28 September 2011 (EDT)

Actually there are some things that should me moved from Help:Editing to this article, the reference to minor edits is only one of them. The scope of Help:Editing should be redefined as a description of all the "tools" that users have for writing articles, and how they work, while Help:Style should define the "boundaries" within one can use those tools. -- Kynikos 20:07, 28 September 2011 (EDT)

On the other hand it would likely be even more effective if "This is a minor edit" were changed to "This is a minor edit" (with the link opening in a new window). James Eder 15:32, 28 September 2011 (EDT)

Eheh the "link opening in a new window" is not something that can be made light of, I don't know if it's possible to do it using wiki syntax on a per-link basis, maybe pointone has more info :) -- Kynikos 20:07, 28 September 2011 (EDT)
This would appear to be a system-wide setting: Opening external links in a new window. The relevant system message is MediaWiki:Minoredit. -- pointone 13:06, 4 October 2011 (EDT)
I see, however I don't think it'd be worth the effort. -- Kynikos 17:52, 4 October 2011 (EDT)

Package installation

pacman -S package vs pacman -Syu package: already started discussing in User talk:Kynikos#"pacman -S foo" vs "pacman -Syu foo" and User talk:pointone#"pacman -Syu package". Probably a nice subject for a new thread in the forum? -- Kynikos 11:46, 3 May 2011 (EDT)

Agreed; this should be discussed with the community at large. -- pointone 22:56, 4 May 2011 (EDT)

[myusualbrainstormingmode ON]I would even add a third opponent: treat official package installation similarly to AUR packages: just list the packages to be installed (possibly with Template:Package Official) and link to Pacman or some other article for details on how to install.[myusualbrainstormingmode OFF] -- Kynikos 05:23, 17 May 2011 (EDT)

Ah, and maybe rename Template:Package Official to Template:Package or just Template:Pkg for ease of use. -- Kynikos 05:32, 17 May 2011 (EDT)

I agree! I don't think we should use the verbose "Install Template:Package Official: pacman -S pkgname" outside of the Beginners' Guide. "Install Template:Package Official." should be enough, and I don't think we need to link to pacman each time we do it, since archers learn how to install packages during the initial install. Explicit instructions are useful when it's not something completely obvious, like using --asdeps or -D. thestinger 05:48, 17 May 2011 (EDT)
Well the link could be implicit, like in "Install Template:Package Official". -- Kynikos 06:03, 18 May 2011 (EDT)
I think we could have a template for that too. Something like {{install|pkgname}} which would render as: "Install the Template:Package Official packagehow?" Bonus points if the template can accept a list of packages. I think the "how?" is small enough to be ignored by the more experienced but friendly enough for the novice. One could have a separate template for AUR packages which links to the AUR Wiki article instead. James Eder 17:19, 3 June 2011 (EDT)
Is there a way to use templates and point to a specific package? This is not what I want, I want just kernel26. Selecting only core repo makes it a bit better, but still not perfect. This method can cause some confusion so it would be nice to avoid it. -- Karol 18:06, 3 June 2011 (EDT)
I don't know if there is a way but it seems in most cases the right package appears at the top of the search results at least. On the other hand, most users probably are going to be using pacman to grab their package anyway. In that case, linking to the web front end for the database might not be that useful anyway. James Eder 19:24, 3 June 2011 (EDT)
About the template, I have the same position as for the daemons: it would force to use always the same wording while there are cases which would require different, more natural ways of explaining the installation. For example what would you do with optional packages? Would you make a Package Optional template? And with lists of packages? As far as I know, templates don't support for loops, so how would you print a list of packages with a single template?
About Karol's question, I think that the main problem would be the difference between i686/x86_64 and any packages: this would require 2 templates, unless we'd like to provide only one package in case it's a i686/x86_64 type. Apart from that, each package has a well defined URI, so it would be easy to compose it providing as arguments the package name and the repository.
Anyway, as stated by Pointone, all "this should be discussed with the community at large", e.g. in the forum I guess. -- Kynikos 10:20, 4 June 2011 (EDT)

Related: #AUR package installation

Let's sum up this discussion:

  • Package installation instructions should be given as "Install Template:Package Official, available in the [reponame] repository". The alternative is a template for doing this.
I think linking to the package is sufficient. Official and unofficial (AUR) packages should be differentiated, however. I do not support the use of a template which would tend to restrict editors. -- pointone 14:03, 22 September 2011 (EDT)
I agree, except that I haven't understood if you support the link to pacman or not. At the moment this is implemented with the link. -- Kynikos 16:38, 22 September 2011 (EDT)
  • Do we enforce also mentioning the repository? This will have to be maintained in case the package is moved somewhere else.
As mentioned above, official and unofficial packages should be differentiated. Maintaining repository information is unnecessary and troublesome; repository changes are not wholly uncommon. -- pointone 14:03, 22 September 2011 (EDT)
Implemented. -- Kynikos 17:16, 22 September 2011 (EDT)
I think we should make an exception for official repositories which are not enabled by default. Currently this is only [multilib] on x86_64 machines and [*testing] repositories. This is somewhat rare if we consider the relatively few (by the numbers) packages in [multilib] and the nature of testing repositories (packages do not stay long and could be broken). However, mentioning a that a package is in multilib which is not enabled by default can avoid some confusion. It would be a loss to not include such information, IMO. James Eder 12:01, 23 September 2011 (EDT)
You certainly have a point there, do we keep a whitelist of allowed repos ([multilib] and [*testing]) or a blacklist of not-allowed ones ([core], [extra], [community])? I'm for the baclklist way. -- Kynikos 15:48, 23 September 2011 (EDT)
A blacklist sounds simpler.  :) James Eder 00:05, 24 September 2011 (EDT)
Done. -- Kynikos 15:34, 24 September 2011 (EDT)
I support this move. What would you suggest as a more succinct title for Template:Package AUR? Template:Pkg2? -- pointone 14:03, 22 September 2011 (EDT)
Uhm, I'd say Template:UPkg or Template:PkgU or Template:PkgAUR or Template:AURPkg or, why not, Template:AUR. -- Kynikos 17:16, 22 September 2011 (EDT)
  • Allow using direct links to packages to avoid ambiguities?
Perhaps the package search API could include an "exact match" option as Template:Package AUR now uses? (Relevant code). -- pointone 14:03, 22 September 2011 (EDT)
Definitely, the template for official packages is not meant to be a search tool, it should point to the right results as fast as possible, and the user inserting it is supposed to use the exact name of the package in the first place. -- Kynikos 17:16, 22 September 2011 (EDT)
Ah, but this means we're not going to allow direct links? I'm in favour of forbidding them, provided that the "exact match" option works as desired. -- Kynikos 17:19, 22 September 2011 (EDT)
The trouble with direct links for packages in the official repositories is that you end up linking to either the 32-bit or 64-bit package which may not be appropriate for the reader. It would be best if the template lead to search results which match an exact name (which should, in most cases, contain only two packages in the results). +1 for not directly linking to packages in official repositories if it can be avoided. James Eder 12:22, 23 September 2011 (EDT)
What about e.g. Template:Package Official, Template:Package Official, Template:Package Official, Template:Package Official? I think we should use
# pacman -S ruby
-- Karol 13:32, 23 September 2011 (EDT)
I'm not sure if I have understood correctly your reply: those packages would be included in sentences like "To get the latest version of Python 3, simply install the Template:Package Official package." (reworded from Python): by clicking on Template:Package Official, with the eaxct match option the user would be shown only 2 results, python for i686 and python for x86_64. I think that would be the desirable way. -- Kynikos 16:02, 23 September 2011 (EDT)
  • Create a template which composes a direct link when given repository name, architecture and package name as arguments?
Maintenance would be difficult -- repository changes are not wholly uncommon. -- pointone 14:03, 22 September 2011 (EDT)
Kk, discarded. -- Kynikos 17:16, 22 September 2011 (EDT)

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

Article summary templates

Article summary templates provide a place to sum up the content of the aricle. The problem is that, in my opinion, this conflicts with the text written in the first part of the articles, before the first heading, which is kind of used for the same purpose. You can see this even in the page I've linked at the beginning of the paragraph, and in Writing_Article_Introductions. I suggest that the summary should only be written as normal text before the first heading, and that Article summary templates should be used only to provide additional schematic introductory informations, like links to related articles (also note that this could conflict with "See also" sections), using the Overview templates, listing packages to download (like in Trinity) and so on. Writing Article Overviews and Writing Article Introductions should be edited in accordance, or maybe merged with this very article? (They actually talk about style) -- Kynikos 12:12, 3 May 2011 (EDT)

I never liked those summary templates and I prefer to have all the related links either in the article itself or at the bottom in the "See also" section. The introduction should have info like This is an article about foo. If you're looking for foo2, go to this page and if you want bar, go to this page. Examples Gnome v. Gnome 3, Virtualbox v. Arch Linux VirtualBox Guest. -- Karol 13:24, 3 May 2011 (EDT)
Would you definitively deprecate Article summary templates? It would KISS things up, I could agree.
Let's try to be concrete, otherwise discussions like this can last for eternity: I'm listing all the possible uses for Article summary (add more if you can think of others), then evaluate each briefly to see if it can be put back in the "normal flow" of the article:
  • Article summary:
it could easily (and I think should) be always substituted by the text before the first heading (which appears before the ToC);
  • Overview template:
more hardly replaceable, unless we just list its links in the See also section and get rid of the rest of the description; I don't like Overview templates very much, they could also be included in the normal summary at the beginning of the article;
  • Related articles and other links (Wikipedia articles, Series, Changelogs...):
easily mergeable with the See also section, anyway I don't know if I would like the opposite more;
  • Legal info:
This is rarely used (Fonts is the only occurrence I've found with a brief random search); it could be easily integrated in the normal flow;
  • List of packages:
Also rarely used (Trinity is the only occurrence I can think of at the moment); it could be integrated in the normal flow, though a long list would not look as good.
  • ...?
In the end, I would start removing the conflict for the summary itself, and then take care of the rest, also because a lot of articles make use of these templates in various ways.
As always the last word will come from the administrators. -- Kynikos 17:54, 3 May 2011 (EDT)
In my mind, the introduction should be used to describe the topic of the article whereas the summary should be used to describe the structure and scope of the article. E.g. Introduction: X is an application that turns your computer into a killer robot. Summary: This article covers installation and configuration of X. A slight distinction, I will admit. (Analogy: abstract versus introduction in research articles).
I created the overview templates as a way to add context to the related articles. Yes, article X is related to Y, but in what way? I also prefer seeing related links at the beginning rather than the end of articles.
-- pointone 23:03, 4 May 2011 (EDT)
Well I agree about the links: as we are trying to standardize the style you could consider approving to move all links from See also and External links sections to the Summary box.
About introduction and summary, I still think the difference is really too subtle to be noticed and applied in all the articles without having to puzzle over what to write where. We should think well if it really gives an advantage to have the two kind of text separated; also IMHO the purpose of the summary, as you have descripted it, is almost completely fulfilled by the Table of Contents. -- Kynikos 10:36, 5 May 2011 (EDT)
I’m not really a fan of these floating templates either. I tend to start reading a page sequentially, at least until I get a feel for what the page is about and decide if I am reading the right page or not. I ignore these sort of floating boxes because they don’t visually have a place in the main text sequence. I often just assume that if they contained important information, that information would be present in the main body as well. Perhaps I would take more notice of these templates if they were on the left (since I read from left to right), but on the other hand perhaps that would make me even more annoyed at the pages that use those templates :P.
How do the templates help add context to related articles? Vadmium 06:13, 1 August 2011 (EDT).
I was referring to the so-called overview templates such as Template:Package management overview. I believe this adds context to related articles rather than simply saying "See also: pacman, Arch Build System, PKGBUILD, etc." However, the overviews can be moved to respective category pages, as touched upon in #A crazy idea (about Summary templates, Overview templates and categories). -- pointone 14:18, 22 September 2011 (EDT)

Is the Article Summary to be optional or required (mandatory) on every article? And if it's optional, the choice is purely based on authors' preferences or do we suggest some guidelines? -- Kynikos 07:02, 17 September 2011 (EDT)

I am neither for nor against the summary templates. The majority of users (here) are against them, so it would seem. -- pointone 14:18, 22 September 2011 (EDT)
Honestly, I would really like to deprecate every summary template except for the overviews, and I would finally implement #A crazy idea (about Summary templates, Overview templates and categories): I read it again, and my own words "This way every category would have a brief description, Overview templates would become unnecessary (merged with category pages), all (categorized) articles would have an almost automatic overview, and people would be more willing to categorize pages well" have convinced me again of the advantages of such a system. -- Kynikos 17:32, 22 September 2011 (EDT)

A crazy idea (about Summary templates, Overview templates and categories)

[Brainstorming mode ON]I don't even know if this could be feasible at all, but what if we could instruct the Article summary template to "read" (with an internal inclusion like those in the Beginners' Guide?) a specific standard section in each Category page that the article belongs to? That standard section would contain a description of the category, and that could somewhat replace the Overview templates. (How hard it is to explain insane ideas, further clarifications could follow)[Brainstorming mode OFF]. -- Kynikos 12:43, 3 May 2011 (EDT)

This is an example: looking at the code, I have used Template:Graphical user interface overview, but with this method its text would be in the includable section (Overview) of the Category, and would be included (automatically with some template hacking?) in the Summary template field:

Lorem Ipsum

Category: Desktop environments

{{:Category:Desktop environments}} (Would this work?)

Template:Graphical user interface overview

Related

External links

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin egestas, magna non sollicitudin commodo, sapien elit semper sapien, adipiscing consectetur nisi ipsum ut elit. Sed ac neque ut nulla tempor porttitor. Mauris interdum. Cras feugiat sodales nibh. Proin neque turpis.

Categories: Desktop environments

<noinclude>

Category:Desktop environments

Overview

</noinclude>

Template:Graphical user interface overview

<noinclude>

Subcategories

...

...

...

</noinclude>

This way every category would have a brief description, Overview templates would become unnecessary (merged with category pages), all (categorized) articles would have an almost automatic overview, and people would be more willing to categorize pages well. -- Kynikos 06:02, 5 May 2011 (EDT)

Ok, this definitely works: see Template:Sandbox, Category:Sandbox and Sandbox for an example (Note that Template:Sandbox has been edited meanwhile, so the examples don't work anymore at the moment. -- Kynikos 08:22, 15 May 2011 (EDT)). My suggestion would be an Article summary category template, or just Category to be put among Article summary templates; note that it automatically adds the page to the category, so it doesn't even duplicate its name in the source.
Template code:
<includeonly>{{Article summary heading|Category: {{{1}}}}}
{{Article summary text|[[Category:{{{1}}}]]{{:Category:{{{1}}}}}}}</includeonly>
Usage:
[[Category:My category]]

{{Article summary start}}
{{Article summary text|bla bla bla}}
{{Category|My category}}
{{Article summary heading|Other heading}}
{{Article summary text|bla bla bla 2}}
{{Article summary end}}
[[Category:My category]] is not needed at the top of the page. -- Kynikos 09:56, 5 May 2011 (EDT)
Of course if there's some category text that needs to be prevented from displaying in the template, it should be enclosed in <noinclude> tags (see the source of Category:Sandbox for an example). -- Kynikos 10:42, 5 May 2011 (EDT)
My original plan with respect to overviews was to include them on their related category pages (category summaries). I, too, thought of something similar, but realized that many existing categories are too broad. Consider Template:Access control overview, which includes pages under Category:Security (English). I also envision an "Encryption overview" which would fall under Category:Security (English). For this to work, we would need to split Category:Security (English) -- not necessarily a bad thing, but I believe the template system provides more flexibility. -- pointone 20:41, 10 May 2011 (EDT)
All this idea was built on the assumption that if two articles need two different overviews, then they very likely belong to different categories (possibly in a parent-child relation) and vice versa: in your example there probably should be an Encryption category, child of Security. I still think that the flexibility given by the Overview template system has a (IMVHO too high) cost in terms of ease of use and maintenance, with respect to the category system, anyway as I said it was just brainstorming. -- Kynikos 08:58, 11 May 2011 (EDT)

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)

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)
  • 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)
  • [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)
  • [add more advantages...]

Notes, Warnings, Tips

Define non-overlapping scopes for these templates. -- Kynikos 18:06, 27 May 2011 (EDT)

A few ideas:
  • Note should be used for information that is important but easily overlooked by someone new to the subject area.
  • Warning should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenario(s) as well as the condition(s) that could lead to or avoid such worst case(s).
  • Tip should be used to indicate a preferred method and the benefit(s) of using it (e.g. it saves time or is safer).
James Eder 14:47, 25 September 2011 (EDT)
My attempt (I have slightly different ideas):
  • Note should be used for information that somehow diverges from what the user would naturally expect at that point. This definition would include also information that gives more in-depth information on something in particular that otherwise would be considered a bit extraneous to the article.
I don't know if "for information that is important" using bold formatting would be better.
  • About Warning I agree with James' definition.
  • Tip should be used to introduce additional information that is absolutely not needed (this does not imply that it can't be useful for somebody) and can be ignored without any negative consequence.
For "preferred" or even faster or "safer" methods I'd like to suggest using keywords like "recommended way", "preferred method" and so on, possibly in subsection titles.
Of course these will just be loose guidelines, those templates have to adapt to many unpredictable situations.
-- Kynikos 18:48, 25 September 2011 (EDT)
Warning is implemented, more opinions are welcome, don't be shy ;) -- Kynikos 20:05, 27 September 2011 (EDT)
I was really hoping someone else would put in some opinions too. Your version of Note seems good enough for me. I'm not sure I agree completely with your Tip but I'm mostly fine with it too. I don't want to hold things up. James Eder 15:52, 28 September 2011 (EDT)
Nobody's "holding things up", there's just no reason to rush things, let's find a common compromise calmly. Probably both definitions for Note can be kept, they don't seem to be contrasting and I like also yours: Note could be used (and in fact it is already) as a way to highlight some important content, instead of using a long bold text, which would indeed look ugly.
Another possible use for Note is when there's the need for pointing out a temporary announcement like a change in the name of a package, although this usage may fall within the scope of my initial definition.
-- Kynikos 19:34, 28 September 2011 (EDT)
I think I've found good compromises for Notes and Tips (how arrogant XD ), this section could be complete. -- Kynikos 17:44, 4 October 2011 (EDT)

Stacking

In general, would you prefer a stack of Note templates, like:

Note: Noting something bla bla bla bla bla.
Note: Noting something else ble ble ble ble.
Note: I'm a note bli bli bli bli bli.

Or a list inside a single template, like:

Note:
  • Noting something bla bla bla bla bla.
  • Noting something else ble ble ble ble.
  • I'm a note bli bli bli bli bli.

-- Kynikos 18:31, 23 September 2011 (EDT)

I prefer the single template so long as the notes are all fairly well related. I suspect most cases where note boxes are stacked that they will be decently related. James Eder 14:47, 25 September 2011 (EDT)
I'm also leaning towards the single template, but I'm leaving this discussion open for more opinions. -- Kynikos 20:05, 27 September 2011 (EDT)
Implemented with list, assuming tacit consent. Closed. -- Kynikos 17:29, 4 October 2011 (EDT)

Migration to new Code formatting templates

Months have passed since the initial proposal to restyle the Code formatting templates, references can be found here:

The new templates are Template:Ic for inline code, Template:Bc for block code and Template:Hc for block code with header.

A possible migration strategy could be the following:

  • Cli -> space-initial lines or Bc
  • Codeline -> Ic (merge some use cases like command names into a generic monospace template without background?)
  • Command -> space-initial lines or Bc
  • File -> Hc
  • Filename -> Ic (or keep Filename? see also #Template:Filename) (or merge in a monospace template without background?)
  • Kernel -> Hc
  • Cursor -> deprecate?

As discussed initially on #Do not use <pre> for one-liners, we could also copy the current Template:Bc to Template:BHc, and restyle Template:Bc to look like <pre>, thus deprecating the use of <pre>. [implemented]

Another related discussion: #Prepare examples of both simple and advanced use of the (new) wiki templates & formating.

Please share your ideas. -- Kynikos 12:50, 21 September 2011 (EDT)

Usage guidelines

Maybe it's better to define the rules based on the various usage examples, so here's a possible starting point (this is the simplest implementation, it only uses 3 templates):

Simple commands

Use Template:ic for inline code: # lspci . Use Template:bc for block code:

# lspci 

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]
Commands with response

Use Template:bc:

# iwconfig

lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0

-- Kynikos 21:51, 29 September 2011 (CEST)

Of course this method would replace Template:Command, and we'd lose the difference between command and output even at source level, so the change would be irreversible.
As an alternative, Template:Command could be restyled like this:
# command
output
But this way we'd need also an output-only template:
output only
-- Kynikos 09:13, 5 October 2011 (EDT)
...just thinking that this would then pose a problem of coherence, in fact we'd have Template:bc for both file and cli code, but a different template for command output: there wouldn't be any reasons left to avoid making also a proper template for file code...
To sum up, the current alternatives are:
  • the 3-templates way (Ic, Bc, Hc)
  • the 6-templates way (Ic (all inline code1), Bc (cli commands), Cc (cli commands with output), Oc (command line output only), Fc (file content), Hc (file content with heading))
    1As a chain effect this method could also lead to a similar differentiation in inline code...
-- Kynikos 09:36, 5 October 2011 (EDT)
File content

Use Template:ic for inline code: IgnorePkg=kernel26.

Use Template:bc for block code:

[core]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

[extra]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

[community]
# Add your preferred servers here, they will be used first
Include=/etc/pacman.d/mirrorlist

Use Template:hc for block code with file name in header:

/etc/fstab
# <file system>        <dir>         <type>    <options>             <dump> <pass>
none                   /dev/pts      devpts    defaults                0      0
none                   /dev/shm      tmpfs     defaults                0      0
 
/dev/cdrom             /media/cd     iso9660   ro,user,noauto,unhide   0      0
/dev/dvd               /media/dvd    udf       ro,user,noauto,unhide   0      0
/dev/fd0               /media/fl     auto      user,noauto             0      0
 
LABEL=Arch_Linux       /             ext4      defaults,noatime        0      1
LABEL=Arch_Swap        swap          swap      defaults                0      0

-- Kynikos 21:51, 29 September 2011 (CEST)

If Template:hc is used only for file content we could prepend "File: " to the heading, as in Template:File, and it could be moved to Template:fc. -- Kynikos 09:17, 5 October 2011 (EDT)
File names

Use Template:ic for inline file names: /etc/pacman.d/mirrorlist.

See also #Template:Filename.

-- Kynikos 21:51, 29 September 2011 (CEST)

I think this would be both consistent with the other new templates and more readable with 'File' in the header. 1+ -- Roygbiv 16:25, 6 October 2011 (EDT)
Command names

Use Template:ic for inline command names: makepkg.

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]
Other names

Use Template:ic for other inline names (e.g. variables): PATH.

-- Kynikos 21:51, 29 September 2011 (CEST)

[discuss here...]

Prepare examples of both simple and advanced use of the (new) wiki templates & formating

so users can easily figure out how to get what they need and not get stuck with ugly stuff like this: Template:Cli

I've added <nowiki> tags and it already looks better:

Template:Cli I'm not sure if this idea belongs in the Style Guide and if the new templates will need much explaining :-) -- Karol 13:31, 9 May 2011 (EDT)

I'm not correcting edits like that, because I have faith the Age of the New Templates will come :P -- Kynikos 13:07, 10 May 2011 (EDT)
I too shall eagerly await its arrival ;P -- Karol 13:42, 10 May 2011 (EDT)

Template:Filename

Is Template:Ic going to replace also Template:Filename? -- Kynikos 09:18, 19 September 2011 (EDT)

My opinion: I like current Template:Filename usage as it is currently. I would, however, like to see other templates and other HTML tags migrated to Template:Ic and Template:Bc. That is, of course, once they are no longer "in development" (nudge, nudge). James Eder 20:37, 19 September 2011 (EDT)
Eheh those templates are in development because they're waiting to be enforced together with this very article, I also prepared some sort of a migration procedure some time ago in User:Kynikos/Random formatting ideas#Upgrade_procedures although it'd need heavy upgrading itself.
Waiting for more responses about Template:Filename, default is not replacing it. I am a bit undecided on this, because replacing it would go in the direction of simplicity, and it would be coherent with the decision not to distinguish between cli and file text in block code templates; on the other hand I've never been very convinced by that decision, so that's why I'm asking for opinions.
-- Kynikos 05:52, 20 September 2011 (EDT)
Can summarize what we do and do not have a consensus on here? The migration process seems to be fairly straight forward it just needs to be said which templates we are sure about. Is Template:Filename the only one left undecided? James Eder 13:06, 20 September 2011 (EDT)
There has never been an official discussion on this, so I'm creating #Migration to new Code formatting templates. -- Kynikos 12:50, 21 September 2011 (EDT)

Template:Cursor

Deprecate Template:Cursor? -- Kynikos 16:35, 29 September 2011 (EDT)

<nowiki> templates?

Consider creating Template:bc2 and Template:ic2 that include <nowiki> tags. Or, perhaps Template:bc and Template:ic include <nowiki> tags and Template:bc2 and Template:ic2 can be used if wiki formatting is desired (i.e. unformatted text is more often the desired outcome). (Taken from User:Pointone/Code Formatting Templates) -- Kynikos 16:35, 29 September 2011 (EDT)

I played around with this last week and failed; may not be possible. -- pointone 13:10, 4 October 2011 (EDT)
Kk, I've tried {{#tag:nowiki|{{{1}}}}} out of curiosity but it doesn't work how I expected, I guess we can close this one: if there were a way to do this, it would be an easy one. -- Kynikos 18:15, 4 October 2011 (EDT)

Darker background?

Use a slightly darker background for code templates to increase its visibility? Compare current color with
darker color
. -- Kynikos 16:35, 29 September 2011 (EDT)

Bugs?

Lists or indentation
  • header
content

Use an outer div to enclose both header and content? (not working) -- Kynikos 16:35, 29 September 2011 (EDT)

Font weight

Main Page.

Main Page I make the text in the link appear in normal weight.

Not investigated yet. -- Kynikos 16:35, 29 September 2011 (EDT)

What if, instead of using <pre> in Template:ic, we used a <span> formatted with font-family: monospace;? -- Kynikos 16:50, 29 September 2011 (EDT)
(of course setting also background-color, and padding if needed (on an inline tag??)). -- Kynikos 17:55, 29 September 2011 (EDT)

Category pages - tree or otherwise?

The ArchWiki category tree was originally designed as just that: a 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. -- pointone 10:39, 23 September 2011 (EDT)

As noted at the top of Table of Contents, Category:Secure Shell (English) 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. -- Kynikos 11:43, 23 September 2011 (EDT)