Documentation

{{subst:Doctl}} inserts boilerplate for consistent documentation of a template on its own Talk page. Once inserted, it must be edited to include specific information.

Usage

{{subst:doctl}}

Save the Talk page. Do not use preview. You must save in order to make the wikitext with the substitutions available for editing.
Re-edit the Talk page. Below Documentation give a clear statement of the purpose of the template you are documenting. In the section Usage adjust the number of parameters and explain what each one does. If your template takes no parameters, delete that word. Note that the Usage section makes use of HTML entities; be careful editing between them. Finally edit or remove the Example section. Keep the self-reference in See also, it offers links to the edit history etc.

Example

This talk page is an example how it works.

Use the talk page of a sandbox like Template:X4(edit talk links history) to check the unedited output of {{subst:doctl}}.

Discussion

Add issues below as you see fit.

History

Created; please comment. — Xiongtalk 08:32, 2005 Apr 4 (UTC)

Right at the moment, this template is broken; I did not properly manage the interaction between HTML, wiki markup, and the parameter call. I will try to fix it now. — Xiong 熊 talk 21:34, 2005 Apr 15 (UTC)

Caved in and used entities to get around the interaction between <nowiki> and subst:. Didn't want to do it that way; I'd rather keep the markup clean. But fixed and ugly is better than broken and beautiful. This template works fine now. — Xiong 熊 talk 14:59, 2005 Apr 19 (UTC)

TFD'd

This template was listed on WP:TFD. The decision was to keep this template. Please see Wikipedia:Templates for deletion/Log/Not deleted for more information. -Frazzydee|✍ 00:45, 14 Apr 2005 (UTC)

What it makes

The template generates the text inside the following box:

{{Doctl}}

Removed in inclusion to not disturb TOC _→AzaToth 20:41, 9 December 2005 (UTC)[reply]

subst magic

Because this template is made only to subst, I added some new subst magic, for example is creator signature automagically expanded, also if no argument is added, relevant information is substed in place _→AzaToth 20:56, 4 December 2005 (UTC)[reply]

The signature magic isn't used anymore, a simple initial self-reference in #See_also offers a link to the edit history etc. Omniplex 14:20, 16 March 2006 (UTC)[reply]

subst:, lcfirst:, <div style="display: none">, <includeonly>, and table-class magic removed, let's stick to KISS and a minimal outline for a documentation + discussion talk page. And now I'll lookup your old history signature magic, I need it elsewhere.. ;-) Omniplex 04:07, 19 March 2006 (UTC)[reply]

I changed most of it back now to keep KISS on the resulting page using this template. Also it's important the Documentation and Discussion is level 1 heading, so that "section=new" creates a section as a child of discussion and not as a sibling. _→AzaToth 13:54, 19 March 2006 (UTC)[reply]

Well, that was mostly a bad idea:

You don't need tons of includeonly-protected subst if you just put the complete code in includeonly. That makes it much more readable.
Yes you do, or you could perhaps type: {{subst:<noinclude></noinclude>Foo}}, havn't checked that.
As you see a global includeonly without subst magic does the trick. Fixing the numbers here, after your comments all my # ended up as 1 ;-)
You don't need CSS magic with no effect on legacy brwowsers if you use includeonly globally. I want doctl to work on my browser, too.
That's only for the direct display when you display it directly, not using it as a template.
Sure, but now unnecessary, that's why we have includeonly. WP:HIDE is always an ugly kludge.
I dislike void sections where the complete content are subsections. It's good enough to state the purpose directly below documentation.
That might be right, I just changed it back because your version stated something like {{foo}} - purpose, sounded wrong.
Should be okay now, the output now directly says what you had as XHTML comment: Put me in a sentence.
The compactToC style is ugly, sweet and short and no nonsense is better. Folks wanting more elaborated ToCs can add them manually.
Then change that template instead if you disslike how it look like.
It's more straight forward to simply not use it. Maybe others like it, they can add it not only here after doctl did its magic.
— and · don't work for me, I've removed that again, it's not essential.
That's strange, you must be using a really old legacy browser then.
Yes, Netscape navigator without UTF-8 support, no big deal, but the main reason why I started Lcs/Lps/Lts, see Template:Lts(edit talk links history).
Who needs a border for a simple table with the example, and if (s)he needs it, why can't (s)he add border="1" or similar manually?
Often it's needed so people can differ which example is an example (are there two rows or one? etc...) {{easytable}} is an adaptation of prettytable (wikitable), because said style doesn't work for nested tables.
ACK, but somebody complained about easytable vs. wikitable. How about border="1"? I could simply remove it manually when I don't need it.
OTOH the X4 example cries for valign="top" in the code column, added again.
X4?
See #Example or Template talk:X4, that's how I test doctl.
IMO there should never be more than one h1 header on a page, but I kept that for the moment reflecting its ugliness here. It's clear that posting won't add h3 sections below discussion automatically, OTOH some manual cleanup when necessary is no problem as you see here, where I've now modified all headers to your style. But they are ugly.
Template talk pages is an exception of that rule. see WP:TPG
Okay, we still have that, and apparently they use <h1><big> or a similar trick for the "real" header, good enough.
There's no point in subst:PAGENAME, the server will survive it to evaluate a PAGENAME. With subst:PAGENAME renaming templates or copying modified doctl output to other templates is much harder. That's bogus, it only obfuscates the code with no real advantage, quite the contrary.
the reason was that people wanted a static output, but perhaps that have changed.
Dynamic is better for renaming or copy & paste. In the Villagepumpppages episode Locke Cole even replaced Wikipedia by {{ns:Project}}, that impressed me... ;-)
lcfirst is okay, and maybe subst:lcfirst makes sense, I don't know how it's implemented.
Lets say it's implemented :) _→AzaToth 15:36, 19 March 2006 (UTC)[reply]
Okay, and removing or inserting compactToC manually is no real issue, dito border=1, but the other points are somewhat critical from my POV.

