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

From ArchWiki
Jump to: navigation, search
(Italic: *misleading*diff*: I've just changed the bullet list to a series of subsections)
(Reducing formatting bloat: split discussion and close the old part)
Line 1: Line 1:
==Reducing formatting bloat==
+
==<s>Reducing formatting bloat</s>==
 
I noticed that some articles tend to become almost unreadable after long editing &ndash; mostly due to extensive usage of bold/blue text and code formatting templates. Does anybody feel the same? To start with &ndash; here is my proposal: prohibit usage of [[Template:Ic]] inside [[Template:Note]], [[Template:Tip]] and other similar templates. Such templates already attract a lot of reader's attention, there is no need to bother one even more (and IMHO combination looks ugly). --[[User:AlexanderR|AlexanderR]] 03:39, 25 January 2012 (EST)
 
I noticed that some articles tend to become almost unreadable after long editing &ndash; mostly due to extensive usage of bold/blue text and code formatting templates. Does anybody feel the same? To start with &ndash; here is my proposal: prohibit usage of [[Template:Ic]] inside [[Template:Note]], [[Template:Tip]] and other similar templates. Such templates already attract a lot of reader's attention, there is no need to bother one even more (and IMHO combination looks ugly). --[[User:AlexanderR|AlexanderR]] 03:39, 25 January 2012 (EST)
 
:Honestly I like how code formatting templates make code recognizable even at a glance in a block of text, even inside Notes, Warnings and Tips. Forbidding the use of Ic inside those templates would generate:
 
:Honestly I like how code formatting templates make code recognizable even at a glance in a block of text, even inside Notes, Warnings and Tips. Forbidding the use of Ic inside those templates would generate:
Line 38: Line 38:
 
::::::::#[[#Bold and italic]]
 
::::::::#[[#Bold and italic]]
 
::::::::-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
 
::::::::-- [[User:Kynikos|Kynikos]] 16:17, 31 January 2012 (EST)
:::::::::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)
+
 
::::::::::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)
+
==General indications==
 +
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)
 +
 
 +
: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)
  
 
==<s>Bold and italic</s>==
 
==<s>Bold and italic</s>==

Revision as of 15:21, 5 June 2013

Reducing formatting bloat

I noticed that some articles tend to become almost unreadable after long editing – mostly due to extensive usage of bold/blue text and code formatting templates. Does anybody feel the same? To start with – here is my proposal: prohibit usage of Template:Ic inside Template:Note, Template:Tip and other similar templates. Such templates already attract a lot of reader's attention, there is no need to bother one even more (and IMHO combination looks ugly). --AlexanderR 03:39, 25 January 2012 (EST)

