Template talk:Documentation

Category for documentation pages

I propose to alter the category in which documentation pages are placed from Category:Template documentation to Category:Template documentation pages. This will allow the former (which is currently swamped) to be retained as a super-category for pages and templates about template documentation, i.e.

• this template
• Wikipedia:Template documentation
• Template:Documentation subpage, etc.

— Martin (MSGJ · talk) 11:49, 24 February 2011 (UTC)

There hasn't been any response so I am going to boldly make this change. It doesn't seem to be controversial to me, but if anyone disagrees I can revert. — Martin (MSGJ · talk) 16:30, 25 February 2011 (UTC)

Yes, seems like a good idea. Plastikspork _―Œ^(talk) 03:05, 26 February 2011 (UTC)

Edit button not working

When I click on the edit button, I am not being taken to a template's documentation subpage. Rather I wind up landing on a Mediawiki API page which shows this error at the top of the page:

<error code="badurl" info="The URL to redirect to must be domain-relative, i.e. start with a /" xml:space="preserve">

It started doing this late last night / early this morning. Hope you can help because I have to use the "all pages with prefix:" page to get to the doc page otherwise. Ashanda (talk) 17:32, 26 March 2011 (UTC)

It seems to work for me. Maybe it was temporary? If it still doesn't work for you, with what template does this problem occur? Svick (talk) 21:00, 4 April 2011 (UTC)

There have been similar reports at WP:VPT. ---— Gadget850 (Ed) ^talk 21:20, 4 April 2011 (UTC)

I had a similar problem until I went into my user preferences and checked the box next to "Exclude me from feature experiments". Plastikspork _―Œ^(talk) 05:20, 5 April 2011 (UTC)

Heading fix redux

There's an outstanding accessibity issue with header levels in this templates; see Template talk:Documentation/Archive 4#Heading fix, which still needs attention. Earlier discussion, with one dissenting voice, is at Template talk:Documentation/Archive 2#Heading fix. It seems to me that the opponents of this template have to provided any evidence to back up their claims that the proposed change will cause any harm. I have requested some extra eyeballs on the matter, with comments here, on VPT and the accessibility project. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 10:18, 16 May 2011 (UTC)

Yeah, this really does need to get fixed. It makes it look like Wikipedians are idiots who can't understand the most basic concepts of HTML and Web design since the early 1990s. It's quite embarrassing. I and various others manually fix this template's malformed output every time we come across it, but this gets very tedious. After correcting the bad markup in hundreds cases of extant and new templates, I can only remember one person ever reverting the change (and not fighting me on the matter after I put it back with an explanation). This strongly suggests to me that a) the average editor does not care at all, and is happy to leave technical [X]HTML matters to experts; b) HTML well-formedness/validity, cross-browser compatibility and of course accessibility rationales are in fact sensible and persuasive; and c) there is no broad support at all for this template abusing markup the way it does. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 07:05, 19 May 2011 (UTC)

I've again reverted another change to Template:Documentation/preload which resulted in using level 2 headings rather than level 3. If I correctly recall, there was no consensus for this change in the earlier discussions linked to by Pigsonthewing. — Martin (MSGJ · talk) 16:17, 5 September 2011 (UTC)

There was opposition from one editor, who never explained why he thought the current heading levels are correct. Andy Mabbett (Pigsonthewing); Talk to Andy; Andy's edits 12:39, 21 November 2011 (UTC)

And it's a moot point anyway, really, as the "burden of proof" is bassackwards on this one. There's no consensus, and given WikiMedia Foundation's general stance on standards compliance, and the project's continual march towards conformity with Web specifications of all kinds, there arguably cannot be a valid consensus, to violate the [X]HTML specifications, here by abusing heading markup by forcing a level-3 heading in absence of an enclosing level 2. Anyone following markup issues at the MediaWiki Bugzilla will be aware that the entire parser is being rewritten to finally excise the remaining cases misuse of HTML elements. Meanwhile editors have been increasingly ensuring proper HTML, XHTML and XML markup in infoboxes and other template) and implementing beyond-HTML metadata and microformat standards. This is 2011, right in the thick of "Web 2.0". The entire project, from top to bottom, is behind this stuff, and against 1995-style Web coding like what is happening in this template. Anyone who does not fully understand semantic HTML and separation of content and presentation needs to just get out of the way. Web pages != word processor documents or powerpoint presentations subject to random aesthetic whims; Wikipedia layout decisions have semantic meanings and consequences, in a tightly-defined, machine-parseable structure. If someone really, really, really hates the default size and/or other appearance of level-2 headings as they appear in this template, that is a CSS issue, not an HTML issue. For 15 years now (well, 14 and 11 months, since CSS Level 1, December 1996) this has been a CSS issue. Please stop dumbing down our code to mess around with fonts, please.

Speaking of which, I'd like to see actual consensus that there's anything wrong with the default <h2> appearance. It seems to me that with the sole exception of this template, it is used 100% consistently across the entire site. That suggests a 99.999% or so consensus against altering its appearance in this template to satisfy what appears to be a single editors' visual preference. Try gaining consensus for this odd-ball variation at MediaWiki talk:Common.css. Good luck.

