Template talk:Documentation/Archive 4

This is an archive of past discussions about Template:Documentation. Do not edit the contents of this page. If you wish to start a new discussion or revive an old one, please do so on the current talk page.

Archive 1

Archive 2

Archive 3

→

Heading fix

{{stale|No significant discussion here for over two months... Consensus does not appear to exist at this time. --Thinboy00 @149, i.e. 02:34, 10 November 2009 (UTC)}} {{AccessibilityDispute}}

Unresolved

I should like to remind everyone that this matter is unresolved: Template talk:Documentation/Archive 2#Heading fix. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 23:26, 23 August 2009 (UTC)

Is there any active debate going on here? If not, it may be best to remove the tags and mark the debate as {{stale}}... It looks like there's been no activity for months. --Thin boy 00 @253, i.e. 05:04, 9 November 2009 (UTC)

No. As far as I know, it's either one or the other. We break the documentation template to fix the accessibility issue, or we keep it like it is. Earlier discussion indicates that people prefer to keep a working documentation template for 99% of the users, rather than fix a problem that affects a small group of the remaining 1%, which even for them seems to be a rather "minor" annoyance at most. —TheDJ (talk • contribs) 14:16, 9 November 2009 (UTC)

This is still an accessibility issue. Fixing it will not "break" the template. Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 15:33, 20 March 2010 (UTC)

Are we going to fix this? Andy Mabbett (User:Pigsonthewing); Andy's talk; Andy's edits 22:51, 15 April 2010 (UTC)

Have you tried pinging SMcCandlish? His was the most lucid explanation of the problem in the original 2008 discussion. It's not likely that this will be fixed simply by bringing it up with no new material every six months. Chris Cunningham (not at work) - talk 13:06, 16 April 2010 (UTC)

[outdent] This really, really needs to be fixed, and I have to concur that nothing will be "broken" by fixing it; claimants to the contrary have never demonstrated otherwise. I've remained silent on this issue for several years mainly because it's just so unbelievably obvious that I've not felt that any further comment would be needed. I'm frankly pretty shocked that it hasn't been fixed after all this time. Where else are we willfully ignoring the [X]HTML specs and blatantly misusing markup in ways that cause actual, not just theoretical, accessibility and usability problems? If people care to review the earlier discussion, someone (one someone, as far as I can tell), decided that because the "Template documentation" line as displayed on the template page kinda looked (to that person) like a level-2 heading, therefor every heading under it should be a level-3 heading, with the result that we now have invalid markup strewn across thousands and thousands of pages. The good news is that it's a very simple fix that a bot or a boring AWB run could fix in short order. Honestly, I had no idea this matter was still open, and if it's not fixed, rapidly, it needs to be settled via an RfC. I am extremely skeptical that the majority of Wikipedians will accept outright abuse of [X]HTML markup and violation of W3C specs and accessibility recommendations that have literally been around since the mid 1990s. Heading levels are stepwise for a reason, and their order and nesting has semantic meaning. In the intervening couple of years since I last raised this issue, I have quite regularly converted "===" markup to proper "==" syntax on template documentation pages that used the former, and I have yet to see a single case of anyone reverting me on it. There simply is no support at all for using semantically-invalid <h3> (===) code for headings on template /doc pages. And even if there were, the proper way to do it would be ==<includeonly>=</includeonly>Heading title here==<includeonly>=</includeonly>, such that the heading appeared as a H2 heading when the page is viewed directly but a H3 heading when transcluded, and even then the "Template documentation" line would have to be coded, when transcluded, to be a real H2 heading in Template:Documentation/core2. Fix it one way or the other, but fix it. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 22:54, 16 April 2010 (UTC)

Template:Category interwiki

There are lots of fully protected templates which do not require any documentation (e.g. stub templates and flag templates) but it would be helpful to put the categories and interwikis on an unprotected subpage so that editors could maintain them without having the help of administrators. What do people think about this idea? Would it be best to build a new template or to adapt this template for this purpose? — Martin (MSGJ · talk) 05:33, 2 October 2009 (UTC)

