Difference between revisions of "Help talk:Style/Formatting and punctuation"

From ArchWiki
Jump to: navigation, search
(Poll)
(Proposed change to repository naming convention: trying to revive the discussion)
Line 63: Line 63:
 
:::::::::Since the two positions are incompatible, I've started a poll below so we can settle this once and for all. Of course the discussion can continue if somebody has something to add.
 
:::::::::Since the two positions are incompatible, I've started a poll below so we can settle this once and for all. Of course the discussion can continue if somebody has something to add.
 
::::::::: -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:08, 23 December 2013 (UTC)
 
::::::::: -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:08, 23 December 2013 (UTC)
 +
 +
:::::::::To elaborate on last Jstjohn's post: I think that using the bracket notation is the ''de facto'' standard only for official repositories. For unofficial repositories it will be necessary to always add "repository" to the phrase to make it clear (e.g. "install ''infinality-bundle'' from [infinality-bundle-fonts] repository). At this point it does not really matter if the brackets are used or not. Also note that "repository" is already in some phrases for official repositories: [[ArchWiki:About#Accessible]].
 +
:::::::::My opinion: in this case it is not necessary to introduce exceptions to the current style guides - only option A complies 100%. Options D and E will tend to use abbreviated expressions like "Users can also access the [community] build files" or "install ''foo'' from [core]", which IMO conflict also with [[Help:Style#Language_register]] (unnecessary shortening). B and C are something in between (technical difficulties with formatting links), there would even be exception from an exception. Do we really need so many exceptions in one ruleset?
 +
:::::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:35, 27 December 2013 (UTC)
  
 
===Poll===
 
===Poll===

Revision as of 15:35, 27 December 2013

Proposed change to repository naming convention

Regarding Help:Style/Formatting_and_Punctuation#Repository_names, I am proposing that the style guide should recommend using square brackets around repository names.

It is a de facto standard in the Arch community to enclose repository names in square brackets, so I feel it would be appropriate to officially adopt this style in the style guide.

Current example:

  • If you enable testing, you must also enable community-testing.

Proposed example:

  • If you enable [testing], you must also enable [community-testing].

-- Jstjohn (talk) 00:24, 5 December 2013 (UTC)

+1, also note that Help:Style#Official_packages (last point) should be updated to whatever version we agree on. -- Lahwaacz (talk) 07:23, 5 December 2013 (UTC)
True that brackets are a de-facto standard, however it's also true that they create problems with wiki links, which is one of the main reasons why they were discarded. See for example the intricacy of [[multilib|[multilib]]] (from [1], now fixed) or [[#.5Bcommunity.5D|[community]]] in the intro of Arch User Repository.
If we recommended using brackets, what would we do when used in section headings? See for example Unofficial User Repositories. Or article titles? E.g. community. Maybe we could recommend to use them only with plain body text (no titles, headings, links...)? Or does it sound too complicated? It does sound complicated to me, however let's see what's your position over these issues ^^
-- Kynikos (talk) 10:07, 5 December 2013 (UTC)
Oops, I didn't recall this one in the morning as I was in a hurry... Links should definitely be kept simple, i.e. without brackets.
I don't like brackets in section headings either, both aesthetically and technically. For article titles, is that even possible?
I just realized deeper connection: square brackets in pacman.conf are used to start new section and the repository name is inside the brackets ([options] is special, no repo can have name "options"). pacman also does not show brackets in its output.
-- Lahwaacz (talk) 15:41, 5 December 2013 (UTC)
I've just added an example to the rule and updated Official Repositories, which now looks cleaner to me. I've also checked Official Repositories's backlinks for any broken fragments. -- Kynikos (talk) 04:06, 7 December 2013 (UTC)
Out of curiosity, why have you used bold in Official_Repositories#Historical_background? Is it just a typo or is there a pattern I did not recognize? -- Lahwaacz (talk) 07:17, 7 December 2013 (UTC)
Well, what happened there is that before my edit the current repos were already bolded, so that inspired me to apply Help:Style/Formatting_and_Punctuation#First_instances to the first relevant mention of each historical repo (that's the intended pattern); however on a second look the current repos have their proper section in the article, and that's a conflict with the first-instance rule, unless we justify it with Help:Style/Formatting_and_Punctuation#Name.2Fterm_lists. In the latter case, maybe the current repos could be highligted with links to their sections instead. -- Kynikos (talk) 02:56, 8 December 2013 (UTC)
Italicizing repository names looks much better than bolding them, but I do prefer the square brackets wrapped around them. Although, I'm not sure how much of that is an unconscious resistance to change/something different. Maybe if I saw more frequent use of repository names in italics or bold, I wouldn't mind it as much. *shrugs*
What about creating Template:Repository or Template:Repo (for less typing)? This would allow us to change the style around repositories with ease. For example, {{Repository|extra}} would result in extra or [extra], depending on what we choose. If done with CSS, I believe this would eliminate the issue with wiki links (e.g. using .repository:before { content: "["; } .repository:after { content: "]"; }).
-- Jstjohn (talk) 21:41, 8 December 2013 (UTC)
I, too, forgot about the issue with wiki links, but if possible, I would still really like to make square brackets part of the officially-approved style (or at the least, part of an allowed style).
pacman could be patched to display square brackets around repository names in its output, but I don't know if Allan or the other pacman developers would want that. I don't feel strongly either way about pacman's output. I can send an RFC to pacman-dev.
-- Jstjohn (talk) 21:29, 8 December 2013 (UTC)
Well, until now I haven't stated my purely aesthetic preference (ignoring any technical issues), and honestly it's still oriented towards the version without brackets.
But really, how often do you encounter repository names on the wiki? Mentioning the official repositories when installing packages is taboo, and when mentioning unofficial repositories, most often they will need a link, which IMO is already highlighted enough without the need for any brackets.
However we may prepare a poll, like it's been done for other style issues in the past, which has always proved to be the best way to find shared solutions. The choices should be sets of styles for repos in plain text, links and section headings, remembering that article titles cannot have square brackets (MediaWiki limitation).
About the possibility of an "allowed" style, of course it can't happen since it would defeat the purpose of a style rule in the first place, which is meant to unify the looks of articles :)
About patching pacman's output, I wouldn't support the request, but, well, if the Devs accepted - or rejected - it, it would certainly be a strong argument for this discussion.
-- Kynikos (talk) 12:11, 9 December 2013 (UTC)
-- I like the brackets. It is the standard syntex in pacman.conf. -- Fengchao (talk) 03:06, 21 December 2013 (UTC)
Well, this is very open to interpretation: as Lahwaacz wrote above, the syntax in pacman.conf could be seen as "["+"repository_name"+"]" thus indicating that the repository name is without brackets, and with brackets it indicates a repository section in the configuration file.
More related arguments on the no-bracket side could be:
  • From [2]:
    • Line 203: "Each repository section defines a section name and at least one location where the packages can be found. The section name is defined by the string within square brackets" (uses "section names", not "repository names").
    • Line 205: "Repository names must be unique and the name 'local' is reserved for the database of installed packages" (doesn't use brackets with "local").
  • From [3]:
    • Line 53: "# Repository entries are of the format:
      # [repo-name]" (Uses "Repository entries", not "names" and "repo-name" is enclosed in brackets, which are not part of it).
    • Line 58: "# The header [repo-name] is crucial" (calls it a "header").
-- Kynikos (talk) 03:54, 22 December 2013 (UTC)
I agree that the true repository name is simply "core" or "extra", which is why in the first post, I said "enclose repository names in square brackets". :)
However, this proposal is about adopting what is quite clearly the de facto naming convention used throughout the Arch forums, the IRC channels, the mailing lists, the G+ communities, etc. When users see [core] or [extra], they immediately know that the reference is to the package repositories named "core" or "extra". This proposal is about keeping the same convention in ArchWiki that is used elsewhere, which I feel is important considering the heavy emphasis used in the Arch community about "read the wiki".
-- Jstjohn (talk) 03:12, 23 December 2013 (UTC)
Putting the link syntax problem aside, I think we can summarize the discussion in: do you prefer repository names to be represented consistently with other names and techincal terms within the wiki (no-bracket side) or do you prefer them to be consistent with how they are most commonly represented in the other Arch community "platforms" (pro-bracket side)?
Since the two positions are incompatible, I've started a poll below so we can settle this once and for all. Of course the discussion can continue if somebody has something to add.
-- Kynikos (talk) 14:08, 23 December 2013 (UTC)
To elaborate on last Jstjohn's post: I think that using the bracket notation is the de facto standard only for official repositories. For unofficial repositories it will be necessary to always add "repository" to the phrase to make it clear (e.g. "install infinality-bundle from [infinality-bundle-fonts] repository). At this point it does not really matter if the brackets are used or not. Also note that "repository" is already in some phrases for official repositories: ArchWiki:About#Accessible.
My opinion: in this case it is not necessary to introduce exceptions to the current style guides - only option A complies 100%. Options D and E will tend to use abbreviated expressions like "Users can also access the [community] build files" or "install foo from [core]", which IMO conflict also with Help:Style#Language_register (unnecessary shortening). B and C are something in between (technical difficulties with formatting links), there would even be exception from an exception. Do we really need so many exceptions in one ruleset?
-- Lahwaacz (talk) 15:35, 27 December 2013 (UTC)

Poll

After reading the discussion above and possibly participating in it, cast your vote by ordering your 4 favorite solutions from the ones below, with a string like "FGHI" where F is the most preferred and I is the 2-nd to least preferred.

You can change your vote as many times as you want before the poll is closed.

The winner will be chosen with the following algorithm:

  • count all the first choices
  • if one choice reaches > 50% of votes it is approved
  • else redo the count using the second choice for those votes that ranked the least-voted choice as their first choice and so on until one choice reaches > 50% of votes

A: example

The example repository is described in the example section.

B: example

The [example] repository is described in the example section.

C: example

The [example] repository is described in the example section.

D: [example]

The [example] repository is described in the [example] section.

E: [example]

The [example] repository is described in the [example] section.

Votes