View source for Template talk:Script doc auto

== About ((script doc auto)) ==

For the discussion that lead to the creation of this template see [[MediaWiki talk:Clearyourcache#Script documentation]].

1: I have done some more thinking and I think we can let this template do its detection in all namespaces. For the .css and .js pages in MediaWiki space we usually don't have a doc page. But if people start to add doc pages there then it would be convenient to have this template link to them too. (Well, we should not add doc pages in MediaWiki space for performance reasons, but redirects to doc pages are probably okay there.)

2: A possible extension of this template would be to detect if for instance a .js page has an accompanying .css page. Then it could output something like this:

{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|45x40px]]
| style = background: #ecfcf4;
| text  = 
This script seems to have a documentation page at [[User:Davidgothberg/clock]] and an accompanying .css page at [[User:Davidgothberg/clock|User:Davidgothberg/clock.css]].
}}

And when there is no doc page but only an accompanying .css page:

{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|45x40px]]
| style = background: #ecfcf4;
| text  = 
This script seems to have an accompanying .css page at [[User:Davidgothberg/clock|User:Davidgothberg/clock.css]].
}}

A funny but useful effect would be that [[MediaWiki:Common.css]] and [[MediaWiki:Common.js]] would then automatically link to each other. If we don't want that then we can of course modify this behaviour in the MediaWiki space.

3: We could show the editnotice of a script, above the script. But we should probably only do that for MediaWiki space. See for instance [[MediaWiki:Common.css]] and its editnotice [[Template:Editnotices/Page/MediaWiki:Common.css]]. For all other spaces we should probably just link to the documentation for the script. Otherwise people might start to use the editnotice as the documentation page for the script, which would be weird.

--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 13:41, 14 December 2009 (UTC)

: Looks good! Concerning {{diff|MediaWiki talk:Clearyourcache|331619878|331179950|your last remarks}} at [[MediaWiki talk:Clearyourcache]], and without having looked at the template source, some incoherent thoughts:
:* Only pages in User and MediaWiki space handle .js/.css specially and consequently show the Clearyourcache message, right? However, people might want to place scripts in Wikipedia space as well, but they'll need to invoke the template manually. Project space is probably too diverse, and things like ([[Wikipedia:Articles for deletion/User:Aditya Kabir/monobook.js]] should not automatically gain a documentation link anyway (even if we found a message where to transclude this template from).
:* Showing it in User and MediaWiki space if the doc page exists should be the desirable behavior. However, I'm unsure about the best course in MediaWiki space. What was the actual problem with the edit notices in MediaWiki space: the number of ''bytes'' in the cache, or the number of ''messages''? If the latter, placing the documentation in MediaWiki talk right away would be a solution, but would be inconsistent, so for now, I agree we shouldn't worry about performance too much unless told otherwise.
:* Having a redlinked documentation page would go a long way to standardize script documentation here on en-wiki. However, displaying the redlink on people's skin scripts (monobook.js) and inviting them to document those would be weird in almost all circumstances, so those would need to be excluded. Not sure about the MediaWiki js files, documentation for the gadgets is usually in some Wikipedia page, since nobody ever uses the scripts there directly.
:[[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 16:05, 14 December 2009 (UTC)

::Oh, I wasn't aware of that MediaWiki only handled .js and .css pages as scripts when in User and MediaWiki space. But as you state, that kind of is a good thing, so we only need to think about those two spaces.
::I don't know if the size or number of messages is the problem in MediaWiki space. What I do know is that the servers keep all the MediaWiki messages in RAM at all times, thus any message we add takes up RAM in the servers. So my guess is that both the number of messages and the size matters, since there probably is some overhead per message. But I know that loading from a template into MediaWiki space does not cost RAM in the servers, since that template only gets cached the normal way. So we don't need to worry much about the size of templates we use in MediaWiki space. But the number of .css and .js pages in MediaWiki space is pretty low, so if we would add documentation there by putting a redirect in the "doc page" of those pages, then it probably would not cost much. That redirect should then go to a page in "Wikipedia:" space or so. But personally I think it would be better to instead show the editnotice on top of the .css and .js pages in MediaWiki space. Then people can add links in those editnotices instead, and in many cases we already have such links in those editnotices.
::Right, if we add red links to possible documentation pages, then we should not do that in MediaWiki space, and not on the standard user skin scripts like /monobook.js. The red links could look something like this:
::Example 1:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
This user script could have a documentation page at [[User:Davidgothberg/mytools]].
}}
::The texts I use in these boxes might need some improvements, suggestions are as always welcome.
::So what I am saying is this:
::* When in user space we should show links to doc pages and perhaps also red links to doc pages if they don't exist.
::* When in MediaWiki space we should instead load the editnotice of the page.
::* We can also link between .js and .css pages that has the same name. I think we can do so both in User space and in MediaWiki space. (For instance some gadgets have both a .js and a .css page so it would be neat to auto-link between them.)
::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 17:29, 14 December 2009 (UTC)

