Template talk:Documentation/Archive 5#Documentation/links

I have now added code to this template so it automatically adds {{tl|pp-template}} to templates that are protected. It only adds the protection template when in the "Template:" namespace.

This means we no longer need to manually add and remove {{tl|pp-template}} when we protect or unprotect templates.

Until we have removed all manually added cases of {{tl|pp-template}} it means the template is executed twice on such templates, but that causes no problems. If we want to speed up the removal of all such cases I can make it so the manually added cases add themselves to a maintenance category, but I think there's no hurry to do that. And I want to wait a while to see if anyone has any objections to this auto-adding before we go around cleaning away the manual cases.

I have previously discussed this at the following places: Template talk:Pp-template#Merge and automate and Wikipedia talk:Protection policy‎#Template protection.

--David Göthberg (talk) 07:12, 3 January 2010 (UTC)

:That's a nice idea. But is it just me, or has that edit introduced an additional line space in the output? — Martin (MSGJ · talk) 08:03, 3 January 2010 (UTC)

::{{fixed}} — Martin (MSGJ · talk) 08:04, 3 January 2010 (UTC)

:::Yes, the way I placed that leading comment could cause an extra line break in some cases. But I didn't bother about that since I don't mind that. And I didn't get any extra line break on the templates I tested it on. But I see you fixed it.

:::--David Göthberg (talk) 08:16, 3 January 2010 (UTC)

If there is a /sandbox or a /testcases subpage this template shows links to them. Depending on which of them exist it shows one of these messages:

:This template has a sandbox (edit) for editors to experiment.

:This template has testcases (edit) for editors to experiment.

:This template has a sandbox (edit) and testcases (edit) for editors to experiment.

But this template doesn't show anything if those pages have not already been created. This means that only experienced template programmers know those pages can be created and what their proper naming is. And that is a bad thing, since sandboxes and testcases should be used more.

So I would like to always advertise them, even if they have not yet been created. I would like to change it to always look like one of the below messages. Note the slight difference if the pages exist or not:

:Editors can experiment in this template's sandbox (create) and testcases (create) pages.

:Editors can experiment in this template's sandbox (edit) and testcases (edit) pages.

--David Göthberg (talk) 04:22, 26 January 2010 (UTC)

:I support this. I also have another suggestion. Quite a few of the more complicated templates have a /core subtemplate. A link to this (if it exists) might be very convenient for myself and other template coders. — Martin (MSGJ · talk) 08:40, 26 January 2010 (UTC)

::I usually link to the /core sub-template and other such sub-templates from the "Technical details" section of the documentation in the templates. That means I can also explain what the sub-templates do. See for instance {{tl|script doc auto}} or {{tl|ambox}}.

::I minor issue is the cases where a template used to use a /core template but then has been updated to not use it anymore. Then an automatic link to the old /core could be confusing. For instance {{tl|navbox}} doesn't use its {{tl|navbox/core}} anymore. While other templates have more descriptive names of their sub-templates. So if we add automatic links to /core then we should also provide a parameter like "core link = off". And perhaps even some parameters like "subtemp1 = /numbered" and "subtemp2 = /blacklist".

:::This template internally uses {{tl|navbox/core}}.

:::This template internally uses {{tl|cat handler/numbered}} and {{tl|cat handler/blacklist}}.

::I like to make things automatic, but I am not sure if I like such links at the top of the green /doc box. I'll have to think a bit more about this.

::--David Göthberg (talk) 11:54, 26 January 2010 (UTC)

:::I would support create links. I think the core templates etc. will add a bit too much mess to the documentation page. I'm also wondering if we shouldn't move the sandbox/testcases link to a less obvious spot. So that we have user information before editor information of templates.... —TheDJ (talk • contribs) 12:51, 26 January 2010 (UTC)

::::TheDJ: Ah, that might be a good idea. We could move the two lines of "template editor stuff" to the bottom. I'll test some variants later tonight and see if I can come up with something that looks good.