I've put the <h2> (==) code back. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 14:23, 21 November 2011 (UTC)

I haven't recently read all the past discussion on this, but I recall that the argument was that the "Documentation" heading was the h2 heading and so the subsections of that should be h3. Is this not the case? If you are making the subsections h2 then surely the "documentation" should be h1? But then we will be introducing inconsistency with all the existing pages. — Martin (MSGJ · talk) 17:17, 21 November 2011 (UTC)

Which "Documentation" heading? Andy Mabbett (Pigsonthewing); Talk to Andy; Andy's edits 22:11, 21 November 2011 (UTC)

And the page title is H1, on all MediaWiki pages. Try actually looking at the rendered code. Whatever; I've already fixed this, and anyone who isn't going to do the basic homework to know what's going on with MediaWiki and heading levels is certainly not in a good position from which to argue, much less to revert, when it comes to heading-level code! We all have better things to do, and should just consider this resolved. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 07:26, 23 November 2011 (UTC)

A H3 header appearing on a page without a preceding H2 header... After reading the discussion, that seems to be the core of the problem. If that is correct, then... Is this a joke? Can anyone cite any situation where the information might be misinterpreted or malformed, or otherwise has some horrible side effects, just becuase there is a H2 missing? Is there a W3C recommendation that explicitely says that there can be no H3 without a H2?

The text reading "Template documentation" should then ideally be a H2, but that runs into practical problem, like an unwanted [edit] link. And (underlined) H2s running throught the entire documentaion is an eyesore. These practical problems need to be adressed before even attempting to discuss semantics. — Edokter (talk) — 22:48, 21 November 2011 (UTC)

As I've said to you before, Edokter, at least twice on other semantic markup and standards compliance issues that you've stonewalled on, you really need to do a lot of reading in topics like separation of presentation and content, semantic HTML, Web 2.0, the semantic web, and other related concepts, and no it isn't "a joke", before trying to take a stand on issues like this. If something's "an eyesore", and others come to consensus with you on that, then we'll fix it with CSS. If you don't want to see "[edit]" links, then use your monobook.css to hide them. Other editors like me depend on them; they're part of the basic functionality of MediaWiki for a reason. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 07:26, 23 November 2011 (UTC)

I never said I didn't want to see an edit link... I meant that an automatically-generated edit link was undesirable. And no, using CSS to hide any changes in semantics makes even less sense; that would obsfucate the correct semantics to noone but the seeing. I am kinda sick of this argument where semantics are put above presentation, especially when you consider that presentation is an unseperable part of semantics. If you remove the relationship between the two, then semantics have no purpose to begin with. — Edokter (talk) — 11:12, 23 November 2011 (UTC)

Seems like nobody knows what anyone is talking about. Wait a sec, and get back to the basics.

Basically, the text "Template documentation" at the top looks like a small header, but it is only make-up! In reality, it's nothing but a span tag that has no semantic value. Since it is virtually impossible to make it a proper H2 header without breaking aesthetics values of Wikipedians, let's forget about this issue.

The second issue was that the template preload for generating doc subpages contained H3 headers instead of H2 headers. Which means that on a standard doc page we had this order of headers:

1. H1 Template:Fifa world cup (for example)
   1. H2 Table of contents
      1. H3 Usage
      2. H3 More info about this template
      3. H3 More bla bla
      4. H3 See also

This looks definitely wrong, as the content under the "usage" header is not part of the table of contents! Oh boy!

Now this second issue has already been manually fixed by Wikipedians on about half of the existing doc pages. All according to the MOS guidelines. Thus SMcCandlish decided to help with that and changed the preload page. Everything has been fixed, you can all go home and have a nice drink. Thanks! Dodoïste (talk) 23:42, 21 November 2011 (UTC)

Could you explain "the content under the usage header is not part of the table of contents" or give me an example so I can understand what you mean? — Martin (MSGJ · talk) 12:34, 22 November 2011 (UTC)

Ah, thanks for asking, it's tricky indeed. Normally, the table of contents is only a bunch of links, a short section in the page. In the second issue explained above, the whole page seems to be a part of the table of contents. Because the "table of contents" is H2 and every following header is H3, the whole page is about "table of contents". Was my clarification of any help? Cheers, Dodoïste (talk) 23:05, 22 November 2011 (UTC)

FYI: There was also this thread: Template_talk:Documentation/Archive_7#Use h2 instead of a span?. Helder 00:56, 22 November 2011 (UTC)

Actually, I think everyone but one user knew what everyone else was talking about, but that's a good explanation anyway. Thanks. As noted before, if someone finds something about the styling to be ugly that's what CSS is for. And, yes, the "Template documentation" text is basically just decor. It could actually be made into a heading, with some CSS tweaks, but there's really no reason to do that; we all already know it is template documentation (this is of course proven beyond any shadow of a doubt by the fact that templates were used and edited and documented just fine before the creation of Template:Documentation and is cutesy pseudo-heading; QED), so it's basically just a fancy "picture frame". If someone wants to go to the trouble to make it a heading, I have no hardcore objection to that, but it seems like a waste of time just to get "Usage" and "See also" to be H3-level. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 05:48, 23 November 2011 (UTC)