::: Sounds good! And I looked it up in MediaWiki's Title.php, it's really only MediaWiki space pages and User space '''sub'''pages ending with .css or .js (i.e. not User:Foo.js). [[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 18:12, 14 December 2009 (UTC)

::::Ah, nice that you like the extension ideas. And thanks for checking the MediaWiki code.
::::I have now deployed the basic version of this template: It is only active in user space and only links to existing doc pages. I will wait some days with adding the rest of the functionality to give people some time to come here and comment. It looks good on for instance [[User:Davidgothberg/clock.js]]. 
::::I noticed that when I edit scripts then this template isn't visible. So we should add this template to some of these messages: [[MediaWiki:Usercssjsyoucanpreview]], [[MediaWiki:Userinvalidcssjstitle]], [[MediaWiki:Userjspreview]], [[MediaWiki:Usercsspreview]]. But we should not add it to all of them, since then this message will show twice under some circumstances. I'll look into that.
::::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 20:11, 14 December 2009 (UTC)

::::: Great, thanks! [[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 20:59, 14 December 2009 (UTC)

:I have now deployed the function that says "''This script seems to have an accompanying .css page at [[User:Davidgothberg/clock|User:Davidgothberg/clock.css]]''". For the time being I didn't bother to filter out the user skin files like /monobook.js, so they are are now linking between their .css and .js versions, if both exist. But that is kind of nice. If/when we add red links to possible doc pages then we of course have to filter out the user skin files.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 00:50, 15 December 2009 (UTC)

Yes, it could have a documentation page, but it could just as easily not. That template almost makes it look like one is obliged to create a dcoumentation page. Not sure I like it, personally, but meh. [[User:Ale_jrb|<span style="color:green;">A</span><small><span style="color:green;">le_Jrb</span></small>]][[User_talk:Ale_jrb|<sup style="color:blue;">talk</sup>]] 11:28, 16 January 2010 (UTC)

:I agree that the text I show above is to strong, but I couldn't come up with any better text at the time. And that's one of the reasons why I have not deployed that part yet. But how about one of these?
:Example 2:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
Documentation for this script can be added at [[User:Davidgothberg/mytools]], but some scripts don't need any documentation.
}}
:Example 3:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
Documentation for this script can be added at [[User:Davidgothberg/mytools]], but not all scripts need documentation.
}}
:Example 4:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
Documentation for this script can be added [[User:Davidgothberg/mytools|here]], but not all scripts need documentation.
}}
:Example 5:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
If this script needs documentation, it can be placed at [[User:Davidgothberg/mytools]].
}}
:Example 6:
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
If this script needs documentation, it can be placed [[User:Davidgothberg/mytools|here]].
}}
:I'm not sure which one I prefer. Other suggestions are of course very welcome.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 12:14, 16 January 2010 (UTC)