::::--David Göthberg (talk) 18:11, 26 January 2010 (UTC)

::::I have done some coding and testing of having the links at the bottom of the documentation instead. The best seems to be to use a separate green box below the big green box, and then show the links in that box. I am currently showing how that could look in {{tl|documentation/test1}}.

::::I am not sure if I prefer that over the current approach of having the links at the top of the doc box. I'll have to look at it for some days to get used to it and then see what I think. Does anyone have any points of view on this?

::::--David Göthberg (talk) 15:05, 28 January 2010 (UTC)

::::I added "preload text" to the "sandbox (create) and testcases (create)" links. Click those links in {{tl|documentation/test1}} to see the preload. The create links give slightly silly page names when demonstrated here, but that's because those links are normally not shown when in a sandbox so the code lacks logic for that. (But the demo code I use here do show so we can see these examples in this sandbox.)

::::And I think I now slightly prefer this new approach with the links in a separate box below the big doc box.

::::--David Göthberg (talk) 06:56, 4 February 2010 (UTC)

:::::Looks good. Any chance we can use CSS to give editors a choice to opt-in to having these at the top as well? One main use of these links is to save time, but now I'm going to be scrolling to the bottom of templates all the time to get to the links. — Martin (MSGJ · talk) 08:52, 4 February 2010 (UTC)

:Looks awesome; and I don't have a problem with the links being moved to the bottom (I expected that I would, but actually I like it a lot!). Happy‑melon 23:12, 4 February 2010 (UTC)

::MSGJ: Using CSS for it would not be a good solution. Instead you could use javascript to move or copy the links back up to their old position, if we place them at the bottom. I can perhaps add some <span> tags with CSS ids in the code at the right places so such a javascript can be short and efficient.

::Everyone: I looked around how some other Wikimedia projects use documentation. The German Wikipedia also places the doc links at the bottom. They use a thick horizontal ruler between the documentation text and the doc links, but I think it is clearer to use a separate box for the links.

::MSGJ: The German Wikipedia has an interesting thing in their links section: They have a link to Special:PrefixIndex, to make it easy to check what sub-pages a template has. That's more flexible than just recognising sub-templates named "/core".

::--David Göthberg (talk) 00:32, 6 February 2010 (UTC)

:::I have now finished the code in {{tl|documentation/test1}} and {{tl|documentation/core}}. It has passed all my tests and as far as I can see it is ready to deploy.

:::--David Göthberg (talk) 00:32, 6 February 2010 (UTC)

:MSGJ: Special for you, here's javascript that moves the box with the doc links to above the main doc box:

// Move the documentation links above the doc box.

addOnloadHook(function() {

var docbox = document.getElementById( "template-documentation" );

var metabox = document.getElementById( "documentation-meta-data" );

if ( docbox && metabox ) {

metabox.style.marginTop = "1em";

docbox.style.marginTop = "0";

docbox.parentNode.insertBefore( metabox, docbox );

}

});

:Take a look at {{tl|documentation/test1}} or {{tl|documentation/core}}. Then add the above code to your personal /monobook.js, then wait one minute for the servers to update, then bypass your browser cache. Then reload {{tl|documentation/test1}} or {{tl|documentation/core}} and see the difference.

:--David Göthberg (talk) 03:22, 6 February 2010 (UTC)

::{{tick|18}} {{ucfirst:Done}} - I have now deployed the new version. (I announced this discussion in several places some days ago.)

::The doc links are now in a box below the main doc box. It links /sandbox and /testcases also when they don't exist, with (create) links with preload. It uses the new {{tl|documentation/core}} sub-template instead of multiple calls to {{tl|documentation/docname}} and {{tl|documentation/links}}. And it can't anyway use {{tlf|documentation/links}} anymore since that sub-template is also used by {{tl|category interwiki}} which probably should show the /sandbox and /testcases links the old way.

