உதவி:Transclusion

Lua error in Module:Header_structure at line 139: attempt to call upvalue 'plain_sister' (a nil value).

⁠See also: Help:Page breaks

Transclusion displays the contents found on another page without having to copy-paste nor synchronize any later changes. It is most commonly used to group text into logical and reasonably sized chunks—most frequently as chapters or sections. Examine the transcluded text at The Wind in the Willows/Chapter 1 and compare with some of the source text found at Page:Wind_in_the_Willows_(1913).djvu/19. As the individual pages from Index:Wind_in_the_Willows_(1913).djvu were saved in the "Page:" namespace, they populated into the chapters of the book through transclusion. Creating readable sections from scanned pages is the most common use of transclusion on Wikisource.

This help page first examines the most common methods of transclusion, this should be enough to help you manage your first texts. Next the page discusses more advanced and uncommon uses for transclusion which can stretch the digital text beyond familiar boundaries. And finally, it examines the full functionality of the two tranclusion methods. If you still have unanswered questions or any problems using transclusion, please post at the Scriptorium or at Scriptorium (Help). Someone there will do their best to help you!

How to transclude full pages

You will most often be transcluding many pages together from the Page: namespace into the main presentation space of the wiki—as you saw at The Wind in the Willows/Chapter 1. There are two methods which can perform full-page transclusion. The <pages/> function, and the older {{Page}} template. Most of the time, the <pages/> tag will be the best method of transcluding, but you may still run across the older template method when editing existing texts.

The syntax for <pages/> is as follows:

<pages index="file name.djvu" from=x to=y/>

"file name.djvu" is replaced with the exact name of the Index you are working with.
The number after the slash (/) following the file name of the first page you wish to transclude is "x".
The number after the slash (/) following the file name of the final page you wish to transclude is "y".

To display what is transcluded at The Wind in the Willows/Chapter 5 you would type:

<pages index="Wind in the Willows (1913).djvu" from=133 to=161 />

Working, though deprecated

The syntax for {{Page}} is as follows:

{{Page|file name.djvu/x|num=z}}

"file name.djvu" is replaced with the exact name of the file you are working with.
The number after the slash (/) following the file name of the page you wish to transclude is "x".
The original corresponding page number from the scanned volume is "z".
Note this can only transclude a single page at a time

To display what is transcluded at The Wind in the Willows/Chapter 5 you would type:

{{Page|Wind in the Willows (1913).djvu/133|num=113}}
{{Page|Wind in the Willows (1913).djvu/134|num=114}}
{{Page|Wind in the Willows (1913).djvu/135|num=115}}
... 
{{Page|Wind in the Willows (1913).djvu/161|num=141}}

How to transclude a portion of a page

Sometimes you will not want transclude a full page all together, examine Page:Popular Science Monthly Volume 25.djvu/169. When two chapters or logical sections appear on the same page, instead of the entire page you need a way to transclude only the relevant parts of the page into the main presentation space. The example page from above presents as Popular Science Monthly/Volume 25/June 1884/Modes of Reproduction in Plants. This is accomplished using Labeled Section Transclusion (LST). The section breaks are marked with anchors in the Page: namespace. Then only the relevant part of the page, rather than the entire page, is called for during transclusion.

Adding section labels

To mark sections in the scan (Page: namespace), insert the following syntax into the typed proofreading text at the start of every new section:

## label ##

Alternatively you can use start <section begin="label" /> and end <section end="label" /> labels at the respective places in the text.

Note:

Section tags are recommended to be wrapped in quotes "label" to avoid ambiguity.
These are just free text labels, however, making labels contextual to the page can have advantages.
Use of letters and numbers is usually a recommendation, and other extended characters may cause some issues when transcluding.
Labels need to be unique for relevant sections on a page, so that the targeted section can be extracted.
If you are using <poem> markers, please make sure to open and close them inside the sections, or else section transcluding will not work properly.

Transcluding to main namespace

An extra parameter, tosection, is required in <pages> to end the transclusion at the anchor. The syntax is as follows:

<pages index="file name.djvu" from=x to=y tosection="label" />

"file name.djvu" is replaced with the exact name of the file you are working with.
The number after the slash (/) following the file name of the first page you wish to transclude is "x".
The number after the slash (/) following the file name of the final page you wish to transclude is "y".
"label" is replaced with the name of the anchor you inserted.

To display what is transcluded at Popular Science Monthly/Volume 25/June 1884/The Sins of Legislators II you would type:

<pages index="Popular Science Monthly Volume 25.djvu" from=155 to=169 tosection=E169/>

To begin the first page of a chapter or section at the anchor, a fromsection parameter is needed. Follow this pattern:

<pages index="file name.djvu" from=x to=y fromsection="label" />

"file name.djvu" is replaced with the exact name of the file you are working with.
The number after the slash (/) following the file name of the first page you wish to transclude is "x".
The number after the slash (/) following the file name of the final page you wish to transclude is "y".
"label" is replaced with the name of the anchor you inserted.

To display what is trancluded at Popular Science Monthly/Volume 25/June 1884/Modes of Reproduction in Plants you would type:

<pages index="Popular Science Monthly Volume 25.djvu" from=169 fromsection=B169 to=180 />

If successive sections finish part way through a page, then both extra parameters may need to be used at once.

How to transclude single-section

If a single logical section begins and ends within the content of a single Page:, it is desirable to transclude only the relevant section from the page content.

