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

From ArchWiki
Jump to: navigation, search
(+ reminders)
(Directory slash suffix (/path/to/dir/): re)
 
(121 intermediate revisions by 13 users not shown)
Line 1: Line 1:
==General indications==
+
__TOC__
''[Split from a longer discussion: [https://wiki.archlinux.org/index.php?title=Help_talk%3AStyle%2FFormatting_and_Punctuation&diff=261275&oldid=261123]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 15:23, 5 June 2013 (UTC)]''
+
  
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)
+
== Dealing with long lines within code block text ==
  
:I think what AlexanderR wrote here is very important: the style rules that will derive from this talk page will have to be a <u>white list</u> of (very) <u>specific</u> cases that require formatting, like in "all text is to be left without formatting except for the following cases: ...". -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:26, 4 June 2013 (UTC)
+
I'd like to get some input and, hopefully, a resolution to the issue of long lines within code block text boxes; even on this Help page the long lines of code or comments within code block text boxes are not constrained within the text box.  Perhaps a horizontal scroll bar can be used to expose the long lines of text within the text box instead of simply allowing the text to span past the width of the text box. This will prove especially useful with the exponential growth in usage of mobile browsers and devices.
  
::We could also mention [[Wikipedia:Manual of Style]] in the guide and only integrate it (or override, if really necessary) where needed. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:03, 6 June 2013 (UTC)
+
[[User:ILMostro|ILMostro]] ([[User talk:ILMostro|talk]]) 17:55, 31 March 2014 (UTC)
  
=== Bold ===
+
:Desktop version of Firefox shows the horizontal scrollbar when needed. Mobile webkit-based browsers don't show the scrollbar, but "swiping" the code box actually scrolls the box.
{{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}}}}
+
:Optimization for mobile devices is another issue; but yes - browsing wiki pages on mobile webkit browsers sucks, mostly because of [https://mailman.archlinux.org/pipermail/arch-general/2013-December/034569.html].
 +
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:28, 31 March 2014 (UTC)
  
<s>With respect to this Wiki specificity (and taking into account various precedents) I propose to limit usage of bold text to:</s> --[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
::Horizontal scroll bars are already enabled for code blocks [https://projects.archlinux.org/vhosts/wiki.archlinux.org.git/tree/skins/archlinux/arch.css#n7], this is indeed a problem with mobile webkit browsers, not limited to MediaWiki, for example I can't properly see long lines of code on github.com either (no horizontal scroll bar either).
 +
::Anyway, if somebody's aware of a CSS fix for that, it should be submitted to MediaWiki's bug tracker.
 +
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 00:49, 2 April 2014 (UTC)
  
=== Italic ===
+
== Reference links before or after punctuation marks? ==
{{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}}}}
+
  
<s>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):</s> --[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
I was about to revert [https://wiki.archlinux.org/index.php?title=PKGBUILD&diff=next&oldid=354351], but I have not found any rule about it in our guidelines, so I'm proposing to add one.
  
=== Underlining ===
+
Basically, reference links are not part of the sentence, so they should be put ''after'' punctuation marks like period or comma. There should be no space between the punctuation mark and the reference link. This style is widely used on [[wikipedia:Wikipedia:Manual_of_Style#Punctuation_and_footnotes|Wikipedia]] and apparently also [http://graphicdesign.stackexchange.com/a/15343 Chicago Manual Of Style].
{{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)
+
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 30 December 2014 (UTC)
  
:Following [[Wikipedia:Manual of Style/Text formatting#How not to apply emphasis]] I would deprecate any use of <u>underlining</u>. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:33, 6 June 2013 (UTC)
+
:Fine with me, although I just recall using reference links in a sentence the other day, which I (obviously) found appropriate usage as well.[https://wiki.archlinux.org/index.php?title=Network_configuration&diff=352654&oldid=352629] Further, if we are going to introduce "reference link" as a term, it should be noted as a case in [[Help:Style#Hypertext_metaphor]] as well (close to the indirect links bullet). --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:35, 30 December 2014 (UTC)
  
=== Quoting and double quoting ===
+
::Well quoting the linked manual of style:
Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
:::''The superior numerals used for note reference numbers in the text should follow any punctuation marks except the dash, which they precede. The numbers should also be placed outside closing parentheses.''
:Now the discussion also includes punctuation :) -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:51, 4 June 2013 (UTC)
+
::So as I understand it, it can be "part of the sentence", just after the respective punctuation (though you wouldn't put a {{ic|1=,}} between the references.) -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:56, 30 December 2014 (UTC)
  
===Alternative approach===
+
:::Good point, sometimes links are part of the sentence, for example in "...as can be found in [42]." or "...for example [43], [44] and [45]." it does not make sense to place the link after the period. On Wikipedia though, where the reference links are formatted as superscript, you would not find it being part of a sentence anywhere. If we keep formatting reference links as normal-size text, I believe the editors should be free to choose if the reference link will be part of a sentence or not.
We could define our own basic (or ''simple'', following Arch's philosophy) rules for italics and bold, and derive all the use cases from them. Citing AlexanderR in [[#Inline templates]], I would find it quite natural to use '''bold''' to "attract additional users attention" and ''italic'' to "offset text from its surrounding content".
+
:::I would define a reference link as a link without an anchor text (which implies that reference link must be of the syntax {{ic|[''full_url'']}}) and the rule would apply only to reference links that are not part of the sentence. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:08, 30 December 2014 (UTC)
  
Once these two cases are defined, all the specific uses should come quite naturally, for example [[#Executables names (as executables in file system, not in command line)]] and [[#Pseudo-variables]] would be in italic, [[#"not"]] and [[#Important part of file/command line contents]] would be in bold. Under these simple rules, I would even be in favour of using italic for [[#Single file names]].
+
::::In [https://wiki.archlinux.org/index.php?title=PKGBUILD&diff=next&oldid=354351]'s case, I'd prefer the link to be after the period too, and I agree with the observations that have been brought here.
 +
::::Just a quickly-thought idea, we could specify that the rule "would apply only to reference links that are not" ''grammatically'' "part of the sentence".
 +
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:10, 31 December 2014 (UTC)
  
In this case I would reserve the use of [[Template:ic]] only for:
+
:::::I like that idea a lot. In my view it would, however, rule out the frequently used "...for example [43], [44] and [45]." cases, because the link count substitution ([43],...) does not make any of them a grammatic part of the sentence. My personal rule of thumb is that the reader should not be required to hover over the link in order to see where it leads out to. Arguably the "for example" does hint enough in this example what the links will lead to. For the wiki here that should be enough; we're using external links in a different manner than wikipedia and the cases they are used in an academic (aka "Chicago") style is very seldom.
* ''Complete'' commands, e.g. "run {{ic|grep Ignore /etc/pacman.conf}} using the ''grep'' utility"
+
:::::I now think we should skip this and leave it up to the editors how they want to present the references. Just make sure we don't end up with bogus sentences like "If [46] is [[Start|started]] with default configuration [47], the journal will show [48]." --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 11:10, 16 January 2015 (UTC)
* Full file paths
+
* Content that can be read or written on a file, e.g. "add {{ic|bind '"\e[A": history-search-backward'}} to your ''.bashrc'' file" or "check that the ''GRUB_CMDLINE_LINUX_DEFAULT'' variable in {{ic|/etc/default/grub}} is set to {{ic|"quiet splash"}}, thus making the whole line of the ''grub'' file be {{ic|1=GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"}}"
+
* In general when it can ''make sense'' to copy-paste the ic'ed text in a terminal or a text editor (i.e. when there can be a ''realistic'' reason for doing it)
+
* Keyboard keys, see [[Help talk:Style/Migration to new Code formatting templates#Template:Keypress]]
+
  
Note however that basically I'm brainstorming, there are probably many aspects that I've overlooked with this reasoning, so please go on and comment!
+
== Styling configuration paths ==
  
(EDIT:Comment '''only''' on the two "basic" definitions defined in the first paragraph; the rest of the post is only used to give an idea of what the consequences would be. To comment each specific case, just reply to one of the sections below or create a new one)
+
Not sure you can understand what I mean from the heading so I'll give an example. I edited [[Cinnamon#Manage_languages_used_in_Cinnamon]] recently and added the third bullet. So I opted for bolding the configuration path, but I see in the article there are cases of using {{ic|ic}} ([[Cinnamon#Themes_and_icons]]), or using italics like in [[Cinnamon#Screenshot]]. So, what's the preferred way if any? I personally have a preference of using bold with the symbol {{ic|>}}. --[[User:Maevius|Maevius]] ([[User talk:Maevius|talk]]) 19:01, 29 May 2016 (UTC)
  
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:31, 6 June 2013 (UTC) (Last edit: 14:38, 6 June 2013 (UTC))
+
:We try to stick to ''Italics'' with ">" to separate the menu points, see the examples (last bullet) here: [[Help:Style/Formatting and punctuation#GUI.2FTUI text]]
 +
:edit: if you think it is worthwhile to change that style rule, we can discuss it here. You probably prefer to bold it, because it is easier to distinguish than italics. Likely other editors chose {{ic|ic}} for a similar reason. An alternative I can suggest here, is that you make the menu path go to a new line, e.g.
 +
:*To change the keyboard layout, navigate to:
 +
:::''System Settings > Hardware > Keyboard > Layouts''
 +
:which will also make it stand out more. Workable like this?
 +
:--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:10, 29 May 2016 (UTC)
  
:Any comments on this? Anybody else with some opinion on these issues? The problem is that it's difficult to make decisions here since I and [[User:Flu|Flu]] do not agree on everything, so any additional point of view will be highly appreciated ^^ -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:17, 10 June 2013 (UTC)
+
== Directory slash suffix (/path/to/dir/) ==
  
==Formatting cases==
+
Is that an intended distinction with the /-suffix in path names?: [[Help:Style/Formatting and punctuation#Examples 6]]
  
===Simple file names===
+
{{ic|/sys/firmware/efi}} vs. {{ic|/etc/modules-load.d'''/'''}} --'''<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>''' 09:32, 10 September 2016 (UTC)
(Highly questionable)  
+
  
:search for '''loop.ko''' in {{Ic|/lib/modules/''kernel_release''}}
+
:The distinction there is purely coincidental: those examples are excerpts that were taken from different articles at the time the page was created.
 +
:That said, we've never discussed a standard about the usage of the final slash in paths, I'm not sure if it can make sense to mention it somehow in [[Help:Style]], if you have some ideas I'm happy to discuss them :)
 +
:— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:19, 10 September 2016 (UTC)
  
--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
::I dunno how to fit that in there, but I'd personally like to see the "core" directory paths possibly without the final slash, e.g. {{ic|/etc}}, {{ic|/usr/local}}, etc. (maybe all the ones from {{pkg|filesystem}}?), and the rest with it, e.g. {{ic|/usr/lib/awk/}}, {{ic|/usr/lib/groff/gpinyin/}}. Is it too complex? --'''<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>''' 21:13, 10 September 2016 (UTC)
  
:I second AlexanderR <s>choices, also the first</s> point (between {{ic|fstab}} and '''fstab''' the latter is better-looking), plus the package name (once Pkg template has been used the first time). I bring to bear witness [[Core_Utilities]] article which is quiet good-looking, I think, also using lynx. -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 16:10, 2 June 2013 (UTC)
+
:::For sure we should at least explicitly except the cases where the final slash is meaningful, e.g. rsync commands.
 +
:::Then maybe also except cases where the word "directory" is explicited in the sentence, thus making the examples in this article compliant again?
 +
:::And also except cases where the "path" is only the directory name and not a longer path, for example "Now create a {{ic|foobar}} directory" vs "Now create a {{ic|foobar/}} directory"?
 +
:::Then I'm also afraid there could be more exceptions needed, I think it would be better to find a couple of articles that are inconsistent in this regard and test how they'd look like if this rule was enforced.
 +
:::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 01:34, 11 September 2016 (UTC)
  
::I'm against bold in this case, consistency is more important than aesthetics, so we should use the same formatting for both full-path file names and short (single) file names. I'm in favour of using [[Template:ic]] for filesystem paths and file names.
+
::::I don't see why {{ic|/etc/}} etc. should be excluded. I would like to see the final {{ic|/}} everywhere except in sensitive commands like rsync and directory names mentioned above. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:06, 11 September 2016 (UTC)
:::search for {{Ic|loop.ko}} in {{Ic|/lib/modules/''kernel_release''}}
+
:: -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:57, 6 June 2013 (UTC)
+
:::good point, changed my mind, +1 -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 21:07, 6 June 2013 (UTC)
+
::::Eheh sorry but now it's me who's changed his mind :) For coherence with executable names I propose using ''italic'':
+
  
::::* "Edit ''resolv.conf'', substituting your name servers' IP addresses and your local domain name:" ([[Beginners' Guide]])
+
:::::Hmm how would you change [[Installation_guide#Mount_the_file_systems]] for example? — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:57, 12 September 2016 (UTC)
::::* "Before installing, you may want to edit the ''mirrorlist'' file and place your preferred mirror first." ([[Beginners' Guide]])
+
::::* "For kernel modules to load during boot, place a ''*.conf'' file in {{ic|/etc/modules-load.d/}}, with a name based on the program that uses them." ([[Beginners' Guide]])
+
::::* "Create a ''refind_linux.conf'' file with the kernel parameters to be used by rEFInd:" ([[Beginners' Guide]])
+
  
::::I guess also device names should fall here:
+
::::::I'd add the slash everywhere, i.e. {{ic|/mnt/}}, {{ic|# mount /dev/sda1 /mnt/}}, {{ic|/mnt/boot/}}, {{ic|/mnt/home/}}. Though it's probably easier to realize that the slash can be added when it's missing than to realize that it can be omitted when it's present.
 +
::::::The {{ic|/}} suffix is useful to clearly indicate that some path is a directory, but it's also the result of tab-completion, which is why it feels more natural to me. In any case making rules about this is hard and global consistency is probably not worth the effort. I think that per-page or even per-paragraph consistency would be enough. Also, people should be aware of both variants anyway.
 +
::::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:34, 12 September 2016 (UTC)
  
::::* "Each partition is identified with a number suffix. For example, ''sda1'' specifies the first partition of the first drive, while ''sda'' designates the entire drive." ([[Beginners' Guide]])
+
:::::::I first noticed this in [[Installation guide#Verify the boot mode]], where it said {{ic|# ls /sys/firmware/efi/efivars}} to try to view the contents of the dir. It mentioned that "directory" word, but way into the right, instead of in line with the command. Personally, I don't see a benefit in omitting it in places like 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>''' 14:01, 12 September 2016 (UTC)
  
::::Also include extensions:
+
::::::::It's listed "way into the right" because it makes no sense to add another break before "To verify this (...)". Anyway as this seems to be specifically about the [[Installation guide]], I'd suggest to open a discussion there rather than suggest another style rule. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 14:58, 12 September 2016 (UTC)
  
::::* "Pacman is written in the C programming language and uses the ''.pkg.tar.xz'' package format." ([[Pacman]])
+
:::::::::That's not the point at all. That's ''why'' a final {{ic|/}} would help in those scenarios, and this isn't only [[Installation guide]]-specific. --'''<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>''' 15:01, 12 September 2016 (UTC)
  
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:18, 26 June 2013 (UTC)
+
::::::::::{{ic|path/to/dir//////////////////////////////////////////////}} is perfectly valid as well. So, does it also need mentioning in [[Help:Style]], together with every other combination?
:::::Good point, changed my mind, +1 XD -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 21:03, 9 July 2013 (UTC)
+
::::::::::If you just want to inform people on the distinction, we could add something to [[Help:Reading]]. Otherwise I agree with Lahwaacz that it isn't worth enforcing this globally. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:07, 12 September 2016 (UTC)
  
=== Executable/application names===
+
:::::::::::I don't know what are you trying to convey there :D, but what would that "distinction piece" consist of? --'''<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>''' 15:12, 12 September 2016 (UTC)
'''javaws''', which is in {{Pkg|icedtea-web-java7}}
+
  
{{Box YELLOW|Clarification required:|should executable names be highlighted always, at first encounter or under other rules?}}
+
::::::::::::E.g., "Note that a path referring to a directory may contain a single, none, or even multiple trailing slashes. For example, {{ic|mkdir /foo}}, {{ic|mkdir /foo'''/'''}} and {{ic|mkdir /foo'''//'''}} are equivalent. Exceptions are programs such as [[Rsync#Trailing_slash_caveat|rsync]] which treat a trailing slash specifically."
 +
::::::::::::-- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 16:56, 12 September 2016 (UTC)
  
--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
:::::::::::::That multiple {{ic|/}} note belongs to [[Help:Reading]]? I thought that thing was just for global clarifications on ArchWiki article syntax? Where is there an article doing {{ic|mkdir /foo'''//'''}} or {{ic|path/to/dir//////////////////////////////////////////////}}? --'''<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>''' 17:10, 12 September 2016 (UTC)
  
:An interesting case from [[Installation Guide]]:
+
::::::::::::::Yes, in particular [[Help:Reading#Append.2C_add.2C_create.2C_edit]]. The multi-slash example was more for demonstration purposes; I guess it should be left out if it somehow encourages usage of that syntax. Link candidate: [http://stackoverflow.com/a/20690872] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:18, 12 September 2016 (UTC)
:*Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with {{ic|locale-gen}}
+
:I guess technically {{ic|locale-gen}} would stay formatted that way, since it would be the same as writing:
+
:*Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it executing {{ic|locale-gen}}
+
:If however for instance the sentence changed very slightly to:
+
:*Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with the {{ic|locale-gen}} utility
+
:Following AlexanderR's way it should become:
+
:*Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with the '''locale-gen''' utility
+
:And with [[#Alternative approach]] it should become:
+
:*Uncomment the selected locale in {{ic|/etc/locale.gen}} and generate it with the ''locale-gen'' utility
+
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:32, 10 June 2013 (UTC)
+
  
::I suggest using ''italic'', and only for full lower-case names:
+
:::::::::::::::That's about dealing with one or more files (a perfectly valid case). That's different from mentioning incoherent syntax. --'''<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>''' 17:28, 12 September 2016 (UTC)
  
::* "You can also use ''iwconfig'' and see which interfaces are not wireless:" ([[Beginners' Guide]])
+
:::<------------------------------------------------|
::* "As of v197, ''udev'' no longer assigns network interface names according to the ''wlanX'' and ''ethX'' naming scheme." ([[Beginners' Guide]])
+
:::First of all I'd just ignore the multiple slash case, otherwise I think we should inform the readers that also {{ic|../..///./path/to/../to//folder///}} is the same as {{ic|./folder}}.
::* "The Arch Linux install media includes the following partitioning tools: ''fdisk'', ''gdisk'', ''cfdisk'', ''cgdisk'', ''parted''." ([[Beginners' Guide]])
+
:::Coming back to the trailing slash problem, I think the point is: what would we do if one day a guy registered an account and started systematically changing all the directory paths to have a trailing slash? Or vice versa removing it from all? Solving this kind of problems is one of the main purposes of a style guide. Now, we already have [[Help:Style#Coding style]]: can we expand it to perhaps require a discussion before starting mass-editing the articles to apply style changes that aren't explicitly backed by [[Help:Style]]? Alternatively there's [[ArchWiki:Contributing#Announce_article_rewrites_in_a_talk_page]], which currently only seems to address content-related edits.
::* "This article deals with so-called ''core'' utilities on a GNU/Linux system, such as ''less'', ''ls'', and ''grep''." ([[Core Utilities]])
+
:::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:25, 13 September 2016 (UTC)
  
::Note that this rule would apply to executables when they represent the application/file itself, not when used in [[#CLI lines]]. In particular pay attention to executables that are usually run without any arguments:
+
::::+1 to mention such in general. [[ArchWiki:Contributing#Improving]] explicitly mentions style fixes, this is better than mixing it with content-related rewrite rule or coding in my view.
 
+
::::Thanks for opening this item Det. Like Lahwaacz I find a trailing slash most clear; if this rule is fixed I'm +1 to his suggestion. Yet, I've often added a trailing slash and/or "directory|path" myself in the course of editing something. Going back to your initial examples, my opinion is that either slash or "directory|path" suffices. I.e. a reader gets the info "directory {{ic|/sys/firmware/efi}}" points to the dir. Likewise the trailing slash alone in {{ic|/etc/modules-load.d'''/'''}} makes that clear (it could also be "{{ic|/etc/modules-load.d'''/'''}} path" but to me it does not read as fluent, because the slash breaks wordflow and then "path" duplicates its meaning). So, IMO it's more a matter of language usage and some variety in it to meld the technical into verbose; variety == more interesting read. This is my main argument against regulating such further. Clearly, though, a "{{ic|/sys/firmware/efi}}" omitting both a slash and "directory|path" is inaccurate, everyone sure agrees to that. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 09:50, 14 September 2016 (UTC)
::* "You can use {{ic|lsblk}} to help with this." ([[Beginners' Guide]])
+
::* "If pacman fails to verify your packages, check the system time with {{ic|cal}}." ([[Beginners' Guide]])
+
::* "Set a root password with {{ic|passwd}}." ([[Installation Guide]])
+
 
+
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:31, 26 June 2013 (UTC)
+
 
+
===Repository names===
+
Currently the [repository] form seems the most frequent, however note the problem of brackets in links, e.g. {{ic|<nowiki>[[#.5Bcommunity.5D|[community]]]</nowiki>}} in the intro of [[AUR]]. The ''repository'' form (italic) can be an alternative, what do you think? -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:29, 26 June 2013 (UTC)
+
 
+
===Package and group names===
+
Use italic for package and package-group names. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:41, 26 June 2013 (UTC)
+
 
+
===Daemons/services, kernel modules===
+
ensure that '''radeonfb''' is blacklisted
+
 
+
--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
 
+
:I'd use ''italic'' in these cases (of course only when the name represents the service/module itself, not when used in [[#CLI lines]]):
+
 
+
:* "The ''dhcpcd'' network daemon starts automatically during boot" ([[Beginners' Guide]])
+
 
+
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:07, 26 June 2013 (UTC)
+
 
+
===Configuration parameters, variables, options, properties...===
+
Use monospace ([[Template:ic]]):
+
 
+
* "By default, the keyboard layout is set to {{ic|us}}." ([[Beginners' Guide]])
+
* "...where ''layout'' can be {{ic|fr}}, {{ic|uk}}, {{ic|dvorak}}, {{ic|be-latin1}}, etc." ([[Beginners' Guide]])
+
* "As of v197, ''udev'' no longer assigns network interface names according to the {{ic|wlanX}} and {{ic|ethX}} naming scheme." ([[Beginners' Guide]])
+
* "In this example, the Ethernet interface is {{ic|enp2s0f0}}." ([[Beginners' Guide]])
+
* "If you are unsure, your Ethernet interface is likely to start with the letter "e", and unlikely to be {{ic|lo}} or start with the letter "w"." ([[Beginners' Guide]])
+
* "Currently, you may include a maximum of three {{ic|nameserver}} lines." ([[Beginners' Guide]])
+
* "you will need to create an extra [[GRUB#GUID Partition Table (GPT) specific instructions|BIOS Boot Partition]] of size 1007 KiB and {{ic|EF02}} type code." ([[Beginners' Guide]])
+
* "All files should have {{ic|644}} permissions and {{ic|root:root}} ownership." ([[systemd]])
+
 
+
Also include command options:
+
 
+
* "The {{ic|-i}} switch can be omitted if you wish to install every package from the {{Grp|base}} group without prompting." ([[Beginners' Guide]])
+
 
+
...and user groups:
+
 
+
* "Adding your user to [[Users and Groups|groups]] ({{ic|sys}}, {{ic|disk}}, {{ic|lp}}, {{ic|network}}, {{ic|video}}, {{ic|audio}}, {{ic|optical}}, {{ic|storage}}, {{ic|scanner}}, {{ic|power}}, etc.) is '''not''' necessary for most use cases with systemd." ([[systemd]])
+
 
+
Plus environment variables:
+
 
+
* "If you are behind a proxy server, you will need to export the {{ic|http_proxy}} and {{ic|ftp_proxy}}environment variables." ([[Beginners' Guide]])
+
* "To use other locales for other {{ic|LC_*}} variables, run {{ic|locale}} to see the available options and add them to ''locale.conf''. It is not recommended to set the {{ic|LC_ALL}} variable. An advanced example can be found [[Locale#Setting_system-wide_locale|here]]." ([[Beginners' Guide]])
+
 
+
...and variables in general:
+
 
+
* "this roughly equates to what you included in the {{ic|DAEMONS}} array." ([[systemd]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:20, 26 June 2013 (UTC)
+
 
+
===CLI lines===
+
Use [[Template:ic]]. Must be inline command examples, not a simple mention of an executable name (see [[#Executable/application names]]). Also console output and text that may reasonably be useful to paste in a terminal.
+
 
+
* "you are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command" ([[Beginners' Guide]])
+
* "You can use the command {{ic|ip link}} to discover the names of your interfaces." ([[Beginners' Guide]])
+
* "If you get a {{ic|ping: unknown host}} error, first check if there is an issue with your cable or wireless signal strength." ([[Beginners' Guide]])
+
* "Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes." ([[Beginners' Guide]])
+
 
+
No prompt symbol is to be represented in inline code: if needed, permission notes must be added explicitly, like in "Execute {{ic|pacman -Syu}} with root privileges", '''not''' "Execute {{ic|# pacman -Syu}}".
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:03, 26 June 2013 (UTC)
+
 
+
===File content===
+
Use [[Template:ic]] for content that can be both read or written on a file or that may reasonably be useful to copy from or paste in a text editor:
+
 
+
* "At the end of the string type {{ic|nomodeset}} and press {{ic|Enter}}. Alternatively, try {{ic|1=video=SVIDEO-1:d}} which, if it works, will not disable kernel mode setting." ([[Beginners' Guide]])
+
* "remove the {{ic|#}} in front of the [http://www.greendesktiny.com/support/knowledgebase_detail.php?ref=EUH-483 locale] you want from {{ic|/etc/locale.gen}}" ([[Beginners' Guide]])
+
* "Please choose the {{ic|UTF-8}} entry." ([[Beginners' Guide]]) (could be grouped in [[#Technical terms]] instead)
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:25, 26 June 2013 (UTC)
+
 
+
===Full file system paths===
+
Use [[Template:ic]]:
+
 
+
* "To test if you have booted into UEFI mode check if directory {{ic|/sys/firmware/efi}} has been created" ([[Beginners' Guide]])
+
* "All files and directories appear under the root directory {{ic|/}}, even if they are stored on different physical devices." ([[Partitioning]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:25, 26 June 2013 (UTC)
+
 
+
===Keyboard keys===
+
Use [[Template:ic]], see [[Help talk:Style/Migration to new Code formatting templates#Template:Keypress]]:
+
 
+
* "you have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST" ([[Beginners' Guide]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:25, 26 June 2013 (UTC)
+
 
+
===Important part of file/command line contents===
+
{{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)
+
 
+
::Since these contents are code themselves, when referenced outside of the template, [[Template:ic]] should be preserved, as opposed to [[#Pseudo-variables]]:
+
:::{{bc|# ln -s /usr/src/linux-'''$(uname -r)'''/include/generated/uapi/linux/version.h /usr/src/linux-'''$(uname -r)'''/include/linux/}}
+
:::You can replace '''{{ic|$(uname -r)}}''' with any kernel not currently running." ([[VMware]])
+
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:53, 26 June 2013 (UTC)
+
 
+
===Pseudo-variables===
+
I don't know if we should use bold or what else when using pseudo-variables like:
+
 
+
{{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.
+
:''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)
+
 
+
::I prefer:
+
::{{bc|# modprobe ''module_name''}}
+
::-- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 15:20, 2 June 2013 (UTC)
+
 
+
:::+1 (plain italic). -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:08, 6 June 2013 (UTC)
+
 
+
::::When mentioning the variable outside of the template, it should drop [[Template:ic]]:
+
::::* "...where ''layout'' can be {{ic|fr}}, {{ic|uk}}, {{ic|dvorak}}, {{ic|be-latin1}}, etc." ([[Beginners' Guide]])
+
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:34, 26 June 2013 (UTC)
+
 
+
===GUI/TUI text===
+
Use ''italic'', for example for menu entries:
+
 
+
* "Then, select ''Boot Arch Linux'' from the menu and press {{ic|Enter}} in order to begin with the installation" ([[Beginners' Guide]])
+
* "When using Gparted, selecting the option to create a new partition table gives an ''msdos'' partition table by default. If you are intending to follow the advice to create a GPT partition table then you need to choose ''Advanced'' and then select ''gpt'' from the drop-down menu." ([[Beginners' Guide]])
+
* "Type {{ic|yes}} and choose ''Quit'' (or press {{ic|Q}}) to exit without making any more changes." ([[Beginners' Guide]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:09, 26 June 2013 (UTC)
+
:Maybe the " > " characters to link elements in lists as suggested  before:
+
:E.g.: Choose ''Help > About''
+
: -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 21:15, 9 July 2013 (UTC)
+
 
+
::Of course, this has been settled in [[Help talk:Style#GUI/UI operations]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:53, 10 July 2013 (UTC)
+
 
+
===Technical terms===
+
I suggest using ''italic'':
+
 
+
* "you are encouraged to type {{ic|man ''command''}} to read the ''man'' page of any command" ([[Beginners' Guide]])
+
* "This article deals with so-called ''core'' utilities on a GNU/Linux system" ([[Core Utilities]])
+
* "''Primary'' partitions can be bootable and are limited to four partitions per disk or RAID volume." ([[Partitioning]])
+
* "This is already a separate partition by default, by virtue of being mounted as ''tmpfs'' by systemd." ([[Partitioning]])
+
 
+
'''Except''' for all-caps terms (usually acronyms):
+
 
+
* "you have to press a key (usually {{ic|Delete}}, {{ic|F1}}, {{ic|F2}}, {{ic|F11}} or {{ic|F12}}) during the POST (Power On Self-Test) phase" ([[Beginners' Guide]])
+
* "Please choose the UTF-8 entry." ([[Beginners' Guide]]) (could be thought of as part of a line in {{ic|/etc/locale.gen}} and grouped in [[#File content]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:20, 26 June 2013 (UTC)
+
 
+
===Stressed/strong words or statements===
+
'''not''' bold when it is worth -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 15:20, 2 June 2013 (UTC)
+
 
+
:I would use italics in this case, see also [[Wikipedia:MOS:text_formatting#Contraindications]] and [[Wikipedia:MOS:text_formatting#Emphasis]].
+
:It would also be great if we could find the right words to define "worth".
+
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:12, 6 June 2013 (UTC)
+
::Attempt 1: it is worth when it may lead a user to a dangerous or inefficient choice.
+
::I do not like italic by the way, it is not that evident. -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 21:15, 6 June 2013 (UTC)
+
:::So would you see these special '''not'''s as kind of a super-compact [[Template:Warning]]? (as defined in [[Help:Style#Notes, Warnings, Tips]])
+
:::About bold vs italic, I'd support bold if there was agreement over [[#Alternative approach]]: I want to find a solid basic reference from which derive all our text formatting rules, instead of deciding case by case without any kind of global vision of the problem; in this section I proposed to base our rules on Wikipedia's style rules, but now I tend to prefer the definitions that I've exposed in [[#Alternative approach]].
+
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:43, 7 June 2013 (UTC)
+
::::Yes, but a warning does not exclude a not -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 10:57, 8 June 2013 (UTC)
+
 
+
:::::So, a general rule could be to use ''italic'' for words whose importance in giving the meaning to a sentence would not be recognized otherwise; usually they would be pronounced in a stressed way if reading out loud:
+
 
+
:::::* "Choose the best environment for ''your'' needs." ([[Beginners' Guide]])
+
:::::* "This command can synchronize the repository databases ''and'' update the system's packages" ([[Pacman]])
+
:::::* "If the screen does ''not'' go blank and the boot process gets stuck" ([[Beginners' Guide]])
+
:::::* "so please type it ''exactly'' as you see it:" ([[Beginners' Guide]])
+
:::::* "If you want, you can make it the ''only'' mirror available by getting rid of everything else" ([[Beginners' Guide]])
+
 
+
:::::When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in '''bold''' (use only when ''really'' needed (or "worth", citing Flu above), though):
+
 
+
:::::* "Partitioning can destroy data. You are '''strongly''' cautioned and advised to backup any critical data before proceeding." ([[Beginners' Guide]])
+
:::::* "keep up to date with changes in Arch Linux that require manual intervention '''before''' upgrading your system." ([[Beginners' Guide]])
+
 
+
:::::The same goes for very important parts of a section that cannot be put in a separate Warning or Note as they are an essential part of the section itself:
+
 
+
:::::* "'''When performing a system update, it is essential that users read all information output by pacman and use common sense.'''" ([[Pacman]])
+
:::::* "This means that partial upgrades are '''not supported'''." ([[Pacman]])
+
 
+
:::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:47, 26 June 2013 (UTC)
+
 
+
=== Acronym/abbreviation expansions===
+
I suggest ''italic'':
+
 
+
* "Pacman is the Arch Linux ''pac''kage ''man''ager." ([[Beginners' Guide]])
+
* "[[Wikipedia:cat_(Unix)|cat]] (''catenate'') is a standard Unix utility that concatenates and lists files." ([[Core Utilities]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:46, 26 June 2013 (UTC)
+
 
+
=== Words/letters when referenced as mere "text entities" ===
+
Use quote marks:
+
 
+
* "When however particular attention is needed, words like "not", "only", "exactly", "strongly", "before"... can be highlighted in '''bold'''" ([[#Stressed/strong words or statements]])
+
* "If you are unsure, your Ethernet interface is likely to start with the letter "e", and unlikely to be {{ic|lo}} or start with the letter "w"." ([[Beginners' Guide]])
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:08, 26 June 2013 (UTC)
+
 
+
:Specify to use typewriter quotes, as per [[wikipedia:Wikipedia:MOSQUOTE#Quotation marks]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:36, 21 July 2013 (UTC)
+
 
+
=== Generic words used in an improper or questionable way ===
+
Use quote marks:
+
 
+
'Words/letters when referenced as mere "text entities"' (from the section above)
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:11, 26 June 2013 (UTC)
+
 
+
:Specify to use typewriter quotes, as per [[wikipedia:Wikipedia:MOSQUOTE#Quotation marks]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:36, 21 July 2013 (UTC)
+
 
+
===Quotations===
+
''All your data belongs to us'' &ndash; Google
+
 
+
--[[User:AlexanderR|AlexanderR]] 19:44, 31 January 2012 (EST)
+
 
+
:...or ''"All your data belongs to us"'' (w/ quotes)? (see e.g. [[Beginners'_Guide#The_Arch_Way]]) -- [[User:Kynikos|Kynikos]] 17:58, 3 February 2012 (EST)
+
 
+
::This is matter of punctuation, not formatting. --[[User:AlexanderR|AlexanderR]] 20:45, 3 February 2012 (EST)
+
 
+
:::Both ways seem incoherent with [[wikipedia:Wikipedia:MOSQUOTE#Italics and quotations]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:00, 6 June 2013 (UTC)
+
 
+
::::I'd like to follow Wikipedia on this topic, and avoid ''italic'' for quotations: in general, I'd refer to Wikipedia's guidelines, so use quote marks for inline quotations, and {{ic|&lt;blockquote>}} or {{ic|:}} (we'd better choose only one form here) for block quotes, ''without'' italic-izing them.
+
:::::"All your data belongs to us" &ndash; Google
+
:::: -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:56, 26 June 2013 (UTC)
+
 
+
:::::Specify to use typewriter quotes, as per [[wikipedia:Wikipedia:MOSQUOTE#Quotation marks]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 12:36, 21 July 2013 (UTC)
+
 
+
==General rules==
+
 
+
===First instances===
+
 
+
The first relevant appearance of a term or name in an article (e.g. executable names) can be highlighted if regarded as worthy of particular attention, considering the topic of the article or the specific section. The first "relevant" appearance may not be the absolute first appearance of the name: its choice is left to the editor.
+
 
+
The preferable way of highlighting the name is using a link to a closely related article in the wiki or to an external page, like Wikipedia; if there are no possible pertinent links, '''bold''' can be used as a fallback solution.
+
 
+
Package and group names should make use of [[Template:Pkg]], [[Template:AUR]] or [[Template:Grp]].
+
 
+
Note that if the name is already introduced by the title of the article or by a section heading, it doesn't require any further highlighting in the article, except in the case of [[#Name/term lists]].
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 13:53, 26 June 2013 (UTC)
+
 
+
====Name of application in the beginning of application-related article====
+
'''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)
+
 
+
::>> so this rule could just add bloat for nothing
+
::Maybe, but for some reason cited HTML5 developers, authors of many articles in this Wiki and even https://www.archlinux.org/ webmaster believe this to be "conventional typographic presentation". This, however, does not oblige us to support such case of usage here.
+
::>> I'd recommend to use the first encounter of the app name as an anchor for a link to the official website instead.
+
::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)
+
 
+
===Links===
+
Whenever any of the above formatting cases can be a link to another article or external page, the link takes precedence over any formatting (which is discarded). -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 04:43, 26 June 2013 (UTC)
+
 
+
===Name/term lists===
+
Keep consistent formatting in lists of executable names, technical terms... even if not all of the items would require to be formatted (e.g. all-caps terms, which shouldn't be italic-ized by themselves, or names in a list where most of the items are formatted according to [[#First instances]]. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:10, 26 June 2013 (UTC)
+
 
+
==Recaps==
+
Ok, I understand this discussion can give a tl;dr feeling to all the thousands of people who would be interested in reading it :P So here's a place for quick recaps of the various proposals. Please reply only to the general ideas here, and use the discussions above for discussing the specific topics. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:36, 6 July 2013 (UTC)
+
 
+
===User:Kynikos===
+
 
+
''<u>italic</u>''
+
*[[#Simple file names]]
+
**also file extensions
+
**also device names
+
**affected by [[#First instances]]
+
*[[#Executable/application names]]
+
**only for full lower-case names
+
**not when used in [[#CLI lines]]
+
**affected by [[#First instances]]
+
*[[#Repository names]]
+
**affected by [[#First instances]]
+
*[[#Package and group names]]
+
**affected by [[#First instances]]
+
*[[#Daemons/services, kernel modules]]
+
**not when used in [[#CLI lines]]
+
**affected by [[#First instances]]
+
*[[#Pseudo-variables]]
+
*[[#GUI/TUI text]]
+
*[[#Technical terms]]
+
**affected by [[#First instances]]
+
*[[#Stressed/strong words or statements]]
+
**can also use bold
+
*[[#Acronym/abbreviation expansions]]
+
 
+
'''<u>bold</u>'''
+
*[[#Important part of file/command line contents]]
+
*[[#Stressed/strong words or statements]]
+
**can also use italic
+
*[[#First instances]]
+
 
+
{{ic|<u>monospace</u>}}
+
*[[#Configuration parameters, variables, options, properties...]]
+
**also command options
+
**also user groups
+
**also (environment) variables
+
*[[#CLI lines]]
+
*[[#File content]]
+
*[[#Full file system paths]]
+
*[[#Keyboard keys]]
+
 
+
<u>"quote marks"</u>
+
*[[#Words/letters when referenced as mere "text entities"]]
+
*[[#Generic words used in an improper or questionable way]]
+
*[[#Quotations]]
+
**but use {{ic|&lt;blockquote>}} or {{ic|:}} for block quotes
+
 
+
Plus [[#General rules]].
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 03:38, 6 July 2013 (UTC)
+
 
+
:Oh well, anyone approving/disapproving this? We need a ''comprehensive'' set of rules, and for the moment this seems the only proposal... If no alternatives are presented soon, I'll have to approve this one all by myself. -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 14:33, 10 July 2013 (UTC)
+
::Have you noticed dozens of people actively (a few edits per month doesn't count) participating in maintaining and improving the wiki? Neither did I, so go ahead, propose & approve anything you want. If someone strongly feels one way or the other, he will speak up. -- [[User:Karol|Karol]] ([[User talk:Karol|talk]]) 15:00, 10 July 2013 (UTC)
+
:::I would not use brackets for repos. +1 for everything left -- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 21:12, 10 July 2013 (UTC)
+
::::@Karol: I understand what you mean, the problem is that these rules will affect a huge amount of articles, it takes only ''one'' user of good will to start a series of edits that would be hard to undo in case we changed our mind afterwards, that's why I want to make sure that this is not only the way ''I'' would like the articles to look like.
+
::::@Flu: thanks, I'm against brackets for repos too, keep it simple (and consistent) ;)
+
::::What's going to happen now is that I'd like to start an [[#Experimentation session]].
+
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:46, 11 July 2013 (UTC)
+
 
+
==Experimentation session==
+
Ok, let's consider [[#User:Kynikos|this set of rules]] approved and start an "experimentation" session where we apply them to some articles ('''no mass-editing for the moment''') so we can see if they need some final fine tuning.
+
 
+
I'd start with:
+
* [[Core Utilities]]
+
* [[Partitioning]]
+
* [[systemd]]
+
which had already been subject to text formatting changes. This will also give me the time to prepare the actual patch for [[Help:Style]] meanwhile (I won't write it before this weekend anyway).
+
 
+
Let's discuss here any problems that should arise, hopefully the experimental articles will look great and we'll be able to let anyone apply the rules everywhere.
+
 
+
-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:46, 11 July 2013 (UTC)
+
 
+
:I'm applying the rules to [[systemd]], and I'd like some feedback on how [[Systemd#Using units]] looks, especially
+
::* If you do not specify the suffix, systemctl will assume ''.service''. For example, {{ic|netcfg}} and {{ic|netcfg.service}} are equivalent.
+
:feels a bit weird.
+
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:51, 17 July 2013 (UTC)
+
::I prefer not to use italic for strings/part of name extensions.
+
::Suggestion #1: Cancel extensions from italic use cases list. Keep italic only for whole words, not parts. Use double quote for any case not described. I prefer this one.
+
::Suggestion #2: Cancel extensions from italic use cases list. Keep italic only for whole words, not parts It is a string after all: use ic.
+
::-- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 12:29, 17 July 2013 (UTC)
+
:::Sorry for not explaining better, however the problem I raised is about how to handle file/service names (which require italic) when mentioned as command parameters (which require monospace/ic).
+
:::The same happens in the following two lines, where I've used a style inconsistent with the line I mentioned above:
+
::::* Mount points will automatically be translated into the appropriate ''.mount'' unit. For example, specifying {{ic|/home}} is equivalent to ''home.mount''.
+
::::* Similiar to mount points, devices are automatically translated into the appropriate ''.device'' unit, therefore specifying {{ic|/dev/sda2}} is equivalent to ''dev-sda2.device''.
+
:::I've written {{ic|netcfg.service}} but then ''home.mount'' and ''dev-sda2.device''. After reviewing it now, I think monospace should win over italic, and those names should be treated as parameters.
+
:::Anyway I'm not sure I understood your suggestions: in #1 you would use double quotes for extensions and in #2 you would use monospace? Could you give here an example of how they would affect these 3 lines under discussion?
+
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 08:43, 20 July 2013 (UTC)
+
 
+
::I modified the other articles: I have a doubt about optional/alternative variables like:
+
::# {{ic|+x{M,G}}} in [[Partitioning#Using_GPT_-_modern_method]] and
+
::# ext[234] in [[Syslinux#Manual install ]]
+
::# option usage read somewhere else, like {{ic|ffmpeg [option] ''myfile''}}.
+
::-- [[User:Flu|Flu]] ([[User talk:Flu|talk]]) 12:29, 17 July 2013 (UTC)
+
 
+
:::# looks good
+
:::# I think we can't be too strict, you can leave ext[234] like that. File system names are considered [[#Technical terms]] though, so I'm not sure if they have to be formatted in italic or we want to leave the choice to the editor whether to use italic or leave normal formatting.
+
:::# that's interesting, can you link to the article where you've found it? I want to see the context.
+
:::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:03, 20 July 2013 (UTC)
+

Latest revision as of 09:51, 14 September 2016

Dealing with long lines within code block text

I'd like to get some input and, hopefully, a resolution to the issue of long lines within code block text boxes; even on this Help page the long lines of code or comments within code block text boxes are not constrained within the text box. Perhaps a horizontal scroll bar can be used to expose the long lines of text within the text box instead of simply allowing the text to span past the width of the text box. This will prove especially useful with the exponential growth in usage of mobile browsers and devices.

ILMostro (talk) 17:55, 31 March 2014 (UTC)

Desktop version of Firefox shows the horizontal scrollbar when needed. Mobile webkit-based browsers don't show the scrollbar, but "swiping" the code box actually scrolls the box.
Optimization for mobile devices is another issue; but yes - browsing wiki pages on mobile webkit browsers sucks, mostly because of [1].
-- Lahwaacz (talk) 18:28, 31 March 2014 (UTC)
Horizontal scroll bars are already enabled for code blocks [2], this is indeed a problem with mobile webkit browsers, not limited to MediaWiki, for example I can't properly see long lines of code on github.com either (no horizontal scroll bar either).
Anyway, if somebody's aware of a CSS fix for that, it should be submitted to MediaWiki's bug tracker.
-- Kynikos (talk) 00:49, 2 April 2014 (UTC)

Reference links before or after punctuation marks?

I was about to revert [3], but I have not found any rule about it in our guidelines, so I'm proposing to add one.

Basically, reference links are not part of the sentence, so they should be put after punctuation marks like period or comma. There should be no space between the punctuation mark and the reference link. This style is widely used on Wikipedia and apparently also Chicago Manual Of Style.

-- Lahwaacz (talk) 08:39, 30 December 2014 (UTC)

Fine with me, although I just recall using reference links in a sentence the other day, which I (obviously) found appropriate usage as well.[4] Further, if we are going to introduce "reference link" as a term, it should be noted as a case in Help:Style#Hypertext_metaphor as well (close to the indirect links bullet). --Indigo (talk) 19:35, 30 December 2014 (UTC)
Well quoting the linked manual of style:
The superior numerals used for note reference numbers in the text should follow any punctuation marks except the dash, which they precede. The numbers should also be placed outside closing parentheses.
So as I understand it, it can be "part of the sentence", just after the respective punctuation (though you wouldn't put a , between the references.) -- Alad (talk) 19:56, 30 December 2014 (UTC)
Good point, sometimes links are part of the sentence, for example in "...as can be found in [42]." or "...for example [43], [44] and [45]." it does not make sense to place the link after the period. On Wikipedia though, where the reference links are formatted as superscript, you would not find it being part of a sentence anywhere. If we keep formatting reference links as normal-size text, I believe the editors should be free to choose if the reference link will be part of a sentence or not.
I would define a reference link as a link without an anchor text (which implies that reference link must be of the syntax [full_url]) and the rule would apply only to reference links that are not part of the sentence. -- Lahwaacz (talk) 20:08, 30 December 2014 (UTC)
In [5]'s case, I'd prefer the link to be after the period too, and I agree with the observations that have been brought here.
Just a quickly-thought idea, we could specify that the rule "would apply only to reference links that are not" grammatically "part of the sentence".
-- Kynikos (talk) 10:10, 31 December 2014 (UTC)
I like that idea a lot. In my view it would, however, rule out the frequently used "...for example [43], [44] and [45]." cases, because the link count substitution ([43],...) does not make any of them a grammatic part of the sentence. My personal rule of thumb is that the reader should not be required to hover over the link in order to see where it leads out to. Arguably the "for example" does hint enough in this example what the links will lead to. For the wiki here that should be enough; we're using external links in a different manner than wikipedia and the cases they are used in an academic (aka "Chicago") style is very seldom.
I now think we should skip this and leave it up to the editors how they want to present the references. Just make sure we don't end up with bogus sentences like "If [46] is started with default configuration [47], the journal will show [48]." --Indigo (talk) 11:10, 16 January 2015 (UTC)

Styling configuration paths

Not sure you can understand what I mean from the heading so I'll give an example. I edited Cinnamon#Manage_languages_used_in_Cinnamon recently and added the third bullet. So I opted for bolding the configuration path, but I see in the article there are cases of using ic (Cinnamon#Themes_and_icons), or using italics like in Cinnamon#Screenshot. So, what's the preferred way if any? I personally have a preference of using bold with the symbol >. --Maevius (talk) 19:01, 29 May 2016 (UTC)

We try to stick to Italics with ">" to separate the menu points, see the examples (last bullet) here: Help:Style/Formatting and punctuation#GUI.2FTUI text
edit: if you think it is worthwhile to change that style rule, we can discuss it here. You probably prefer to bold it, because it is easier to distinguish than italics. Likely other editors chose ic for a similar reason. An alternative I can suggest here, is that you make the menu path go to a new line, e.g.
  • To change the keyboard layout, navigate to:
System Settings > Hardware > Keyboard > Layouts
which will also make it stand out more. Workable like this?
--Indigo (talk) 19:10, 29 May 2016 (UTC)

Directory slash suffix (/path/to/dir/)

Is that an intended distinction with the /-suffix in path names?: Help:Style/Formatting and punctuation#Examples 6

/sys/firmware/efi vs. /etc/modules-load.d/ --Dettalk 09:32, 10 September 2016 (UTC)

The distinction there is purely coincidental: those examples are excerpts that were taken from different articles at the time the page was created.
That said, we've never discussed a standard about the usage of the final slash in paths, I'm not sure if it can make sense to mention it somehow in Help:Style, if you have some ideas I'm happy to discuss them :)
Kynikos (talk) 14:19, 10 September 2016 (UTC)
I dunno how to fit that in there, but I'd personally like to see the "core" directory paths possibly without the final slash, e.g. /etc, /usr/local, etc. (maybe all the ones from filesystem?), and the rest with it, e.g. /usr/lib/awk/, /usr/lib/groff/gpinyin/. Is it too complex? --Dettalk 21:13, 10 September 2016 (UTC)
For sure we should at least explicitly except the cases where the final slash is meaningful, e.g. rsync commands.
Then maybe also except cases where the word "directory" is explicited in the sentence, thus making the examples in this article compliant again?
And also except cases where the "path" is only the directory name and not a longer path, for example "Now create a foobar directory" vs "Now create a foobar/ directory"?
Then I'm also afraid there could be more exceptions needed, I think it would be better to find a couple of articles that are inconsistent in this regard and test how they'd look like if this rule was enforced.
Kynikos (talk) 01:34, 11 September 2016 (UTC)
I don't see why /etc/ etc. should be excluded. I would like to see the final / everywhere except in sensitive commands like rsync and directory names mentioned above. -- Lahwaacz (talk) 15:06, 11 September 2016 (UTC)
Hmm how would you change Installation_guide#Mount_the_file_systems for example? — Kynikos (talk) 10:57, 12 September 2016 (UTC)
I'd add the slash everywhere, i.e. /mnt/, # mount /dev/sda1 /mnt/, /mnt/boot/, /mnt/home/. Though it's probably easier to realize that the slash can be added when it's missing than to realize that it can be omitted when it's present.
The / suffix is useful to clearly indicate that some path is a directory, but it's also the result of tab-completion, which is why it feels more natural to me. In any case making rules about this is hard and global consistency is probably not worth the effort. I think that per-page or even per-paragraph consistency would be enough. Also, people should be aware of both variants anyway.
-- Lahwaacz (talk) 12:34, 12 September 2016 (UTC)
I first noticed this in Installation guide#Verify the boot mode, where it said # ls /sys/firmware/efi/efivars to try to view the contents of the dir. It mentioned that "directory" word, but way into the right, instead of in line with the command. Personally, I don't see a benefit in omitting it in places like this. --Dettalk 14:01, 12 September 2016 (UTC)
It's listed "way into the right" because it makes no sense to add another break before "To verify this (...)". Anyway as this seems to be specifically about the Installation guide, I'd suggest to open a discussion there rather than suggest another style rule. -- Alad (talk) 14:58, 12 September 2016 (UTC)
That's not the point at all. That's why a final / would help in those scenarios, and this isn't only Installation guide-specific. --Dettalk 15:01, 12 September 2016 (UTC)
path/to/dir////////////////////////////////////////////// is perfectly valid as well. So, does it also need mentioning in Help:Style, together with every other combination?
If you just want to inform people on the distinction, we could add something to Help:Reading. Otherwise I agree with Lahwaacz that it isn't worth enforcing this globally. -- Alad (talk) 15:07, 12 September 2016 (UTC)
I don't know what are you trying to convey there :D, but what would that "distinction piece" consist of? --Dettalk 15:12, 12 September 2016 (UTC)
E.g., "Note that a path referring to a directory may contain a single, none, or even multiple trailing slashes. For example, mkdir /foo, mkdir /foo/ and mkdir /foo// are equivalent. Exceptions are programs such as rsync which treat a trailing slash specifically."
-- Alad (talk) 16:56, 12 September 2016 (UTC)
That multiple / note belongs to Help:Reading? I thought that thing was just for global clarifications on ArchWiki article syntax? Where is there an article doing mkdir /foo// or path/to/dir//////////////////////////////////////////////? --Dettalk 17:10, 12 September 2016 (UTC)
Yes, in particular Help:Reading#Append.2C_add.2C_create.2C_edit. The multi-slash example was more for demonstration purposes; I guess it should be left out if it somehow encourages usage of that syntax. Link candidate: [6] -- Alad (talk) 17:18, 12 September 2016 (UTC)
That's about dealing with one or more files (a perfectly valid case). That's different from mentioning incoherent syntax. --Dettalk 17:28, 12 September 2016 (UTC)
<------------------------------------------------|
First of all I'd just ignore the multiple slash case, otherwise I think we should inform the readers that also ../..///./path/to/../to//folder/// is the same as ./folder.
Coming back to the trailing slash problem, I think the point is: what would we do if one day a guy registered an account and started systematically changing all the directory paths to have a trailing slash? Or vice versa removing it from all? Solving this kind of problems is one of the main purposes of a style guide. Now, we already have Help:Style#Coding style: can we expand it to perhaps require a discussion before starting mass-editing the articles to apply style changes that aren't explicitly backed by Help:Style? Alternatively there's ArchWiki:Contributing#Announce_article_rewrites_in_a_talk_page, which currently only seems to address content-related edits.
Kynikos (talk) 10:25, 13 September 2016 (UTC)
+1 to mention such in general. ArchWiki:Contributing#Improving explicitly mentions style fixes, this is better than mixing it with content-related rewrite rule or coding in my view.
Thanks for opening this item Det. Like Lahwaacz I find a trailing slash most clear; if this rule is fixed I'm +1 to his suggestion. Yet, I've often added a trailing slash and/or "directory|path" myself in the course of editing something. Going back to your initial examples, my opinion is that either slash or "directory|path" suffices. I.e. a reader gets the info "directory /sys/firmware/efi" points to the dir. Likewise the trailing slash alone in /etc/modules-load.d/ makes that clear (it could also be "/etc/modules-load.d/ path" but to me it does not read as fluent, because the slash breaks wordflow and then "path" duplicates its meaning). So, IMO it's more a matter of language usage and some variety in it to meld the technical into verbose; variety == more interesting read. This is my main argument against regulating such further. Clearly, though, a "/sys/firmware/efi" omitting both a slash and "directory|path" is inaccurate, everyone sure agrees to that. --Indigo (talk) 09:50, 14 September 2016 (UTC)