Help talk:Style/Formatting and punctuation

From ArchWiki
Jump to: navigation, search

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)
In conclusion: everyone left disagreeing with each other? --Dettalk 14:23, 9 October 2016 (UTC)
Does this make everybody happy? The next happy participant can close the discussion :) — Kynikos (talk) 10:26, 10 October 2016 (UTC)

Orphan brake line tag?

Hi, all! I'm new to contributing in ArchWiki but I'm not quite familiar with wikitext... I'll try not to make many or serious errors! Is the "<br>" tag inside the first item of the first list of the article orphan, or do I miss something...?

P.S. I see now my message has a different formating from the rest of the messages in the page... Hows that...? —This unsigned comment is by Fragos.george (talk) 10:46, 1 December 2016. Please sign your posts with ~~~~!

The usage of <br> in Help:Style/Formatting and punctuation#General rules is explained in the last line in Help:Style#HTML tags, basically it's used to add a line break without breaking the list.
As for your different formatting, see Help:Editing#Code. -- nl6720 (talk) 11:09, 1 December 2016 (UTC)
Just in case by "orphan" OP meant that the tag is not closed, <br> is an empty tag in HTML, and it takes no end tag. — Kynikos (talk) 11:50, 1 December 2016 (UTC)
Why not make it valid XHTML and use <br/>? -- nl6720 (talk) 11:55, 1 December 2016 (UTC)
Are you proposing to add a generic style rule (e.g. "always self-close void html tags"), or would you only change the tags in this article? In the former case Help:Style#HTML tags is the right place, I think I'd be in favor, but then I wouldn't start a campaign to mass-edit the tags in the articles... In the latter case, without a style rule I think it would not make a real difference, since the two syntaxes are well supported by the vast majority of modern browsers anyway. — Kynikos (talk) 10:36, 2 December 2016 (UTC)
I added the new style rule with an explicit <br/> example. While mass editing tags would not be the most productive thing to do, maybe bots could update them when making other changes to articles? -- nl6720 (talk) 10:08, 3 December 2016 (UTC)
Well yes, bots could do it indeed. — Kynikos (talk) 16:03, 3 December 2016 (UTC)
<br> is valid HTML5. We serve HTML5 at Arch Wiki, so the XHTML argument is invalid. <br /> is accepted as well in HTML5, but is not better in any way than <br>, so it makes no sense to let a bot change all of these. See http://stackoverflow.com/questions/1946426/html-5-is-it-br-br-or-br for more information. (edit: to clarify: I think the rule should not be there and we should remove it) Lonaowna (talk) 14:01, 3 December 2016 (UTC)
Just like with any other style rule, the purpose of this one would not be to improve the functionality or compatibility with browsers or standards, but more simply to resolve possible editing disputes by stating what is the preferred way to write html tags, and also to have a more consistent source text in general. Usually I do tend to prefer self-closed tags (when I pay attention to that detail, which wasn't clearly the case when I wrote this article :P ), however if more users think that this rule is too strict, when compared to the other ones, we can always just fall back on Help:Style#Coding style. — Kynikos (talk) 16:03, 3 December 2016 (UTC)
I too think the self-closed style looks better, but I think it is too unimportant to make a rule about. It makes no difference in how the reader experiences the page, both options are technically valid, and the rule only creates extra work for the editors. It also makes the Help:Style page needlessly longer. The longer it is, the less people will read, honour and memorise it. I really don't see why we should enforce one or the other. Lonaowna (talk) 16:33, 3 December 2016 (UTC)
I agree this is too specific to make an explicit rule over. After all, we're not trying to compete with w:Wikipedia:Manual of style. -- Alad (talk) 17:52, 3 December 2016 (UTC)
How about replacing the usage of <br> with a template (Template:\n) which would insert it instead. We could get rid of the special rule for br (and also the one I added) and the page would be shorter than before I edited it. Help:Editing#Line breaks and maybe others would need adjusting, but it should not make them longer. -- nl6720 (talk) 09:44, 4 December 2016 (UTC)