User talk:Tennessee Ernie Ford/Templates/Dungeon chest/Includes digression


 * I don't use onlyinclude much at all. I keep on getting it confused with includeonly, but if it's not showing, then I can determine which one it is. It is true that using noinclude *can* cause some spacing problems, it's generally easier to use and more wiki users will understand it. --JonTheMon 20:55, August 25, 2010 (UTC)


 * Okay, I thought I understood these things, but clearly I'm missing something substantial. Are there 3 tags? 4? What is best practice?
 * What's the difference between IncludeOnly and OnlyInclude? Is one better? Why?
 * Is there no value in NoInclude? Does it make sense to explicitly tag both things that should carried forward and those that should not?
 * Does it matter whether the tags are for templates, DPL, or article transclusion?
 * tl;dr What practices should we be using going forward (and is there a good place to document them so that no one gets as confused as I just did). &mdash;Tennessee Ernie Ford ( TEF ) 21:00, August 25, 2010 (UTC)


 * (edit conflict) noinclude / onlyinclude is really just a matter of opinion/habit, as far as I can tell. Either way, you have to know how/where to use them correctly, as you can get extra whitepsace even with onlyinclude if you put it in the wrong place.  &mdash;Dr Ishmael Diablo_the_chicken.gif 21:02, August 25, 2010 (UTC)


 * @Ernie: Transclusion &mdash;Dr Ishmael Diablo_the_chicken.gif 21:03, August 25, 2010 (UTC)


 * Still confused. The linked article suggests that they are different and says nothing at all about white space. My impression is:
 * NoInclude: stuff you want on the source, but not on the destination
 * IncludeOnly: stuff that you want to display on the destination article, but not on the source
 * OnlyInclude: stuff that you want to display on both the source and the destination.


 * The article suggests that there are rules-of-precedence, but doesn't explain them. Left on my own, I would conclude that:
 * Use NoInclude when you want most of the article to show at the destination.
 * Use OnlyIncude when you want only tiny bits to show.
 * Use IncludeOnly when the destination's needs context that the source doesn't.
 * But I don't see anything that suggests that there are best practices. What am I missing? &mdash;Tennessee Ernie Ford ( TEF ) 21:43, August 25, 2010 (UTC)


 * I should've done more searching before posting that link - Wikipedia has a more comprehensive explanation. And this is how I usually explain them:
 * Stuff wrapped in noinclude will display on the source, but will not be transcluded.
 * Stuff wrapped in includeonly will not display on the source, but will be transcluded.
 * onlyinclude acts like the 'inverse' of noinclude: when transcluding, everything outside onlyinclude will be ignored (as if it were all wrapped with noinclude). For example, both of the following are equivalent and would produce "B":
 * I don't know anything about best practices, other than what WP says. &mdash;Dr Ishmael Diablo_the_chicken.gif 22:30, August 25, 2010 (UTC)
 * I don't know anything about best practices, other than what WP says. &mdash;Dr Ishmael Diablo_the_chicken.gif 22:30, August 25, 2010 (UTC)
 * I don't know anything about best practices, other than what WP says. &mdash;Dr Ishmael Diablo_the_chicken.gif 22:30, August 25, 2010 (UTC)

include tags explained
Imagine page A transcludes Template B, i.e. page A has on it. The you open both page A and Template:B in your browser. It is possible to nest all of these tags; in that case, all of the appropriate rules apply together. (See User:M.mendel/Sandbox-include.)
 * 1) Everything on template B is shown on page A, with the following exceptions:
 * 2) Everything tagged noinclude is not shown on page A.
 * 3) Everything tagged includeonly is not shown on Template:B.
 * 4) If at least one onlyinclude tag is present, rule 1 does not apply; instead, only what is tagged onlyinclude is shown on page A.

The trick with whitespace is that if you have a line break at the end of a template, it may combine with a line break in the source to make an empty line = a paragraph break; if templates include other templates, sometimes these add up. These hidden line breaks can occur if you put the &lt;/onlyinclude> on a line by itself (the line break before gets transcluded), or if you have a linebreak after the final &lt;/noinclude>, which is insidious because it's hard to see. If you put such a template on a line by itself, the tanscluding page will have an empty line = paragraph break; if the template is used on the last line of another template, with a line break past it, you may have 2 empty lines, and sometimes more. (Think about how the different paragraph breaks in User:M.mendel/Sandbox-include come to pass; now imagine how difficult that might be if there were line breaks you did not see as easily.)

Generally, I find that it's easier to keep track if the transcluded content is always in &lt;onlyinclude> because then everything that gets transcluded is "out in the open". Sometimes somebody adds a category at the bottom or expands the documentation with no regard for the include tags; with &lt;onlyinclude>, that's perfectly ok, but with &lt;nowiki>, stuff tends to bleed into the trancluding pages because editors do not realize that the end of the page (after the nowiki section) is getting transcluded, too. -- ◄mendel► 15:08, August 26, 2010 (UTC)

