explain xkcd talk:Editor FAQ

Explain xkcd: It's 'cause you're dumb.
Jump to: navigation, search

Feel free to enter any question about editing this Wiki and don't forget to sign you comment. --Dgbrt (talk) 21:18, 31 May 2018 (UTC)

Formatting of explanations[edit]

Many pages contain tables where a definition list would be 1) easier to read 2) mobile friendly, for example: 1957.

I was also involved in rewriting the transcript for 1963, where the discussion came up about how those should be styled. ("as if you were reading the comic to someone")

I think we should have a small style guide to encourage sane formatting. What else should such guidelines contain?

Edit: One more thing I'd love to see: semantic headlines (i.e. < h3> headlines for explanation subchapters instead of < h2> which is the same level as the explanation itself)

(Sidenote: I've been active on explainxkcd for quite some time, but only now got around making an account.) //gir.st/ (talk) 15:01, 19 August 2018 (UTC)

Thanks for your remarks. First: There is no need to start every new sentence at a new line. Tables are meant for small content in all other cases it's bad layout. I recently changed this 2034: Equations to a proper floating text. At the transcript tables should never be used, even when there is a table in the comic image it should be described by text. The guide here was mainly written by me because there was nothing like this here before. Some people already helped and I'm happy for any further remarks to enhance it. And this table issue is definitely one; I just not wanted to be the only (arrogant) layout master. Your help is welcome to write something, otherwise I will do so soon.
For headlines we don't use HTML-code but WIKI-code. The main headlines are written like this: ==Explanation==, ==Transcript==, and (optional) ==Trivia==. Headlines inside that chapters should be done in this way: ;Subtitle. The preceding semicolon causes the entire line to be rendered in bold. Only when the explanation really needs sub-chapters it can be done by this: ===Sub header=== (three equal signs before and after the text). I will put this also into the FAQ.
Welcome and thanks for helping. PROTIP: Always use the preview button to check the layout before saving. --Dgbrt (talk) 13:39, 20 August 2018 (UTC)
hi, I'm aware about the headlines and stuff, it was just shorter to write it this way in the comment. I see you started a bit with a styleguide already; I hope I can contribute to it next week, when things cool down at work a bit. //gir.st/, who is to lazy to log in 172.68.51.190 06:51, 24 August 2018 (UTC)

So, one more thing, regarding 'What is the proper layout for headers?'. I think we should better use small ====headings==== instead of just description titles (;bold text), since it makes the intent clearer. what is your reasoning behind suggesting it the other way round? greetings, //gir.st/ (talk) 14:49, 25 August 2018 (UTC)

Thanks for your input and of course Wiki markup headers should be valid. I just believe that the simplest way should also be valid for less experienced writers. When a new explanation starts it's often awful and chaotic; giving a simple but effective structure at the beginning helps against this chaos. So, I'm thinking about dividing the section "What is the proper layout for headers?" (it's a question because it's a FAQ) into two subsections:
  • easy: a semicolon, the colon at the following paragraph may be mentioned - but I'm not sure about the colon because it should be easy
  • advanced: ===headings=== if the comic really can be divided into chapters; ====headings==== as a replacement for the semicolon; and ==headings== is forbidden because it belongs to expl, trnsc, trivia. The semicolon, colon issue should be mentioned here.
Please consider that there was many chaos in the past and many writers will do their edits without reading this FAQ. So keeping this simple as possible seems to me to be inevitable. And dividing sections by using the semicolon for a header is still much better than many of those tables. --Dgbrt (talk) 17:41, 25 August 2018 (UTC)
Based on this discussion I edited the current comic here: [1] and compare it to this former version [2]. Do not focus on the edits, just scroll down to the resulting page.
This brought me to another important issue: NO links in a header. At Wikipedia this is also not welcome. This site isn't Wikipedia but in this case I feel this is a good rule. But the TOC (Table of content) is shown in the preview while it's not at the resulting page. The result is preferred but the TOC in the preview may confuse editors here.
So, I'm still looking for simple instructions, layouts which advanced people always can enhance.
And consider that some editors are probably younger than xkcd is. Not sure about this but there are definitely young people here and I welcome them all. And I'm NOT getting old like Randall sometimes feel, I like to support every editor despite any other background. And this has to be simple on the first place. STOP(I could talk much more) --Dgbrt (talk) 20:49, 25 August 2018 (UTC)
Sorry, I missed this. I'd personally go with the "advanced" option, but mentioning both is fine too. Nice work on 2037! Really enjoying our conversations about this, I hope i'm not a bother ;-) //gir.st/ (talk) 11:20, 28 August 2018 (UTC)