::--David Göthberg (talk) 04:30, 6 February 2010 (UTC)

:::It seems that when the documentation subpage effectively starts with a header, the header isn't formatted properly and its wikicode (like == Usage ==) is displayed instead. See Template:Contains Tifinagh text. Svick (talk) 04:46, 6 February 2010 (UTC)

::::17px Doing... Ah, that must be related to how MediaWiki interprets wikimarkup at the beginning of lines inside parserFunctions. See bugzilla:12974. I have some ideas how to fix that, I'll test that right away.

::::--David Göthberg (talk) 05:21, 6 February 2010 (UTC)

::::18px Fixed - Thanks for the bug report Svick. I have now tested several ways to fix it, some of them worked more or less well. I opted to use a line break before the if-case that inserts the /doc page or "content" text. That causes no extra newlines even if the /doc page has extra newlines at its start. That is the same solution that this template used up until I edited it today. I see that PEJL and Patrick were aware of this problem and fixed it back in 3-6 November 2007. (There are some other bugs that have been added and fixed several times in this template too.) I left a comment in the code so that this bug hopefully will not be re-added in the future.

::::--David Göthberg (talk) 07:12, 6 February 2010 (UTC)

:::::I like it. Good work David ! —TheDJ (talk • contribs) 13:11, 7 February 2010 (UTC)

A few comments about the new box:

• Generally I like the new look and I agree that the technical editor-related info should be at the bottom.
• However, it looks a little strange when there is not yet a documentation page because you have two very short boxes. Perhaps some different behaviour for a non-existent /doc page, with just one box, could be looked at in future.
• I would like to add the advice somewhere that categories and interwikis should be added to the /doc page rather than the template. Perhaps it is even possible to add an anchor so that the includeonly section can be edited directly from a link.
• It should be noted that this template is used by some other templates in a non-standard way. For example Template:Asbox/templatepage and Template:Flag template documentation both use this template to display some standard documentation as well as transcluding the /doc page for categories and interwikis. I need to check these properly, but I fear the changes were detrimental. The latter uses the {{para|1}} option which prevented a link to the /doc page at the top; however it does not prevent the extra box at the bottom. I think we might need some extra customisability for the small box to allow these templates to work properly.
• With the technical info now at the bottom, the argument against including extra links to subtemplates (e.g. /core) because of clutter is now rather weaker, and I propose again that we consider adding some other useful links here.
• Thanks for the javascript. I haven't yet tried it out, but will do shortly.

— Martin (MSGJ · talk) 19:57, 9 February 2010 (UTC)

:1: Thanks.

:2: Well, a documentation box usually should not go empty for long, so I don't think it matters if there are two small boxes while waiting for the documentation to be filled in.

:3: Hehe, I already yesterday added the text "Add categories and interwikis to the /doc subpage" to my sandbox version: {{tl|documentation/test1}}. I have made it so that text doesn't show in the cases when it often makes no sense, like when the "content" parameter has been fed, or when parameter 1 has been fed since then the doc page is often somewhere else or shared between several templates. Having an anchor that points to a place in the edit window is unfortunately not possible.

:4: Thanks for the pointer to those templates. I do have some code in {{tl|documentation}} to handle such situations. The small box below doesn't show in a number of circumstances, and it doesn't show all its items at all times.

:4b: I had a look at {{tl|asbox/templatepage}}, there this template does exactly what it should. {{tlf|asbox/templatepage}} feeds the "content" parameter and it has no /doc page, and then the doc box shows no [edit][purge] or [create] links in the upper right corner and no /doc links in the small box below. But it still is a template in template space, so the small box below shows with links to the /sandbox and /testcases.