I am currently working on a new mechanism specifically for flag templates that would resolve this. — Andrwsc (talk · contribs) 17:35, 17 October 2009 (UTC)

Pray tell ... — Martin (MSGJ · talk) 21:29, 18 October 2009 (UTC)

No special solution needed. Just add a /doc page as usual. It doesn't hurt if a template has a fairly empty green /doc box visible. Besides, I think every template should at least have one sentence telling what it is, or a link to the main template where one can learn more or similar. For instance, take a look at {{MNG}}. What is its purpose? What does it do? How should I use it? And compare that to {{wrap}}.

--David Göthberg (talk) 15:25, 25 October 2009 (UTC)

I think its purpose is fairly self-apparent - to show the flag of Mongolia. It might make sense to have a central documentation for all the flag templates (this is what we have now done for the stub templates), but I think it would be a huge effort and duplication to have separate documentation for each flag template. — Martin (MSGJ · talk) 15:40, 25 October 2009 (UTC)

No, its purpose is not self-apparent for someone not already working with the flag templates. But sure, this case wasn't that bad. There are much worse cases out there of "small" templates that are very cryptic and that has no documentation, not even a link to some main template or so. And you apparently didn't take a look at {{wrap}}, right? Since it just has one sentence linking to the main template that has the documentation.

But my main point was that the green /doc box don't have to contain any text from start. There doesn't even have to exist a /doc subpage. But the {{documentation}} template should still be added in the noinclude area to all protected templates. Then it shows an empty green /doc box with a [create] button on it. That allows non-admins to add interwikis, categories, and perhaps eventually add some explanation.

--David Göthberg (talk) 17:00, 25 October 2009 (UTC)

Yes, I did look at Template:Wrap and the line is useful, although it might be even better just to transclude Template:Nowrap begin/doc there. Anyway ... I understand all your points, although I still believe that adding this template, in its current form, to all protected templates would be sub-optimal because:

It actively encourages users to create documentation for each template.
Creating individual documentation pages for templates in a series (e.g. flag templates) would be time-consuming and inefficient. (The main reason the stub sorters were so concerned about using this template is that it would be hard to monitor all the doc pages and keep them consistent.)

However I do agree that it is appropriate that all protected pages transclude an unprotected page for the purpose of maintaining categories and interwikis. I am imagining a version of this template with the following differences:

The title "Template documentation" is omitted.
Instead of "create documentation" when /doc doesn't exist, it says "add categories/interwikis".
The preload template contains just the includeonly section.

— Martin (MSGJ · talk) 18:39, 25 October 2009 (UTC)

MSGJ: Ah, I see what you mean. I think I like your template idea.

But here is my long answer. Regarding your first section:

No, I strongly advice against transcluding the same /doc page onto several template pages. That causes the same categories and interwikis to show up on all the template pages. People often try to fix that by using a lot of if-cases, but that makes the categorising and interwikiing very complex. Remember that most interwiki links are added by users from other language editions of Wikipedia, where they often don't even have the /doc system. So they are completely lost when they come to a /doc page that contains such if-cases. It doesn't help if the code has comments explaining where to put each interwiki, since some of those users don't even understand English. Consider if you tried to add an interwiki link to a Russian page, and find that the interwikis are mixed with some complex code with comments all in Russian.

Also, the documentation text often becomes confusing since people editing it often aren't aware of that the text will show up on many templates. I have seen that happen many times. And it is harder to write the text even if one knows the documentation is shown in several places, since the readers then will be reading the text in different contexts.

So using a "soft redirect" the way we do for {{wrap}} is the method that causes the least trouble, and the least work. We have used such soft redirects in /doc pages on lots of templates, for some years now, and it works great. In my experience people don't try to add documentation text to them. I guess the reason is that they immediately grasp the idea that the template belongs to a group and is centrally documented. And the users from other Wikipedia editions add their interwikis just as usual, they are not confused by the soft redirect.

Regarding your second section:

Keep the green box so it is easy to recognise. (But I guess that is what you already intended, right?) Assuming you would call your template say {{cat iwik}}, then it could look like this:

Lots of template code<noinclude>

{{cat iwik}}
<!-- Add categories and interwikis to the /doc subpage, not here! -->
</noinclude>

[Add categories or interwikis]

I think that button can have the same text, no matter if the /doc page exists or not.

To make the categories and interwikis work the template of course has to transclude in the /doc page if/when it exists. I suggest it is transcluded into the green box, below the button, not outside the box. So if the /doc page contains text it becomes clear where that text comes from so one can handle it.

I think you might not like my next idea: I would like a parameter so one can feed a short text, that will be displayed nicely in the plain green box. Then it could look like this:

Lots of template code<noinclude>

{{cat iwik| This template works together with {{tl|example}}. See documentation there. }}
<!-- Add categories and interwikis to the /doc subpage, not here! -->
</noinclude>

This template works together with {{example}}. See documentation there.

[Add categories or interwikis]

I am aware of that if the template page is protected, then regular users can not edit that short text. But I think such short texts only rarely need editing. And users can of course still add other text by putting it in the /doc page as usual, and the text will then show up inside the box.

This system means you can paste the same code onto all templates in a group, and still don't have to create a single /doc page (until of course you want to add an interwiki or a category). You can also do all this with the current {{documentation}} template, but as you mentioned you want to avoid the "Documentation" header and have a cleaner preload page etc. But it is compatible with the current /doc system, so it is easy to switch between using {{cat iwik}} and {{documentation}}.

I guess you already were planning it much as I described it here. Anyway, I think I agree with your idea to make a light-version of the {{documentation}} template.

--David Göthberg (talk) 21:29, 25 October 2009 (UTC)

These are interesting ideas and I think we are thinking the same way. I also like the short text idea. I am still wondering if it might be possible to adapt this template rather than create a new template because a lot of the features will be the same. For example, I still think it will be useful to link to the /sandbox version and also /testcases if these pages exist. Would you have a look at an old version of a template I created to see if there are any features you like? (It was still in its infancy though.) Finally, I am puzzled when you keep saying "green" because it is most definitely blue on my browser :) — Martin (MSGJ · talk) 22:44, 25 October 2009 (UTC)

Oh, you are very right. It should show the /sandbox and /testcases too. I really like your old template. Note that I like having some kind of heading. I mostly made the suggestions above without a heading since I thought that was what you wanted. But I don't know what would be a good heading to differentiate the "light version" from the normal full documentation version. I think I need to think about this for a while, since I have no more meaningful comments about this at the moment.

And the /doc box colour: On my screen it looks light green with some blue in it, clearly more green than blue. And I checked, its colour codes are #ecfcf4 = RGB 236,252,244 = hue 100. Full green is hue 80, full blue is 160. So the numbers too say it is more green than blue. I bet you are using an LCD screen, right? LCD screens have really bad colours. Try putting an old school CRT screen next to your LCD screen and compare the colours if you get the chance. You will probably be chocked.

--David Göthberg (talk) 01:29, 26 October 2009 (UTC)

I have a few other thoughts about this.

I think if the short text is specified, the heading could be something like "Template summary". But otherwise I don't think that any heading would be appropriate ...
In order to prevent "doc-lite" being improperly used as "doc" it would be good to prevent display of anything (except the cats and interwikis of course). You would probably know if this was possible or not. Ideally it would be able to automatically detect if there was any visible content, but unfortunately PAGESIZE can not distinguish between visible and "invisible" content.
If a template is not protected and there is no documentation, then it is pointless to create a /doc page to hold the categories and interwikis. Do you agree? If so, perhaps we should consider detecting the protection level.
If we are going with your short text idea, then it is probably worthwhile to include a type parameter so that, for example, |type=flag would produce a standard message about flag templates and where to find the documentation instead of having to put it separately on >100 separate templates.

Yes, I mainly use LCD monitors. I'll have to try a CRT and compare the difference! — Martin (MSGJ · talk) 14:57, 26 October 2009 (UTC)

1: I agree, "Template summary" is a good heading. And yes, when there is no text, then no need to have any header at all.