Honestly I like how code formatting templates make code recognizable even at a glance in a block of text, even inside Notes, Warnings and Tips. Forbidding the use of Ic inside those templates would generate:
Tip: You can run rm -rf / as root to free some space on your hdd.
Instead of:
Tip: You can run rm -rf / as root to free some space on your hdd.
I find the second template much more readable and clear than the first one.
That said, it's worthy of mention the solution used in Python's official documentation (code inside Notes and Warnings gets a darker background than the surrounding background color), but we can't implement that here because we'd have to play with css classes.
-- Kynikos 16:12, 25 January 2012 (EST)
Nice tips. Nearly gave me a hear attack ;P -- Karol 16:50, 25 January 2012 (EST)
AlexanderR, can you give some examples, which articles look bad to you? -- Karol 16:50, 25 January 2012 (EST)
This is not whole article but IMHO still counts: MySQL. There are several instructions like this:
edit /etc/rc.conf and add mysqld to the DAEMONS array.
Link to rc.conf is almost invisible and actually is not helpful for ones who do not remember what daemon is. For me this looks a bit better:
add mysqld to the list of daemons in /etc/rc.conf
--AlexanderR 00:12, 29 January 2012 (EST)
Link to rc.conf is perfectly visible for me - it's blue and underlined.
As for people "who forgot what XYZ is", they can always check it in the wiki, e.g. by searching for 'XYZ', but adding link to the daemons article seems reasonable. -- Karol 06:13, 29 January 2012 (EST)
In any case it's true that we're missing an official phrasing like those for installation requests. I like:
Add example to the DAEMONS array in /etc/rc.conf.
[[Daemon#Starting on Boot|Add]] {{ic|example}} to the {{ic|[[DAEMONS]]}} array in {{ic|/etc/[[rc.conf]]}}.
We should probably start a poll after we have collected some ideas here. The same should be done for immediate starting/stopping/restarting of daemons, for adding kernel modules to the MODULES array and for immediate adding/removing of kernel modules.
@karol: internal links become gray with the default theme when visited, and I agree they lose a lot of visibility (unless you move the mouse over them) see one of my proposals at the bottom of #Style vs. Usability.
-- Kynikos 11:32, 29 January 2012 (EST)
>>Add example to the DAEMONS array in /etc/rc.conf.
Does not look good for me. Three links in the single sentence? Two of them to the same article? How is rc.conf related to the entire concept of daemons? E.g. what is the purpose of linking to rc.conf in such phrase? Also mentioning DAEMONS array, /etc/rc.conf and other details would only become a disservice if implementation changes in future. Anyway, managing daemons autostart is more complicated process than just adding/removing entries within some array. Users should also be able to understand which daemons specific one depends on, how to perform lazy (parallel) loading etc. In other words, average Arch user should know contents of Daemons just like Pacman quite well and highlighting /etc/rc.conf together with single link to Daemon should be enough to trigger all required associations.
About formatting: highlighting file names and random code lines by means of pale bluish background is already common in Wiki and looks really cool. But, IMHO, it would be nice to use bold text more intensively: for names of kernel modules, daemons, random executables. Note, that unlike Template:Ic bold formattiong works also in console browsers (at least Links and Lynx can render it noticeably).
--AlexanderR 23:44, 29 January 2012 (EST)
Another example from PulseAudio:
make sure the module snd_pcm_oss is not in the MODULES array in /etc/rc.conf
(is link to rc.conf visible for you?)
--AlexanderR 20:00, 30 January 2012 (EST)
AlexanderR, I fixed the link in the PulseAudio#ALSA example you gave. However, I understand what you mean. I often find that most authors prefer to just write commands without enough explanation. I have certainly done it myself. That can make the formatting stand out. I find the PulseAudio example far more reasonable than the MySQL example you gave earlier because there is more context around the formatting. ~ Filam 22:44, 30 January 2012 (EST)
In the My SQL example, that “Add” link is like Wikipedia’s easter egg links, which I find annoying. Linking to Daemon and introducing the mysqld script should probably be done even earlier in the article; this snippet should just be explaining how to run that script at boot time.
In the OSS example, from a technical point of view, the link is hidden because its formatting is overridden by the inner {{ic}} template. If you add text around it (the /etc/rc.conf file) it might be clearer why. It works if you put the link inside the code ( /etc/rc.conf) or if you use plain <code> tags (/etc/rc.conf). Personally I’d just go for a plain link (/etc/rc.conf) because the formatting of the link is enough emphasis for me, but I understand many people wouldn’t agree. Vadmium 23:14, 30 January 2012 (EST).
Ok guys you surely have some points about this, I'd like to concentrate especially on two things that AlexanderR has rightly pointed out (I'm rewording them, please correct me if I got them wrong), so I'm splitting the discussion here:
  1. #Daemons and modules wording
  2. #Bold and italic
-- Kynikos 16:17, 31 January 2012 (EST)

General indications

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. --AlexanderR 20:45, 3 February 2012 (EST)

I think what AlexanderR wrote here is very important: the style rules that will derive from this talk page will have to be a white list of (very) specific cases that require formatting, like in "all text is to be left without formatting except for the following cases: ...". -- Kynikos (talk) 13:26, 4 June 2013 (UTC)

Bold and italic

Currently the style guide completely ignores bold formatting, which instead could probably be used in some cases in place of Template:ic. Let's include also italic in the discussion. Is there the possibility to have well-defined rules (applicable in real articles) about when to use Template:ic, when to use bold and when to use italics?

-- Kynikos 16:17, 31 January 2012 (EST)

Bold

Template:Box

With respect to this Wiki specificity (and taking into account various precedents) I propose to limit usage of bold text to: --AlexanderR 19:44, 31 January 2012 (EST)

(Highly questionable) Single file names

search for loop.ko in /lib/modules/kernel_release

--AlexanderR 19:44, 31 January 2012 (EST)

It seems I raised the problem again:
I second AlexanderR choices, also the first point (between 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. -- Flu (talk) 16:10, 2 June 2013 (UTC)

Executables names (as executables in file system, not in command line)

javaws, which is in icedtea-web-java7

Template:Box YELLOW

--AlexanderR 19:44, 31 January 2012 (EST)

Kernel module names

ensure that radeonfb is blacklisted

--AlexanderR 19:44, 31 January 2012 (EST)

Important part of file/command line contents

root=/dev/sda6 ro 5 radeon.modeset=1 vga=current logo.nologo quiet splash

--AlexanderR 19:44, 31 January 2012 (EST)

This one can be acceptable. -- Kynikos 17:58, 3 February 2012 (EST)

Name of application in the beginning of application-related article

Foo is the most popular Linux alternative to Wikipedia:Bar.

--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. -- 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 – user can not see link destination without hovering cursor over it. As I 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 article summary template and should probably be placed in that single predefined place. --AlexanderR 20:45, 3 February 2012 (EST)

Pseudo-variables

I don't know if we should use bold or what else when using pseudo-variables like:

# modprobe module_name
# modprobe module_name
# modprobe <module_name>
# modprobe [MODULE_NAME]

(from Kernel Modules). -- 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 –
# 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". --AlexanderR 20:45, 3 February 2012 (EST)
I prefer:
# modprobe module_name
-- Flu (talk) 15:20, 2 June 2013 (UTC)

"not" bold when it is worth

not bold when it is worth -- Flu (talk) 15:20, 2 June 2013 (UTC)

Compatibility with text browsers

As a start, if improving compatibility with text browsers is key, which would be quite fair, we could exploit the fact that they ignore css and fake some html bold for them by using <b style="font-weight:normal;"></b> in Template:ic. -- Kynikos (talk) 12:23, 3 June 2013 (UTC)

A direct consequence of this would be that in '''text {{ic|code}} text''' "code" would be in normal weight in all browsers except in text browsers. I don't know if I'd consider that a flaw or a good thing (maybe the latter). -- Kynikos (talk) 12:59, 3 June 2013 (UTC)

In doubt the latter, I was not supporting text browsers. -- Flu (talk) 21:47, 3 June 2013 (UTC)
Ah I see, thanks for clarifying. I'm trying to find a better way to discuss this whole thing because this way it's too confusing... I think I'll start moving everything to a subpage and reorganizing the various ideas more schematically. -- Kynikos (talk) 11:00, 4 June 2013 (UTC)
The subpage is here, this discussion is complete, closed. -- Kynikos (talk) 13:40, 4 June 2013 (UTC)

Italic

Template:Box
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): --AlexanderR 19:44, 31 January 2012 (EST)

Cites from external sources

All your data belongs to us – Google

--AlexanderR 19:44, 31 January 2012 (EST)

...or "All your data belongs to us" (w/ quotes)? (see e.g. Beginners'_Guide#The_Arch_Way) -- Kynikos 17:58, 3 February 2012 (EST)
This is matter of punctuation, not formatting. --AlexanderR 20:45, 3 February 2012 (EST)

Inline templates

(IMHO, those with italic formatting look much better than ones with bold formatting):

http://127.0.0.1:8080/index.jsp#section_name

--AlexanderR 19:44, 31 January 2012 (EST)

I don't understand, you'd use always italic inside Template:ic regardless of the content? In that case I don't even like it aesthetically :) -- Kynikos 17:58, 3 February 2012 (EST)
This is exactly what you name "pseudo-variables" (your wording was better than mine, lets use it). Using bold in this case conflicts with "important part of file/command line contents" part; italic would also be more intuitive: we want to offset text from its surrounding content rather than attract additional users attention. --AlexanderR 20:45, 3 February 2012 (EST)

Quoting and underlining

Also note that, although with less frequency, even underlining, 'quoting' and "double quoting" are used more or less commonly.

Let's go through this discussion treating one specific problem at a time, without rushing it, since this can be an enormous topic and with our current shortage of manpower there's not much we could do to correct the articles even if we managed to find a decent set of rules.

-- Kynikos 17:58, 3 February 2012 (EST)

Quoting and double quoting

Quoting belongs to punctuation rather than formatting, so there is nothing to discuss. --AlexanderR 20:45, 3 February 2012 (EST)

Now the discussion also includes punctuation :) -- Kynikos (talk) 11:51, 4 June 2013 (UTC)

Underlining

Template:Box
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. --AlexanderR 20:45, 3 February 2012 (EST)