Pomoc:Transkluzja przy pomocy tagu pages

W skrócie transkluzja to prezentacja treści jednej ze stron na innej. Istnieje kilka sposobów transkluzji (patrz poradnik Sekcje). Na Wikiźródłach najistotniejsze jest prezentowanie przepisanego tekstu w przestrzeni głównej. Standardowo używa się wtedy znacznika <pages ... />. Tekst jako taki znajduje się w przestrzeni Strona:.^[1]

Mechanizm transkluzji jest zwykłą metodą zamieszczania tekstu w przestrzeni głównej – czyli w sposób dostępny dla użytkownika końcowego tj. czytelnika.

W żargonie Wikiźródeł używane jest powszechnie określenie „przenoszenie do main”, co jest nieścisłe, gdyż tekst w przestrzeni Strona jest transkludowany a nie „przenoszony”. Transkluzja oznacza dynamiczne włączenie tekstu.

W tym dokumencie omówiony jest znacznik <pages … /> jego składnia, działanie i wskazane są różne aspekty z tym związane.

Zakres użycia <pages ... />

Znacznik <pages ... /> jest używany do transkluzji tekstu z przestrzeni Strona z reguły do przestrzeni głównej. Poradnik Przestrzeń nazw informuje o przestrzeniach nazw na Wikiźródłach.

Sposób zapisu

W dokumencie przedstawiany jest sposób transkluzji tekstów z trzech fikcyjnych indeksów:

Indeks:Jan Nowak Ciekawa książka.djvu
Indeks:Zabawna książka
Indeks:Ważne listy

Numery lub nazwy stron są przypadkowe, nazwy sekcji zaczynają się od r_ ale mogą być dowolne i zależą od redaktora opracowującego tekst.

Indeksy

Strona w przestrzeni Indeks grupuje i jednocześnie porządkuje strony w przestrzeni Strona. Przy pomocy omawianego znacznika <pages … /> mogą zostać transkludowane strony z danego zakresu stron.^[2]

Jak wskazano w poradniku Indeksy, używamy na Wikiźródłach dwóch typów indeksów. Rozróżnienie ich jest istotne, ponieważ składnia znacznika <pages … > jest w tych wypadkach różna. W przypadku indeksów nowego typu w polach from, to oraz exclude i include należy podać jedynie numer strony (liczba arabska po ukośniku), zaś w przypadku indeksu starego typu pełną nazwę strony (bez prefiksu określającego przestrzeń nazw). Dodatkowo w indeksach starego typu pola exclude i include nie mogą być używane.

Spośród omawianych przykładów, pierwszy indeks to indeks nowego typu, dwa następne są indeksami starego typu.

Najważniejsze konstrukcje

W praktyce najczęściej stosujemy składnię:

from/to – #Transkluzja pełnych stron z danego zakresu
fromsection, tosection – #Transkluzja od/do środka strony
onlysection – #Transkluzja jednej sekcji

Pozostałe konstrukcje są mniej istotne.

Parametr index

Parametr index jest jedynym obowiązkowym parametrem znacznika <pages ... /> . Najprostsza możliwa składnia:

jednak nie działa.

Możliwe jest pominięcie (choć niezalecane dla jasności kodu) pierwszej lub ostatniej strony.

np.

<pages index="Jan Nowak Ciekawa książka.djvu" from=1 />

co spowoduje transkluzję wszystkich stron od pierwszej do ostatniej.

Zazwyczaj jednak nie transkludujemy razem wszystkich stron z danego indeksu, dlatego stosujemy bardziej rozbudowaną składnię.

Transkluzja pełnych stron z danego zakresu

Jest to najprostsza sytuacja, gdy chcemy transkludować cały tekst z danego zakresu stron.

W konkretnych przykładach:

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 />

transkludowane są strony:

Strona: Jan Nowak Ciekawa książka.djvu/10
Strona: Jan Nowak Ciekawa książka.djvu/11
⋮
Strona: Jan Nowak Ciekawa książka.djvu/19
Strona: Jan Nowak Ciekawa książka.djvu/20