:4c: I also had a look at {{tl|flag template documentation}}. Its own documentation is quite normal, and works fine. But that template creates documentation for the flag templates, and that is a tricky case. And there we do have a problem. (That explains some weird code that the old version of {{tl|documentation}} had, it was to handle that case!) But I know how to fix it. They feed the "content" parameter, but some flag templates like {{tl|FRA}} have a /doc page with interwikis. Currently {{tlf|documentation}} then shows the /doc link in the box below, but they have fed an empty but defined "1=", which used to suppress that (and I will perhaps make it so again, or use the better option that I'll explain next). But now we have the added thing that when in User or Template space this template always shows the links to the /sandbox and /testcases, with (create) links if they don't exist. But for the flag templates those /sandbox and /testcases links are probably silly. There's no good way I can autodetect when not to show them, so I guess I will have to add a new parameter named "link box = off" that will turn off the box below. By the way, is "link box" a good name for that box below?

:5: Agreed, now that the meta-data is at the bottom we can add some more stuff there. But different templates name their sub-templates differently. So I want to do like the German Wikipedia does, have a link that says "Subpages of this template" that uses Special:PrefixIndex to list all subpages of the template. I have already implemented that too in my sandbox version: {{tl|documentation/test1}}.

:6: Hehe. I still often scroll to the top to click the /sandbox link, and then have to scroll down again. I guess it will take a week or so to re-learn where the links are. :))

:7: I have more stuff in the works, but I'll write about that in a new section on this talkpage.

:--David Göthberg (talk) 22:39, 9 February 2010 (UTC)

::4c: I investigated {{tl|flag template documentation}} more. Feeding an empty but defined parameter 1 to the old version of {{tl|documentation}} suppressed the /doc links. But from what I can see in the old code of {{tlf|documentation}} it seems to have been more a bug than a feature, or at least a very unclean implementation. So instead I added the more useful "link box=off" parameter to {{tlf|documentation}}. I have updated {{tlf|flag template documentation}} to use "link box=off" so now {{tl|FRA}} looks fine again.

::Which parameter naming do you guys prefer: "link box=off" or "link box=hide" ?

::--David Göthberg (talk) 00:37, 10 February 2010 (UTC)

:::{{tick|18}} {{ucfirst:Done}} - Added the text "Add categories and interwikis to the /doc subpage". It has some logic that only makes it show when relevant. And added the "Subpages of this template" link. And I made it so the [create] links for the /doc subpage instead use Template:Documentation/preload-filespace when in File space.

:::--David Göthberg (talk) 23:59, 11 February 2010 (UTC)

::::No preference between {{para|link box|off}} and {{para|link box|hide}}. But it might be nice to be able to customise the "link box" a little more. Perhaps the link box parameter could be used to actually specify the content of the box. This would be handy for the templates mentioned above. For example, the stub template documentation could say "Part of the above documentation is transcluded from Template:Stub documentation." There are other templates which could use this feature as well - I will be looking at converting Template:Country showdata to use this template shortly. — Martin (MSGJ · talk) 20:35, 16 February 2010 (UTC)

:Oh, good idea, that would be useful. The most generic and flexible would be this:

:* link box = 'not defined' or 'empty string' = Shows as usual

:* link box = off = No linkbox

:* link box = Any other text = The other text is shown instead of the usual link box content. The link box automatically makes the text italic since the whole link box is set to italic style.

:I don't think we need to supply some ready made versions of the other text, since as far as I understand such other text is only fed directly by some specialised templates, so it is better that they themselves feed the full text they want in the link box.

:MSGJ: I assume that is what you meant, I just like to make it clear before we add it to the code and documentation.

:--David Göthberg (talk) 15:53, 17 February 2010 (UTC)

::Yes, you have understood correctly. That is exactly what I am asking for. — Martin (MSGJ · talk) 16:47, 17 February 2010 (UTC)

:::Let's wait one day before we make the "link box" parameter more versatile, so the other editors here have a chance to comment.

