Template talk:Documentation/Archive 3

Template:Rfd starter
As indicated at Template_talk:Rfd_starter, template:Documentation won't work at Template:Rfd starter. Would you please revise template:Documentation to work at Template:Rfd starter. Thanks. -- Suntag  ☼  17:38, 2 October 2008 (UTC)


 * No, that is not possible since Template:Rfd starter is not a template, it is a preload text. And preload texts can not contain &lt;noinclude> areas and thus can not use documentation. Or rather, such areas (including the &lt;noinclude> tags) get included when the preload text is preloaded. And that's a feature, not a bug, of MediaWiki. Since we often need to preload such noinclude text.
 * But this was a tricky one. Took me some minutes to figure out that it is a preload text.
 * What instead is a minor issue with Template:Rfd starter is that it should preferably have been named in a way that made it clear it is a preload text. The usual way to do that is to put it below the template or page it is used on as a subpage named "/preload".
 * By the way, documentation itself uses a preload text. The [edit] button in the upper right corner of the green /doc box uses a preload text if the /doc page has not yet been created.
 * --David Göthberg (talk) 01:07, 17 October 2008 (UTC)
 * Thanks for the reply. I updated the Template:Rfd starter talk page with this discussion. -- Suntag  ☼  07:53, 17 October 2008 (UTC)

Edit request
editprotected

This change is to add the " " parameter (case sensitive). This will allow the the preload template to be loaded from Template:Userbox documentation/preload instead of Template:Documentation/preload. It is also necessary that the page used for preload be encoded using  magic word.

Test pages:
 * User:Lightsup55/Template Sandbox (ignore the documentation section - imagine that it is Template:Documentation/doc in its place)
 * User:Lightsup55/Template Sandbox 2
 * User:Lightsup55/Template Sandbox 2/doc - a non-existent /doc page (note the  link on the base page)





