Wikipedia talk:Template documentation

From Wikipedia, the free encyclopedia
Jump to: navigation, search
the Wikipedia Help Project  
WikiProject icon This page is within the scope of the Wikipedia Help Project, a collaborative effort to improve Wikipedia's help documentation for readers and contributors. If you would like to participate, please visit the project page, where you can join the discussion and see a list of open tasks. To browse help related resources see the help menu or help directory. Or ask for help on your talk page and a volunteer will visit you there.
 ???  This page does not require a rating on the project's quality scale.
 ???  This page has not yet received a rating on the project's importance scale.

Defaultsort does not work[edit]

Unresolved: Has only been fixed in Template:Documentation subpage.

The subpage template sets a {{DEFAULTSORT:{{PAGENAME}}}} ensuring that a Template:X will be properly sorted at "X" and not "T", it is thus not useful or desirable to add a {{PAGENAME}} sortkey to the categories. - Obviously, this does not work properly. e.g. {{music}} is sorted under "T" instead of "M". --FordPrefect42 (talk) 11:30, 10 February 2008 (UTC)

Ah, you are right. I checked the code for {{documentation}} and there is no {{DEFAULTSORT:{{PAGENAME}}}} there. I also checked {{documentation subpage}} and it has such code but in the wrong part of the #ifeq statements so it never gets used on the template pages, only on the /doc pages. I'll have to take a closer look at it and think for a while before I fix it. I think that code should be added to both {{documentation}} and {{documentation subpage}} since not all pages use both and the /doc pages need good default sorting themselves.
--David Göthberg (talk) 18:06, 17 April 2008 (UTC)

How to do good inline documenting[edit]

Resolved: Question answered.

Hi, is there some help available on how to document a template inline (in code), e.g. by using <!-- comments & newline & indent-->? Is it good practice to add many comment text to clarify, or is there a basic level of insight we might expect? Good example templates maybe? -DePiep (talk) 00:28, 23 January 2011 (UTC)

There's no written standard, and very little is done in this area. MediaWiki template and ParserFunction syntax is so simple that commenting is rarely needed, and because it has to be done in HTML comments, it is tedious, messy, and easy to break. Indentation and linebreaking just for code beautification often has unintended consequences on the output if you're not careful. Complex templates like {{WikiProjectBannerMeta}} make use of it, but general practice for templates that don't need an {{Intricate template}} warning is to keep the code as concise and compact as possible, since template are transcluded, sometimes millions of times per day. They are not like computer program source code that can be longwinded, but gets reduced to lean, fast machine language after being compiled once. MediaWiki has to parse it character by character every single time, so characters in the code that are not necessary are, in the aggregate, a non-trivial matter, even if one inefficient template isn't going to break anything. Talk pages are cheap, so if anything is unusual about the code, it can be noted on the template's talk page (probably not in its documentation, which is usually for editors writing articles, not for meta-editors maintaining templates). — SMcCandlish Talk⇒ ʕ(Õلō Contribs. 21:42, 18 December 2011 (UTC)

Why does the preload text differ from that suggested in WP:DOC?[edit]

Resolved: Fixed.

So, Wikipedia:Template documentation#How_to_create_a_documentation_subpage suggests one hunk of text be used in /doc subpages, and Template:Documentation/preload contains a 'different' block of text which is preloaded into the editbox when one actually goes to create such a page. How is an editor supposed to know which to use?

Might it not be better if these were merged, so that Wikipedia:Template_documentation would transclude the source of Template:Documentation/preload into a <pre> somehow (with a nearby hyperlink to that page to facilitate editing), rather than containing an out-of-sync suggestion for what to put there?

Or I suppose that code could be removed entirely from the page, though that might make things harder for those who might wish to use it as an example from which to update old /doc subpages...

Regardless, this seems gratuitously confusing. —SamB (talk) 22:10, 7 June 2011 (UTC)