OK, after a few days and some more edits (for example see here: 2035: Dark Matter Candidates) I believe this would be the best guide:

  • ====headings==== should be preferred because the advantage is that each header has it's own edit button. One other advantage is that the header text will be shown at the summary in the history.
  • The semicolon may be used as a preliminary layout for new comics until it's clear of what content the explanation is composed of.
  • On more rare circumstances the ===headings=== may divide the explanation into different larger chapters.
  • ==headings== is reserved to the general layout and has not to be used.

And I still oppose to the colon at the beginning of any paragraph at all. Any thoughts? --Dgbrt (talk) 13:17, 29 August 2018 (UTC)

Please do not use semicolon-lines as "headings"[edit]

Hi, sorry to butt in, but I was going to mention this here anyway after I saw it in the FAQ. Please don't continue to give this advice to editors:

For headlines you have to use Wiki-style code. The simplest way is a preceding semicolon at the beginning of the line which causes the entire line to be rendered in bold.[1]

References[edit]

The previous Editor FAQ section has it right: in wikicode, the semicolon opens a description list, and will be translated into equivalent HTML. In other words, the wikicode is processed as follows:

Wikicode HTML
; xkcd
: a popular webcomic
<dl>
<dt>xkcd</dt>
<dd>a popular webcomic</dd>
</dl>

One or more lines started with a semicolon must be followed by at least one line that starts with a colon, to provide the <dd>...</dd> part of the description list block.

It is a common mistake to use semicolon-lines as "headings". Unfortunately the result is invalid HTML, since the HTML spec requires that a <dl> block contain:

Zero or more groups each consisting of one or more dt elements followed by one or more dd elements

It's fine to have multiple semicolon-lines in a row (as the HTML standard allows for groups of several <dt>...</dt> blocks in sequence), but they must always be followed by at least one <dd>...</dd> block, created in wikicode by following a line started with a semicolon with another line that starts with a colon.

Just like lines started with * or #, a line started with a ; creates a list element, and has syntactic requirements that must be followed. Abusing the description-term wikicode for purposes other than description-list creation not only breaks the HTML on the resulting page, but it makes the content much harder for screen readers and other assistive technologies to parse and accurately reproduce.

