Wikipedia talk:Template doc page pattern

From Wikipedia, the free encyclopedia

[edit] "/doc" or "X/doc"?

Using {{/doc}} instead of {{X/doc}} does have the benefit, that it transcludes the doc page which is relative to the name of the template. So moving the template to another name, say "Y", does still expect that the doc page of Y is at Y/doc and not shared with the doc page of X. So, for now I'm going to change this back at the project page, until there are other arguments. --Ligulem 07:46, 31 August 2006 (UTC)

The '/doc' format can be used as a 'cut and paste' standard on any template page (allowing its use even by people who don't understand it) and is shorter and thus better for staying under the transclusion limit. Sub-pages apparently do not get moved when the primary page is move... so using 'X/doc' would allow the old sub-page to still be displayed if the template itself were moved to 'Y'. However, I don't think we would want template and documentation to reside in different locations and thus presumably we would move the '/doc' page separately. At which point '/doc' works just as well and doesn't require an 'X' to 'Y' update of the link on the template page itself. --CBD 11:12, 3 September 2006 (UTC)

[edit] Good idea

I have a slight concern over it. I have been playing (for legitimate reasons!) with noincludes etc. and it seems to me that something like:

</noin<noinclude> evil grin </noinclude>clude> rude message here

in the /doc would break this model.

Rich Farmbrough 09:32 1 September 2006 (GMT).

I discussed this with CBD and he convinced me that it isn't possible to foul this pattern. You can do whatever you want on the doc page, everything that is transcluded into the main template page is still inside noincludes, because the main template page has it so. If the main template is protected, then it is impossible to inject anything via doc into the template. Ok, you can vandalise the documentation display of the template, but that's all. Transclusions of the main template are not affected. So I say no. Do you have an actual example (in a sandbox or somewhere) that would prove me wrong? (not that I would think so, but I could be wrong, who knows ;-). --Ligulem 09:55, 1 September 2006 (UTC)

The evaluation of any given page processes 'noinclude' style tags before it brings in the contents of any transcluded templates... thus there is no further evaluation of any 'noinclude' style tags those templates may contain. So, the above would evaluate as '</noinclude> rude message here' on the template page (actually displaying the 'noinclude' tag there), but then as nothing on pages to which that template were transcluded because it is inside 'noinclude' tags on the template page. Another way of looking at it is that transcluded 'noinclude' tags are treated strictly as text. --CBD 11:25, 3 September 2006 (UTC)

[edit] Loved the idea ...

How do i replicate this effect at pt.wikipedia??? thanxs a bunch .. Biasuz 16:33, 3 September 2006 (UTC)

Hmm, I fear I don't know what your problem is. Why not just use it on pt on a template? Good candidates are templates that are used often or templates with a long documentation. However, if you are not sure how it works, it might be good to start up slowly and do it on a non-critical template first as a trial. Just some thoughts ;-). --Ligulem 16:44, 3 September 2006 (UTC)

This effects seems to be impossible to replicate in Slovenian WP as well. I added <noinclude>{{/doc}}</noinclude> to a template and got link to the template:/doc page instead of the template:templatename/doc page. --Eleassar ^{my talk} 08:55, 18 September 2006 (UTC)

I've fixed that in the description. Try <noinclude>{{{{FULLPAGENAME}}/doc}}</noinclude> instead. --Ligulem 09:12, 18 September 2006 (UTC)

[edit] Wrong additions of interwikis

Wikipedians do have problems understanding that interwikis (and categories) should go to the doc subpage. They often add interwikis on the main template page instead of on the doc page. I've thus added a comment into the copy/paste reciepe.

However, I'm not happy with that, because it eats up from precious pre-expand include size. If anybody has a better idea to make this pattern less error prone for interwiki adding Wikipedians, please let me know by posting here. --Ligulem 11:41, 23 September 2006 (UTC)

[edit] Including categories with fields

Having a problem with categories in the /doc file (on another site, private sorry I can't provide example). It just doesn't seem to work. I inserted the category command, e.g. [[Category:foo]], but it does not show up as a category on pages where the template is used. All the other documentation appears correctly on the template page itself when it's viewed. Should this always work or does it require a certain version of wikimedia to function correctly?Elf | Talk 22:47, 26 September 2006 (UTC)

If you add categories to the doc page per this pattern, then these categories end inside <noinclude>...</noinclude> in the template, which means the template itself is added to the category. If you want to add pages to a category where the template is transcluded, then those categories must be added to the template outside <noinclude>...</noinclude>. The pattern as described here is only for documentation of the template and adding the template itself to categories. Everything else must stay outside of the doc page and outside <noinclude>...</noinclude>. Also, I don't know of any software version dependency. In other words, if you do write [[Category:foo]] into a template and transclude that template into a page P, then P is added to foo, provided that [[Category:foo]] was put outside <noinclude>...</noinclude> clauses, which isn't the case if you add a category to the doc page as described here. See also m:Help:Template. --Ligulem 23:04, 26 September 2006 (UTC)

Thanks. The comments are so emphatic about catg's not being in the template that I was convinced. (Of course, by having an example of the template's output in the template's documentation, this then puts both the /doc and the template into the category... oh, well...) Elf | Talk 17:32, 27 September 2006 (UTC)

Well, people should still know whether they want their cat in noinclude-land or not. If they don't know, they'd better first ask ;). But I admit the comment is really emphatic. I just didn't know what else to do to detain people from adding the noinclude-land cats and interwikis to the template page instead of to the doc page. This was also one of the reasons why I was first a bit reluctant to do the cats and interwikis on the doc page. But going through a cache invalidation of all transculding pages only because yet another interwiki wants to join they party is - erm - rather suboptimal. People do have problems to understand that. But maybe I should simply refrain from applying the doc page pattern to non-protected templates. Anyway, to my defense, I can say: the comment says "not here!" and that comment line is inside noinclude-land ....:] --Ligulem 18:08, 27 September 2006 (UTC)

[edit] This page is too wide so I'll fix it.

This page is too wide so I'll fix it. -- Chuck Marean 09:31, 14 October 2006 (UTC)

Done. -- Chuck Marean 09:35, 14 October 2006 (UTC)

[edit] Better header

This header places a different notice at the top of the /doc page when viewed directly informing the viewer that there may be broken links because of variables. Any objections to making this the standard header text? It's in action at {{Lorem ipsum}} (/doc), and I've created a template that can be subst'd to include this text at User:Flamurai/Template doc page header.

<noinclude>:''This is the [[Wikipedia:Template doc page pattern|doc page]] 
for {{tl|{{BASEPAGENAME}}}}. It is not intended to be viewed directly. 
Therefore, if it uses [[Help:Variable|variable]]s, some links may appear 
broken. Do not replace these variables with [[hardcoded]] page names or URLs.
</noinclude><includeonly>:''This template documentation is 
[[Wikipedia:Template doc page pattern|transcluded]] from [[{{FULLPAGENAME}}/doc]]'' 
[<span class="plainlinks">[{{fullurl:{{FULLPAGENAMEE}}/doc|action=edit}} edit]</span>]
</includeonly>

(This could be an alternative when relative variables are used on the page.)

– flamurai (t) 03:12, 11 November 2006 (UTC)

No objections from me. --Ligulem 09:52, 11 November 2006 (UTC)

New idea: Create two templates, then change the template on this page to be something like:

<includeonly>{{Template doc page included}}</includeonly><noinclude>{{Template doc page viewed directly}}</noinclude>

Where the first template is the current "This template documentation..." and the second would be the new header. I created a new version in a box: User:Flamurai/Template doc page viewed directly This hides the variables and cleans up the top of the page. – flamurai (t) 20:17, 11 November 2006 (UTC)

Could you give a full working example? For example on {{Lorem ipsum}}? --Ligulem 17:37, 12 November 2006 (UTC)

Done. – flamurai (t) 00:51, 15 November 2006 (UTC)

Looks good. Merged into recipe. --Ligulem 16:06, 15 November 2006 (UTC)

[edit] unmatched includeonly tags?

The first example in the How to do it section seems to have an unmatched number of includeonlys. I thought these needed to be matched? Or can you start includeonly's multiple times? I would have changed it but I am not sure it's an error... Thanks! (this is an interesting technique! I know a template that should use it already.) ++Lar: t/c 11:48, 15 November 2006 (UTC)

Nope. Everything fine. Just scroll to the right. --Ligulem 15:23, 15 November 2006 (UTC)

[edit] Putting {{fact}} on it

Freak seems not to believe in the original research presented here. Since this page here is close to "primary source" material, I suggest you post your concerns here instead of re-inserting {{fact}}. Thank you. --Ligulem 23:52, 16 November 2006 (UTC)

[edit] noinclude vs. includeonly

Okay... I'm feeling dense, but I'm trying to get my head around this. What do the <noinclude> and <includeonly> tags acutally do? (ex: such as using them in a userbox template). In laymen terms please. Drcwright 08:11, 16 December 2006 (UTC)

In short (hopefully not too short!):

Anything between <noinclude> .... </noinclude> on a page is not included when that page is transcluded on (roughly, "used on" – visit the link for more info) another page. Example:

This is the code for
a template named "Blah1" 
<noinclude>– but this
bit of code won't be
used! –</noinclude> and
this is the end of the
code.

This is an article about
blah blah blah, bla-blah
blah blah blah...
{{Blah1}}
Blah bl-blah blah, blah
blah blah bla-blah blah...

Meanwhile, anything between <includeonly> .... </includeonly> on a page is only included when that page is transcluded ("used on") another page. Example:

This is the code for
a template named "Blah2"
<includeonly>– and this
is the code that's only
used when the template
is transcluded! –
</includeonly> and
this is the end of the
code.

This is an article about
blah blah blah, bla-blah
blah blah blah...
{{Blah2}}
Blah bl-blah blah, blah
blah blah bla-blah blah...

Hope enough of the above makes sense!  Best wishes, David Kernow (talk) 10:02, 16 February 2007 (UTC)