User talk:The Minister of War/Template:Helpbox

Purpose
&#123;&#123;helpbox&#125;&#125; is a toolmaker's tool. Templates, like any other code, should be documented (as this template is on this page). For standard templates generated with divbox, &#123;&#123;helpbox&#125;&#125; provides a compact, standard link to docs.

Compare tl, which generates copyable markup which doubles as a clickable link. As useful as this is, the actual page of some templates is all but incomprehensible, as the markup source is rendered without required parameters.

Usage
Insert this template within  tags of a template for which you wish to provide documentation. The only parameter (required) is the name of the talk page on which the docs are to be found.

As this template floats right, you may wish to clear the float at some point; however, this has not yet been found necessary.


 * Note that it is completely inappropriate to attach this helpbox to templates that do not generate a  of some kind, with border and/or background. If thrown onto a page "loose", it will float all the way to the right of the main content area and appear unconnected to anything in particular.


 * Note that to achieve standard position within the documented template, &#123;&#123;helpbox&#125;&#125; must appear as the first line of template content. See Example.

Example
This is how not to use it! &rarr;





Demo This is a demonstration of an imaginary template documented with &#123;&#123;helpbox&#125;&#125;. The parameter (link) points to this page, so it is not clickable.

History
Created &mdash; Xiong&#29066; talk*  07:56, 2005 August 11 (UTC)

Minor improvements: &mdash; Xiong&#29066; talk* 14:31, 2005 August 15 (UTC)
 * Changed link symbol from i to ?
 * Cursor now changes to "help" when hovered.

Fixed display problem with white color. &mdash; Xiong&#29066; talk* 17:28, 29 December 2005 (UTC)

Parameter elimination contest
I'm pretty pleased with myself; this is the sort of tool taken for granted in more sophisticated development environments. It drives me nuts to see templates with no docs, and one of my long-term projects is to go through and document all the ones that seem worth keeping. Complementary to this is a discreet link to the docs so they may be read.

But (and is there not always a fly in the ointment?) I cannot think for the life of me how to do away with the target parameter. Given that a template's talk page is the logical and correct place for its documentation, I see no reason to allow any flexibility here. What I want is markup that "detonates" precisely when &#123;&#123;helpbox&#125;&#125; is instanced within the source of the template in question.

I should dearly love to see this solution and I offer by way of incentive to the clever wizard who manages it an Old #1 Barnstar Teeshirt or equivalent bit of ephemera. Don't forget to leave me your size. &mdash; Xiong&#29066; talk* 08:20, 2005 August 11 (UTC)


 * I attempted to fix this problem here by changing  to  . However, this hack of course does not work if the template is ever used on a talk page, rendering it useless.


 * However, lads, do not lose faith! For I believe that there may be a solution using if templates (i.e. if namespace Template, then Template talk, if namespace (main), then Talk, etc.), but I'm unsure of the coding. We'll see&mdash;I'll be looking into it. Blackcap (talk) 04:44, 5 April 2006 (UTC)
 * Well, well, well. I just came across a much, much simpler way to fix the problem, through the use of a newfound magic word: . Does just what you think it would: replace   with   and remove the   bit in my above post and the problem's gone (at least, AFAICS). *wipes hands clean* Ahhh. How satisfying. Blackcap (talk) 04:54, 5 April 2006 (UTC)
 * Bollocks, I'm wrong again (that'll teach me to jump the gun before I'm done debugging). The problem is this: now, anywhere you place the template, it'll link to that page's talk page, and not the template's talk page. I may still have to resort to if templates, but I think that I have a variety of solution. I can code it so that if you subst the helpbox into each and every template you use it on, it'll function, but then I don't reckon that that's what's wanted. The coding for that would be  (the tags have the effect of not having   be substed into , and only having it be substed into anything that  is substed into). If we're O.K. with always substing helpbox, then that's fine. Otherwise, more thinking and perhaps the iffies will be necessary. Blackcap (talk) 05:14, 5 April 2006 (UTC)