View source for Help:Labeled section transclusion

{{BattleTechWiki how-to|H:LST}} 

'''Labeled Section Transclusion''' ([[mw:Extension:Labeled Section Transclusion|LST]]) offers two basic ways to specify a "section" of a [[help:page|page]] for [[BattleTechWiki:transclusion|transclusion]]. One way uses the page name and a '''heading''' (section title, as seen on the rendered page). The other way enables an arbitrary "section" for transclusion, but it requires markup first in order to add the '''label'''.

Three functions can transclude a section from a given [[BTW:Page name|page name]].
* <kbd>{<nowiki />{#section''':'''''page&nbsp;name''|'''''label'''''}}</kbd> (a labeled section)
* <kbd>{<nowiki />{#section'''-x:'''''page&nbsp;name''|'''''label'''''}}</kbd> (all except that labeled section)
* <kbd>{<nowiki />{#section'''-h:'''''page&nbsp;name''|'''''heading'''''}}</kbd> (a normal section)

Note that there are also equivalent names for these functions, the base names being <code>#lst</code>, <code>#lstx</code>, and <code>#lsth</code>.

To prepare an arbitrary "section" for a labeled section transclusion, mark it with ''begin'' and ''end'' attributes inside {{tag|section|s}} tags that contain your '''''label''''':
:{{xtag|section|single|params=begin=''label''}} and {{xtag|section|single|params=end=''label''}} 

Compared to LST transclusion, [[BTW:Transclusion#Partial transclusion|partial transclusion]] markup cannot be ''labeled'', and thus the source page cannot have one set of its sections transcluded to one page while having also a different set for another page.  A page marked up with partial transclusion tags only, will always transclude the same.  But LST and partial transclusion can work together on the same page.

These LST functions take additional parameters, as explained below. {{section link||Example pages}} provides search links for the articles that currently employ LST so you can see how they are using it.

== Functions summary ==

This section summarizes the three parser functions in the Labeled Section Transclusion extension.

{{break}}
Syntax: {<nowiki />{'''function''': ''fullpagename'' | ''section'' | ''range''/''change''}}
{| class="wikitable"
!colspan=2| Parameter!!Parsing entity it identifies
|-
|'''1'''
|[[BattleTechWiki:Page name|Fullpagename]]
|'''Source page'''. The only required argument. Type it in, or use [[help:magic words#Variables|variables like {<nowiki />{FULLPAGENAME}}]], (but not [[help:link#Subpage links|subpage linking with <kbd>../</kbd>]]).
|-
|'''2'''
| Section
| '''''Label''''' ("labeled section"), or '''''heading''''' (section title), to transclude. Optional parameter. If a label, it must have been added and saved first.  
|-
|'''3'''
|Range|| '''Final section''' in a contiguous series of headings or labels to transclude. Optional. 
* <kbd>#section</kbd> transcludes the final section.  
* <kbd>#section-h</kbd> does not transclude the final section. 
* <kbd>#section-x</kbd> does not take a range.
|-
|'''3'''
|Change|| '''Replacement wikitext.''' Only <kbd>#lstx</kbd> can rewrite a labeled section during transclusion. Optional.
|}

It is not possible to pass [[Help:Template#Parameters|template parameters]] to the transcluded section or page but the code of the page can use [[Help:Magic words|magic words]] like <code><nowiki>{{PAGENAME}}</nowiki></code> to test where it is and behave differently.

{{break}}

{| class="wikitable"
|+ style="text-align: left;" |Behaviors
|-
! width=6em| Parser Function !! Alias !! Description
|-
| <kbd>#lst</kbd> || <kbd>#section</kbd> || Transclude a ''label'' found inside {{tag|section|s}} tags. Honors transclusion tags. Default is entire page. If the label is not found, transclude nothing.
|-
| <kbd>#lstx</kbd> || <kbd>#section-x</kbd> || Transclude entire page, but ''exclude'' a label. Blind to headings.  Honors transclusion tags. Default is entire page.  If the label is not found, transclude entire page.
|-
| <kbd>#lsth</kbd> || <kbd>#section-h</kbd> || Transclude a ''heading'' (section title).  Blind to labels. ''Does not'' honor transclusion tags.{{sup|&dagger;}} Defaults to the lead section.   If the heading is not found, transclude nothing.
|}
:&dagger;{{spaces|2}}<kbd>#section-h</kbd> makes its target look the same as its source. On the ''source'' page 
:*&lt;noinclude> displays its content
:*&lt;onlyinclude> displays its content
:*&lt;[[BTW:Transclusion#Markup|includeonly]]<nowiki />> ''does not'' display its content
:So <kbd>#section-h</kbd> must not render {{tag|includeonly|o}} content on the ''target'' page.

{{break}}

LST {{xtag|section|s}} tags behavior:
* The ''end'' tag is not required.  When only a ''begin'' tag is found, it goes to the end of the page.
* The same label can mark several ''begin/end'' sections. A range is then everything from the first ''begin'' to last ''end''. 
* Different labels can overlap.  They can also nest.
* Cannot be placed by a transclusion, but instead must be present on the page as saved in the database. See {{section link||No template}} below. 

LST transclusion options:
* It can be previewed. 
* The target page can be the source page ''itself''.
* It can be substituted.  See {{section link||Substitution}} below.

Standard syntax applies:
* Generous whitespace is allowed: <kbd>{{nowrap|{<nowiki />{ {{spaces|1}}#lst:{{spaces|2}}''namespace'':{{spaces|2}}''pagename''{{spaces|2}}{{!}}{{spaces|2}}''section''{{spaces|2}}}}}}</kbd>
* An unspaced : colon follows the parser function name.
* In tags no spaces around the = sign of the label (attribute): <kbd>begin=''label''</kbd> 
* In tags space is optional before the / slash: <kbd>&lt;section end=''label'' /></kbd>

Common usage errors.
* {{font color|red|Template loop detected:}} preview transcluding a transclusion in the saved version?
* Cite errors.  You must have the full definition of a named reference on any page that this "multiply-cited-reference shortcut" is needed.
* To render transcluding footnotes, you must tag where they go on the page.

==Markup==
No markup of the source page is needed if only section titles are used to specify the transclusion.  This is the case with <kbd>#section-h</kbd>.  

For labeling a section for LST transclusion use the following markup. 

===Section marking===
Markup your section boundaries in the source page using two, singular, {{xtag|section|s}} tags; for example, to label a section "chapter1":

 {{tag|section|s|params=begin=chapter1}}this is a chapter{{tag|section|s|params=end=chapter1}}

Note this is not normal opening-tag, closing-tag HTML. In HTML {{tag|section}} is invalid. This parser tag, {{tag|section|s}}, is incompatible with an HTML element because MediaWiki markup employs a unique parser tag, added just for the Labeled Section Transclusion extension. 

===Section transclusion===
Use the parser function <code>#section</code> to transclude the section. For example, to transclude section labeled ''chapter1'' from a page called ''articleX'':

<syntaxhighlight lang="text">{{#section:ArticleX|chapter1}}</syntaxhighlight >

===Transclude the page but exclude the section===
To transclude a page, but exclude a specified section, use the <code>#section-x</code> parser function:

 <nowiki>{{#</nowiki>section-x:''fullpagename''|''label''}}

or

 <nowiki>{{#</nowiki>section-x:''fullpagename''|''heading''}}

Optionally, you may add replacement text to the excluded section.

 <nowiki>{{#</nowiki>section-x:''fullpagename''|''label''|''replacement text''}}

Example:
<syntaxhighlight lang="wikitext">{{#section-x:articleX|chapter1|See chapter 1 in [[articleX]].}}</syntaxhighlight>

The replacement text will appear in the area where the section is skipped (excluded).

===Dealing with stray whitespace===
By default, <code>#section</code> will include all the whitespace in the section, which can lead to issues if you're trying to transclude the section into a different article. To solve this, make use of the fact that the {{pf|if}} parser function trims its inputs, e.g.

<syntaxhighlight lang="text">{{#if:1|{{#section:ArticleX|chapter1}}}}</syntaxhighlight>

This will get rid of both leading and trailing whitespace, and the article will render as intended. Because you are nesting templates, it will double the post-expand include size of the excerpt, which can present a problem on longer pages, so you may wish to edit the source page to wrap the content you want to include, without the whitespace, in {{tag|onlyinclude}} tags instead. You can also use the {{tl|trim}} template instead of {{pf|if|1}}, but because it is just a wrapper for the {{pf|if|1}} technique above, it results in a tripling of the post-expand include size.

==Other functions==
===Discontiguous sections===
It is possible to have multiple sections with the same name; in this case, every section with that name will be included/excluded. This is especially useful to mark various discussions.

===Section ranges===
These functions can transclude the whole page, so they have the two, optional argument to specify behaviours: 1) a name-tagged section or heading-title, 2) a range of such named section-tags or section titles, and 3) replacement content for a named section. 
*<code><nowiki>{{#section:articleX|chapter1|chapter3}}</nowiki></code> includes everything from the beginning of chapter 1 to the end of chapter 3. This allows using empty marker pairs to mark one end of the section, possibly in a template.
*<code><nowiki>{{#section-h:articleX|chapter1|chapter3}}</nowiki></code> includes content of chapter1, heading and content of chapter 2.
*<code><nowiki>{{#section-x:articleX|chapter1|chapter3}}</nowiki></code> replaces chapter1 heading and content with the word "chapter3".

===Substitution===
Instead of transcluding every time, to "transclude" once (to copy), use [[help:substitution|substitution]]:
: <kbd>{<nowiki />{subst:{<nowiki />{#section...}}}}</kbd>

For example to archive old [[Help:talk|talk]] on your talk page, you can copy it to an archive page, then delete it, all using LST:
# Put {{tag|section|s|params=begin=archive}} at the beginning of the section you want to archive and {{tag|section|s|params=end=archive}} at the end. (We use "archive" for the label, but any label will do.).  This section can be anywhere, and it can be multiple sections.
# Save those change to your talk page.
# Create a new archive page.  Put <kbd>{<nowiki />{subst:#section:User talk:''pagename''|archive}}</kbd>.
# Save that archive page.  The old talk is copied over to it. The transclusion disappears because it was substituted.
# Edit your talk page again.  Replace all the wikitext on the entire page with <kbd>{<nowiki />{subst:#section-x:User talk:''username''|archive}}</kbd>.  The ''database page'' will be transcluded, minus the exact same wikitext in the saved archive, and minus the section tags (which we had labeled "archive").

When using substitution to transclude content on BattleTechWiki, please use the edit summary to apply [[BattleTechWiki:Copyrights#Reusers.27_rights_and_obligations|reusers' rights and obligations]].  This applies to any substantial content, and not just article contents.

==No template==

Currently, no template can facilitate this LST markup because it is necessary to use #tag in order to [[mw:Manual:Tag extensions#How do I render wikitext in my extension? | "preSaveTransform"]] magic words inside a tag of any kind.  For the proper attempt see (the non-functioning) {{tl|section}}.

The only way to [[w:eval|evaluate]] template arguments ''inside a tag'' (because of the parsing order) is [[help:magic words#Formatting|#tag]]. LST would need (template) evaluation of the label as the section tag is generated:
<syntaxhighlight lang="wikitext">{{ #tag: section | {{{1}}} }}</syntaxhighlight>

But #tag only produces [[w:XML|XML]]-like (balanced, open-closed, start-end, pairs of) tags, while LST will use a singular, explicitly self closing, tag. So LST tags cannot be generated by any template. Compare actual (only in effect) output:
 
 {{#tag:section|''content''|begin=''label''}<nowiki />} &rarr; 
 {{ font color || yellow | &lt; }}section begin=''label''> ''content'' {{ font color || yellow | &lt;/}}section>  {{cross}}

with the requested output: 

 &lt;section begin=''label'' {{ font color || yellow | /> }} ''content'' &lt;section end=''label'' {{ font color || yellow | /> }}

== See also ==
* [[:mw:Extension:Labeled Section Transclusion]]
* [[Help:Transclusion#Drawbacks]]
=== Templates ===
* {{tl|Excerpt}}
* {{tl|Section transclude}}
* {{tl|R}} - a referencing/citation template optionally taking advange of labeled section transclusion to mark context sections