Examples:
I want to move that to Forum:Coding anyway, once any remaining questions have surfaced. -- ◄mendel► 20:53, August 26, 2010 (UTC)

More discussion
. &mdash;Tennessee Ernie Ford ( TEF ) 01:47, August 27, 2010 (UTC)
 * So, I think I already knew these things (from earlier in this convo). What I didn't know is why use one method of tagging over another, with the exception of Mendel's preference for onlyinclude. (I still don't understand why it doesn't make sense to explicitly tag both includes and excludes; seems even less likely to to get confused down the road.) At this point, it seems to me that we should decide upon a guideline for this wiki, so that it's more likely that we're in synch instead of stepping on each other's
 * The reason to use onlyinclude is that the other method misleads people; since you think it is possible to "explicitly tag both includes and excludes", you have already been so misled. You can either tag one or the other, but not both. -- ◄mendel► 07:40, August 27, 2010 (UTC)


 * Ok, you've managed to confuse me again. Your notes sound like you can tag everything. Unless you screw up the tags (e.g. as in whoops ), why wouldn't you want to put every bit of code on a source page (template or article) into one of the three tags?


 * Everything tagged noinclude is not shown on page A.
 * Isn't that explicitly tagging what is excluded?


 * If at least one onlyinclude tag is present, rule 1 does not apply; instead, only what is tagged onlyinclude is shown on page A.
 * Doesn't that explicitly tag what is included?


 * Everything tagged includeonly is not shown on Template:B.
 * Doesn't that explicitly tag items as a converse (definitively not shown in source, definitively shown at destination)


 * The reason I'm harping on this: tagging everything clues in future editors to the original intent.  demonstrates clearly which parts the originators meant to transclude and which not. In contrast,   leaves ambiguous about the plans the editors had for that.


 * Regardless, I think this conversation suggests that we should start making better use of commenting, which is an even surer way of 'splainin' the way it spozed to be. &mdash;Tennessee Ernie Ford ( TEF ) 10:08, August 27, 2010 (UTC)


 * Mendel's point is that if you use [onlyinclude], then there's no point or reason to use [noinclude] at all. Likewise, if you use [noinclude], then there's no reason to use [onlyinclude] with it.  Using both together is what would "mislead" people into thinking it was required to explicitly tag both types of sections.  You either tag the sections you want included, or you tag the sections you don't want included, you don't do both.  The practical difference, which you can see with how the 'x' is treated in mendel's examples, is:
 * Using [noinclude] means that everything outside [noinclude] gets included.
 * Using [onlyinclude] means that everything outside [onlyinclude] does not get included.
 * Mendel's other point is that there's less chance for "mistakes" when you use [onlyinclude], since you are designating exactly what you want included. With [noinclude], you have to be more careful that you are getting every little bit that you don't want included.
 * ([includeonly] doesn't affect which sections of the page get included, it's only used to hide things on the source page, so you would still use it with either of these approaches.) &mdash;Dr Ishmael Diablo_the_chicken.gif 13:01, August 27, 2010 (UTC)


 * Ah! That makes more sense (than what I thought was being said). That makes it a philosophical question, not a technical one. I'm also suggesting that such over-tagging is useful. Here are 4 equivalent lines of wiki-ish code that should transclude/not the same: Which will be easier for us to deconstruct two years later when we want to review/change? 
 * [show]this[/show] (not that)
 * [show]this[/show][noshow] (not that)[/noshow]
 * <1-- begin text to show -->[show]this[/show]<1-- end text to show --> [noshow] (not that)[/noshow]
 * <1-- begin text to show -->[show]this[/show]<1-- end text to show --> <1-- begin text to not show --> (not that) <1-- end text to not show -->


 * Personally, I think #2 is the easiest to demonstrate what the original editor(s) intended. Obviously, it doesn't matter much for short text and for relatively static templates. It might matter a great deal for more interesting cases: transclusion of sub-pages, DPL look-ups, ..., especially if the various bits are scattered across several URLs. My question is: what's the best way to document that? &mdash;Tennessee Ernie Ford ( TEF ) 17:08, August 27, 2010 (UTC)


 * Your #2 misleads. The &lt;noinclude> (called "noshow" by you) is meaningless (in the sense of: has no technical function) if [show] is &lt;onlyinclude>; and if the [show] is &lt;includeonly>, then it is meaningless as pertains to transclusion. These misunderstandings are subtle; they will reaffirm themselves most times they are used because they seem to work; but when a bug crops up, this affirmed misunderstanding will prevent identifying the bug unless the meaning of the tags is relearned (as you are relearning them now, and see the effort it takes?).
 * If you had not been exposed to this dual markup, but only seen &lt;onlyinclude>, you would readily understand that it marks that which is to be transcluded, and everything else is not. It is not necessary to mark everything (or even anything) else.
 * In my fourth example, everything except for the "x" seems to be tagged, right? Yet there is a line break between and, and it may be of importance to be aware of whether this is included or not. With &lt;onlyinclude>, you are aware that it is not because it would occur after &lt;/onlyinclude>.
 * Using &lt;onlyinclude> explicitly tags the included content. There are no ifs, buts or hidden things about it; the transcluded content is sharply defined, and that is often more important than to sharply define that which is not included, because if you mess the latter up, it only affects the page you are currently editing, and you'll see any errors in that directly. (You do need to learn to see the line breaks that are there if you put the onlyinclude tags on lines of their own, but that is all.) The only exception to this sharp definition is &lt;noinclude>d content inside the &lt;onlyinclude>, and that is hard to miss.
 * There is seldom a reason for me to use includeonly tags; I like to see the actual template output atop the documentation even if it is full of omitted lines or ungiven ; the only reason to includeonly this wholly (it is ok to includeonly auto-categories ofc) is to avoid ugly errors (mostly in conjunction with #expr:) if they cannot be fixed by choosing sensible defaults for the missing parameters (choosing defaults might be wise to avoid if you want to draw a template user's attention to the fact that he has not provided vital parameters).
 * So, yes, this is a "philosophical" distinction, but it has an impact on how well to debug and, ultimately, how bug-free our templates are that is quite practical. -- ◄mendel► 17:48, August 27, 2010 (UTC)


 * I'm suggesting a philosophy about commenting using excess-tagging; you're saying the tagging is excessive and could lead to debugging trouble. &mdash; is that a reasonably summary? (If it is, then we disagree, but (a) I'm probably going to follow your lead b/c I don't have any experience in this and you do and (b) I don't feel that strongly about it...I'm mostly blathering on in the hopes that I'll grok this better.)


 * And, erm, I'm not "relearning" anything &mdash; this is all new to me. Every wiki seems to use all three types of tags and (prior to your explanation above), no one has suggested there's fine and better ways of implementing them. And, as you noted about the DragonAge wiki templates, not everyone's implementation is good. So, my prior examples all have equal weight and their usage is all over the map.


 * In other words, thank you for spending the extra time helping me to understand how you would like templates here to work and why. &mdash;Tennessee Ernie Ford ( TEF ) 20:28, August 27, 2010 (UTC)
 * Well, the "onlyinclude" tag was introduced later than the other two, if I recall correctly, so there'd be a body of work to found the slightly inferior tradition.
 * I wouldn't necessarily feel strongly about this (though I am completely convinced that one is better than the other) -- certainly not strongly enough to rework every template; I felt more strongly about | being available as pipe symbol and not as !-icon --; recall that my initial remark was I suggest making a habit of using &lt;onlyinclude> instead of &lt;noinclude> (they are very different!), and it sort of spiralled into a WoT because I haven't figured out how to clarify the subtle difference succinctly and convincingly. Which would be the prerequisite to putting this on Forum:Coding. Hmm. -- ◄mendel► 05:22, August 28, 2010 (UTC)


 * You appear to feel strongly enough to keep correcting me ;-) As I mentioned, you have more experience with this than I and I'm willing to follow your lead, at least until I can pretend to know enough to disagree more knowledgeably. I think the following is reasonable to convey to an official discussion:
 * While there are three possible tags, this wiki encourages the use of a specific one
 * Why? Well, trust us, but if you want the gory details, see...
 * You will find a lot of older templates using different syntax; soz &mdash; those were written before we had our act together on standards.
 * Regardless, take some time to document the intended use/display of the template/transclusion, so that none of us who follow in your footsteps have to hunt you down and eat your mRNA to understand what you did.
 * In the meantime, aside from the inclusion tags, is the template that started this off ready for prime time? (I want to do something similar with LoDs &mdash; they, too, are a mess of inconsistency.) &mdash;Tennessee Ernie Ford ( TEF ) 05:35, August 28, 2010 (UTC)
 * I keep correcting you because I like you and would hate for you to be wrong.
 * Re: the docs, we've been switching to a convention where docs that go beyong 3 lines or so are documented on a seperate page, usually at Template:template/doc . There's a also a category for those pages, and I arranged the style for ;definitions: to allow for italic in the first part to not be bold, which is great for usage explanations. -- ◄mendel► 08:37, August 28, 2010 (UTC)


 * "While there are three possible tags, this wiki encourages the use of a specific one" <-- Now that is misleading. [includeonly] should not be lumped with the other two in this, because, as I've been pointing out, it does not affect what gets included.  All it does is hide stuff on the source page, and it can be used alongside both of the others.  &mdash;Dr Ishmael Diablo_the_chicken.gif 13:09, August 28, 2010 (UTC)

(Reset indent) is the template that started this off ready for prime time? -- You're not using it on that many pages; you'll see when you use it whether it is bug-free; if you'd like some sort of external confirmation that it'd be good to use, you should ask on the community portal talk. (Looking at the example, maybe the drops texts should also be in the vertical middle?) -- ◄mendel► 08:33, August 28, 2010 (UTC)