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)

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)