Thanks. --Lightsup55 ( T | C ) 20:11, 12 February 2009 (UTC)


 * Not done
 * 1: You should first explain what this "userbox=yes" thing is and why you need it. People should not have to read your code to make a guess. And they should not have to guess at all.
 * 2: I strongly advice against letting the "userbox=" parameter accept multiple forms of "yes" such as "YES, "Y" and "y". Since that means we have to support that "forever", which makes life much harder for people who need to update this code later on. And we know by experience that to later on find and fix all cases to use only "userbox=yes" takes a HUGE effort. I recommend only allowing lower-case "userbox=yes" and document that properly.
 * 3: Since this is not a trivial change: You should supply a link to a /sandbox where this code is running. And to some /testcases where we can see the result. As it is now we have no idea if you have even tested your code, or if you just typed it down right into this talk page.
 * 4: You should not use Template:Userbox documentation/preload as a page name for a preload page or for any other kind of subpage, since the parent page Template:Userbox documentation doesn't exist. Since if the parent page doesn't exist then it is hard to know what that page is. And someone might later create a template at that parent page that has some totally unrelated purpose. And trigger happy admins using semi-automatic tools are likely to come and delete your subpage, since it will look orphaned. Instead put that subpage at some more logical page name, like perhaps Template:Documentation/userbox preload. (Not sure if you can have a space in a preload name, you might have to name it Template:Documentation/userbox-preload. But that is easy to test.)
 * 5: Note: I will probably not be the one that in the end tests your code and adds it, since I am too busy elsewhere. I just saw these obvious reasons why this editprotected request currently can not be fulfilled, so I responded to it so you don't have to wait for an answer and instead can get to work with fixing this stuff. (Since many admins simply don't answer when they don't know what they are looking at, hoping that some other admin might know what it is about.)
 * --David Göthberg (talk) 23:06, 12 February 2009 (UTC)


 * 1: If the documentation is for a userbox, this change uses different  link when the " " parameter is set. Upon clicking the link to create the new /doc page, the preload template used contains   instead of  . This would make it easier for someone to create a documentation subpage and not have to manually update   with either   or using   in its place.
 * 2: Already covered in my original comment.
 * 3: Already covered (though I forgot to mention it): User:Lightsup55/Template Sandbox and User:Lightsup55/Template Sandbox 2 (with its non-existent /doc page - note the  link on the base page)
 * 4: I didn't get around to that yet as I had something to do in my personal life. Though your suggestion of moving it would be better (for now at least). And as far as spaces, you can have spaces in URLs. If you use the  magic word, you'd get:   from   (which works perfect as the   link).
 * --Lightsup55 ( T | C ) 00:39, 13 February 2009 (UTC)


 * I kinda figured out what this does a bit ago, but I don't understand why. Why does a userbox page need a different type of documentation page? Most of them are pretty self explanatory and don't need any documentation. --—— Gadget850 (Ed)  talk  -  01:02, 13 February 2009 (UTC)


 * Gadget850:
 * It doesn't change how the documentation looks. It only just makes the  link use a different preload template (Template:Documentation/userbox preload) when no /doc page exists. The only change in the preload template is   instead of  . --Lightsup55 ( T | C ) 07:34, 13 February 2009 (UTC)


 * Lightsup55:
 * 1: So you have now explained that "userbox=yes" causes a different preload page to load, which in turns contain the userbox documentation subpage. From reading the code inside userbox documentation subpage I see that it in turn calls, which probably is what you mean above. However, you do not explain here what does. I have also looked over at your request at Template talk:Documentation subpage, but you don't explain anything there either. By reading the code in your request over there I can guess what it does, but I can't be sure I read the code right and can't be sure that is what you intend it to do. So please explain what  is supposed to do? And why do you need it to do that?
 * 2: I still strongly disagree with letting the "userbox=" parameter accept multiple forms of "yes/Yes/YES/y/Y". I strongly advice it should only accept exactly "userbox=yes" in lower case. If this is not changed my recommendation is to not deploy your code. Since I know from experience how much havoc such "flexibility" and "user friendliness" creates later in time when others have to update the code. (I spent a fair part of 2008 cleaning up problems with templates that had over-flexible parameters. And we are currently running automatic clean-up searches for several major templates that are deployed on a couple of million pages. Such searches take weeks to run. And often weeks of manual editing to fix all cases, once the search is complete.)
 * 3: Ah, thanks for the links to the test versions. Do you have any test versions installed for ?
 * 4: Ah good, point 4 resolved then.
 * --David Göthberg (talk) 02:12, 13 February 2009 (UTC)


 * 1: I will explain further. See the talk page there (which I'm sure that it is already on your watchlist).
 * 2: Sorry, I must have read your comment wrong. You're saying it shouldn't, when I thought you meant that it should. It is as simple as removing the  magic word, but without removing the code inside the magic word itself.
 * 3: Yeah, I did have a test page, but had overwritten it with the current test page. I can create a separate page for that if you wish. Again, see the talk page there.
 * --Lightsup55 ( T | C ) 03:15, 13 February 2009 (UTC)


 * I've given examples, made changes based on your recommendations, inserted the new code, and re-applied the editprotected template. --Lightsup55 ( T | C ) 04:45, 13 February 2009 (UTC)


 * I see that you have given a longer response over at Template talk:Documentation subpage, so I have responded over there. Thus this discussion now has continued over there.
 * But regarding the editprotected request above: I have now suggested a simpler and better option over at that other talk page. So I recommend this editprotected request should be denied or withdrawn.
 * --David Göthberg (talk) 09:44, 13 February 2009 (UTC)


 * Request withdrawn. --Lightsup55 ( T | C ) 18:38, 13 February 2009 (UTC)

Purge link redux
Above, someone mentioned a purge link. I think that is a good idea, and would like to recommend putting &lt;small>&lt;/small> next to the edit link, perhaps within the brackets. If there are no objections any time soon I'll add a sudo. Here's a sandbox diff: []. -- Thin boy  00  @326, i.e. 06:49, 20 February 2009 (UTC)


 * I agree, this template needs a purge link. Since often when one have edited the /doc it doesn't become visible on the template page. (I myself have a javascript installed that give me a purge button at the very top right of all Wikipedia pages I go to, but most users probably don't have that. There are plenty of nifty user scripts over at WikiProject User scripts/Scripts.)
 * Thinboy00: I also agree with where you placed the purge link (top right) in your sandbox example. But you choose the link caption "[update]". I think that caption might be somewhat confusing. To me "update" can mean the same thing as "edit". So I suggest either we call it by its actual Wikipedia jargon name "purge", even though that word might be somewhat confusing, or we could call it "refresh" which I think for most computer users means exactly what it does. Of course, "purge" is shorter which is nice, so it's a tough choice. So whatever the rest of you guys prefer.
 * --David Göthberg (talk) 11:35, 21 February 2009 (UTC)
 * Okay, I think we can spare a little real estate for a few letters. [] is the revised diff with the suggested wording of "refresh".  Apparently I made a mistake the first time and broke the sandbox.  Now fixed (see the testcases page for confirmation).  Requesting administrator assistance, since it's been a while without significant objection.  You might want to substitute the purge template.  --Thinboy00's  sockpuppet  alternate account 23:21, 17 March 2009 (UTC)
 * Yes check.svg Done, but I did decide to go with a "purge" link label, mostly because that is the established description all over Wikipedia for purging/refreshing the squid cache. See e.g. WP:PURGE vs. WP:REFRESH. I'd expect that most editors who make changes to template documentations will have been around long enough to know the meaning of "purge", so I don't think it's going to be unclear. If anyone disagrees I'm of course open to discussion. :) Cheers, Amalthea  00:42, 18 March 2009 (UTC)
 * Yes check.svg Done, but I did decide to go with a "purge" link label, mostly because that is the established description all over Wikipedia for purging/refreshing the squid cache. See e.g. WP:PURGE vs. WP:REFRESH. I'd expect that most editors who make changes to template documentations will have been around long enough to know the meaning of "purge", so I don't think it's going to be unclear. If anyone disagrees I'm of course open to discussion. :) Cheers, Amalthea  00:42, 18 March 2009 (UTC)


 * Amalthea: You got some good points there, so [purge] seems to be the better choice.
 * I added a space between the [edit] and [purge] buttons, just as in Thinboy00's /sandbox example. I think it looks much better that way.
 * Thanks guys, the green /doc boxes have never been better!
 * --David Göthberg (talk) 01:18, 18 March 2009 (UTC)


 * Yep, I noticed, I should have just copy&pasted :) Thanks, Amalthea  01:20, 18 March 2009 (UTC)

