Template talk:Template doc page

From Wikipedia, the free encyclopedia

Contents

[edit] Three proposed additions

Abstract: Code for a big change. Everything is already tested, working, and visible in the local sandbox. Below is the step-by-step description of what went into the new code and why, as documented during the development.

[edit] To do the detection on SUBPAGENAME is "doc"

I'd suggest changing the test criterion from:

{{#ifeq: {{PAGENAME}} | {{BASEPAGENAME}}

to this code base (with a reversal of results order):

{{#ifeq: {{SUBPAGENAME}} | {{{doc|doc}}}
 | <!--     equal --> {{Template doc page viewed directly}}
 | <!-- not equal --> {{Template doc page transcluded}}
}}<noinclude>
  • This would work for docs or subdocs at any level, such as subtemplates' documentations, instead of only the top-level.
  • Particularly, this would allow the tests versions for any template in /sandbox that needs to use its own /sandbox/doc to work too (including this very Template:Template doc page/sandbox).
  • Since the test is case-sensitive and would be true only for a lowercase "doc" (not "Doc") page, it can only be a /doc subpage, not a top-level Template:Doc (automatic uppercase to "Doc").
  • The only drawback I see is that (for the default behavior) it forces to use or move to a /doc location, but that would actually help standardization of the /doc pattern. Also, if there would be special cases such as documentations broken into many /doc1 /doc2 pages, the {{{doc|doc}}} allows to add doc=doc2 in the template call.

[edit] To integrate {Intricate template} too

I'd suggest adding an optional parameter so that instead of this common:

{{Template doc page}}
<includeonly>{{Intricate template}}</includeonly>

as well as this older, equivalent:

{{Template doc page}}
<includeonly>{{Esoteric}}</includeonly>

we could just have this:

{{Template doc page| intricate=yes }}

New codebase (build on top of suggestion #1):

{{#ifeq: {{SUBPAGENAME}} | {{{doc|doc}}}
 | <!--     equal --> {{Template doc page viewed directly}}
 | <!-- not equal --> {{Template doc page transcluded}}
{{#ifeq: {{lc: {{{intricate|}}} }} | yes
 | {{Intricate template}}
}}
}}<noinclude>

(Note: on this version I used an #ifeq on "yes" instead of testing with just {{{intricate|}}} because if someone changed it to intricate=no it would still have activated it. But it's changed with the next code below.)

[edit] To forward parameters to the embedded templates

The templates we embed sometimes need their own parameters, such as:

We could provide optional parameter forwarding with such a call syntax:

{{Template doc page
 | intricate   = Easily broken architecture of If's and Switch's.
 | directly    = [[Template:1]] and [[Template:2]]
 | directly2   = inhib=yes
 | transcluded = Template:Foo
}}

The naming scheme for the params is the main keyword of each embeded template. For intricate= we'll embeded it if {{{intricate}}} is non empty, and we will forward its value if different from just "yes", so that changes its section too. Implemented as (build on top of suggestions #1 and #2):

{{#ifeq: {{SUBPAGENAME}} | {{{doc|doc}}}
 | <!--     EQUAL, WE ARE ON A DOC SUBPAGE -->
 {{#if: {{{directly|}}}
  |
  {{#if: {{{directly2|}}}
   | {{Template doc page viewed directly|{{{directly|}}}|{{{directly2|}}}}}
   | {{Template doc page viewed directly|{{{directly|}}}}}
  }}
  | {{Template doc page viewed directly}} <!--NO PIPE IS DIFFERENT OF EMPTY PIPE-->
 }}
 | <!-- NOT EQUAL, WE ARE TRANSCLUDED ON A TEMPLATE PAGE -->
 {{#if: {{{transcluded|}}}
  | {{Template doc page transcluded|{{{transcluded|}}}}}
  | {{Template doc page transcluded}} <!--NO PIPE IS DIFFERENT OF EMPTY PIPE-->
 }}
 {{#if: {{{intricate|}}} <!--VALUE CAN BE "yes" OR "Some text to forward."-->
  |
  {{Intricate template
   | {{#ifeq: {{lc: {{{intricate|}}} }} | yes |<!--NIL-->|{{{intricate|}}}}}
  }}
 }}
}}<noinclude>

(The nested #if's are needed because merely adding an empty | to the called templates name creates an empty string parameter instead of an undefined one, which makes the target templates get a false positive on their {{{1|}}}...)

[edit] Parameters recap and tests OK

For updating the syntax, the new copy-pasteable self-doc is:

{{Template doc page    <!-- ALL PARAMETERS ARE OPTIONAL -->
 | intricate   =  <!-- "yes" or "Intricacy to be displayed inside the Intricate box."   -->
 | directly    =  <!-- "[[Template:1]] and [[Template:2]]" or such when doc is shared   -->
 | directly2   =  <!-- "inhib=yes" prevents categorization, BUT USE directly= IF UNUSED -->
 | transcluded =  <!-- "Template:Foo" if the Template:Foo/doc is transcluded elsewhere  -->
 | doc         =  <!-- "subpage name" if not "doc" (PREFERABLY MOVE TO "doc" INSTEAD)   -->
}}

I have tested each of those suggestions and code, step by step in the local sandbox (note: can require &action=purge to have the sandbox updated to the new self-referential version and be sure we see the right results).

Then I did tests from the /sandbox/doc page calling the /sandbox template, with various values of the parameters, and they all worked:

  • no "intricate=" (ok, box disappears), "intricate=yes" (ok, just the box), "intricate="Please don't hurt me." (ok, box with message inserted).
  • no "directly=" (ok, regular link and categorized doc page), "directly=inhib=yes" (ok, regular link and doc page not categorized any more), "directly=Template:1 and Template:2" (ok, link updated and categorization is done), "directly=Template:1 and Template:2 | directly2=inhib=yes" or "directly=inhib=yes | directly2=Template:1 and Template:2" (both ok, link updated and no categorization)
  • no "transcluded=" (ok, regular link on the template page), "transcluded=Template:X1" (ok, changed the hatnote's link as expected)

[edit] Discussion

Works enough for me, but I prefer to first seek possible comments about side-effects or better implementation before applying this to the live template. Objections?

— Komusou talk @ 04:16, 24 September 2007 (UTC)

[edit] Merge into Template:Documentation subpage

This template is part of the {{Template doc}} template set. The merge proposal was discussed and decided here. – Conrad T. Pino 06:47, 7 November 2007 (UTC)