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)
Draft for Help:Style/Formatting and punctuation#Links:
  • A numbered external link that does not have a grammatical function should appear at the end of the sentence that it supports, immediately after a punctuation mark that terminates the sentence, unless such mark is a dash or a parenthesis, in which case the link shall be inserted immediately before it.
Kynikos (talk) 10:23, 3 June 2017 (UTC)
Well, after a couple of years, I've actually got used to the option #3 below, which is about the most common style in academic papers. See also this question and the two answers, and this question with the same result even for non-numeric references. I should also correct my original reference to the Chicago Manual Of Style, which in that snippet talks only about superscripts, which is entirely different beast. -- Lahwaacz (talk) 11:28, 3 June 2017 (UTC)
I think I've almost always used option #2 here instead, but I don't really mind as long as we agree on a common style. Your proposal would also simplify the wording:
  • A numbered external link that does not have a grammatical function should appear at the end of the sentence that it supports, separated from the last word by one space, and immediately before a punctuation mark that terminates the sentence. For example:
  • Lorem ipsum [6], dolor sit (amet consectetur [7]) adipiscing elit [8].
Multiple references, still without grammatical function, should be joined without spaces, for example:
Note that numbered links are automatically enclosed in brackets, so there is no need to further enclose them in parentheses, for example ([15]).
Numbered links that have a grammatical function should be treated like regular words, following the same punctuation conventions, for example:
  • Lorem ipsum, as reported in [16]'s last paragraph, dolor sit amet consectetur adipiscing elit, see also [17], [18] and [19].
Kynikos (talk) 06:21, 4 June 2017 (UTC)

Positioning of numbered external links

[Moved from Help talk:Style#Positioning of numbered external links — Kynikos (talk) 10:02, 3 June 2017 (UTC)]

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. [20]
  2. Lorem ipsum dolor sit amet, consectetur adipiscing elit.[21]
  3. Lorem ipsum dolor sit amet, consectetur adipiscing elit [22].
  4. Lorem ipsum dolor sit amet, consectetur adipiscing elit, [23].
  5. Lorem ipsum dolor sit amet, consectetur adipiscing elit, see [24].

I have seen all of these. I prefer #1. #2 looks clinched, #3 and #4 look weird. While #5 improves the reading flow it is superfluous.

Proposed convention:

  • Numbered external links should be put after the relevant sentence or term separated by a space.

Larivact (talk) 05:18, 2 June 2017 (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)
No follow-up, closing. -- Lahwaacz (talk) 16:41, 2 June 2017 (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)
I rolled back the changes to Help:Style. Any thoughts about the Template:\n idea? -- nl6720 (talk) 15:12, 5 December 2016 (UTC)
I see, however we're still 2 for and 2 against the new style rule :)
Regarding Template:\n, I'm against instead because it feels too complicated, and it would look a bit incoherent to me if a style rule about void tags syntax was rejected because unimportant, but then we passed one to enforce replacing <br> tags altogether. — Kynikos (talk) 10:16, 6 December 2016 (UTC)
I'm still for the new style rule, it just seemed wrong to have it sitting there while someone so strongly objects to it. If the for side wins we can undo the rollback.
About Template:\n, I thought that having a template would be preferable to using plain HTML. -- nl6720 (talk) 10:31, 6 December 2016 (UTC)
Wikipedia has Template:break for this purpose, but it's not just a stupid wrapper around <br> since their Lua module allowed the implementation of the "count" parameter. They also have many similar templates to replace XHTML tags, but most of them are not simple wrappers. Some are convenient shortcuts, some involve Lua programming, and some are there just for consistency. If we want to go the same way (except for Lua obviously), I'd say the "consistency templates" like a <br> wrapper should be created last and not induce the creation of the more complex templates. -- Lahwaacz (talk) 15:00, 6 December 2016 (UTC)
So, which of the other templates do we need? -- nl6720 (talk) 15:44, 10 December 2016 (UTC)

[[Wikipedia:Manual of Style]] authority reference

In the General rules section, it currently states "For cases not covered in this guide, Wikipedia:Manual of Style is the authority reference". The current link [[Wikipedia:Manual of Style]] leads to the page "Manual of Style" in Wikipedia which is not the same page as "Wikipedia:Manual of Style". Shouldn't the latter one be the authority reference? - Josephgbr (talk) 12:46, 22 November 2017 (UTC)

I think that you're right. -- Lahwaacz (talk) 22:13, 22 November 2017 (UTC)
I edited to use Wikipedia:Manual of Style instead of Manual of Style after also getting the confirmation from Kynikos, which is the author of the edit. -- Josephgbr (talk) 14:53, 24 November 2017 (UTC)