Bug
I have a problem that seems to be traceable to this template. See User:Droll/bug for an example. Notice that an error message appears. If you look at User:Droll/bug/doc you will see no error message. See User:Droll/bug/test where the doc page is transcluded and no error message appears. It seems that the bug is specific to I hope this can be resolved. I have spent many hours trying to figure this out. Find other examples of similar but not necessarily identical problems at User:Droll/test and User:Droll/test1. -- droll  &#91;chat&#93;  08:33, 14 March 2009 (UTC)


 * So that no one makes the same mistake I made at first, I dont think its a problem with the template . I jumped to that conclusion right off and started a thread on the discussion page there. The editors I talked with don't think its a problem with that template. I tend to agree with them although it might be an interaction between the two templates although I don't understand how that could happen. The interesting thing is that sometimes is happens and sometimes it doesn't but the conditions under which it occurs are consistent. If your are interested, and the examples don't help, I'll go into more detail as to what conditions seem be related. -- droll  &#91;chat&#93;  09:46, 14 March 2009 (UTC)


 * For a total shock go to User:Droll/bug and uncomment the &lt;noinclude>&lt;/noinclude> at the top of the page, save the page and purge. You should see the transclution and the rendering by the documentation template. The error message will have disappeared. It gets better. Restore the comment at the top of the page and then look at the bottom of the page and uncomment, save and purge. Now the error will occur twice. Once in the Documentation version and once in the transcluded version. Please restore when done. This is mad house stuff. It probably means that the bug is at a lower level than this template. Maybe a metawiki bug. If I get a few people to agree I'll do the bugzilla thing unless someone with more influence wants to carry the ball. -- droll   &#91;chat&#93;  12:08, 14 March 2009 (UTC)


 * The error seems to start in, as you can see by following the transclusion tree below. Notice that after the redirect, the template uses parameters that are not defined and have no defaults (bolded). These are then passed on to equations, which fail because "{" is not a valid operand or operator. These errors are wrapped in &lt;span&gt; tags, which in turn cause other equations to fail because "&lt;" is not a valid operand or operator. Mayhem ensues.
 * 3,080.73 km2
 * REDIRECT → Template:Convert/LoffAoffSoff
 * 3,080.73 km2
 * REDIRECT → Template:Convert/LoffAoffSoff
 * REDIRECT → Template:Convert/LoffAoffSoff
 * REDIRECT → Template:Convert/LoffAoffSoff


 * The structure is so tortuous, I'm not at all surprised it has weird effects.
 * — {admin} Pathoschild 12:42:52, 14 March 2009 (UTC)