(And, yes, technically Mediawiki's use of :-lines for indenting, as on talk pages, is also invalid since it creates a <dl><dd>...</dd></dl> block with no <dt> element. So it's bad enough on talk pages, it's 100x worse to encourage doing it on article pages.) Please consider removing this bad advice from the Editor FAQ. Thanks. -- FeRDNYC (talk) 05:48, 5 September 2018 (UTC)

Thanks for your remarks, that's why I started this FAQ and the discussion about it. Especially the header section is still preliminary, just check the section above here at the talk page.
My first purpose is to keep it as simple as possible for writers having not much or no knowledge about wiki code or HTML. After that an advanced section should follow and define the rules for a complete article.
Please check my summary from 29 August 2018 just above here. You're right the semicolon isn't a header, that's why I'm saying it should be used only temporary. And after reading your remarks here I would propose a single line with bold text and a following empty line instead of that semicolon thing.
Keep it simple for people who just want to write something here; advanced users will change it to an appropriate layout later. Consider: When a new comic is out the explanation often starts in chaos. And for now I'm really happy that the overwhelming usage of tables is stopped.
Let me know what you do think about the bold text line (not by semicolon) and the more sophisticated header guidance for the final layout as I've mentioned on 29 August 2018. --Dgbrt (talk) 12:45, 5 September 2018 (UTC)
And of course the usage of a semicolon should also be mentioned together with the colon because it's a list. An entire paragraph "How do I format lists?" has still to be written yet. --Dgbrt (talk) 12:51, 5 September 2018 (UTC)
One more: I've checked the definition for dd/dt/dl and it's clear the dd tag must be followed by at least one (either dt or dl) child. This tells me that the indent done by a colon is proper HTML. This is very important because every transcript since the first comic uses this indentation. --Dgbrt (talk) 13:20, 5 September 2018 (UTC)
On one hand, yes, the HTML is technically invalid, but on the other hand, every browser gets the intended layout correct, in no small part because these sorts of errors have been parts of industry-wide regression test suites since the mid-1990s. Asking users to try to achieve completely unnecessary perfection is a waste of time. Even screenreaders are completely unfazed by this nominal flaw. 172.70.211.36 01:29, 11 July 2022 (UTC)

Incomplete tags[edit]

The FAQ says to use {{incomplete transcript|YOUR REASON}} but instead of rendering like this (like with the incomplete template):

Ambox notice.png This transcript is incomplete: YOUR REASON
If you can address this issue, please edit the page! Thanks.

It renders like this:

Ambox notice.png This transcript is incomplete. Please help editing it! Thanks.

Can someone please change this? 172.68.133.180 02:55, 13 October 2018 (UTC)

The FAQ also says: "The reason at the transcript is not shown to the viewer." You can see it when you edit the transcript. And because the reason for the comic is also often not given this should be enough for the transcript. --Dgbrt (talk) 16:49, 15 October 2018 (UTC)

math markup[edit]

Just to note - I was curious about the "math markup" message at the top of each page, and duly followed the link to the Editor FAQ as instructed, but ther--e is no mention of why it shouldn't be used... (no account yet, as I've not made any edits - yet! and i use google data saver, so this is not my ip -->) --162.158.34.22 23:49, 11 December 2018 (UTC)

damn, I'm tired - just re-read the section titles, and there it is. It's late, so sorry! --162.158.34.22 23:54, 11 December 2018 (UTC)
I think the reason given is incomplete, but wanted to check here before I amended it. Transcripts are for the benefit of visually-challenged visitors, so using math markup, and thus rendering the text as images, is counterproductive. Right? -- Dtgriscom (talk) 15:06, 20 March 2019 (UTC)
The explanation is (in my opinion) somewhat silly, as the image generated by MathML has an alt tag for text browsers/accessible use. Further, if this wiki's settings were chosen correctly, the image would be output with MathML alongside, which is the actual (non-plaintext) accessible solution for displaying mathematical formulas on the web. See also: https://accessibility.princeton.edu/about/blog/mathml-accessible-math-markup DimeCadmium (talk) 02:20, 12 October 2019 (UTC)

Create page for new comic[edit]

Should there be a paragraph about this? Since the bot is not working anymore, people need to do this. I know I have seen isntructions somewhere on this wiki, but cannot find them... [btw: there is a new comic up, right now, as I post this line, which is not yet in the wiki. SO if you know how to do it, do it before explaining it on the FAQ :)] --Lupo (talk) 13:27, 3 January 2020 (UTC)

Page targeted by Spam[edit]

The page is currently targeted heavily by Spambots. I am not sure why they target this specific page. It might be, because it is linked in the header? Since Admins (who could protect the FAQ) seem to be currently absent from the page, anyone got any ideas what to do about it? leave it to spam and create a seperate FAQ with the same content? --Lupo (talk) 10:08, 26 February 2020 (UTC)

Spaces[edit]

Seriously, why oh why is 1285 not linked into the statement about the one space / two space controversy? This feels like an inexplicable gap. Is there a policy insisting the FAQ remain fastidiously humorless in all ways? 162.158.107.231 02:10, 29 January 2021 (UTC)

Duplicating the hover text/title in the transcript section?[edit]

Is there a reason not to duplicate the title/hovertext in the transcript section, so a screenreader user can be sent there and not have to page back up for that bit (besides "one or more editors would need to check all entries and edit it in where missing")? 141.101.68.43 00:11, 28 November 2021 (UTC)