Nazwa indeksu jest ujęta w cudzysłów. Jest to konieczne ze względu na spacje występujące w nazwie, jest jednocześnie zalecane dla większej przejrzystości i spójności.

Numery stron nie są ujęte w spacje. Ujęcie w cudzysłowy nie jest błędem, jednak moim zdaniem taki zapis (a więc bez spacji) jest tu bardziej przejrzysty i podkreśla charakter indeksu (tj. nowego typu).

<pages index="Zabawna książka" from="Jan Kowalski – Zabawna książka t1.pdf/10" to="Jan Kowalski – Zabawna książka t1.pdf/20" />

Tutaj transkludowane będą strony Strona:Jan Kowalski – Zabawna książka t1.pdf/10, Strona:Jan Kowalski – Zabawna książka t1.pdf/20 a między nimi strony, które są w indeksie między tymi stronami (zazwyczaj będą to tu oczywiście strony:

Strona:Jan Kowalski – Zabawna książka t1.pdf/11
Strona:Jan Kowalski – Zabawna książka t1.pdf/12
⋮
Strona:Jan Kowalski – Zabawna książka t1.pdf/18
Strona:Jan Kowalski – Zabawna książka t1.pdf/19

Jednak należy podkreślić, że kontrolę tutaj ma kolejność, w jakiej te strony występują na odpowiedniej stronie w przestrzeni Indeks

Cudzysłowy są tu z reguły niezbędne a zawsze zalecane (patrz wyżej).

<pages index="Ważne listy" from="List do Jana Kowalskiego.png" to="List do Andrzeja Nowaka.png" />

Transkludowane są Strona:List do Jana Kowalskiego.png i dalej wszystkie strony aż do Strona:List do Andrzeja Nowaka.png włącznie. Kolejność wynika z kolejności, w jakiej występują na stronie w przestrzeni Indeks (tutaj: Indeks:Ważne listy). Cudzysłowy są tu z reguły niezbędne a zawsze zalecane (patrz wyżej).

Transkluzja co drugiej strony

W tekstach dwujęzycznych możemy mieć sytuację, że strony nieparzyste są napisane w jednym języku, parzyste – w drugim. Możliwe są oczywiście również inne warianty.
Gdy chcemy z jakiegoś powodu transkludować co drugą stronę (szerzej co n-tą), można użyć parametru step= w połączeniu ze znanymi już parametrami from= i to= .

W konkretnym przykładzie:

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 step=2 />

transkludowane są strony:

Strona: Jan Nowak Ciekawa książka.djvu/10
Strona: Jan Nowak Ciekawa książka.djvu/12
Strona: Jan Nowak Ciekawa książka.djvu/14
Strona: Jan Nowak Ciekawa książka.djvu/16
Strona: Jan Nowak Ciekawa książka.djvu/18
Strona: Jan Nowak Ciekawa książka.djvu/20

Nazwa indeksu jest ujęta w cudzysłów. Jest to konieczne ze względu na spacje występujące w nazwie, jest jednocześnie zalecane dla większej przejrzystości i spójności.

Numery stron nie są ujęte w cudzysłowy. Ujęcie w cudzysłowy nie jest błędem, jednak moim zdaniem taki zapis (a więc bez cudzysłowów) jest tu bardziej przejrzysty i podkreśla charakter indeksu (tj. nowego typu).

Składnia ta działa tylko z indeksami nowego typu.

Transkluzja jednej pełnej strony

Gdy zachodzi potrzeba transkluzji jednej całej strony z przestrzeni Strona można użyć składni from=... to=... , jednak lepsze, jeśli to możliwe, jest użycie parametru include=...
W ten sposób idea zawarta w kodzie jest najlepiej czytelna.

W konkretnym przykładzie:

<pages index="Jan Nowak Ciekawa książka.djvu" include=10 />

transkludowana jest strona:

Strona: Jan Nowak Ciekawa książka.djvu/10

Podobnie jak wyżej opisano, z reguły konieczne jest ujęcie nazwy indeksu w cudzysłowy (a zawsze jest to wskazane), nieujęcie numeru strony w cudzysłowy podkreśla, że jest to indeks nowego typu.

Składnia ta działa tylko z indeksami nowego typu.

Transkluzja kilku stron niekoniecznie kolejnych

Parametr include jest jednak dużo bardziej elastyczny. Umożliwia podanie kilku stron lub nawet zakresu stron.

include=3,7,9,10,15,18
include=3,7-10,15

Ta składnia działa tylko z indeksami nowego typu.

Pominięcie przy transkluzji niektórych stron

Jeśli jakieś strony są ujęte przez parametry from/to lub include, natomiast z jakiegoś powodu chcemy je przy transkluzji pominąć, można użyć parametru exclude. Składnia jest równie elastyczna, jak w przypadku include.

W konkretnych przykładach:

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 exclude=13,16,17/>

transkludowane są strony: 10, 11, 12, 14, 15, 18, 19, 20

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 exclude=13-17/>

transkludowane są strony: 10, 11, 12, 18, 19, 20

<pages index="Jan Nowak Ciekawa książka.djvu" include=10,15-20 exclude=16,17/>

transkludowane są strony: 10, 15, 18, 19, 20

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 include=25,27,29-32 exclude=13-17,30/>

transkludowane są strony: 10, 11, 12, 18, 19, 20, 25, 27, 29, 31, 32

Nazwa indeksu jest ujęta w cudzysłów. Jest to konieczne ze względu na spacje występujące w nazwie, jest jednocześnie zalecane dla większej przejrzystości i spójności. Numery stron nie są ujęte w cudzysłowy. Ujęcie w cudzysłowy nie jest błędem, jednak moim zdaniem taki zapis (a więc bez cudzysłowów) jest tu bardziej przejrzysty i podkreśla charakter indeksu (tj. nowego typu).

Ta składnia działa tylko z indeksami nowego typu.

Transkluzja od/do środka strony

W praktyce dość często zdarza się konieczność rozpoczęcia transkluzji tekstu gdzieś w środku strony – od początku danej sekcji. Analogicznie przebiega zakończenie transkluzji w środku strony – na końcu wskazanej sekcji. Mechanizm ten jest dokładniej opisany dokumencie Sekcje (istotny jest zwłaszcza rozdział Początek lub/i koniec rozdziału na środku strony).

Składnia:

oznacza: transkluduj od strony strona początkowa poczynając od sekcji od sekcji do końca strony strona końcowa .

analogicznie:

oznacza: transkluduj od początku strony strona początkowa do sekcji do sekcji na stronie strona końcowa włącznie.

Łącznie:

oznacza: transkluduj od strony strona początkowa poczynając od sekcji od sekcji do sekcji do sekcji na stronie strona końcowa włącznie.

W konkretnych przykładach:

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 fromsection=r_03 />

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 tosection=r_04 />

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 fromsection=r_03 tosection=r_04 />

<pages index="Zabawna książka" from="Jan Kowalski – Zabawna książka t1.pdf/10" to="Jan Kowalski – Zabawna książka t1.pdf/20" fromsection=r_03 />

<pages index="Zabawna książka" from="Jan Kowalski – Zabawna książka t1.pdf/10" to="Jan Kowalski – Zabawna książka t1.pdf/20" tosection=r_04 />

<pages index="Zabawna książka" from="Jan Kowalski – Zabawna książka t1.pdf/10" to="Jan Kowalski – Zabawna książka t1.pdf/20" fromsection=r_03 tosection=r_04 />

<pages index="Ważne listy" from="List do Jana Kowalskiego.png" to="List do Andrzeja Nowaka.png" fromsection=r_03 />

<pages index="Ważne listy" from="List do Jana Kowalskiego.png" to="List do Andrzeja Nowaka.png" tosection=r_04 />

<pages index="Ważne listy" from="List do Jana Kowalskiego.png" to="List do Andrzeja Nowaka.png" fromsection=r_03 tosection=r_04 />

Nazwa indeksu jest ujęta w cudzysłów. Jest to konieczne ze względu na spacje występujące w nazwie, jest jednocześnie zalecane dla większej przejrzystości i spójności.

Numery stron w przypadku indeksów nowego typu nie są ujęte w cudzysłów. Ujęcie w cudzysłowy nie jest błędem, jednak moim zdaniem taki zapis (a więc bez spacji) jest tu bardziej przejrzysty i podkreśla charakter indeksu (tj. nowego typu).

Nazwy stron w przypadku indeksów starego typu są ujęte w cudzysłowy. Jest to konieczne ze względu na spacje występujące w nazwie, jest jednocześnie zalecane dla większej przejrzystości i spójności.

Nazwy sekcji muszą być ujęte w cudzysłowy jeśli w nazwie występują spacje. Często są ujmowane dla większej przejrzystości. Ujmowanie lub nieujmowanie można traktować jako sprawę stylu.

Uwaga

Jeśli na pierwszej wskazanej stronie jest nieciągła sekcja od_sekcji transkluzja rozpoczyna się od początku pierwszego fragmentu.
Jeśli na ostatniej wskazanej stronie jest nieciągła sekcja do_sekcji transkluzja kończy się na końcu pierwszego fragmentu.

Transkluzja jednej sekcji

Transkluzję jednej sekcji można uzyskać przy pomocy parametru onlysection. W przypadku sekcji ciągłej (tj. niepodzielonej na fragmenty, nieprzeplatanej tekstem nienależącym do sekcji) jest to po prostu bardzo przejrzysta konstrukcja:

<pages index= nazwa indeksu include= strona onlysection= nazwa sekcji /> (tylko w przypadku indeksów nowego typu ze względu na parametr include)

która może być zastąpiona kodem

... fromsection= nazwa sekcji tosection= nazwa sekcji />

W przypadku nieciągłej sekcji daje to trudny do uzyskania w inny sposób efekt.

Przykłady:

<pages index="Jan Nowak Ciekawa książka.djvu" from=10 to=20 onlysection=r_03 />

<pages index="Zabawna książka" from="Jan Kowalski – Zabawna książka t1.pdf/10" to="Jan Kowalski – Zabawna książka t1.pdf/20" onlysection=r_03 />

<pages index="Ważne listy" from="List do Jana Kowalskiego.png" to="List do Andrzeja Nowaka.png" onlysection=r_03 />

O stosowaniu cudzysłowów patrz wyżej w sekcji #Transkluzja od/do środka strony

Zastosowanie parametru include jest możliwe w przypadku indeksów nowego typu:

<pages index="Jan Nowak Ciekawa książka.djvu" include=10 onlysection=r_03 />

Konstrukcja zamienna

Gdy chcemy w formie szablonu wstawiać parametry w znaczniku <pages ... /> zwykła konstrukcja nie działa. Wynika to z kolejności parsowania kodu. Należy zastosować wtedy inną składnię:

{{#tag:pages||index= nazwa indeksu |from= strona początkowa |to= strona końcowa }}

Nie stosujemy wtedy cudzysłowów wokół nazw. Możliwe jest również stosowanie wszystkich innych parametrów (include, exclude, fromsection, tosection, onlysection, step).

Stosowanie tej składni w zwykłych sytuacjach jest niewskazane, ponieważ utrudnia zrozumienie intencji redaktora.

↑ Ideę przestrzeni nazw wyjaśnia poradnik Przestrzeń nazw.
↑ Do tysiąca stron w ramach jednego tagu.

Części tekstu • Klasyfikacja tekstów ze względu na strukturę • Nawigacja w przeglądarce między częściami tekstu • Samodzielność części tekstu • Mechanizm działania eksportera • Odnośniki wewnętrzne w tekście • Graficzno‑wizualne wyróżnienia części tekstu • Transkluzja przy pomocy tagu pages • Formatowanie bloków tekstu • Metryka dokumentu • Budowa strony w przestrzeni głównej • Strony całości • Tytuły tekstów, nazwy stron • Tworzenie stron powyżej limitu transkluzji

[1] Ideę przestrzeni nazw wyjaśnia poradnik Przestrzeń nazw.

[2] Do tysiąca stron w ramach jednego tagu.

[1]

[2]