Help:Transclusion

Part of the refactoring of Help:Editing; main page is User:Lord Farin/Sandbox/Help:Editing

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, 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-Schroeder Theorem and Definition:Connected (Topology)/Topological Space.

Technical details
The transclusion method as practised on deals almost exclusively with subpages.

These are simply pages whose title contains a forward slash, like a folder structure. For example:


 * Definition:Connected (Topology)/Topological Space

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.

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  and   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
... The actual proof

... 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, 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:

Title of section
where the  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 of the way the  tags are naturally placed (on the empty lines preceding and succeeding the part to be transcluded), there are two extra line breaks introduced.

This means that the spacing desired based on house style, which one would expect to be achieved by the following lines:

Next section
is instead achieved by omitting the preceding and succeeding empty lines, which results in:

When to transclude
As mentioned in the beginning of this article, the transclusion mechanism is used to attain unambiguous reference within.

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  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.