2: I can easily hide content by using a little CSS magic, and still the categories and interwikis would work. But then we would not see if there is any text content on the /doc page. And I think it is important to for instance be able to see if there already exist a /doc page with content when one adds the {{cat iwik}} template to a template.

3: I disagree. Right, since some time now we can detect the protection level from template code. But since the /doc page is reachable/editable with one click, then the categories and interwikis are just as accessible as if they were put on the template page itself. And it shields the person who edits the categories and interwikis from seeing the messy template code. Also, we rarely move/rename templates, and when we do that the move dialogue actually lists the subpages and offers the options "Move subpages" and "Move associated talk page". So the move of a template, its /doc page, its subtemplates, and all the associated talk pages, can be done in one operation. If we don't use the /doc page, then if we later protect a template it adds the extra burden of then having to create the /doc subpage manually, and cut and paste the categories and interwikis there. That's something many admins tend to forget when they protect a template. (Templates are often protected by admins being asked to do so, and some of those admins don't know anything about template programming.) So I think we should always use the /doc subpages.

4: Nah, don't add standard messages in this template. There are hundreds or even thousands of different groups of templates, many of which then would like their own message. You are talking about the difference between pasting something like this:

{{cat iwik| This flag template works together with {{tl|flag main}}. See documentation there. }}

And this:

{{cat iwik}}

If you are going to paste the same message into many templates, and you want to be able to later update the message in one place, then you can create a small template named say {{flag doc}}, and it would contain:

{{cat iwik| This flag template works together with {{tl|flag main}}. See documentation there. }}

Then you instead put {{flag doc}} on all the flag templates. Thus keeping the technical code and the text content separate.

--David Göthberg (talk) 16:39, 26 October 2009 (UTC)

I have now made a start on this template at Template:Category interwiki. I am still in favour of supressing display of any content from the /doc page. (Otherwise there seems no neat way to do it; the output on the template is a mess; also is prevents misuse of the template when they should be using {{documentation}}.) So I have implemented that. I have left the "standard message" feature off for now, while I think about it more. Still think it might be useful. — Martin (MSGJ · talk) 15:52, 10 January 2010 (UTC)

Padding

I'd like to change the padding to 1em 5px 5px 1em, as the content clings to close to the top and left border. Thoughts? — Edokter • Talk • 14:17, 25 October 2009 (UTC)

I assume you mean you want more padding inside the green /doc boxes, right?

So I did a little testing (but I didn't save it anywhere, sorry):

They already have 5px padding all around, so they already have 5px padding to the left border. Do you mean you want an extra 5px padding left and right compared to now? Which in total will correspond to about 1em so we can just as well use 1em then. Which I think looks okay.

And do you want about 1em padding top and bottom? Which would mean about double as much padding top and bottom compared to now. With top I here mean between the top text "This documentation is transcluded from Template:Example/doc. (edit | history)" and the begin of the actual documentation text. Which I think looks okay.

Or do you also want extra padding above and to the side of the "{{i}} Documentation [edit] [purge]" header too? Which I also think looks okay.

Basically, I think anything between the current 5px all around to about 1em all around looks okay.

--David Göthberg (talk) 15:10, 25 October 2009 (UTC)

Yes I mean the padding inside the green box. Basically, I want 1em for top and left (as that seems to be the default for most content boxes), while retaining 5px for right and bottom, to prevent to much space between the edit links and the right border. (remember CSS notation is top right bottom left.) — Edokter • Talk • 15:38, 25 October 2009 (UTC)

Oops, you're right, I forgot it should be read in clockwise order. So I tested that: Ouch, it looks asymmetrical. I don't like it.

--David Göthberg (talk) 17:06, 25 October 2009 (UTC)

In that case, I propose a padding of 1em all around. — Edokter • Talk • 20:15, 25 October 2009 (UTC)

Which as I stated above, is fine with me. Any one else have any comments before Edokter boldly goes ahead and changes the padding? (By editing the .template-documentation class in MediaWiki:Common.css.)

--David Göthberg (talk) 21:35, 25 October 2009 (UTC)

No comments for a week. I'll implement the change. — Edokter • Talk • 15:14, 31 October 2009 (UTC)

Problem with right-aligned images

(Note: not related to padding above; this is pre-existing.) See the image example above. Notice the left side border is showing with no left-margin in Internet Explorer 6 (but the content doesn't shift). This happens only when there is a right-aligned image, either with or without thumb. Thoughts? — Edokter • Talk • 15:45, 31 October 2009 (UTC)

Since I didn't understand what you meant: I tested with my girlfriends IE 7, and I see it there too. It is the left margin of the whole green box that is lacking. I did some testing, it only happens for right floating content, not for left floating content:

I guess we should investigate this. I hope it is something we can fix, but it looks like a nasty browser bug...

--David Göthberg (talk) 05:11, 3 January 2010 (UTC)

Since this was brought up again (see section Template documentation box width issue on Internet Explorer below) I took a look at it again. It seems we should fix this the usual way: We should change {{documentation}} from using a <div> to instead use a <table> for the big box. Divs simply aren't a mature technology, different browsers cause all kinds of different bugs when using divs, while tables are robust and work the same in most browsers. That's why we use tables for the mboxes such as {{ambox}}, since that was the only way we could make them render consistently in all browsers.

I probably won't be able to code for a week or two, since I just came back from surgery and am so full of drugs and painkillers that I am pretty "drunk". If anyone else is thinking of having a go at it, remember that there is much more to this template than first meets the eye.

--David Göthberg (talk) 07:16, 3 March 2010 (UTC)

In my opinion, this is such a small issue, that it is not really worth solving. I mean, for the amboxes, it HAD to be solved, because they are so visible and common, but here, it doesn't really matter much. —TheDJ (talk • contribs) 15:01, 5 March 2010 (UTC)

It is perhaps not a high-priority issue, but it would be nice to have fixed. {{Documentation}} is, of course, not as common or visible as the amboxes, but it does have nearly 40,000 transclusions. Even if this issue affects only a small percentage of templates transcluding {{documentation}}, the number of affected pages would easily be in the hundreds. -- Black Falcon ^(talk) 20:20, 5 March 2010 (UTC)

For those with IE... Check out the sandbox version i have deployed in here. I'm wondering if under IE, the green boxes now align, even though the text inside the documentation box, now no longer has padding. If so, that would point at "The fake Indent-problem" as detailed here: http://www.positioniseverything.net/explorer/floatIndent.html . If so, then

should work as well. —TheDJ (talk • contribs) 21:49, 5 March 2010 (UTC)

Solution

OK, managed to get access to a computer with IE7 for a few minutes. The above does not work, but I have found something that will work and it is called the zoomfix. Basically, we add the following to MediaWiki:Common.css

.iezoomfix div.thumb,
.iezoomfix table.infobox {
  zoom: 1;
}

Now we add the iezoomfix class to the wikitable, and the problem is solved. —TheDJ (talk • contribs) 22:13, 5 March 2010 (UTC)

We can also just set it on all child div's and table's, because i doubt it will break on any other browsers. —TheDJ (talk • contribs) 22:17, 5 March 2010 (UTC)

Done —TheDJ (talk • contribs) 19:38, 8 March 2010 (UTC)

It's still visible on IE8. I noticed that you made the change about 10 minutes ago, so perhaps we just need to wait? -- Black Falcon ^(talk) 19:52, 8 March 2010 (UTC)

It will definitely require that your cache is cleared, and IE is known to be troublesome with that. It worked when I tested this yesterday in the library, so hopefully it will work now as well. —TheDJ (talk • contribs) 19:59, 8 March 2010 (UTC)

I cleared my cache and checked again: some instances appear to have been fixed while others remain. For example, the first and fourth examples in this section still display the issue, as does {{Copy to Wiktionary}}, but it is no longer present in {{R from alternative name}}. -- Black Falcon ^(talk) 19:39, 12 March 2010 (UTC)

It appears to be fully resolved now. Thank you fixing the issue, -- Black Falcon ^(talk) 17:38, 15 April 2010 (UTC)