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)