I synched the instructional text to use the actual transclusion code. I tinkered, but I can't think of a way to actually transclude the code from Template:Documentation/preload into the instructional text without it also processing as a transcluded template. Wikipedia:Template_documentation will just have to be periodically checked for conformance with the "live" code in {{documentation/preload}}. — SMcCandlish Talk⇒ ʕ(Õلō Contribs. 21:29, 18 December 2011 (UTC)
I've experienced a problem when this edit was implemented. Under the section "How to create a documentation subpage" the code for the includeonly's does not work. See this edit, which shows that there are 2 extra, orphaned "includeonly" tags at the bottom left of the /doc pg. Since the old instructions worked, I'd like to update the instructions to include the revision that worked before. --Funandtrvl (talk) 19:31, 3 January 2012 (UTC)
Why not just fix the error? But, by all means revert to something that worked in the interim. I would just go fix this stuff myself right now, but I'm on my way out the door... — SMcCandlish Talk⇒ ʕ(Õلō Contribs. 21:35, 3 January 2012 (UTC)
No problem, in the meantime, I did update the instructions. Thanks, --Funandtrvl (talk) 23:33, 3 January 2012 (UTC)
Fixed. Properly, this time. — SMcCandlish Talk⇒ ʕ(Õلō Contribs. 01:12, 5 January 2012 (UTC)

Remove implicit reference to "pre-expand include limit"[edit]

In the last paragraph of the "What to include" section, this guide says:

Text on the template page itself adds to the amount of text that must be processed when displaying the template, which is limited for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason).

However, following the link and reading all the way to the bottom at WP:Template limits#History, we see:

The inclusion limits were put into effect on the English Wikipedia by Tim Starling on 14 August 2006. A new preprocessor was enabled in January 2008, removing the "pre-expand include limit" and replacing it with a "preprocessor node count" limit.
The practice of using a template documentation page, while it can still be useful for other reasons, is no longer needed for avoiding documentation to be counted on pages that call the template.

So it seems that this paragraph should be removed or replaced. Set theorist (talk) 04:41, 13 March 2012 (UTC)

Well, I didn't mean that the whole paragraph should be removed, as certainly the first sentence is correct. I meant that the two sentences I quoted should probably be removed. Set theorist (talk) 04:44, 13 March 2012 (UTC)

Section heading levels on doc pages[edit]

Is there any basis for template documentation pages not to have level 2 section headings as required by MOS:LAYOUT#Headings and sections? I've seen a number of doc pages that start with level 3 headings. Set theorist (talk) 07:15, 26 March 2012 (UTC)

Can we have an answer to this please? Every doc subpage I have looked at has level 3 headings including that for {{Documentation}}, so it rather looks as if these instructions should be corrected. --Mirokado (talk) 23:46, 23 October 2012 (UTC)
At present, Wikipedia:Template documentation#How to create a documentation subpage shows (but does not explicitly state) to use level 2 headings; and if you set up a template for a doc page by adding <noinclude>{{documentation}}</noinclude> to the bottom, and then click the "create" link at upper right of the new doc box, the new doc page is pre-filled from Template:Documentation/preload, which also uses level 2 headings. The preload feature has used level 2 for the last eleven months, so doc pages using level 3 headings were probably created before then.
If you look through the revision history for the preload, you'll see that there has been much disagreement. Some of the edit summaries point to discussion elsewhere, which may have been archived (although as I recall, some were quite extensive).
Until and unless both WP:DOC and the preload change again, I would therefore use level 2 for new doc pages; do not change existing doc pages from level-2 style to level-3 style; but be careful of changing existing doc pages from level-3 style to level-2 style, since you might provoke an adverse reaction. --Redrose64 (talk) 09:04, 24 October 2012 (UTC)

half-listing cat in noinclude[edit]