For my two (or three) cents:
1) You'd be duplicating it, so you ought to lose the sub-image record if you do that or you could get silly with all kinds of repeating of everything..
2) It's a Transcript to try to record/present the text (and imagery) you cannot already screen-read.
3) It doesn't need manual editing (and manual editing is more likely to have mistakes, anyway).
...Perhaps some Template(-pair?) could be developed to sit post-template to "display:screenreader-only" (or whatever the markup format would be) the upper-templated titletext field? 172.70.86.12 04:00, 28 November 2021 (UTC)

it's/its typo[edit]

At § How_do_I_enter_mathematical_or_chemical_formulas? please change “it's Wikipedia help page” to “its Wikipedia help page” (for the same reason that "our" and "their" don't have apostrophes). Kurahaupo (talk) 23:44, 29 January 2022 (UTC)

Came here to say this, but I see I'm two months too late. 172.70.86.64 12:32, 9 April 2022 (UTC)

Punctuation inside quotes and parentheses[edit]

Can we add a section saying ." or ," is always better than putting the quotation mark first, and .) or .") are similarly preferable to ). and "). please? We also need to remind editors that numbered hyperlinks come after periods, commas, and parentheses, not before them. 172.69.33.83 03:30, 3 September 2022 (UTC)

...Erm. For quotes, it depends. If a proper sentence(-fragment) then I'd put punctuation in front (entry and exit), with ','=>'.' or vice-versa, as required by the full container sentence, but retaining notable exclamation- and question-marks. He said, "Erm," with a hint of hesitation, "For quotes, it depends." I know this is how I was taught to deal with quoted speech (close on fifty years ago), although I know standards change, and it may not even then have been so necessary for non-speech quotations. Yet certainly if I were to mention a set of randomish words like "Red green blue" (or "Red", "Green" and "Blue", perhaps) I would unhesitatingly consider it utterly wrong to move punctuation within any such quotation section. And note that an Oxford Comma (even without the quotes) would confuse matters in that second example.
As for .) (etc), I've seen somebody wrongly do this. Do not do it if you have a in-sentence parenthesis (like this). I have never seen any suggestion that you'd do that (like this.) [<= Deliberately wrong!] And, even if it works "like a quote", it really looks wrong to me. (The clear exception is when you entirely make a sentence parenthetical, like this.)
Now, this is just my own experience/preference/habituation. I have no doubt there are alternative points of view, which I would welcome to be added hereafter. But, whilst supporting the initial idea to precede quotes with punctuation (yet content to let it slip when others have prior authorship and it causes no additional confusion), I rail against it as an unwavering/absolutist style for all quotes ("quotes" and 'quotes', and maybe even «quotes» and the rest?) and especially it having any bearing at all in any bracketting/bracing/parenthesi(s|z)ing situations where full and proper start/end mark nesting should be adhered to as the only useful criteria.
An interesting counter-examplee, however, might even mean individualised punctuation either side of a close-paren (if the sentence somehow does not require the same mark as the aside somehow begs, whether that be exclamation, question or even… ellipsis…?!?). Just so. But I'd normally consider rewriting that, as too stream-of-consciousness-like. 162.158.159.73 04:25, 3 September 2022 (UTC)
This is covered in sections 6.5 and 6.9 of the Chicago Manual of Style. The intent is to aid readability. The reasons for variation from such style guidelines are evident when they are compelling, but whether a quotation doesn't actually end with a comma is simply not a compelling reason to write typography which distracts the ordinary reader. 172.70.206.213 09:32, 3 September 2022 (UTC)
(Chicago links need registration to access, so no idea whose arguments/what alternative it supports.)
There are many Style Manuals (I'd defer to H. W. Fowler's Modern English Usage, if forced). But, I would say, clarity is king above all. And I think the original suggestion is incorrect in that regard.
And depends upon medium. I was taught to put a little finger between words when learning to write with nibbed-pens (and don't smudge/flick the ink!) and a thumb-width indent to each paragraph's first line. Later two spacebars between sentences (and four as indent) when typing.
But that's old-hat (and doesn't survive whitespace condensing in XMLish context, etc, anyway). Spell things correctly (or, because of where Randall lives, all Americanised!) and try not to be accidentally ambiguous! And "-1" to original suggestion. 172.70.91.80 12:04, 3 September 2022 (UTC)
A Google search on, "Fowler's Modern English on quotation," returns the question, "What is the correct punctuation for quotes?," in the second paragraph of results. Clicking on it shows the answer, "Commas and periods always go inside the quotation marks in American English; dashes, colons, and semicolons almost always go outside the quotation marks; question marks and exclamation marks sometimes go inside, sometimes stay outside."[3] Does Fowler diverge from Chicago in any of these respects? The paywall has a free 30-day trial, and it isn't difficult to find citations to those sections elsewhere. 172.70.206.163 21:38, 3 September 2022 (UTC)
(On principle, I don't do 'free trials', but that's just me and a comment on being asked to check something that has hoops to it.)
Like I said, if forced, I'd defer to Fowler of the many options, after the clear suggestion that Chicago was effectively the Académie Française of English, no matter which flavo[u]r of the lingo you're defaulting to. And this article is interesting, but I'm not sure I agree with its single-/double-quotes mark primacy suggestion.
Anyway, when it's an actual speech-quoting-quote I'd probably adhere to preceding the quotation marks. But was resonding to OP's (your?) suggestion that it "is always better". And, coincidentally, just there it is not. Furthermore, Fowler does suggest that where a sentence is equally clear with and without punctuation, one should leave it out. I may not always stick to that myself, with an inordinate love of comma-bound sub-clausing, but I find it a decent principle to aspire to.
As for "Foo (bar.)"-form sentences. No. Just no. Though "(Foo bar.)", and then always so in that case! Noting that you've not defended this part of the original idea, so I don't feel the need to continue to flog that aparently terminal equine.
It's all just opinions, however, just to demonstrate my feelings on the subject as sympathetic to the gist of OP's first respondant. I have no idea if OP and Chicago-linker (and, in turn Chicago-trialler) are the same person or just separately of the opposing opinion. Let those who actually administer the site have the ultimate say (if they wish to have), naturally. 172.69.79.201 23:18, 3 September 2022 (UTC)
The reason we don't try to assign identities to the sources of ideas when we discuss them, is because we believe, as Oscar Wilde once said, the value of the idea is greater than the value of the person expressing the idea. Would you please answer the question about whether Fowler diverges from Chicago? 172.69.33.83 23:49, 3 September 2022 (UTC)
I have yet to delve into the Windy City's precise text. And Fowler has said much, but how about:
      [...] Neatness is the sole consideration; just as the ears may be regarded as not hearing organs, but 'handsome volutes of the human capital', so quotation marks may be welcomed as giving a good picturesque finish to a sentence; those who are of this way of thinking must feel that, if they allowed outside them anything short of fine handsome stops like the exclamation and question marks, they would be countenancing an anticlimax. But they are really mere conservatives, masquerading only as aesthetes; and their conservatism will soon have to yield. Argument on the subject is impossible; it is only a question whether the printer's love for the old ways that seem to him so neat, or the writer's and reader's desire to be understood and to understand fully, is to prevail."
And later, as part of a conclusion, the interesting:
      [...] We recommend that the Times method should be abandoned, and the first or second of the others used according to circumstances.
       The next question is, Whence is this income derived?—Times.
       The next question is 'Whence is this income derived?'. (Full direct quotation. Observe the 'monstrosity' stop)
       The next question is whence this income is derived. (Indirect quotation)
       The next question is 'Whence this income is derived'. (Indirect quotation with quotation marks, or half-and-half quotation, like the Borrow sentence)
Far too much to copypasta. The concluding para just over-eggs my already eggy pudding, so above are just two of the many interesting bits that popped up in the source given at the top of my own definitive search (by exactly the same terms as given above), that demonstrate the evolution of what might be considered acceptible (and why) going into the future, from 1908! 162.158.159.11 10:06, 4 September 2022 (UTC)