Help:Transclusion
Purpose and functionality
The technique of transclusion is designed to allow for including (part of) a page in another one without having to resort to maintenance-heavy copy-and-paste methods.
On $\mathsf{Pr} \infty \mathsf{fWiki}$, this technique is used to:
- Shorten long pages to make editing them easier.
- Separating multiple proofs cq. definitions of one theorem cq. concept to allow for maximally accurate internal reference while retaining a readable presentation.
Good examples of the last two uses are the Cantor-Bernstein-Schröder Theorem and Definition:Connected (Topology)/Topological Space.
Transcluding and Subpages
The transclusion method as practised on $\mathsf{Pr} \infty \mathsf{fWiki}$ deals almost exclusively with subpages.
These are simply pages whose title contains a forward slash, like a folder structure. For example:
is a subpage of Definition:Connected (Topology).
The most important feature of a subpage is that it has a link to its parent page (or pages in case of nested subpages) right at the top.
This rule is however not universal - for example, a page may be transcluded onto several different pages, in which case it is better to retain it as a separate entity.
Technical instructions
There are two parts in setting up the transclusion:
- Preparing a page for transclusion
- Transcluding the page
which are explained below.
Preparing for transclusion
To allow for meaningful use of transclusion, the page that is to be transcluded needs to have an indication as to what part of it one wants to transclude.
For example, it is undesirable that the "Definition" or "Theorem" header of a page is also transcluded.
This is accomplished by means of the <onlyinclude> and </onlyinclude> tags.
Simply enclose the section of the page that you would like to transclude in these tags, and you're all set to go.
Thus, for example, to transclude one of the proofs of a theorem that has been relegated to a subpage, we would place the tags as follows:
... Theorem statement
== Proof ==
<onlyinclude>
... Here comes
the actual proof.
{{qed}}
</onlyinclude>
... Further sections like "Also see" and "Sources"
A drawback of this method is that a page can be transcluded in only one way. This issue is very minor though, and in almost all situations this poses no problem.
Transcluding the page
In instances of transclusion on $\mathsf{Pr} \infty \mathsf{fWiki}$, only whole sections are transcluded.
Thus, they naturally come with a section heading.
So as to provide a means to access the whole page from which the material is transcluded, this section heading should contain a link to it.
Thus, we come to the following mould for including a transcluded section:
== [[Name of Transcluded Page|Title of section]] ==
{{:Name of Transcluded Page}}
where the {{:Name of Transcluded Page}} part is the actual magic that transcludes the page.
Of course, the heading may be adjusted to different levels (that is, more equals signs) if such is appropriate.
Because the onlyinclude tags are placed on the empty lines preceding and succeeding the part to be transcluded, some blank lines can be omitted.
That is, the desired spacing based on house style, which one would normally achieve by the following lines:
== [[Name of Transcluded Page|Title of section]] ==
{{:Name of Transcluded Page}}
== Next section ==
is achieved by omitting the preceding and succeeding empty lines:
== [[Name of Transcluded Page|Title of section]] ==
{{:Name of Transcluded Page}}
== Next section ==
When to transclude
As mentioned in the beginning of this article, the transclusion mechanism is used to attain unambiguous reference within $\mathsf{Pr} \infty \mathsf{fWiki}$.
In general, transclusion is appropriate if a page contains multiple definitions, results, or proofs.
Because of an evolved consensus as to precisely what part of a to-be-transcluded page is to be inside the onlyinclude tags, it is advisable that only experienced editors create new transclusions in the main namespaces.
If you feel that according to the rules explained above, a certain page needs a transclusion set up, then please add a call to the refactor template at the top of the page.
Also, make sure to include a note that makes clear that transclusion is the reason for that template call, by adding an explanatory note to it (for example containing a reference to this page).
One of the members of the maintenance team will then try to look into the matter soon, though due to time constraints the actual refactoring may be postponed to a time they consider more suitable.