Omniplex 15:19, 19 March 2006 (UTC)[reply]

Omniplex 16:11, 19 March 2006 (UTC)[reply]

Remaining ToC and table issues

Generally acceptable now, but I'd still very much prefer to get rid of used unessential decorative templates: (1) wikitable or easytable, whatever they do, simply border="1" should be good enough if you want borders. ~~One of you doesn't, or~~ I don't see it with my legacy browser. (2) CompactToC is a royal PITA, it makes no sense without inserting magic word __TOC__ below discussion, that's unnecesary decoration only confusing users who don't know the ToC magic. Stick to the defaults where possible. A common layout as on almost all pages is a feature and no bug. IOU two Euro cents, Omniplex 17:18, 19 March 2006 (UTC)[reply]

"One of you" was you, I thought it was the other guy with easytable vs. wikitable. Fine now, I don't get any border, and whatever you get with CSS is none of my business <gd&r>. But the ToC is still utter dubious. Omniplex 17:43, 19 March 2006 (UTC)[reply]

The reason for {{compactDocToc}} is that some templates (for example {{Infobox Language}}) contains a rather large ammount of documentation and a large ammount of discussion. A normal TOC at the top usually there takes up a couple of frames, and it was then custom to have the TOC after the documentation, because the documentation shuld always be at the definite top of the page, no one should need to scroll down to that. I added the tiny TOC so people easly could jump directly to the discussion instead of need to scroll down etc. _→AzaToth 18:11, 19 March 2006 (UTC)[reply]

Makes sense as you explain it. But I typically start out with empty talk pages, where I'd now remove these two lines manually - no big deal, let's test it as is for some weeks. Omniplex 18:31, 19 March 2006 (UTC)[reply]

Pointer for AzaToth, the · {{Lt}} vs. {{Lts}} issue was hidden in #5. Also "discussed" in the Lts edit history... ;-) Omniplex 19:29, 19 March 2006 (UTC)[reply]

middot

Thanks, but my "mozilla 3" monster is unfortunately too old for Unicode. Anything that's no symbolic HTML 3.2 entity cannot work, and even those fail, because the server translates them to Unicode on the fly, e.g. &lsaquo; ‹ or ² ² arrive as Unicode here. Fortunately the server doesn't touch   - otherwise I'd be lost. Omniplex 20:33, 22 March 2006 (UTC)[reply]

Sadly for you that mediawiki is designed to use utf-8. You havn't thought of getting a new browser? _→AzaToth 23:29, 22 March 2006 (UTC)[reply]

