Help talk:Style/Formatting and punctuation

From ArchWiki

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)Reply[reply]

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)Reply[reply]
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)Reply[reply]

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)Reply[reply]

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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
I changed my mind and now support your previous proposal for option #2. I dislike option #3 because placing periods after bold text and a symbol makes them hard to spot. --Larivact (talk) 06:39, 7 October 2018 (UTC)Reply[reply]

Positioning of numbered external links

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

  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].

I have seen all of these. I prefer #1. #2 looks clinched and #3 looks weird.

Larivact (talk) 05:18, 2 June 2017 (UTC)Reply[reply]

Orphan break 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)Reply[reply]
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)Reply[reply]
Why not make it valid XHTML and use <br/>? -- nl6720 (talk) 11:55, 1 December 2016 (UTC)Reply[reply]
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)Reply[reply]
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)Reply[reply]
Well yes, bots could do it indeed. — Kynikos (talk) 16:03, 3 December 2016 (UTC)Reply[reply]
<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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
I rolled back the changes to Help:Style. Any thoughts about the Template:\n idea? -- nl6720 (talk) 15:12, 5 December 2016 (UTC)Reply[reply]
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)Reply[reply]
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)Reply[reply]
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)Reply[reply]
So, which of the other templates do we need? -- nl6720 (talk) 15:44, 10 December 2016 (UTC)Reply[reply]

Formatting for pseudo-URLs

There are many cases which use wording like "Navigate to some URL", where "some URL" is usually something like http://yoursite.com/foo/bar, http://yourdomain/foo/bar, http://example.com/foo/bar, http://domain.tld/foo/bar, http://domain:8080/foo/bar or http://localhost/foo/bar. Note that the "/foo/bar" part does not necessarily have to be intended as a pseudo-variable, it is usually a fixed string like "/mediawiki/" or "/phpMyAdmin" which represent the web-application's default location.

How should these links be formatted? I wouldn't like them to be clickable, but links to localhost might be an exception. Then, should they be plain text or something else, and should the pseudo-variable formatting apply to the whole URL or just the variable parts of the URL?

-- Lahwaacz (talk) 21:32, 28 February 2020 (UTC)Reply[reply]

They could also be seen as Help:Style/Formatting and punctuation#File names and paths (maybe we can rename it to "Resource names and paths"), so monospace, which would at the same time solve the problem of allowing to highlight their variable parts with italics.
I'd also be ok with excepting localhost links, but then Help:Style/Formatting and punctuation#Links should apply.
-- Kynikos (talk) 15:25, 16 March 2020 (UTC)Reply[reply]
I encountered this one yesterday. I turned it into a path for now because it was detected as a dead link.
Perhaps something like the following will work?
Open https://domain.tld/some/path in a web browser
I do not like this too much because this is potentially misleading, but you get the idea. Maybe a new section in Help:Reading is appropriate for this? Also it requires typing out the full URL which is tedious but acceptable.
Another idea would be to use https://example.com but I also do not like this because it depends on external resources and this is unnecessary.
A new template for this might be a good idea, but this potentially requires maintenance and a lot of effort.
-- NetSysFire (talk) 05:20, 16 February 2021 (UTC)Reply[reply]
I'd avoid formatting the pseudo-URLs as clickable links to something else, because it makes it harder to select the pseudo-URL text (or its part) without actually clicking the link. So I think using monospace with italics, e.g. "Open https://domain.tld/some/path in a web browser.", would be best. — Lahwaacz (talk) 13:49, 8 May 2021 (UTC)Reply[reply]
I agree. But one thing that still needs to be clarified is what example (pseudo) domain/host to use. There are some possible solutions:
  • domain.tld - my favorite so far
  • host
  • address - sometimes there is no DNS involved
Alternatively one could also use a template perhaps? This is effort and potentially unnecessarily complex. Like this:
Open https://domain.tld:8000/some/path and do something.
-- NetSysFire (talk) 09:19, 14 May 2021 (UTC)Reply[reply]
I like domain.tld too because of the included dot. It can be easily extended to e.g. sub.domain.tld if some page talks about subdomains. — Lahwaacz (talk) 14:56, 1 August 2021 (UTC)Reply[reply]

Merge Help:Style#Formatting here?

This page is all about formatting, so why don't we merge Help:Style#Formatting here to keep all formatting rules in one place? — Lahwaacz (talk) 19:08, 9 September 2023 (UTC)Reply[reply]