Template talk:Documentation

From WikiProjectMed
(Redirected from Module talk:Documentation)
Jump to navigation Jump to search
WikiProject Templates  
WikiProject iconThis template (like all templates) is within the scope of WikiProject Templates, a group dedicated to improving the maintenance of Wikipedia's templates. This particular template is especially important to the project because it is used in the maintenance of other templates. If you would like to participate, please visit the project page, where you can join the discussion and see a list of open tasks.
 

Purge button for just-created documentation

When this template has been added to a page but there appears to be no subpage, the only button displayed is [create]. Often in this situation, the subpage actually does exist but the template page just needs to be purged, so it'd be nice if the purge button was displayed, just as it is when the documentation has been found. {{u|Sdkb}}talk 00:17, 11 February 2021 (UTC)

Mr. Stradivarius, I'm not overly comfortable with Lua. As you seem to be the primary editor of the module, could you help implement this? {{u|Sdkb}}talk 23:06, 11 October 2021 (UTC)
Code-wise this should be enough: Special:Diff/1035088965/1049459408. See also the new test failure of testRenderStartBoxLinksDoesntExist at Module talk:Documentation/testcases.
Is there a consensus for such a change? —⁠andrybak (talk) 23:35, 11 October 2021 (UTC)
@Andrybak, there's WP:SILENT consensus, given that it's not too huge a change. I'll be happy to make it myself if we're confident the technical aspect is sound. I haven't seen that test failure thing before—does that indicate that the technical aspect of the change is sound? {{u|Sdkb}}talk 02:24, 12 October 2021 (UTC)
Sdkb, sorry, I wasn't clear. The test failure is expected – the new sandbox version is outputting the new link, for which a testcase update would be needed.
The change in the output is also visible on the page Template:Documentation/testcases: for Template:Documentation/testcases/nodoc (second box above Template:Documentation/testcases#Notest), the sandbox output has the [purge] link, while the live template (for the same "nodoc" subpage) does not. —⁠andrybak (talk) 03:26, 12 October 2021 (UTC)
As for consensus for this, I don't mind either way. This use case is rare (editors could use Preferences → Gadgets → Appearance → check Add a "Purge" option to the top of the page [...] with keyboard shortcut for purging), but the cost is negligible. —⁠andrybak (talk) 03:32, 12 October 2021 (UTC)
Okay, implemented; thanks for the help! {{u|Sdkb}}talk 04:09, 12 October 2021 (UTC)

Allow pass-thru params destined for the doc template

Tl;dr: Please modify Module:Documentation to allow addition of pass-thru params destined for a named template.

What I'm looking for, is to allow something like this:

  • {{Documentation|Template:Welcome-foreign/doc|lang=es}}     # |lang=es to be passed through to the /doc page

so that the template doc page is transcluded with the passed parameter(s) given. I.e., in this example, passing through the |lang=es param, and effectively doing this:

The reason for this, is to allow a single /doc template to provide variable output, especially in the case of a tesselation of similar templates that may make more sense using a single, common /doc page, instead of a set of highly similar ones.

Background and use case

Members of the WP:Welcoming committee welcome new users by placing a friendly message on a new user's talk page. Several dozen welcome templates are available for this purpose, including about twenty aimed at users with poor English who appear to speak another language. For example, we have Template:welcomeen-zh for users who appear to speak Chinese, Template:welcommen-pt for Portuguese speakers, and so on (view complete list here). Most of these templates have their own /doc page, such as Template:welcomeen-zh/doc, Template:welcommen-pt/doc (some have very brief doc <noinclude>d right on the template page). These doc pages are mostly highly similar; for example, this diff: (compare Chinese /doc::Portuguese /doc), with the differences mostly constrained to the language name itself.

We recently consolidated these twenty similar templates into one, called {{welcome-foreign}}, with /doc page {{welcome-foreign/doc}}. The twenty or so legacy templates have been turned into wrappers (e.g., {{welcomeen-zh}}, {{welcomeen-pt}}). One downside of the consolidation, is that the consolidated /doc page no longer refers specifically to the language name, in the case of someone using one of the wrappers. That is, all the wrapper /doc pages now render exactly the same, regardless whether you're coming in from Chinese, Portuguese, or any other language wrapper. That is a loss of function from what the legacy templates provided.

Proposal and param handling

It seems like this problem could be remedied, by allowing the {{Documentation}} module to support pass-thru params. I can foresee a technical issue in possible confusion/collision of params, i.e., what if the template in question has a param called |heading= or |content= and so on. I see several possible solutions:

  • disallow the four params already used by {{Documentation}} – not ideal, but probably okay for almost all templates
  • disallow positional params – acceptable; in the case of {{welcome-foreign}}, positional param |1= is already aliased by named param |lang=; any template that wanted to take advantage of the new feature could simply add named aliases where needed.
  • specify a conventional param naming adjustment, e.g. add a prefix token, like, say, underscore, or passthru_, so that:
    • coding {{Documentation|Template:Welcome-foreign/doc|passthru_fr}} would invoke: {{Welcome-foreign/doc|fr}}, or:
    • coding {{Documentation|Template:Welcome-foreign/doc|passthru_lang=de}} would invoke: {{Welcome-foreign/doc|lang=de}}, or simply:
    • coding {{Documentation|Template:Welcome-foreign/doc|heading=Doc page title|_heading=foo}} would invoke: {{Welcome-foreign/doc|heading=foo}}.

Justification

Template doc subpages are in the template space, and it seems somewhat artificial to cripple the utility of a doc page by not allowing it to use parser functions that might increase its usefulness, provide a better user experience (in this case, by including the correct language name), and ease the workload of template writers by having one /doc page to maintain, instead of twenty or more, every time something changes.

Template {{Welcome-foreign/doc}} currently contains a bit of code to substitute in the language name corresponding to the passed lang code, but it never gets invoked, because the code isn't passed to the /doc page by the {{Documentation}} module. (Only one of the legacy wrappers passes the code; see testing note.)

Testing note

One of the legacy templates, namely the Spanish one, {{welcomeen-es}} has been coded to pass thru the |es= parameter to the /doc page as positional param 1 (coded as: {{ {{{|safesubst:}}}welcome-foreign|es}}). It's when I noticed that this wasn't working, that I followed the breadcrumbs and ended up here. I've cloned this to {{welcomeen-es/sandbox}} specifically for anyone who wants to take this on, and needs something to test with. Note that I've changed the positional param |(1=)esto named param |lang=es in the sandbox version, because I presume that will be technically easier for the module to process, but feel free to change the sandbox version to whatever you like, to facilitate testing.

These templates are substed. It's not clear to me whether that plays a role in any of this.

One other possible wrinkle: all of the legacy templates (the wrappers) are included in the Twinkle installation, and are being used there. I'm unfamiliar with technical details of Twinkle, so just thought I'd mention it, in case it's relevant.

Summary

Thanks for reading this far; I tried to make this as clear as possible, sorry it is rather long. If {{Documentation}} could be modified to handle pass-through params, I think it could be useful beyond just this one situation. Thanks! Mathglot (talk) 21:41, 4 June 2021 (UTC)

 Not done for now: please establish a consensus for this alteration before using the {{edit template-protected}} template. Addition of arbitrary parameters to the module is probably not in the cards. You can maybe sell me on passthrough special-named parameters as in the 3rd bullet. However, probably the easiest way to do all this is simply {{documentation|content={{Welcome-foreign/doc|lang=es}}}} and then add some custom {{navbar}} to the specific doc page. Have you tried that? Izno (talk) 01:21, 5 June 2021 (UTC)
@Izno:, thanks for your response. That's an interesting idea, I'll look into that. Maybe a custom navbar can replicate the background color and other features of the {{Documentation}} template, so that's a good suggestion. Thanks again. Mathglot (talk) 22:06, 6 June 2021 (UTC)
@Mathglot: in addition to what Izno has described, another approach is what Template:Barnstar documentation does. You could create a separate template (e.g. Template:Welcome-foreign documentation) with its own parameters which contains the transclusion of {{Documentation}}. —⁠andrybak (talk) 14:21, 7 June 2021 (UTC)
@⁠Andrybak:, thank you, that's another good idea! I feel a bit sheepish that I didn't think of either one of these, before starting this discussion section, and I appreciate Izno's feedback and yours. I wonder if adding a "how-to" section to the /doc page of {{Documentation}} describing both of these ideas briefly might be of benefit to others who fall into this situation in the future? They are both really useful ideas, and may help speed a solution as well as reduce further questions like this one after this section gets archived. Mathglot (talk) 17:59, 7 June 2021 (UTC)
Ping correction: User:andrybak Mathglot (talk) 18:06, 7 June 2021 (UTC)
The use is (almost) described at #Usage in this template's documentation at the last item. It probably just needs a "if you realllly need it, you can call the specific doc's content via template in |content= as well as list it in the first parameter".
I do think that template documentation should shoot to describe the most common cases first (or only), so I'm not totally certain it needs to be present in the guidelines from that perspective.
As for pass-through template documentation, I'm not a fan. Trying to find cases where this template are used becomes quite difficult. Izno (talk) 18:17, 7 June 2021 (UTC)
I agree (most common first/only); this is admittedly an edge case. What I sometimes do in that case, is add a brief explanatory note, so the regular flow of the documentation narrative is not interrupted by verbiage from the edge case, but the detail is available (in small font, at the bottom somewhere) for those who are interested enough to click down and read it. Might work here. Mathglot (talk) 02:56, 8 June 2021 (UTC)
Go for it. Izno (talk) 03:22, 9 June 2021 (UTC)

Proposal: Don't display in certain namespaces

Occasionally editors accidently use this template in the Article namespace, often because they simply copy the raw template code instead of invoking it. This generates a ugly empty green box which has no value. As I can't see a reasonable use for having a working {{documentation}} inside article namespace I would like to propose that the templates code be changed to suppress displaying inside the Article namespace. -- Asartea Talk | Contribs 17:31, 26 June 2021 (UTC)

This was mentioned on Discord and we found several cases where this occurred in the mainspace. I think the template shouldn't display at all in the mainspace, but rather place the page in Category:Pages with templates in the wrong namespace which should serve to making other related issues spotted more quickly as well. --Trialpears (talk) 17:42, 26 June 2021 (UTC)
I'd support this. A namespace detection wrapper is trivial to implement, and as Trialpears says we can then add a category to track them. There is absolutely no reason to display {{documentation}} in mainspace. firefly ( t · c ) 07:59, 30 June 2021 (UTC)

I've sandboxed a version that hides any transclusions in mainspace and instead adds Pages with templates in the wrong namespace. Would like to get a second opinion on implementation given localization concerns and such though (especially since the module has code indirectly dealing with doc pages for articles). Otherwise I will implement it in a week anyway. --Trialpears (talk) 11:20, 8 July 2021 (UTC)

Prefill TemplateData

 You are invited to join the discussion at Wikipedia talk:Template documentation § Including TemplateData. I suggest there that TemplateData should be included in the documentation prefill content. SWinxy (talk) 06:12, 23 November 2021 (UTC)