Where the page says, "to place the doc subpage into a category, add the [[Category:Category name]] code inside a <noinclude>...</noinclude> section on the doc subpage" (boldfacing and italics omitted), I added, "the category won't be listed on the doc page but the category will list the doc page." This was reverted because, according to an editor, "the cat is shown at the doc page even if inside <noinclude></noinclude> - it's <includeonly></includeonly> that prevents this". In that case, something else must be causing one doc page to not list although the category lists the doc page. Whether I have line breaks around the category link or not does not matter. Is something wrong with the doc? Nick Levinson (talk) 17:29, 18 November 2013 (UTC)

Line breaks do not make any difference to categorisation. The <noinclude>...</noinclude> tags prevent transclusion, not processing, of enclosed content. I think I know why you don't see it... it's a hidden category. Go to Preferences → Appearance, and under "Advanced options", enable "Show hidden categories". --Redrose64 (talk) 20:38, 18 November 2013 (UTC)
Thank you, I now see that it's a hidden category, and I can add that explanation to the how-to page, although the WP:HIDDENCAT guideline says hiding occurs if {{Wikipedia category|hidden=yes}} or __HIDDENCAT__ is in the page source code, but neither one is. However, according to Category:Hidden categories, any subcategory of a hidden category is also hidden, and that applies here. The doc for Template:Wikipedia category should state that principle and I can take care of that. Do you think there's any problem with these two edits? Nick Levinson (talk) 17:14, 19 November 2013 (UTC)
Being hidden is not inherited. It was a hidden category because of the rather strange presence of {{DYKT}}, which brings in {{tracking category|container=yes}}, and if you go deep enough, you'll find that it adds __HIDDENCAT__. The {{DYKT}} was added by John Cline (talk · contribs). I have reverted it because Category:Template documentation pages is nothing to do with DYK, and is not a tracking category either. --Redrose64 (talk) 20:27, 19 November 2013 (UTC)
Okay and thanks; at the moment I won't do either of the edits. That leaves me wondering what the basis for the claim of subcategories being hidden is, and I've begun a talk topic/section about it, albeit on a page that doesn't get looked at much. Nick Levinson (talk) 18:08, 20 November 2013 (UTC)
The page has 74 watchers, myself included; I've replied there. --Redrose64 (talk) 20:05, 20 November 2013 (UTC)

Comments in the code - still necessary?[edit]

Follow-up to WP:VPT#Can we please get rid of those shouty comments in template documentation?

I find the instructional comments in the code to be of little use, to be honest, and a source of much clutter around the project. There's already {{Documentation/doc}}, and that, to me, is where instructions like "Add categories to the /doc subpage and interwikis in Wikidata" should be - not copied and pasted thousands of times around the project in source code. In there they're most likely to only be seen by experienced template editors, anyway, and they don't need to be told over and over again. (It's even worse for older template documentation templates, because until February 2011 the comments were all IN CAPITALS! which is really annoying.) If categories get added to a template rather than its documentation by an inexperienced user, the mistake will almost certainly be caught swiftly; and interwiki additions will get zapped by some bot or other. So, as far as I can see it, the comments are largely redundant. They even give us maintenance overhead: because they're copied every time, if a change needs to be made, it can't be done by only editing one template. That's already making work for people.

I propose, for the sake of clean source code and maintainable documentation, that we remove the comments from the preload template, and ensure that the documentation explains properly how to use template categories and interwiki links. Then, we recruit a bot to hoover up all the places where they got in since their introduction in 2006. What do you think? — Scott talk 16:26, 17 January 2014 (UTC)

I see your point, but I still think the comments are useful in the code. You're an experienced editor, so you know what to do, but I still see lots of templates that have duplicate categories both on the temp page and the doc page, and I still see missing "noinclude" and "includeonly" only tags on those same pages, and I've cleaned up a lot of templates! I think w/o the code, there may be even more mistakes to be cleaned up. Funandtrvl (talk) 18:23, 17 January 2014 (UTC)
That's what bots are for! — Scott talk 22:06, 18 January 2014 (UTC)