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:

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

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.

--David Göthberg (talk) 13:41, 14 December 2009 (UTC)

Looks good! Concerning 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.

Amalthea 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:

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.)

--David Göthberg (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 subpages ending with .css or .js (i.e. not User:Foo.js). Amalthea 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.

--David Göthberg (talk) 20:11, 14 December 2009 (UTC)

Great, thanks! Amalthea 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.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.

--David Göthberg (talk) 00:50, 15 December 2009 (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 {{script doc auto|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 {{script doc auto|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.
Cheers, Amalthea 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 {{script doc manual}}. I'll create that one later on.

--David Göthberg (talk) 22:38, 14 December 2009 (UTC)

Note to other readers: This template used to be named {{script doc}}.

Amalthea: I did some thinking. I have now renamed this template to {{script doc auto}} since this template is only called from the system message MediaWiki:Clearyourcache. So now we can use the shorter name {{script doc}} for a template for manual human use.

--David Göthberg (talk) 02:38, 21 December 2009 (UTC)