UTF-8 is the best they could do. In theory their software could offer a kind of legacy skin, where it leaves HTML 3.2 entities as is, dito u+00A0 up to u+00FF (printable Latin-1), presenting anything else as decimal NCR Ā etc., because old browsers can handle this mechanism. I can't afford a system upgrade (hardware and OS) at the moment (money and time), I could use Netscape 4.x. But that beast is already too fat (slow + buggy). Funny thing, my local pc-multilingual-850+euro charset has middot, and as shown at this link it would work with four tested browsers, but not as UTF-8. Omniplex 03:41, 23 March 2006 (UTC)[reply]

I'm all for backwards compatibility usually, but this is really really ugly. Is it actually breaking your browser? Or just not rendering nicely? —Locke Cole • t • c 19:44, 5 April 2006 (UTC)[reply]

No crash, only excessively ugly. If you don't like <tt>|</tt> as separator maybe try a (monospace) comma, or a (small) non-breaking space. I'm fighting with the unnecessary · everywhere:

It's the reason why I started {{Lts}}, {{Lps}}, {{Lcs}}, plus some stuff here for {{doctl}}. BTW, parts of your signature also appear as gibberish on my browser. For related display tricks see Tlx. -- Omniplex 21:49, 5 April 2006 (UTC)[reply]

Have you tried this? Firefox 1.5.0.1 for OS/2. Firefox isn't very bulky. —Locke Cole • t • c 22:08, 5 April 2006 (UTC)[reply]

I've looked at one of its mozilla-predecessors, at that time the compressed archive was 40MB and more than I had as entire free harddisk space (excl. old DOS 8+3 FAT partitions), and it was tested only for Warp 4 (my Warp 3 connect is a bastard vintage '94). I got used to my good old "mozilla 3" monster, knowing all its bugs and features: e.g. the complete binary is only 2 MB. -- Omniplex 22:22, 5 April 2006 (UTC)[reply]

And I thought my comp was getting old :) _→AzaToth 23:03, 5 April 2006 (UTC)[reply]

<g> - we're apparently all not up to hacking the software to keep HTML 3.2 entities as they are. But if you don't like the vertical bar as separator - maybe because it's a tiny bit overused here - I'm sure you find something working without UTF-8, like comma or nbsp. -- Omniplex 00:07, 6 April 2006 (UTC)[reply]

Seriously, install Windows '98 (it's dirt cheap now) or NT4 (also dirt cheap). Firefox should definitely work fine in either of those (well, not sure on NT4; but can't think of why it wouldn't). Or try and find a distro of *nix that'll run on your beast. :P This template being ugly sucks. —Locke Cole • t • c 23:28, 5 April 2006 (UTC)[reply]

OS/S Warp 3 '94 is seriously better than any Win ME/98/95. W2K (NT5) is okay, but all my tools are based on REXX, the REXX support was the very reason why I bought OS/2 (I like REXX since '82). My next box will be Linux or another *NIX, anything from Redmond only if somebody pays me for it. -- Omniplex 00:07, 6 April 2006 (UTC)[reply]

Four recommended improvements

Looking at some of the other template talk pages, I've noticed that the template name is often made bold, as well as an expansion of the name. I'm reworking this one, for example:

{{CompactDocToc}} is a shorter alternative to {{subst:doctl}}, both commonly used on template talk pages. CompactDocToc, short for compact documentation table of contents, is currently included within doctl, as well.

Having the "History" section in "Discussion" is confusing. I see that Omniplex removed it in March, but I don't understand the justification. I guess a combination of "Discussion" and "See also" is good enough to replace "History"?

The "history" was a part of the "docu", like "example". With {{Lts}} or similar in "see also" there is a direct link from the talk page to the template's edit history, a separate "history" subsection was unnecessary. -- Omniplex 19:55, 26 May 2006 (UTC)[reply]

On the WP:SUB guideline, I recently suggested adding HTML comments to the top of frequently-subst'd templates (e.g. ). Thoughts?

It seems kind of odd that m:Template:Doctl doesn't include compactDocToc. Once the above issues are resolved, shall we recopy this template over to Meta? I've looked at some of the sister project practices of sharing and copying templates, but haven't found any policies or guidelines. --J. J. 19:00, 25 May 2006 (UTC)[reply]

Sure, get them in sync. {{Tl}}, {{Tlx}}, and {{Lts}} are also available on Meta. For {{CompactDocToc}} and {{Tlsp}} I'm not sure. "Doctl"-style docu isn't used much on Meta. Once you got the taste of it you probably do it manually from scratch anyway, only typing the line "Add issues below as you see fit" should really get its own template... :-) -- Omniplex 19:55, 26 May 2006 (UTC)[reply]