::Perhaps the first one, but without the 'but some scripts don't...' part. So, 
{{fmbox
| id = mw-script-doc
| type  = system
| image = [[File:Template-info.svg|43x40px]]
| style = background: #ecfcf4;
| text  = 
Documentation for this script can be added at [[User:Davidgothberg/mytools]].
}}
::That makes it sound more like it's a possiblility, rather than something that should be done. Hmm... [[User:Ale_jrb|<span style="color:green;">A</span><small><span style="color:green;">le_Jrb</span></small>]][[User_talk:Ale_jrb|<sup style="color:blue;">talk</sup>]] 15:15, 16 January 2010 (UTC)

:::Yes, I like your short version. Should we ask some more users for opinions, or should we boldly deploy it? There's no better way to get feedback than deploying a feature. :)
:::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 19:54, 16 January 2010 (UTC)

::::Tbh, I don't think it's a very big deal - if it's deployed, and people don't like it, it's simple to remove it again. I'm not adverse to mentioning it at VPT either though. I don't mind. [[User:Ale_jrb|<span style="color:green;">A</span><small><span style="color:green;">le_Jrb</span></small>]][[User_talk:Ale_jrb|<sup style="color:blue;">talk</sup>]] 22:48, 16 January 2010 (UTC)

:{{tick|18}} '''{{ucfirst:Updated}}''' - This template (and thus this system message) now gives a red link to possible documentation pages, using the text from Ale jrb's example above. And it handles user skin file separately, it uses different text for them and doesn't link to documentation on them. See the [[Template:Script doc auto/testcases|/testcases]] page for examples of the six different message combinations.
:This template is still only loaded used in user space. It is not used in MediaWiki space, and seems unnecessary there.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 23:19, 25 January 2010 (UTC)

== Manual doc pointer ==

When I just wanted to manually create the doc pointer on [[Wikipedia:Dazzle!/code.js]] I created the redirect [[Wikipedia:Dazzle!/code]] → [[Wikipedia:Dazzle!]], but then figured I could just point to [[WP:Dazzle!]] right away and bypass the redirect since I had to transclude the template manually in Wikipedia space. I intuitively used {{tlp|script doc auto|2=Wikipedia:Dazzle!}}, which of course doesn't work since there are no numbered parameters in the template, but even using the page parameter I'd have to write {{tlp|script doc auto|2=page=Wikipedia:Dazzle!'''''.js'''''}} which is quite a hack. Hardcoding the fmbox is of course no option, not least because this template is going to gain more functionality than it currently has. So how about adding a parameter to pass in the actual documentation page itself, which bypasses the name shortening logic? Would probably require an additional subtemplate, but that's probably necessary anyway once more functionality is added.<br>Cheers, [[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 20:59, 14 December 2009 (UTC)

:I am currently working with the extended version. I tried to add parameters for manual linking to the doc page as you suggest, but that messed up the code. And when manually adding a doc link on a Wikipedia space page we have slightly different needs. For instance then the message should not say "''seems to have a documentation page''", instead it should say "''has a documentation page''". So it is better if we make a separate template for that. We could for instance call it <s>{{tl|script doc manual}}</s>. I'll create that one later on.
:--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 22:38, 14 December 2009 (UTC)

::Note to other readers: This template used to be named {{tlf|script doc}}.
::Amalthea: I did some thinking. I have now renamed this template to {{tl|script doc auto}} since this template is only called from the system message [[MediaWiki:Clearyourcache]]. So now we can use the shorter name {{tl|script doc}} for a template for manual human use.
::--[[User:Davidgothberg|David Göthberg]] ([[User talk:Davidgothberg|talk]]) 02:38, 21 December 2009 (UTC)

::: Sounds good. [[User talk:Amalthea|<span style="font-variant:small-caps;color:#832">Amalthea</span>]] 09:40, 21 December 2009 (UTC)

== Protected edit request on 13 July 2019 ==

{{edit fully-protected|Template:Script doc auto|answered=yes}}