{unindent} -- droll  &#91;chat&#93;  19:34, 14 March 2009 (UTC)
 * 1) Why does this happen in the context of documentation pages and nowhere else?
 * 2) Should I go back to and shake that tree some more?
 * 3) Should I wait and see what else people here can do?
 * 4) Did anyone try the "uncomment trick" mentioned above and why should any of that happen.


 * Furthermore, when 's code is used directly (by pasting its code and manually inserting parameter values), the call works perfectly ([ example]). The erratic behaviour is probably due to quirks or caching in the parser. I don't think this is a problem with, which is relatively straightforward: if the page exists, transclude it. Convert is the right place to discuss this.
 * — {admin} Pathoschild 22:21:17, 14 March 2009 (UTC)


 * I wish to thank Jimp for his work in fixing this problem. Things are working smoothly. -- droll  &#91;chat&#93;  04:08, 19 March 2009 (UTC)

Request
Resolved

Currently there is no link to /testcases on the version which appears on the /sandbox. Could this be added? You are normally using the sandbox when testing things out, so it would be good to have the link there :) &mdash; Martin (MSGJ · talk) 20:43, 22 April 2009 (UTC)


 * Don't use the documentation in the /sandbox, since it makes it unclear which page you are on, since it makes the sandbox and the deployed template page look the same. That sometimes result in people mixing them up and doing experimental edits on the main template itself. Long debug sessions make people prone to such mistakes...
 * Instead use template sandbox notice in the sandbox. And that one gives you a link to /testcases, if that page exist.
 * And if you feel you must have to have the documentation in the sandbox, then add template sandbox notice too, to make it clear you are in the sandbox and to get the /testcases link.
 * --David Göthberg (talk) 01:34, 23 April 2009 (UTC)


 * Usually, sandboxes are synchronised to and from the actual template, and it is easier if both copies are the same. It takes extra care when you have to add or remove bits like template sandbox notice when synchronising. Therefore I think it might be a nice idea if this template could automatically that when on a sandbox page. &mdash; Martin (MSGJ · talk) 15:55, 10 January 2010 (UTC)


 * Ah, good idea. Just to clarify: I assume you mean we should make the documentation template automatically display template sandbox notice above itself when on a /sandbox page. And yes, that is easy to add, and I agree we should add that.
 * However, I still recommend that people only copy and paste the part from the &lt;noinclude> tag and up when they copy between the template and its /sandbox page. And that is why we recommend at Template documentation to leave an empty line between the &lt;noinclude> tag and the documentation template, since that empty line makes the copying and pasting easier and makes it clearer which part is template code and which is noinclude stuff.
 * --David Göthberg (talk) 09:09, 12 January 2010 (UTC)


 * Partly done. This template now adds template sandbox notice above itself when on a /sandbox page. But I don't think that is enough, since when working in the edit window the sandbox notice is not visible, so it is still easy to mix up the template page itself and the /sandbox page. So I tested to change the border of the green doc box when on sandbox pages, but that looked weird and wasn't very clear. So instead I tried to add the also below the green doc box, and that looks good and is also convenient since then we get the link to the /testcases page easily accessible. I am currently displaying that in documentation/sandbox. I would like to deploy that.
 * --David Göthberg (talk) 14:37, 19 January 2010 (UTC)


 * Yes, that looks fine to me. I'm not sure why you are so worried about people forgetting which template they are on ... perhaps this happens to you, but I can't remember it ever happening to me! (And it does have /sandbox in big letters at the top.) Anyway your proposed idea looks good. &mdash; Martin (MSGJ · talk) 20:21, 19 January 2010 (UTC)


 * Sometimes I edit sandboxes in cooperation with other editors, and some of those editors want to have the doc as reference in the sandbox. And yes, then I often mix up which page I am editing. (I usually have the main template's code open in another tab, for comparison.) I almost always discover my mistake before saving, but it is very annoying. I see other editors do the mistake every now and then (they mention they did the mistake), and they have often even saved their test edits, so it seems to be an even worse problem for them than for me.
 * A bigger problem is that I have an old slow computer, so loading the preview is much slower if a long documentation is on the /sandbox page. And having a long doc box means a lot of scrolling between the edit window at the bottom of the page and the template preview at the top of the page, while doing the coding.
 * Nowadays I often instead create my own subpage named /test1 where I do my editing. And that also has the benefit that others don't edit my code while I display it as a suggestion.
 * Anyway, displaying the both above and below the green doc box looks a bit odd, so I just have a weak preference for having it at both places. So I think we should wait for some more comments before we deploy that, since it might annoy some editors.
 * --David Göthberg (talk) 22:47, 19 January 2010 (UTC)


 * I have thought more about this. It is enough to have the above the green /doc box. It kind of looks silly to also have it below. So I withdraw that idea. So I think this is now fully resolved.
 * --David Göthberg (talk) 14:50, 28 January 2010 (UTC)