PS: I've also yet to see any rationale for why the heading shouldn't have an [edit] link like, well, all headings here do. Myself and other hardcore template editors on Wikipedia make frequent use of these. It's a massive pain in the butt to have to manually go to the /doc subpage to edit something near the top of the documentation. I reiterate that someone who wants to do something weird and non-standard with headings on Wikipedia needs to make a case for it and get consensus for it, not just assume that their unusual personal preference is okay with everyone (I'm here talking about styling the headings weirdly, not reverting back to the wrong heading level; that's just not acceptable at all). This is a protracted instance of WP:BRD at work. The heading documentation was boldly made to do something weird by someone more concerned with their own sense of aethetics than more important matters like code portability and semantic markup. This decision was, in the view of several other editors, less than optimal and it has been reverted, several times over several years by several parties, with plenty of discussion, multiple times and in multiple places, as to why. Someone wanting to restore that mis-functionality has a long way to go to justify doing so. Then again, there are surely more productive things to do. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 05:59, 23 November 2011 (UTC)

PPS: MSGJ said in an edit summary, "we have been using level 3 forever and this will create inconsistency", but that's not really applicable (even beyond the "I've been shoplifting forever, so it must be okay" fallacy inherent in that line of reasoning). What really happened is that this was flagged as problematic forever ago, by several tech-savvy editors, but a dug-in editor or two WP:FILIBUSTERed the preload being fixed. This has led to a large number of editors - enough to fix nearly half of all deployed instances (and that's thousands and thousands of templates!) according to Dodoïste, above - simply correcting the bad code in situ every time they encountered it. I.e., it's already been inconsistent for years, with a strong trend to consistency being manually enforced away from the preload's code by correcting the code in every instance. Frankly, we're tired of doing that, and the time has come to fix the pre-load, which I've done. It was just getting blindingly obvious that it needed to be fixed, and that if there had ever been any kind of quasi-consensus to use the wrong heading level in the preload to begin with, it has long since changed as evidenced by actual practice. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 06:58, 23 November 2011 (UTC)

*applause!* Andy Mabbett (Pigsonthewing); Talk to Andy; Andy's edits 17:30, 23 November 2011 (UTC)

I feel like the only sane man here after reading SMcCandlish's stream of consciousness. It's not an actual <H2> element because MediaWiki inserts the TOC at the first one unless __TOC__ is used elsewhere. Now MW has two different H2 elements == Example == and <H2>Example</H2>, the latter does not produce section edit links (useful since they'd be pointing to {{documentation}} and not /doc), other misconceptions I might attribute to m:NewPP. Possibly a bug should be opened to prevent this behavior or to create a built-in template documentation system.

The template is certainly more than window dressing which the many iterations attest to. Considering the system is styled as two pages glued together, perhaps "Template documentation" should be a level one heading (or at least styled to look like one)? — Dispenser 05:22, 27 November 2011 (UTC)

Template:Documentation/core2

What does Template:Documentation/core2 actually do? It doesn't have any transclusions. McLerristarr | Mclay1 09:36, 1 August 2011 (UTC)

Nothing these days. This template was redesigned by Plastikspork in 2010. I've removed the protection. We could just redirect it to /core. — Martin (MSGJ · talk) 16:18, 5 September 2011 (UTC)

Or simply delete it. — Edokter (talk) — 22:52, 21 November 2011 (UTC)

"Mirror" link in footer is broken

The sandbox "mirror" link in the template footer is broken. It strips all includeonly tags, and all noinclude tags and the sections they enclose. It should probably be removed, as I can't see a way of fixing it. (It is a victim of the behaviour of MediaWiki preload.) — This, that, and the other (talk) 10:31, 3 October 2011 (UTC)

Template:Documentation/end box, for those who hadn't twigged. --Redrose64 (talk) 11:37, 3 October 2011 (UTC)

Yep, this was me. Having noinclude tags respected by preload had advantages and disadvantages. One advantage was that it resolves the concerns that User:DePiep had about sandbox templates being categorised (discussion). The main disadvantage is that it will omit other parts of the code, as noted by TTATO. — Martin (MSGJ · talk) 10:27, 17 October 2011 (UTC)

Edit request on 26 January 2012

In addition to the [edit] and [purge] links, can you add one for [history]? (Pref. between the 2 existing links.) I noticed this viewing a template on the Russian Wikipedia.

Hgrosser (talk) 21:43, 26 January 2012 (UTC)

For example, ru:Шаблон:Abbr. Top right corner of the blue box (the Russians use blue where we have green), there are four links: the first views the doc page, the second edits it, the third is the doc page's history, the fourth is the purge function for the template. --Redrose64 (talk) 22:11, 26 January 2012 (UTC)