Please replace with the [[Special:Permalink/906115642|current]] version of the sandbox ([//en.wikipedia.org/w/index.php?title=Special:ComparePages&rev1=340018083&rev2=906115642 diff]). This will remove an unneeded parser function, since if a parameter isn't specified a default can be supplied (in this case the pagename magic word) --[[User:DannyS712|DannyS712]] ([[User talk:DannyS712|talk]]) 19:00, 13 July 2019 (UTC)
:{{done}} — [[User:Xaosflux|<span style="color:#FF9933; font-weight:bold; font-family:monotype;">xaosflux</span>]] <sup>[[User talk:Xaosflux|<span style="color:#009933;">Talk</span>]]</sup> 01:25, 15 July 2019 (UTC)

== Proposal: link to WP:US ==

We should change "script" to "user script" and then link it to [[WP:US]]. [[User:Enterprisey|Enterprisey]]&nbsp;([[User talk:Enterprisey|talk!]]) 21:48, 13 December 2020 (UTC)
* Love this idea... surprised it wasn't done already.  There should be more explicit recs to WP:US.  (are there any examples of non-user scripts that trigger this?)  <span style="color:#666">&ndash;&nbsp;[[User:Sj|SJ]][[User Talk:Sj|<span style="color:#f90;">&nbsp;+</span>]]</span> 21:48, 13 December 2020 (UTC)
* Good idea. – [[User:SD0001|<span style="font-weight: bold; color: green">SD0001</span>]] ([[User talk:SD0001|talk]]) 07:56, 14 December 2020 (UTC)
* [[Special:Diff/420235283/994734774|Done]], since any objections seem unlikely. [[User:Enterprisey|Enterprisey]]&nbsp;([[User talk:Enterprisey|talk!]]) 07:49, 17 December 2020 (UTC)
*:Can I suggest that we use "Wikipedia" instead of "WP" in the links? [[User:DannyS712|DannyS712]] ([[User talk:DannyS712|talk]]) 00:52, 18 December 2020 (UTC)
*::Sure, will do. [[User:Enterprisey|Enterprisey]]&nbsp;([[User talk:Enterprisey|talk!]]) 09:03, 18 December 2020 (UTC)

== Protected edit request on 26 January 2024 ==

{{edit fully-protected|Template:Script doc auto|answered=yes}}
Please sync with [[Template:Script doc auto/sandbox]]. Changes:
* Converts template to Lua, making the code simpler and more amenable to future changes. The current wiki template is complex and uses /core and /core2 sub-templates. The /core template call is only needed according to the documentation so that {{t|str len}} is called only once, because, wait for it, in the pre-lua era before 2013, {{t|str len}} was expensive on the servers due to its abuse of parser functions.
* Adds a header on top of gadget pages as well – indicating the gadget to which the page belongs and the number of users it has. If the gadget is default, a bold "enabled by default" is included. For hidden gadgets, the list of gadgets depending on it is included in the message.

Right now, this template is not used for MediaWiki namespace, so the 2nd point is not a visible change. I have separately [[Mediawiki talk:Clearyourcache#Protected edit request on 26 January 2024|requested an edit]] to make it so. 

Testcases available at [[Template:Script doc auto/testcases]], which show the sandboxed version giving identical output for user space cases. – [[User:SD0001|<span style="font-weight: bold; color: #C30">SD0001</span>]] ([[User talk:SD0001|talk]]) 09:24, 26 January 2024 (UTC)
: {{Done}} [[User:Pppery|* Pppery *]] [[User talk:Pppery|<sub style="color:#800000">it has begun...</sub>]] 16:10, 26 January 2024 (UTC)

== ResourceLoader is not mandatory for style gadgets ==

@[[User:SD0001|SD0001]], great module, but currently it fails (with Lua errors) if styles gadgets [https://ru.wikipedia.org/?diff=136286393 do not have ResourceLoader], even though it is fine for them. You might also consider [https://en.wikipedia.org/?diff=1209399664 this change to the code] because it would make module not include anything in noincluded parts. (I [[:ru:Модуль:Script doc auto|adapted this module for Russian WP]], maybe you’ll see something you might want to adopt back.) [[user:stjn|stjn]] 21:36, 21 February 2024 (UTC)
:@[[User:Stjn|Stjn]] Will look into porting over some of the improvements, thanks! However, as for [https://en.wikipedia.org/?diff=1209399664 this], it doesn't reflect reality – MediaWiki reads the gadgets definition page as plain text and considers anything beginning with a bullet as a potential definition. Putting something within noinclude tags doesn't make any difference. – [[User:SD0001|<span style="font-weight: bold; color: #C30">SD0001</span>]] ([[User talk:SD0001|talk]]) 17:15, 22 February 2024 (UTC)
::In Russian Wikipedia [[:ru:MediaWiki:Gadgets-definition|MediaWiki:Gadgets-definition]] has some stuff in the {{tl|Flatlist}} that is marked with bullets, and I suspect it would trip up your parsers while not tripping up Special:Gadgets etc. [[user:stjn|stjn]] 17:19, 22 February 2024 (UTC)

== Edit request to complete TfD nomination ==

{{edit fully-protected|Template:Script doc auto/core|answered=yes}}
[[Template:Script doc auto/core]] has been listed at Templates for discussion ([[Wikipedia:Templates for discussion/Log/2024 March 11#Template:Script doc auto/core|nomination]]), but it was protected, so it could not be tagged. Please add:

<code><nowiki>{{subst:template for discussion|help=off}}
</nowiki></code>

to the top of the page to complete the nomination. Thank you. <!-- Template:Xfd edit protected -->[[User:Gonnym|Gonnym]] ([[User talk:Gonnym|talk]]) 09:20, 11 March 2024 (UTC)
:{{done}}<!-- Template:EP --> &mdash;&nbsp;Martin <small>([[User:MSGJ|MSGJ]]&nbsp;·&nbsp;[[User talk:MSGJ|talk]])</small> 09:35, 11 March 2024 (UTC)

[[Template:Script doc auto/core2]] has been listed at Templates for discussion ([[Wikipedia:Templates for discussion/Log/2024 March 11#Template:Script doc auto/core2|nomination]]), but it was protected, so it could not be tagged. Please add:

<code><nowiki>{{subst:template for discussion|help=off}}
</nowiki></code>

to the top of the page to complete the nomination. Thank you. <!-- Template:Xfd edit protected -->[[User:Gonnym|Gonnym]] ([[User talk:Gonnym|talk]]) 09:20, 11 March 2024 (UTC)
:{{done}}<!-- Template:EP --> &mdash;&nbsp;Martin <small>([[User:MSGJ|MSGJ]]&nbsp;·&nbsp;[[User talk:MSGJ|talk]])</small> 09:37, 11 March 2024 (UTC)

== Dark mode changes ==

This probably needs the same changes as {{t|doc}} to work in dark mode i.e. have the styles<br/>{{#tag:syntaxhighlight|        background-color: #0b1e1c;{{Truenewline}}|lang="css"}}in dark mode (from [[Module:Documentation/styles.css]]).<span id="Qwerfjkl:1723738402474:Template_talkFTTCLNScript_doc_auto" class="FTTCmt"> —&nbsp;[[User:Qwerfjkl|<span style="background:#1d9ffc; color:white; padding:5px; box-shadow:darkgray 2px 2px 2px;">Qwerfjkl</span>]][[User talk:Qwerfjkl|<span style="background:#79c0f2;color:white; padding:2px; box-shadow:darkgray 2px 2px 2px;">talk</span>]] 16:13, 15 August 2024 (UTC)</span>
:Looks like this was done some time back ([[Special:Diff/1250343929]]). – [[User:SD0001|<span style="font-weight: bold; color: #C30">SD0001</span>]] ([[User talk:SD0001|talk]]) 09:48, 14 February 2025 (UTC)