:::I took the liberty of splitting the rest of your comment into a new section below, since I think that part will cause some discussion. (I hope you don't mind?)

:::--David Göthberg (talk) 19:40, 17 February 2010 (UTC)

::::I have now added this code and will update the documentation shortly. — Martin (MSGJ · talk) 17:00, 19 February 2010 (UTC)

:This section was split of from the above section. --David Göthberg (talk) 19:40, 17 February 2010 (UTC)

By the way, when this box is fully customisable, would it be a good idea to deprecate the {{para|1}} parameter? Unnamed parameters are less clear, and it wouldn't be necessary anymore I think. — Martin (MSGJ · talk) 16:47, 17 February 2010 (UTC)

:Everyone: The "fully customisable" refers to that we plan to extend the "link box" parameter, see discussion above.

:MSGJ: I don't know exactly what you mean by "deprecate" since Wikipedians misuse that word too often. The "1=" parameter is used (abused) a lot, so we can't remove it for the time being. But I think we should deprecate it in the correct sense of the word: Leave the function, but update the documentation to strongly advice against its usage and perhaps even mention that we might remove it some day.

:I assume you already know the reasons why feeding another /doc page is so bad. But since I know it has some defenders, for anyone else reading this: If only using the /doc page for one template, then having it under a different name is just silly. And if sharing the same /doc page for several templates it wreaks havoc with the categories and interwiki links. Remember, the interwiki links are often added by users from other language editions of Wikipedia who often doesn't use the /doc system, and those users often don't understand English code comments. And we have bots handling interwiki links...

:And it is hard to write the documentation in a way that makes sense when reading it on the different templates. And other users updating the documentation often fail to understand that it is used on several templates.

:Instead, we already have much better solutions:

:* Use a /doc page for each template, but make most of them "soft redirects" to the main template where the full documentation is placed. See {{tl|wrap}} for an example.

:* If several templates share some part of the documentation text, then put that text in a separate template and transclude it onto the /doc page of each template. See {{tl|mbox templates see also}} for an example.

:* If the templates are part of a whole system, then write a how-to guide in "Wikipedia:" space about it, and link to that how-to guide from all the templates in that group. See Wikipedia:Line break handling for an example.

:--David Göthberg (talk) 19:40, 17 February 2010 (UTC)

::Think I was getting confused. For some reason I was thinking only about the "This documentation is transcluded from ..." line rather than the main use of this parameter. This is widely used, and can be very useful I think, so we probably shouldn't try to stop people doing this. I see what you mean about the category and interwiki links. Perhaps there is some way of transcluding both a centralised documentation and a /doc page for interwiki links? Have a look at how Template:Yes2 handles this currently; we might be automate something like this. — Martin (MSGJ · talk) 20:56, 18 February 2010 (UTC)

:::I took a look at {{tl|yes2}}. That's exactly how not to do it. I clicked the [edit] button and landed on Template:Table cell templates that has a category and some interwikis, it took me a while to realize those are not the interwikis for {{tl|yes2}}. When going around fixing interwikis we don't look at the top of the page where the pagename is, instead we look at the bottom of the page to find the interwikis, thus it is all to easy to miss that the /doc page isn't a regular /doc page.

:::How is a user from some other Wikipedia going to find what page holds the interwikis for that template? It is even tricky for our local editors (who hopefully know about /doc pages) to find where the interwikis for {{tl|yes2}} are placed.

:::Also, there is nothing in the doc text that mentions it is a shared doc page. I could very well have gone ahead and "corrected" the first sentence "These templates are designed" to "This template is designed". I have often seen people doing such corrections on such shared doc pages. So it is not just about the categories and interwikis, it is also confusing to show the same doc text on different templates. Humans write and read text in a context, and what template one is currently looking at is such a context. It is hard to write a doc text that works on several templates, and it is confusing to read a doc text that is not written specifically for the template one is currently looking at. For instance, the doc says that {{tl|yes}} has green background. But when reading that from {{tl|yes2}} (light green) or {{tl|Yes-No}} (yellow) it is confusing, since they are not green. It sounds like "yes" is perhaps a redirect to the other names, so one might not realise that {{tl|yes}} is an entirely different template.

:::So really, that template group should use the methods I described above.

:::--David Göthberg (talk) 01:24, 19 February 2010 (UTC)

::::Okay, this seems to be a pet hate of yours, but in this particular case with the {{tl|yes}} templates and co. I think I agree that it's simpler just to transclude /doc. I have now added Template:Table cell templates to each of the doc pages and removed the unnamed parameter from the call to this template. — Martin (MSGJ · talk) 16:38, 19 February 2010 (UTC)

:::::Haha, yeah it is something that has annoyed me a lot over the years. I looked at what you've done there now, and yeah, that is a fairly good solution. Although I think soft redirects to the shared documentation is clearer.

:::::To respond to your comment further up: The German Wikipedia has the categories and interwikis on a separate subpage called /meta, and only have the doc text on the /doc subpage. Thus they can feed shared documentation from another page without first creating the local subpages, since their "add cats and interwikis" button always go to the local /meta subpage. But as you know I prefer soft redirects, and having /meta pages means having yet another bunch of subpages.

:::::--David Göthberg (talk) 07:45, 20 February 2010 (UTC)

I am planning to add some fairly complex namespace handling in {{tl|documentation}}. It is probably uncontroversial, but I'd like to explain anyway. (And so future editors of this template have a chance to understand the code.)

While coding the new version of {{tl|documentation}} I noticed that there were some code in it that hinted that this template sometimes is used on talkpages. So I spent a whole night checking lots of usage cases to see how this template is used. Here's my conclusions:

• In some cases the {{tl|documentation}} template needs to be on the talkpage:
• For preload pages (usually in Template or Wikipedia space), since they can't use <noinclude>. See for instance Template talk:AfC preload and Template talk:RfD subpage starter. And those pages are even marked with a special template {{tl|talkdoc}}.
• This is no longer true and {{tl|talkdoc}} is now being deleted. Dpleibovitz (talk) 22:09, 23 November 2013 (UTC)
• In MediaWiki space, since <noinclude> often doesn't work in system messages.

• The /doc, /sandbox and /testcases pages should normally be in subject space, except in the namespaces that don't have the MediaWiki subpage feature enabled: Main, File, MediaWiki and Category. (But currently we only show the /sandbox and /testcases links in User, User talk, Template and Template talk space.) There are also a whole bunch of other technical reasons why the /doc page must be stored under the talkpage for those namespaces.

This means that in some cases the {{tl|documentation}} template is on the talkpage while the /doc page is under the subject page, and in some cases it is the opposite. So I am planning to update this template so it automatically links to the right place.

Of course, we don't have actual usage cases in all those namespaces, but we have it in some of them so we anyway need to handle it.

For protected images it makes sense to add {{tl|documentation}} and use an unprotected /doc page, so anyone can update the image description, add links to other versions of the image, and add categories. In fact, that's the very reason why we started to use /doc pages for templates, so normal users can edit the documentation of protected templates. For images the /doc page has to be under the talkpage since File space doesn't have the subpage feature, and since we have tools that would warn and list those /doc pages as "file pages without an image". By the way, in file space the traditional first heading is named "Summary", so the green doc box should have that heading instead of "Documentation" when in file space. See my example of how this can look and work over at :File:Ambox style.png.

--David Göthberg (talk) 01:58, 10 February 2010 (UTC)

:{{tick|18}} {{ucfirst:Done}} - And seems to work fine.

:I will add some debug code to the template so it reports strange usage to :Category:Wikipedia pages with strange ((documentation)) usage to see what kind of usage is out there and to check that the new version doesn't cause problems with old faulty usage.

:--David Göthberg (talk) 20:08, 11 February 2010 (UTC)

::See discussion at Wikipedia talk:Template documentation#File pages about using {{tl|documentation}} on protected image pages.

::--David Göthberg (talk) 19:53, 12 February 2010 (UTC)