This is also accomplished by using Labeled Section Transclusion (LST). Again, the relevant part of the page's content is marked with a begining & ending section tag and then, upon transclusion, only the marked part of the page, rather than the entire page, is called.

To mark sections in the "Page:" namespace, insert the following syntax into the typed proofreading text to label the start & end of Section A (where Section A's content is found witin the content of a single Page:):

<section begin="sectionA" />This is Section A text.<section end="sectionA" />

There are three basic methods, with a few additional variations per each method, which can accomplish single-section content (found within a single page) transclusions. These are the <pages> tag function, the {{Page}} template, and the #section tag parser.

In most instances, the <pages> tag is the best method of transcluding a single section. The syntax is as follows:

<pages index="file_name.djvu" from="20" to="20" onlysection="sectionA" />

(In this case, the page range consists of a single page; page 20)

onlysection is the label name assigned to the section tags containing the desired content.

From May 2012 forward the above is the recognized community recommended preference.

Working, though deprecated

You may also use the {{Page}} template as follows, replacing "djvu" with the djvu file name and "#" with the page number where the text appears:

{{Page|djvu/#|section=sectionA}}

Alternatively, the following format can be used, replacing "article" with the article name (excluding namespace):

{{#section:Page:article|sectionA}}

If you experience problems, post a question on the Scriptorium.

How to place images with transcluded text

The preferred means of placing a picture or other image in the main pagespace is to upload the cropped image to Wikimedia Commons as a separate picture, for example as a png or jpeg file.

[[File:Title and number and subject.png|frameless|center]]

The page image could also be displayed in the book's Wikisource mainspace like at Personal Recollections of Joan of Arc/Book I/Chapter 2, using:

[[File:Personal_Recollections_of_Joan_of_Arc.djvu|page=27|right|thumbnail|200px|{{uc|The Fairy Tree}}]]

Advanced usage

Transclusion can also be used to produce alternative displays of text without having to repeat the proofreading and validation. Celtic Fairy Tales/Guleesh presents the story of Guleesh as published in Celtic Fairy Tales. It shows the preceding and following stories from that publication and also has a link to the foreword and commentary by the editor. Alternatively Guleesh presents the same text as a stand-alone work. Presenting suitable titles outside of the editions they may have been collected in not a necessary task any more than it is necessary to present a famous essay as a subpage of the magazine it happened to be printed in. However, both are possible by transcluding the same validated text. The consensus has been to allow individual editors to use whichever style they like inclusively.

More complicated transclusion can be used to present a comparative study of several editions. Elegy I Comparative text compares the 1633 printing of the poem to the 1896 printing. Bible/Obadiah/1/1 uses Labeled Section Tranclustion (LST) to show verse 1 of chapter 1 of the book of Obadiah starting with the original languages and then the Anglic translations from oldest to the most recent. These more complicated types of transclusion are actually very uncommon. The examples used here were experiments to see what was possible with tranclusion and pre-date the Proofread Page extension. If they were done today they would all be based on on a scanned edition, and the transclusions would be pulled from the Page: namespace.

Using the <pages/> function

Most of the time, the <pages/> tag will be the best method of transcluding. There is only one required parameter, which is index=. This field must always be supplied or nothing happens. The exact pattern to use is as follows: <pages index="file name.djvu"/> where the name file name.djvu is just a placeholder for whatever file you have used when proofreading.

Try it out with a real file name: Copy

<pages index="Wind in the Willows (1913).djvu"/>

into here and save. There is one other way to type this and have the same result. Try out <pages index=Wind_in_the_Willows_(1913).djvu/>. This works just the same. The important thing to know is that <pages index=Wind in the Willows (1913).djvu/> will not work. If you use any spaces in the field, then you must also surround the field with quotation marks ("), or it will not work.

While you always must supply the index= field, if you do not add any other parameters this syntax will only transclude the index of the file. Whenever you also supply some of the optional parameters, the index will be superseded by your other commands. Some of these optional parameters must be paired together in order to work. The numbers used in these fields are the titular number after the / in the Page: namespace. The optional parameters are as follows:

include= to supply the numbers of the page(s) to be transcluded
from= (paired with to=) to supply the number of the first page to be transcluded
to= (paired with from=) to supply the number of the last page to be transcluded
fromsection= (paired with from=/to= or include= or exclude=) to supply the initial anchor on the first page of the section
tosection= (paired with from=/to= or include= or exclude=) to supply the final anchor on the last page of the section
onlysection= (paired with from=/to= or include= or exclude=) to supply the anchor used to mark off a section for transclusion
step= (paired with from=/to= or include= or exclude=) to supply a incremental number where every x page will be transcluded.

Transclude every other page by increments of n. By example : <pages from=1 to=10 step="2" /> show the 1st, 3rd, 5th, 7th and 9th pages.

exclude= (paired with from=/to= or include=) to supply the anchor used to mark off a section to remove from transclusion
include

Include following pages. This allows a more flexible list. For example : <pages include="2-5,9" /> show the 2nd, 3rd, 4th, 5th and 9th pages.

exclude

Don't include following pages. By example : <pages from=1 to=10 exclude="2-5,9" /> show the 1st, 6th, 7th, 8th and 10th pages.

We can, of course, use all the attributes on the same tag. By example <pages from=1 to=10 include="31" exclude="2-4" step="2" /> will show 1st, 5th, 7th, 9th and 31st pages.

Note: Good practice says that attributes within the <pages> tag should be quoted. It is important to not have unquoted empty attributes within tags, so please either quote empty attributes, or remove the unneeded optional attributes.