> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/pl/wiecej-tematow/04-an-introduction-to-tagged-pdf-files-internals-and-the-challenges-of-accessibility.md). # Wprowadzenie do plików PDF z tagami: wnętrze i wyzwania związane z dostępnością ## Aktualizacja: styczeń 2026 Proszę zobaczyć [instrukcje Overleaf dotyczące tworzenia oznaczonych plików PDF](https://docs.overleaf.com/writing-and-editing/creating-accessible-pdfs). Ta [zespół LaTeX](https://latex-project.org/) wprowadził nowe funkcje umożliwiające automatyczne tagowanie PDF, będące podstawowym wymogiem dostępności PDF. Te nowe funkcje są dostępne w Overleaf w [TeX Live 2025](http://\(https//www.overleaf.com/blog/tex-live-2025-is-now-available), a nowsze aktualizacje są dostępne w wydaniu rolling TeX Live dostępnym przez [Overleaf Labs](https://www.overleaf.com/labs/participate). Obecnie można wygenerować oznaczony plik PDF z kodu źródłowego LaTeX zgodny z WCAG 2.1 na poziomie AA, postępując zgodnie z [naszą dokumentacją użytkownika](https://docs.overleaf.com/writing-and-editing/creating-accessible-pdfs) korzystając z wydań TeX Live dostępnych w Overleaf. Artykuł poniżej z 2020 roku, choć nie został zaktualizowany o najnowsze informacje dotyczące dostępności LaTeX, może być nadal czytany z zainteresowaniem i jako materiał wprowadzający do tagowania PDF. *** ## Co obejmuje ten artykuł? Celem tego artykułu jest wprowadzenie do oznaczonego PDF wraz z omówieniem niektórych wyzwań technicznych, z jakimi mierzy się oprogramowanie, w tym silniki TeX i LaTeX, którego celem jest tworzenie oznaczonych i dostępnych plików PDF. Dostępność, zwłaszcza plików PDF, to szeroki i złożony temat, który wiąże się również z wyzwaniami technicznymi, nie zawsze mającymi jedno, powszechnie uznane lub przyjęte rozwiązanie — na przykład jak przedstawić złożoną matematykę w plikach PDF w sposób dostępny: używając MathML czy kodu LaTeX? Chociaż nie możemy zagłębić się w każdy temat i musimy uprościć wiele szczegółów, możemy zajrzeć do wnętrza plików PDF, aby pokazać, na czym naprawdę polega tagowanie PDF. Overleaf ma nadzieję, że ten artykuł będzie użytecznym wprowadzeniem, dostarczając wystarczającego tła, by umożliwić czytelnikom lepsze zrozumienie wyzwań technicznych oraz wesprzeć dalszą lekturę i zgłębianie tematyki oznaczonego PDF i dostępności. Zasoby w tym artykule obejmują: * [8-minutowy film](#video-showing-the-logical-structure-of-a-tagged-pdf) przedstawiający oznaczony PDF wygenerowany przez LaTeX; * [projekt Overleaf](#using-luatex-an-example-in-the-overleaf-gallery) służący do eksploracji użycia znaków spacji w LuaTeX; * [nagrania dźwiękowe](#tagged-yes-but-the-reading-order-is-incorrect) pokazujące problemy z dostępnością PDF. ## Wstęp Zapewnienie dostępności treści cyfrowych słusznie uznaje się za ważny aspekt tworzenia i rozpowszechniania treści. Ponadto rządy, w tym [Wielka Brytania](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps) oraz [Stany Zjednoczone](https://www.hhs.gov/sites/default/files/Intro%20to%20Accessibility%20and%20508.pdf), wprowadzają przepisy wymagające, aby treści tworzone w ich jurysdykcji spełniały określone kryteria dostępności. Zgodność poprzez publikację treści w HTML nie stanowi nadmiernego obciążenia, ale zapewnienie wymaganego poziomu dostępności dokumentów rozpowszechnianych w formacie PDF może być znaczącym wyzwaniem technicznym — zależnie od oprogramowania użytego do tworzenia treści przeznaczonych do wyjścia jako plik PDF. PDF pojawił się na początku lat 90. jako rozwiązanie problemów związanych z niezawodnym przesyłaniem dokumentów, a historia pokazała, że odniósł ogromny sukces. Jednak PDF jest również złożonym formatem plików, który powstał zanim powszechnie uznano i zaakceptowano potrzebę ułatwiania dostępności treści dokumentów. Mimo to z czasem specyfikacja PDF ewoluowała, wprowadzając funkcje umożliwiające i wspierające tworzenie dostępnych dokumentów PDF przy użyciu „stylizowanej” odmiany PDF, którą Adobe nazywa *oznaczonym PDF*. W praktyce tworzenie oznaczonych —*i w pełni dostępnych*—plików PDF nakłada na oprogramowanie generujące PDF znaczące dodatkowe wymagania techniczne — a obejmuje to silniki TeX oraz ekosystem makr i dodatkowych pakietów LaTeX. ## Geneza PDF jako cyfrowego papieru ostatecznej postaci Ta [geneza Portable Document Format (PDF)](https://theblog.adobe.com/evolution-digital-document-celebrating-adobe-acrobats-25th-anniversary/) sięga czasów, w których przesyłanie dokumentów między komputerami było pełne trudności, często spowodowanych konwersjami plików prowadzącymi do przełamywania tekstu na strony i innych rozbieżności, potęgowanych przez niekompatybilne czcionki i kodowania tekstu używane w różnych systemach operacyjnych (zwłaszcza Windows i Macintosh). Autor tego dokumentu pracował wówczas w branży wydawniczej i ma żywe wspomnienia zmagania się z tymi wyzwaniami! PDF został zaprojektowany, aby rozwiązać problemy związane z udostępnianiem plików poprzez wprowadzenie uniwersalnego cyfrowego papieru ostatecznej postaci (nieedytowalnego), umożliwiającego bezproblemowe przesyłanie samodzielnych dokumentów zawierających czcionki potrzebne do ich wyświetlenia. Użytkownicy mogli wreszcie przesyłać wszelkiego rodzaju dokumenty z uzasadnioną pewnością, że odbiorcy, niezależnie od platformy komputerowej, będą mogli je otworzyć i odczytać — zachowana została wierność dokumentu, a kłopotliwe przełamywanie stron oraz kompatybilność/dostępność czcionek stały się przeszłością. ### Cyfrowy papier: dobry dla wszystkich użytkowników? Rodowód PDF jako formy cyfrowego papieru naturalnie zakładał użycie numerów stron drukowanych, typografii lub elementów projektu jako wskazówek do wizualnej nawigacji po jego treści — na ekranie lub na papierze. Jednak te wizualne wskazówki/mechanizmy są oczywiście pozbawione znaczenia dla osób z poważnym uszkodzeniem wzroku. Dziś lepsza dostępność treści cyfrowych słusznie uznawana jest za ważny aspekt tworzenia i rozpowszechniania treści. Wyzwaniem dla PDF było zapewnienie mechanizmów ułatwiających niewizualny dostęp do treści zamkniętych w „kontenerze” pierwotnie zaprojektowanym tak, by odwzorowywać wizualne medium drukowanej strony. Pierwsza wersja specyfikacji PDF (PDF 1.0) została [oficjalnie opublikowana 15 czerwca 1993 roku](https://theblog.adobe.com/evolution-digital-document-celebrating-adobe-acrobats-25th-anniversary/) a następnie pojawiały się nowe wersje z aktualizacjami, które w 2001 roku (PDF 1.4) obejmowały wprowadzenie „oznaczonego PDF”, co [„...umożliwiło użytkownikom technologii wspomagających”](https://www.adobe.com/accessibility/pdf.html). Kolejne wydania specyfikacji PDF rozszerzały i ulepszały funkcje PDF, czego kulminacją było najnowsze wydanie (PDF 2.0), które, na podstawie [raportów](https://www.pdfa.org/tagged-pdf-2-0/), znacząco przebudowało funkcje dostępności — choć PDF 2.0 nie jest jeszcze dobrze obsługiwany przez silniki TeX. ## Treść wewnątrz plików PDF Aby docenić związane z tym problemy, warto przyjrzeć się temu, jak pliki PDF faktycznie reprezentują zawartą w nich treść strony. Głęboko wewnątrz pliku PDF treść każdej strony znajduje się w jej *strumieniu treści*: sekwencji operatorów PDF („poleceń”), które umieszczają tekst lub grafikę w określonym miejscu na stronie do renderowania (wyświetlania) przez oprogramowanie używane do *przeglądania* PDF. W istocie strumień treści dostarcza graficznego opisu lub „przepisu”, który mówi aplikacjom przeglądającym PDF, jak „narysować” każdą stronę — określając, co ma być wyświetlone na stronie i gdzie. Naturalnie, ten zestaw operatorów obejmuje instrukcje wyboru określonych czcionek o konkretnym rozmiarze, wybór kolorów, określenie grubości linii, rysowanie linii, krzywych i tak dalej — wszystko, co jest potrzebne do zapewnienia pełnego graficznego opisu wizualnej prezentacji strony. Aby zmniejszyć rozmiar pliku, strumienie treści PDF są kompresowane i przechowywane w zwartym formacie binarnym, ale jeśli masz dostęp do odpowiedniego oprogramowania, takiego jak Adobe Acrobat Pro DC, możesz użyć go do wyświetlenia „dekompresowanej” wersji zwykłego tekstu strumieni treści stron. Rozważmy, jak operatory PDF mogą „narysować” tabelę: strumień treści PDF zawierałby odpowiednią sekwencję operatorów do utworzenia linii poziomych/pionowych, wyboru różnych czcionek i wyprowadzenia tekstu umieszczonego w różnych miejscach strony, aby stworzyć zawartość tabeli. Aby to zademonstrować, rozważmy bardzo prosty nieoznaczony dokument PDF zawierający nic więcej niż podstawową tabelę z tekstem — utworzoną w Microsoft Word z powodów, które staną się jasne później w artykule. Oto zrzut ekranu przedstawiający nasz prosty PDF: ![Tabela utworzona w Microsoft Word](/files/a41ec2a1ecdb6a998f7f0d2f2110161c5efb6a56) Jeśli wyodrębnimy (zdekompresowany) strumień treści strony dla tego pliku i wkleimy kilka pierwszych wierszy do edytora tekstu, możemy podsumować niektóre operatory PDF, aby uzyskać „wyczucie”, jak pliki PDF „opisują” treść wyświetlaną na tej stronie. ![Obraz strumienia treści w pliku PDF](/files/0d79b7457b55a0ff31e8346c2b82996465d778d8) Jeśli masz dostęp do Adobe Acrobat Pro DC, możesz użyć go do wyświetlenia listy operatorów zawartych w strumieniu treści strony PDF. Oto *wewnętrzna struktura PDF* widok tego samego PDF w Acrobat, który pomocnie podaje jednowierszowy opis każdego operatora użytego do „narysowania” naszej pojedynczej strony zawierającej podstawową tabelę — pamiętaj, że te krótkie opisy są dostarczane przez Adobe Acrobat Pro DC, a nie *nie* obecne w samym pliku PDF: ![Obraz strumienia treści PDF wyświetlony w Adobe Acrobat Pro DC](/files/73b6c9f78ad34c648b7b3408c4ec278624813a91) Zauważ jednak, że żadna z tych instrukcji rysowania (operatorów) nie przechowuje żadnego „znaczenia” ani „opisu” tego, co faktycznie tworzą: są po prostu zbiorem operatorów grafiki, które skutkują powstaniem tego, co *obserwator widzący rozpoznaje* jako tabelę. Oczywiście dla osób z poważnym uszkodzeniem wzroku wyświetlanie tabeli powstałej w wyniku tych graficznych operatorów w strumieniu treści PDF nie jest użyteczną metodą dostępu do tej treści. Potrzebny jest mechanizm, dzięki któremu pliki PDF zawierają odpowiedni niewizualny (czytelny maszynowo) opis tej tabeli — i oczywiście wszystkich innych elementów treści zawartych na stronach wewnątrz pliku PDF. Aby umożliwić niewizualny dostęp do treści, pliki PDF muszą zawierać dodatkowe dane, które przypisują „znaczenie” lub semantykę zbiorom bądź grupom operatorów używanych do „rysowania” określonego fragmentu treści. Z konieczności ta zasada przypisywania lub nadawania „znaczenia” musi obejmować wszystkie formy treści zawarte w PDF: ten mechanizm istnieje i nazywa się *tagowaniem* PDF-a, tworząc „odmianę” PDF-a zwaną, co nie dziwi, *oznaczonym PDF*. ## Wprowadzenie do oznaczonego PDF Oznaczony PDF to nazwa nadana określonemu typowi pliku PDF, który zawiera dodatkowe dane (oraz struktury danych) niewystępujące w nieoznaczonych plikach PDF. Chociaż zasady/idee stojące za oznaczonym PDF dają się opisać w zarysie, pełne szczegóły są złożone i zajmują wiele stron w formalnej specyfikacji PDF. Adobe zaprojektowało oznaczony PDF, aby osiągnąć szereg celów, w tym uczynić treści dostępnymi dla użytkowników z niepełnosprawnością wzroku, ale obejmuje on również poniższą listę zaczerpniętą z sekcji 10.7 [specyfikacji Adobe PDF 1.7](https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdf_reference_archive/pdf_reference_1-7.pdf): * proste wyodrębnianie tekstu i grafiki w celu wklejenia do innych aplikacji; * automatyczne przekształcanie układu tekstu i powiązanej grafiki tak, aby pasowały do strony o innym rozmiarze niż założony dla oryginalnego układu; * przetwarzanie tekstu do takich celów jak wyszukiwanie, indeksowanie i sprawdzanie pisowni; * konwersję do innych popularnych formatów plików (takich jak HTML, XML i RTF) z zachowaniem struktury dokumentu i podstawowych informacji o stylowaniu. Ponadto oznaczony PDF wymaga także: * aby tekst w treści PDF był reprezentowany w formie, którą można przekształcić do Unicode; * podziały słów muszą być reprezentowane jawnie — zauważ, że silniki TeX nie używają znaków spacji do oddzielania słów, używają elastycznego odstępu TeX-a zwanego glue (patrz niżej); * rzeczywista („prawdziwa”) treść jest odróżniana od artefaktów układu i składu stron. U podstaw oznaczonego PDF leżą dwa kluczowe pojęcia, które omówimy: * określanie logicznej struktury treści w pliku PDF; * oznaczanie (tagowanie) treści PDF zestawem standardowych typów treści. ## Struktura logiczna W dłuższych dokumentach treść jest zwykle podzielona na sekwencję mniejszych elementów treści; na przykład książki są zazwyczaj dzielone na rozdziały, które z kolei są podzielone na sekcje i podsekcje zawierające akapity, tabele, rysunki/wykresy, listy punktowane lub numerowane, przypisy i odwołania itd. Struktura i organizacja treści w takiej książce lub innym typie dokumentu nazywana jest jej *strukturą logiczną*. Pojęcie logicznej struktury dokumentu odgrywa ważną rolę w dostępności PDF-ów, ale jako koncepcja może wydawać się nieco niejasne i trudne do zrozumienia. Poniższa definicja z [Encyclopedia of Database Systems](https://link.springer.com/referenceworkentry/10.1007%2F978-0-387-39940-9_213) daje pomocny wgląd: > „Struktura logiczna odnosi się do sposobu organizacji informacji w dokumencie; określa hierarchię informacji oraz relacje między różnymi częściami dokumentu. Struktura logiczna wskazuje, jak dokument jest zbudowany, w odróżnieniu od tego, co dokument zawiera.” Zauważ, że ta definicja struktury logicznej nie odnosi się dokładnie *jak* do tego, gdzie te informacje strukturalne są fizycznie przechowywane; jedynie do tego, że zapewniają reprezentację struktury i organizacji dokumentu. Dokładne szczegóły tego, jak logiczna struktura dokumentu jest przechowywana lub reprezentowana, zależą od implementacji: są funkcją oprogramowania używanego do jej generowania i przetwarzania. ### Struktura logiczna w PDF-ach Specyfikacja PDF zapewnia mechanizmy, dzięki którym logiczna struktura dokumentu może być zapisana wewnątrz pliku PDF — do wykorzystania przez oprogramowanie, które na przykład może chcieć wyeksportować treść PDF do innych formatów, takich jak XML, HTML czy Microsoft Word. Te procesy eksportu muszą wytworzyć poprawnie ustrukturyzowany dokument tekstowy zgodny z zasadami docelowego formatu pliku eksportowego — a najlepiej można to osiągnąć, gdy przetwarzanie eksportu jest kierowane informacjami o strukturze logicznej dostarczonymi w PDF. Dodatkowo logiczna struktura pliku PDF jest niezbędna dla oprogramowania wspomagającego, które na przykład może chcieć wykonywać operacje zamiany tekstu na mowę, czytając treść na głos osobie z niepełnosprawnością wzroku. Proces zamiany tekstu na mowę musi zapewnić, że treść jest czytana na głos w poprawnej kolejności/sekwencji, w przeciwnym razie dałoby to bezsensowne rezultaty. Zauważ też, że samo pojęcie strony może nie mieć żadnego istotnego znaczenia dla aplikacji wspomagających, które interesuje jedynie treść i struktura dokumentu PDF, a nie wizualny podział i prezentacja w blokach wielkości strony. #### Nazywanie elementów treści Rejestrowanie (przechowywanie) logicznej struktury dokumentu PDF wymaga pewnego zestawu znaczących nazw przypisanych do różnych *typów* elementów treści, które mogą występować w typowym dokumencie PDF — identyfikujących części treści reprezentujące nagłówki, akapity, tabele, listy itd. Ponadto niektóre elementy treści, takie jak spis treści, listy numerowane/punktowane oraz materiał tabelaryczny, mają własne dość złożone struktury, więc potrzebne są także pewne wskazówki/reguły określające, jak te bardziej złożone elementy treści są zbudowane — ich podstrukturę. Kolejnym wymogiem jest wyraźne wskazanie wszelkiej treści PDF, którą powinno zignorować oprogramowanie wspomagające przetwarzające PDF; na przykład nagłówki i stopki stron są artefaktami składania stron zawierającymi tekst zbędny dla osób z poważnym uszkodzeniem wzroku: ta treść powinna być ignorowana. Mechanizmy używane przez PDF do definiowania logicznej struktury dokumentu zostały zaprojektowane tak, aby były elastyczne, więc w zasadzie różne aplikacje generujące i przetwarzające pliki PDF mogłyby używać nazw typów treści według dowolnej przyjętej konwencji. Jednak aby zmaksymalizować wymianę dokumentów i umożliwić różnym aplikacjom przetwarzającym PDF uzyskiwanie spójnych wyników, Adobe zdefiniowało zestaw standardowych nazw dla typów elementów treści, których oprogramowanie generujące PDF powinno przestrzegać. W specyfikacji PDF te standardowe nazwy określa się mianem tagów, co prowadzi do pojęcia *oznaczonego* PDF-a. ### Oznaczanie treści PDF: spojrzenie „pod maskę” Aby nieco odczarować dyskusję, przyjrzymy się krótko wnętrzu plików oznaczonego PDF — chociaż nie możemy omówić wszystkich szczegółów, ponieważ oznaczony PDF to tak duży i złożony temat. #### Sekwencje oznaczonej treści: podstawowe elementy oznaczonego PDF Na najniższym poziomie proces zapisywania znaczenia treści zawartej na stronie PDF (tj. w jej strumieniu treści) zaczyna się od *sekwencji oznaczonej treści* które służą do identyfikowania (nadawania „znaczenia”) skupisk lub grup operatorów PDF. Sekwencjom oznaczonej treści przypisywany jest numeryczny identyfikator zwany `MCID` (*identyfikatorem oznaczonej treści*) który jest liczbą całkowitą od 0 do pewnego maksymalnego N na każdej stronie. Te `MCID` wartości zapewniają sposób jednoznacznej identyfikacji sekwencji operatorów zawartych w strumieniu treści konkretnej strony. Dla jasności, dla każdej strony `MCID` identyfikatory zaczynają się od 0 i rosną kolejno aż do pewnej maksymalnej wartości, która zależy od tego, ile sekwencji oznaczonej treści znajduje się w strumieniu treści danej strony. Sekwencje oznaczonej treści są w istocie podstawowymi „elementami budulcowymi”, które służą do tworzenia wyższych struktur danych zwanych *elementami struktury*. Te elementy struktury zawierają tag, czyli nazwę używaną do identyfikacji, jaki typ elementu treści reprezentują. #### Przykład elementów struktury Tu nieco wyprzedzamy wydarzenia, ale warto przejrzeć przykład. Załóżmy, że masz 3 małe fragmenty tekstu strony, a każdy z nich jest identyfikowany w strumieniu treści przez inną sekwencję oznaczonej treści. Każdy z tych 3 fragmentów tekstu można opakować we własny element struktury z tagiem, a wszystkie trzy można „połączyć” za pomocą innego elementu struktury, aby reprezentować wyższy element treści, taki jak wiersz w spisie treści. ![Obraz wyjaśniający elementy struktury i sekwencje oznaczonej treści](/files/ed4cd8dac000a1bb0f404b20e8d2f70d7d86f939) Za pomocą formy relacji danych nadrzędny–podrzędny zbiory elementów struktury są łączone w celu tworzenia połączonych struktur danych reprezentujących bardziej złożone elementy danych, takie jak listy numerowane i punktowane, tabele, matematyka itd. Ostatecznie cały zbiór elementów struktury zawartych w całym pliku PDF jest dalej łączony i zestawiany w celu utworzenia logicznej struktury dokumentu PDF — wrócimy do tego później w artykule. ### Czym jest sekwencja oznaczonej treści? W powyższej dyskusji użyliśmy prostego nieoznaczonego dokumentu PDF zawierającego tabelę (utworzoną w Microsoft Word), ale jeśli polecimy Wordowi utworzenie oznaczonego PDF, zobaczymy, że w strumieniu treści strony pojawiło się dodatkowe oznaczenie. Tutaj bierzemy pod uwagę tylko kilka pierwszych wierszy strumienia treści (są ich setki), ale zwróć uwagę na obecność dodatkowych operatorów, takich jak `/P <> BDC` i `EMC` które służą do identyfikacji sekwencji oznaczonej treści. Nie będziemy zgłębiać pełnej składni sekwencji oznaczonej treści, lecz odsyłamy czytelnika do strony 862 [oficjalnej specyfikacji Adobe PDF 1.7](https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdf_reference_archive/pdf_reference_1-7.pdf). ![Obraz przedstawiający sekwencje oznaczonej treści w strumieniu treści oznaczonego PDF](/files/9caa58d8613bb60f7869ed9836584a619a96a477) Dla łatwego odniesienia ponownie pokazujemy wersję nieoznaczoną: ![Obraz przedstawiający strumień treści PDF](/files/0d79b7457b55a0ff31e8346c2b82996465d778d8) W *nieoznaczony* PDF, operatory takie jak `/P <> BDC` i `EMC` nie występują, ale pozostałe operatory są niezmienione: nieoznaczony PDF nie zawiera dodatkowego oznakowania używanego do identyfikacji pewnych sekwencji/grup operatorów. Ponownie możemy też użyć funkcji Adobe Acrobat do wyświetlenia sekwencji oznaczonej treści w strumieniu treści — tutaj wyróżniliśmy je zieloną ramką: *wewnętrzna struktura PDF* funkcję do wyświetlania sekwencji oznaczonej treści w strumieniu treści — tutaj wyróżniliśmy je zieloną ramką: ![Obraz pokazujący sekwencje oznaczonej treści w strumieniu treści oznaczonego PDF wyświetlonym w Adobe Acrobat Pro DC](/files/37087858e6aae292e2276f2e7067ea64eee244ed) Zauważ, że niektóre elementy treści są oznaczone jako `/Artifact` co identyfikuje materiał na stronie PDF, który powinien być *zignorowany* przez aplikacje wspomagające, takie jak te, które czytają na głos osobom z niepełnosprawnością wzroku. Poniższy zrzut ekranu pokazuje rozwinięty widok pierwszej sekwencji oznaczonej treści — tej o `MCID` wartości `0`. Koniec sekwencji oznaczonej treści jest identyfikowany przez operator PDF `EMC`. ![Obraz pokazujący szczegóły operatorów objętych przez oznaczony strumień treści](/files/9bb00ae40837f10f78ab2d5d2c268590f7a93e71) ### Przechowywanie struktury logicznej Jak wspomniano, oprócz zapewniania opisu poszczególnych elementów treści (akapitów, list, tabel itd.) dostępne PDF-y muszą zawierać reprezentację całego dokumentu w postaci jego struktury logicznej. Poszczególne fragmenty dostępnej treści muszą być ze sobą połączone, aby stworzyć kompletny, możliwy do nawigacji i dostępny dokument — podobnie jak pojedynczy dokument HTML jest tworzony z akapitów, grafiki, tabel, aby utworzyć stronę internetową. Ponadto kluczowe jest, aby logiczna struktura dokumentu PDF zapewniała, że całą treść można przeglądać w poprawnej *kolejności czytania*, niezależnie od kolejności, w jakiej treść strony została zapisana do strumieni treści strony PDF. Kolejność czytania omówimy bardziej szczegółowo poniżej. #### Struktura logiczna: „drzewo” elementów struktury Zauważyliśmy, że PDF-y używają czegoś zwanego *elementem struktury* do reprezentowania pojedynczych elementów treści oraz że element struktury zawiera tag identyfikujący typ treści, który reprezentuje. Aby przedstawić logiczną strukturę dokumentu, wszystkie elementy struktury są ze sobą łączone za pomocą relacji nadrzędny–podrzędny i organizowane w „drzewo struktury”. We wnętrzu pliki oznaczonego PDF zawierają obiekt o nazwie `StructTreeRoot` , który zawiera (wskazuje na) elementy struktury pełniące rolę punktu początkowego lub „korzenia” drzewa logicznej struktury dokumentu. Zwykle „korzeń” drzewa struktury zaczyna się od jednego elementu struktury oznaczonego jako `Document` , który zawiera liczne *podrzędne* elementy struktury, które łącznie reprezentują całą zawartość dokumentu. Każde oprogramowanie zaprojektowane do tworzenia dostępnych PDF-ów poprzez tagowanie musi zbudować tę bardzo złożoną strukturę danych (i inne!) — a obejmuje to silniki TeX i LaTeX. Przykład takiego drzewa struktury dokumentu (`StructTreeRoot`) pokazano na poniższym zrzucie ekranu z oznaczonym PDF otwartym w Adobe Acrobat Pro DC: ![Obraz pokazujący StructTreeRoot w oznaczonym PDF](/files/9d239ec2dacf2320dea6337a7751b16deeac52d4) Porównaj powyższą strukturę z wersją nieoznaczonego PDF: ![Obraz pokazujący brak StructTreeRoot w nieoznaczonym PDF](/files/59e838db6495d1ca5ec2146b4f4b44dd2814f196) ### Badanie struktury logicznej PDF-ów Zaczniemy od kilku grafik podsumowujących to, co omówiliśmy, a zakończymy filmem wykorzystującym Adobe Acrobat Pro DC, aby pokazać więcej szczegółów dotyczących logicznej struktury oznaczonego pliku PDF. Najpierw pokażemy schemat przedstawiający ogólne zasady: stronę PDF z jej strumieniem treści oznaczonym sekwencjami oznaczonej treści (MCS). ![Grafika przedstawiająca koncepcję sekwencji oznaczonej treści na stronach dokumentu PDF](/files/d427f1bc9f96364c50ac81c41843b5263f013a50) Te MCS są następnie łączone w *elementami struktury* które stanowią podstawę dla większych typów treści, a te z kolei są dalej łączone, aby przechowywać logiczną strukturę PDF-a w obiekcie o nazwie `StructTreeRoot`. ![Grafika przedstawiająca logiczną strukturę oznaczonego pliku PDF](/files/f3213acf0d7ed45a341f84db57ef179b554b191e) #### Film pokazujący logiczną strukturę oznaczonego PDF Poniższy film (8 minut) wykorzystuje Adobe Acrobat Pro DC, aby zabrać Cię na „prowadzone zwiedzanie” i przedstawić szczegóły logicznej struktury oznaczonego pliku PDF utworzonego za pomocą LaTeX. Oznaczony plik PDF użyty w filmie nosi nazwę `tagpdf.pdf`, który jest doskonałym przykładem zawierającym dokumentację eksperymentalnego pakietu LaTeX [`tagpdf`](https://ctan.org/pkg/tagpdf?lang=en). Celem tego `tagpdf` pakietu jest zapewnienie „narzędzi do eksperymentowania z tagowaniem i dostępnością przy użyciu pdfLaTeX i LuaTeX”. {% embed url="" %} ### Uwagi dotyczące tagowania i elastyczności Specyfikacja HTML zapewnia dużą liczbę predefiniowanych tagów do użycia przy tworzeniu stron internetowych, ale także pozwala na elastyczność w sposobie ich łączenia w celu utworzenia wybranego dokumentu HTML. Podobnie specyfikacja oznaczonego PDF Adobe zapewnia zestaw predefiniowanych nazw tagów, ale nakłada bardzo niewiele ograniczeń na to, jak można łączyć te tagi, aby reprezentować złożone elementy treści w PDF — z założenia daje to bardzo dużą elastyczność. Ponadto przy każdej tak dużej i złożonej specyfikacji jak PDF nieuchronnie do pisanej specyfikacji wkradają się pewne niejednoznaczności lub kwestie związane z jasnością opisu. Programiści odpowiedzialni za implementację tak złożonej specyfikacji mogą musieć podejmować „decyzje uznaniowe” przy jej interpretacji, ponieważ stoją przed zadaniem przełożenia opisów pisanych na działający kod. Wrodzona elastyczność oznaczonego PDF-a wraz z interpretacją specyfikacji (lub standardów dostępności) naturalnie wpływa na twórców aplikacji do tworzenia dokumentów: jakie kombinacje tagów należy stosować do reprezentowania treści tworzonej przez użytkownika podczas eksportu do oznaczonego pliku PDF? Jeśli uwzględnić nieograniczoną zdolność użytkowników do tworzenia wszelkiego rodzaju treści dzięki funkcjom oprogramowania do tworzenia dokumentów, to widać, że automatyczne tworzenie dostępnych, oznaczonych PDF-ów jest sporym wyzwaniem! Być może odzwierciedlając nieuniknione złożoności tworzenia oznaczonych PDF-ów w pełni zgodnych ze standardami dostępności, internet obfituje w poradniki „jak to zrobić”, „wskazówki” i „najlepsze praktyki” dotyczące tworzenia oznaczonych PDF-ów za pomocą oprogramowania takiego jak Adobe InDesign czy Microsoft Word. Ponadto PDF Association przygotowało przydatny dokument o nazwie [Tagged PDF Best Practice Guide](https://www.pdfa.org/wp-content/uploads/2015/12/StructureElementsBestPracticeGuide_2016-01-19.pdf) napisany, aby pomóc programistom mierzącym się z wyzwaniami implementacji oznaczonego PDF i PDF/UA. ## Masz PDF, ale czy jest dostępny? Aby ustalić, czy dany plik PDF spełnia wymagane standardy dostępności, takie jak PDF/A lub PDF/UA (patrz poniżej), musi zostać *zwalidowany* za pomocą uzgodnionego procesu walidacji lub narzędzia programowego. Jednak walidacja zwykle odbywa się po zakończeniu dokumentu, ale proces ten może nie być przeprowadzany przez autora dokumentu, lecz przez specjalistów ds. dostępności w organizacji lub instytucji, która zażądała zgodności. Jeśli PDF nie przejdzie walidacji, może wymagać fachowej ręcznej interwencji w Adobe Acrobat Pro DC, aby naprawić tagowanie (jeśli to możliwe). Alternatywnie może nawet trzeba będzie odesłać go do autora, aby poprawił oryginalny dokument, być może poprzez unikanie użycia funkcji oprogramowania do tworzenia, które spowodowały problemy — co może być niezwykle trudne do osiągnięcia, ponieważ może wykraczać poza kontrolę autora. ### Kolejność czytania i kolejność treści Jak wspomniano, tworzenie naprawdę dostępnych PDF-ów nakłada dodatkowe wymagania techniczne na oprogramowanie do tworzenia, a potencjalnie także na autorów dokumentów, wymuszając „dyscyplinę autorską” w sposobie korzystania z funkcji tego oprogramowania. Chociaż oznaczony PDF jest mechanizmem, który *umożliwia* tworzenie w pełni dostępnych PDF-ów, samo to, że PDF jest oznaczony, nie *nie* oznacza automatycznie, że jest on w pełni dostępny, jak zobaczymy w przykładzie poniżej. Aby tworzyć w pełni dostępne PDF-y, wszystkie elementy treści w PDF powinny być oznaczone tak, aby powstała logiczna struktura zapewniająca dostęp do treści i ich odczyt w poprawnej sekwencji — zwanej *kolejności czytania*. Może się to wydawać „oczywiste”, ale gdy oprogramowanie zapisuje plik PDF, może umieścić grafikę i tekst w strumieniach treści strony w dowolnej wybranej przez siebie kolejności. Na przykład załóżmy, że strona zaczyna się od tekstu, następnie zawiera tabelę, a kończy grafiką, dając naturalną *kolejności czytania* kolejność: 1. tekst 2. table 3. grafika Gdy zapisuje się to do PDF, oprogramowanie generujące strumień treści dla tej strony mogłoby zacząć od operatorów rysujących tabelę, następnie wyprowadzić operatory tworzące grafikę, a potem operatory dla tekstu, co w strumieniu treści dałoby *kolejność treści* kolejność: 1. table 2. grafika 3. tekst Oczywiście wszystko zostanie umieszczone we właściwym miejscu podczas wyświetlania tej strony. Dla czytelnika widzącego kolejność, w jakiej te elementy są przechowywane w strumieniu treści strony, nie ma znaczenia: widzi on kompletnie wyrenderowaną stronę ze wszystkim we właściwym miejscu. Jeśli jednak oprogramowanie wspomagające musiałoby polegać na kolejności elementów w strumieniu treści (kolejności treści), napotkałoby trudności, gdyby kolejność treści różniła się od naturalnej kolejności czytania; na przykład narzędzia do czytania na głos odczytywałyby materiał w złej sekwencji. Na szczęście oprogramowanie wspomagające może korzystać z logicznego porządku (struktury) oznaczonego PDF-a, który musi być zorganizowany tak, aby odzwierciedlał sekwencję, w jakiej treść powinna być czytana. Z tych właśnie powodów dane reprezentujące logiczną strukturę dokumentu są przechowywane oddzielnie od rzeczywistej treści wyświetlanej na widocznych stronach, aby umożliwić > „...aby kolejność i zagnieżdżenie logicznych elementów treści były całkowicie niezależne od kolejności i położenia obiektów graficznych na stronach dokumentu.” (strona 856 [The PDF Reference, wydanie szóste, listopad 2006](https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdf_reference_archive/pdf_reference_1-7.pdf)) W praktyce zagwarantowanie logicznej kolejności zachowującej kolejność czytania jest znacznie trudniejsze, niż mogłoby się wydawać, więc użyjmy prostego, choć wymyślonego, przykładu, który pokaże skalę problemu. #### Nieprawidłowa kolejność czytania: przykład z użyciem Microsoft Word Autor dokumentu może użyć funkcji wybranego oprogramowania do tworzenia, aby osiągnąć określony efekt wizualny — na przykład używając tabel do utworzenia konkretnego układu tekstu. Na przykład poniższy zrzut ekranu pokazuje dokument Microsoft Word użyty w poprzednich przykładach. Zawiera on tabelę, która została użyta do utworzenia zestawu ponumerowanych akapitów obok siebie. Ale jeśli chodzi o tagowanie tej treści, jak należy ją traktować: jako tabelę czy jako listę numerowaną? Oba te typy treści wymagają złożonej struktury tagowania, aby poprawnie je przedstawić. Na poniższym obrazie zwróć uwagę na kolejność, w jakiej ponumerowane akapity mają być czytane: kolumna po kolumnie, a nie wiersz po wierszu. ![Obraz tabeli utworzonej w Microsoft Word](/files/18513e828097f3be18165f374d28a53e15dae957) Jeśli poprosimy Worda, aby zapisał ten dokument do pliku PDF, korzystając z wbudowanego eksportu — a nie wtyczki Acrobat PDFMaker — możemy polecić mu utworzenie oznakowanego PDF-a: ![Okno dialogowe opcji procesu eksportu w programie Microsoft Word](/files/fda535ca757c700d16bb996bc5e92822365579f1) A więc jak Word oznacza ten układ? W poniższym bardzo krótkim filmie (14 sekund) używamy Adobe Acrobat Pro DC, aby sprawdzić strukturę znaczników utworzoną przez Microsoft Word. {% embed url="" %} W tym dokumencie Word utworzył oznakowany dokument PDF, który używa `Tabela` znacznika zawierającego dwa podznaczniki: `THead` dla grupy wierszy nagłówka tabeli oraz `TBody` do reprezentowania grupy wierszy dla treści tabeli. `THead` i `TBody` oba zawierają `TR` znaczniki reprezentujące poszczególne wiersze treści. Znaczniki `TR` zawierają dalsze znaczniki reprezentujące pozycję listy numerowanej obecną w każdej komórce. Poniższy obraz ekranu pokazuje głęboko zagnieżdżoną strukturę znaczników oraz odpowiednio złożoną strukturę logiczną potrzebną do reprezentacji nawet tak niezwykle podstawowego dokumentu! ![Obraz pokazujący głęboko zagnieżdżoną strukturę znaczników i strukturę logiczną prostej tabeli utworzonej w Microsoft Word](/files/c324689603d70dcce882a46c73628a51f4e03172) W porównaniu z plikami PDF generowanymi przez TeX i LaTeX ten przykład z Worda jest dokumentem niezwykle prostym, ale nadal wymaga złożonej struktury logicznej, aby go odwzorować. Wyobraź sobie poziom złożoności oznaczania potrzebny do reprezentowania plików PDF generowanych przez LaTeX, zawierających złożoną matematykę i tabele! #### Oznakowany, tak, ale kolejność czytania jest nieprawidłowa Mimo że Word rzeczywiście tworzy [oznaczonym PDF](https://assets.ctfassets.net/nrgyaltdicpt/3vcgZmG5mkCPYUPTjV30CF/4c34ae919212fa19e979e4cf852e66c1/ReadAloud.pdf) pokazuje to jedno z podstawowych wyzwań stojących przed każdą aplikacją próbującą tworzyć w pełni dostępne pliki PDF: poprawne odwzorowanie zamierzonej kolejności czytania treści. Podczas tworzenia oznakowanego PDF-a wewnętrzne procesy Worda zdecydowały się zapisać odpowiadający strumień treści, wyprowadzając tabelę w układzie wiersz po wierszu, a nie kolumna po kolumnie. Dla widzącego czytelnika oglądającego PDF-a te szczegóły niskiego poziomu nie mają znaczenia: tabela wyświetla się poprawnie. Jednak dla osób z dysfunkcją wzroku logiczna struktura dokumentu Worda daje niewłaściwy rezultat, ponieważ pożądana kolejność czytania (kolumna po kolumnie) nie jest zachowana: treść jest odczytywana na głos w niewłaściwej kolejności. Poniższe nagranie audio zostało utworzone przy użyciu funkcji „Read Out Loud” w Adobe Reader DC. Jak widać, tekst jest odczytywany w niewłaściwej sekwencji: wiersz po wierszu, a nie kolumna po kolumnie: ![Tabela utworzona w Microsoft Word](/files/01a47b95215cb8d76bc73b930b3c1db5c42ed714) Jak wspomniano powyżej, ten przykład jest nieco sztuczny, ale pokazuje, jak łatwo jest zastosować kombinacje funkcji oprogramowania, które wywołują problemy z dostępnością — ale skąd autor dokumentu ma to wcześniej wiedzieć? Prawdopodobnie problem zostałby wykryty dopiero wtedy, gdy wynikowy plik PDF przeszedłby praktyczne testy użyteczności pod kątem dostępności — np. przy użyciu oprogramowania wspomagającego. Potencjalnie takie dokumenty mogłyby przejść testy zgodności/walidacji PDF/A, ale nie zdać egzaminu w „rzeczywistym” użyciu. Zapewnienie poprawnej kolejności czytania takiego pliku PDF wymagałoby fachowej, ręcznej interwencji z użyciem zaawansowanych narzędzi do edycji PDF, takich jak Adobe Acrobat Pro DC: czasochłonnego i kosztownego procesu. Alternatywnie autor dokumentu mógłby powstrzymać się od używania tej konkretnej formy prezentacji treści lub układu — ale tylko wtedy, gdyby wiedział, że jest ona problematyczna! ### Używanie znaków spacji do oddzielania słów Podczas wpisywania tekstu w edytorach tekstu używa się znaku spacji, aby zaznaczyć koniec jednego słowa i początek następnego. Jeśli następnie utworzysz z takiego dokumentu plik PDF, wpisane przez ciebie znaki spacji oczywiście zostaną wyprowadzone i staną się częścią tekstu zapisanego w PDF. Jednak silniki TeX-a nie używają znaków spacji do oddzielania słów w składanym tekście; zamiast tego zamieniają znaki spacji na formę elastycznego odstępu zwaną glue (zobacz to [artykule Overleaf](/latex/pl/artykuly-szczegolowe/11-boxes-and-glue-a-brief-but-visual-introduction-using-luatex.md) aby uzyskać więcej informacji o pudełkach i glue w TeX-ie). W strumieniu treści stron PDF utworzonych przez silniki TeX-a rozdzielenie poszczególnych słów osiąga się poprzez przejście do innej pozycji na stronie i rozpoczęcie tekstu następnego słowa — zamiast wyprowadzania znaku spacji, aby uzyskać ten odstęp. Ponadto ilość odstępu między słowami w akapitach tekstu składanych przez silniki TeX-a różni się w zależności od wiersza z powodu algorytmu łamania wierszy TeX-a. Ta zmienność jest odzwierciedlona w danych położenia zapisanych do strumienia treści stron PDF. Ten aspekt składu w TeX-ie ma konsekwencje dla kopiowania/wklejania tekstu z plików PDF oraz dla oprogramowania wspomagającego próbującego odczytać na głos tekst złożony w PDF-ach tworzonych przez silniki TeX-a. Oprogramowanie wspomagające musi analizować strumień treści strony PDF, aby wyodrębnić tekst potrzebny do przetworzenia. Oczywiście takie oprogramowanie potrzebuje jakiegoś mechanizmu wykrywania początku i końca słów — najbardziej oczywistym rozwiązaniem jest użycie znaku spacji. Mając to na uwadze, standardy dostępności wymagają, aby poszczególne słowa były wyraźnie zakończone (np. znakami spacji), co w przypadku silników TeX-a jest problematyczne ze względu na użycie glue międzywyrazowego. #### Ale nie wszystko stracone! W 2014 roku pdfTeX wprowadził 2 nowe prymitywy, aby poprawić obsługę dostępności, umożliwiając użycie znaków spacji między słowami w PDF-ach, które generuje: * `\pdfinterwordspaceon` * `\pdfinterwordspaceoff` Te polecenia korzystają z „dummy font”, zawierającego tylko glif spacji. Szczegóły i przykład można znaleźć na stronie 29 [Podręcznika użytkownika pdfTeX](http://texdoc.net/texmf-dist/doc/pdftex/manual/pdftex-a.pdf). #### Używanie LuaTeX: przykład w galerii Overleaf LuaTeX nie obsługuje tych prymitywów pdfTeX, ale można go zaprogramować tak, aby osiągał rezultaty bardzo podobne do pdfTeX, wykorzystując tak zwany mechanizm callbacków LuaTeX. Projekt Overleaf do konwersji glue na znaki spacji jest dostępny w galerii Overleaf pod tytułem [Używanie LuaTeX do konwersji glue międzywyrazowego na spacje i kerny](https://www.overleaf.com/latex/examples/using-luatex-to-convert-interword-glue-to-spaces-and-kerns/sfdkdkybrvkv). Jeśli składasz kod LaTeX za pomocą LuaTeX (tj. opcji kompilatora LuaLaTeX w Overleaf), to używając kodu Lua możesz przetworzyć złożony akapit po fakcie, znaleźć ewentualne glue międzywyrazowe i zastąpić je znakiem spacji plus odpowiednim kernem. Odstęp zapewniany przez szerokość znaku spacji można zwiększyć (lub zmniejszyć) poprzez obliczenie odpowiedniej wartości kernu, tak aby zachować ilość odstępu dostarczaną przez glue międzywyrazowe, co nie powoduje żadnej wizualnej różnicy w wyniku składu. Aby zrozumieć, jaką różnicę to robi dla użytkowników oprogramowania wspomagającego, posłuchaj tego nagrania dźwiękowego przechwyconego z funkcji Adobe Reader DC *Read Out Loud* Funkcja ta rejestruje głośne odczytanie dwóch wierszy tekstu w tym projekcie, przed i po konwersji glue na spacje. Zauważ, jak drugie odczytanie wiersza, które używa spacji, jest wypowiadane szybko i płynnie w porównaniu z wierszem używającym glue międzywyrazowego. Projekt Overleaf jest zwykłym plikiem TeX skompilowanym za pomocą LuaTeX i udostępnionym wyłącznie do celów eksperymentalnych; nie jest przeznaczony jako pełne rozwiązanie produkcyjne wysokiej jakości. Przede wszystkim ma on pomagać w zrozumieniu problemów technicznych związanych z dostępnością plików PDF. Kod Lua użyty w tym projekcie opiera się na pracy zawartej w znacznie wcześniejszym artykule Overleaf [Pudełka i klej: krótkie, ale wizualne wprowadzenie z użyciem LuaTeX](/latex/pl/artykuly-szczegolowe/11-boxes-and-glue-a-brief-but-visual-introduction-using-luatex.md). Uwaga: dla uproszczenia projekt używa własnego, bardzo minimalistycznego programu ładującego czcionki OpenType, wywodzącego się z tego kodu: . ### Inne problemy z dostępnością i oznakowany PDF Chociaż tagowanie pozwala identyfikować elementy treści obecne w pliku PDF, niektóre rodzaje treści, takie jak grafika lub złożona matematyka, wymagają dodatkowych danych lub informacji, jeśli mają być dostępne za pośrednictwem oprogramowania przeznaczonego dla osób z dysfunkcją wzroku. Aby zapewnić i wspierać dostępność szerokiego zakresu typów treści, specyfikacja PDF umożliwia dołączanie do elementów treści „alternatywnych opisów” lub „ActualText”, zapewniając odpowiednie opisy tekstowe lub inne reprezentacje czytelne maszynowo. Na przykład w tym celu w specyfikacji PDF 2.0 wskazano MathML. #### Czy to „prawdziwa treść”, czy tylko artefakt? Dla osób z dysfunkcją wzroku proces dzielenia i wyświetlania treści w prostokątnych, wielkości strony fragmentach ma niepożądane skutki uboczne, takie jak dzielenie wyrazów na końcu linii. Ponadto aspekty projektu strony lub układu używane w celu poprawy prezentacji wizualnej są całkowicie bez znaczenia dla tych, którzy tego nie widzą. Z tych powodów tagowanie treści PDF musi uwzględniać, że niektóre treści w pliku PDF powinny być traktowane jako *artefakt* prezentacji wizualnej lub łamania stron. Na przykład numery stron, nagłówki i stopki, cieniowane tła lub inne elementy projektu muszą zostać zidentyfikowane, aby oprogramowanie dostępności przetwarzające treść wiedziało, że ma je ignorować. ## Przegląd standardów PDF/A Prośby o tworzenie dostępnych plików PDF zwykle odwołują się do standardu ISO o nazwie [ISO 19005](https://www.iso.org/standard/38920.html), częściej określanego jako PDF/A. Jednak ponieważ PDF/A jest *rodzina* zestawem standardów, samo żądanie „zgodności z PDF/A” może nie precyzować w pełni rzeczywistych wymagań. Aby zobaczyć dlaczego, zacznijmy od krótkiego zarysu PDF/A ze strony [stowarzyszenia PDF Association](https://www.pdfa.org/resource/iso-19005-pdfa/) (dostęp 21 maja 2020), która opisuje ISO 19005 (PDF/A) następująco: > „Podstawowym celem ISO 19005 jest zdefiniowanie formatu pliku opartego na PDF, znanego jako PDF/A, który zapewnia mechanizm przedstawiania dokumentów elektronicznych w sposób zachowujący ich statyczny wygląd wizualny w czasie, niezależnie od narzędzi i systemów używanych do tworzenia, przechowywania lub renderowania plików. > > Drugim celem ISO 19005 jest zdefiniowanie ram do przedstawiania struktury logicznej i innych informacji semantycznych dokumentów elektronicznych w plikach zgodnych ze standardem. > > Kolejnym celem ISO 19005 jest zapewnienie ram do zapisywania kontekstu i historii dokumentów elektronicznych w metadanych w plikach zgodnych ze standardem.” Jasne jest, że PDF/A ma kilka podstawowych celów. ### Ewolucja i rozwój PDF Ta [Specyfikacja PDF 1.0](https://web.archive.org/web/20150617123515/http://acroeng.adobe.com/PDFReference/PDF%20Reference%201.0.pdf) została opublikowana w 1993 roku i liczyła zaledwie 230 stron. Jednak 13 lat później specyfikacja [PDF Adobe w wersji 1.7](https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdf_reference_archive/pdf_reference_1-7.pdf) miała już znacznie ponad 1000 stron! Z biegiem czasu rozmiar i złożoność specyfikacji PDF rosły wraz z dodawaniem obsługiwanych funkcji: obejmujących nowe technologie oraz wymagania coraz bardziej zaawansowanych przepływów pracy i przypadków użycia opartych na PDF w różnych rynkach i społecznościach. Jednak prawdopodobnie żaden użytkownik ani grupa użytkowników nigdy nie korzysta ze wszystkich możliwości: PDF musi „obejmować wszystkie podstawy”, aby mieć pewność, że będzie w stanie zaspokoić potrzeby jak najszerszego rynku. Na przykład wiele funkcji PDF przeznaczonych do obsługi wysokiej klasy druku komercyjnego nie jest wymaganych w typowym codziennym użyciu biurowym jako formacie do przechowywania lub udostępniania dokumentacji. ### PDF/A: „powrót do podstaw” dla PDF Podstawowym celem PDF/A jest zapewnienie, że zgodne pliki PDF nadają się do długoterminowej archiwizacji lub zawierają treści dostępne dla osób korzystających z różnych technologii wspomagających do „konsumpcji” tych plików PDF. Aby osiągnąć te cele, PDF/A ogranicza zestaw funkcji PDF dozwolonych w zgodnych plikach PDF, zakazując używania funkcji, które mogłyby zagrozić archiwizowalności lub dostępności. Można myśleć o PDF/A jako o zestawie standardów określających, jak zgodne pliki PDF używają *podzbiór* pełnej specyfikacji PDF do tworzenia plików odpowiednich do długoterminowej archiwizacji lub zapewnienia dostępności ich treści. Ograniczenia PDF/A umożliwiają używanie plików PDF jako „archiwalnego papieru cyfrowego”, niezależnego od technologii odczytu PDF i środowiska obliczeniowego używanego do dostępu do ich treści. Zgodne pliki PDF nie powinny zawierać niczego, czego zachowanie jest „zależne od implementacji” — tzn. zależy od konkretnego oprogramowania lub systemów operacyjnych używanych do ich wyświetlania lub przetwarzania. Pliki PDF muszą być również *kompletne*: kluczowe zasoby dokumentu muszą być osadzone w pliku — takie jak czcionki lub profile kolorów. ### Wersje PDF/A i poziomy zgodności Istnieją różne *wersje* wersje standardu PDF/A, z których każda odzwierciedla określoną wersję formalnej specyfikacji PDF (PDF 1.4, 1.7 i 2.0). Ponadto istnieją różne *poziomy zgodności* określające, z którym aspektem/którymi aspektami standardu PDF/A dany plik PDF jest zgodny. W związku z tym, mówiąc o „zgodności z PDF/A” lub jej wymagając, należy myśleć o plikach PDF zgodnych z **PDF/A-** Na przykład * PDF/A-1a: oznacza wersję PDF/A 1, poziom zgodności a * PDF/A-2b: oznacza wersję PDF/A 2, poziom zgodności b Przyjrzymy się temu nieco dokładniej. #### Wersje PDF/A Standard PDF/A znajduje się pod auspicjami ISO i jest publikowany jako standard o nazwie ISO 19005. Jak wspomniano, specyfikacja PDF ewoluowała z czasem, a to z kolei wymagało aktualizacji ISO 19005, co dało wynik w postaci poniższej tabeli: | | | | | ---------------- | ---------------- | ------------------------ | | **Wersja PDF/A** | **Standard ISO** | **Oparty na wersji PDF** | | PDF/A-1 | ISO 19005-1:2005 | PDF 1.4 | | PDF/A-2 | ISO 19005-2:2011 | PDF 1.7 | | PDF/A-3 | ISO 19005-3:2012 | IS0 32000-1 (PDF 1.7) | W chwili pisania tego tekstu (kwiecień/maj 2020) zaktualizowany PDF/A-4 (ISO 19005-4) jest [w przygotowaniu](https://www.iso.org/standard/71832.html). #### Poziomy zgodności PDF/A Oprócz trzech wersji PDF/A (PDF/A-1, PDF/A-2 i PDF/A-3) istnieją trzy *poziomy zgodności*: * Poziom A (dostępny) dla dostępności (obejmuje wymagania archiwizacyjne poziomu B) * Poziom B (podstawowy) dla archiwizacji * Poziom U (Unicode) (= archiwizacja plus użycie Unicode dla tekstu) Oto krótki opis tych poziomów zgodności: * **Poziom B (podstawowy)** jest minimalnym wymaganiem zgodności z PDF/A. Definiuje wymagania zapewniające, że zgodne dokumenty PDF nadają się do długoterminowej archiwizacji — że zawsze można je niezawodnie wyświetlić lub wydrukować niezależnie od konkretnego oprogramowania, narzędzi lub systemów operacyjnych. * **Poziom A (dostępność)** obejmuje wymagania zgodności poziomu B, a ponadto wymaga użycia oznakowanego PDF-a, aby zapewnić informacje o strukturze logicznej i kolejności czytania, wraz z użyciem Unicode, aby umożliwić dostęp do tekstu dokumentu. * **Poziom U (Unicode)** zgodność została dodana do PDF/A-2 i opiera się na poziomie B, dodatkowo wymagając użycia Unicode dla tekstu dokumentu, ale nie idzie tak daleko jak poziom A, ponieważ nie nakazuje informacji o strukturze. Wersje PDF/A i poziomy zgodności można podsumować w tabeli: | | | | | | --------------------- | ----------------------------- | -------- | -------- | | **Poziom zgodności** | **PDF/A-** | | | | Poziom A (dostępny) | PDF/A-1a | PDF/A-2a | PDF/A-3a | | Poziom B (podstawowy) | PDF/A-1b | PDF/A-2b | PDF/A-3b | | Poziom U (Unicode) | N/D (nie istniał dla PDF/A-1) | PDF/A-2u | PDF/A-3u | ### PDF/UA („Uniwersalna dostępność”) Chociaż zgodność na poziomie A standardu PDF/A w pewnym stopniu definiuje wymagania dla dostępnych plików PDF, inny standard ISO o nazwie [ISO 14289](https://www.iso.org/standard/64599.html), określany jako PDF/UA, idzie dalej. PDF/UA wzmacnia wymagania dotyczące dostępności i doprecyzowuje wytyczne zawarte w standardach PDF/A, dzięki czemu stał się preferowanym standardem dla dostępnych plików PDF. #### Protokół Matterhorn Czytelnicy z dużym zainteresowaniem chęcią poznania szczegółów zgodności PDF/UA mogą być zainteresowani [Protokołem Matterhorn](https://www.pdfa.org/resource/the-matterhorn-protocol-1-02/) który jest „listą wszystkich możliwych sposobów niezgodności z PDF/UA”. ### Oprogramowanie walidacyjne Aby sprawdzić, czy plik PDF jest zgodny z określonym standardem, musi zostać *zwalidowany* za pomocą oprogramowania do sprawdzania zgodności, które skanuje PDF, aby sprawdzić, czy jego treść i struktura są zgodne z wymaganiami tego standardu — takimi jak PDF/UA lub PDF/A-*x*a (gdzie *x* = 1, 2 lub 3). Zauważ, że walidacja plików PDF — przetwarzanie ich przy użyciu preferowanego narzędzia walidacyjnego — może generować komunikaty diagnostyczne lub ostrzeżenia, które dla użytkownika niebędącego ekspertem mogą być dość zagadkowe — być może z powodu pewnych niskopoziomowych danych PDF (lub struktury), które nie spełniają odpowiedniego standardu. Dla wielu autorów interpretacja tych ostrzeżeń i przekształcenie ich w działającą poprawkę dokumentu(ów) może być sporym wyzwaniem. #### Darmowe oprogramowanie walidacyjne * [veraPDF](https://verapdf.org/) które, cytując ich stronę internetową (dostęp 28 maja 2020), jest „zbudowanym do tego celu, open source’owym walidatorem formatu plików obejmującym wszystkie części PDF/A i poziomy zgodności”. * (tylko Windows) [PDF Accessibility Checker (PAC 2024)](https://pac.pdf-accessibility.org/en/download) który jest „...darmowym narzędziem do sprawdzania dostępności PDF-ów, przetestowanym i sprawdzonym od 2010 roku”. #### Komercyjne oprogramowanie walidacyjne * [Adobe Acrobat](https://acrobat.adobe.com/uk/en/acrobat/pricing.html) udostępnia zestaw testów walidacyjnych PDF wraz z narzędziami do edycji i naprawy znaczników w niezgodnych plikach PDF. ### PDF Association: świetne źródło informacji Ta [PDF Association](https://www.pdfa.org/) tworzy wiele *doskonałej* zasobów dotyczących PDF/A, PDF/UA i wielu innych tematów związanych z PDF — w tym filmy na ich [kanale YouTube](https://www.youtube.com/user/ThePDFAssociation/playlists) oraz artykuły i bezpłatne publikacje techniczne dostępne na ich stronie internetowej. Jedną z takich publikacji jest [PDF/UA w pigułce](https://www.pdfa.org/resource/pdfua-in-a-nutshell/) która stanowi bezcenne wprowadzenie do standardu PDF/UA i jego wymagań. ## Dostępne pliki PDF z silników TeX i LaTeX Miejmy nadzieję, że poprzednie omówienia pokazały, iż tworzenie w pełni dostępnych i poprawnie oznakowanych plików PDF jest wymagającym wyzwaniem technicznym. Co więcej, nawet prosty przykład z Microsoft Word pokazał, że autorzy mogą bardzo łatwo użyć kombinacji funkcji oprogramowania, które skutkują dokumentami PDF z oznaczeniami, nieprzechodzącymi kryteriów dostępności. Jako narzędzie do tworzenia dokumentów LaTeX zapewnia autorom niemal nieograniczoną elastyczność w zakresie i złożoności dokumentów, które można tworzyć — co może być właśnie powodem jego wyboru. LaTeX obsługuje także rozszerzalność poprzez tysiące dodatkowych pakietów, z których autorzy mogą korzystać w swoich dokumentach. Do tego wszystkiego autorzy mają swobodę pisania nowych makr TeX lub LaTeX albo redefiniowania istniejących, aby osiągać określone efekty. Być może jednak ta swoboda i elastyczność mają swoją cenę, ponieważ treści powstające w wyniku niezliczonych interakcji wszystkich tych pakietów i makr LaTeX „jakoś” muszą zostać skoordynowane, jeśli LaTeX ma automatycznie generować poprawnie oznakowany i dostępny wynik PDF. W praktyce rozszerzalność, moc, wszechstronność i „wolność” tworzenia, jaką daje LaTeX, stawiają wyzwania techniczne przed płynnym i niewidocznym dla użytkownika („automatycznym”) tworzeniem w pełni dostępnych dokumentów PDF z oznaczeniami, zgodnych ze standardami PDF/UA lub PDF/A-{1|2|3}a. Szersza społeczność TeX i LaTeX intensywnie pracuje nad rozwiązaniem tych wyzwań, a The TeX User Group (TUG) koordynuje wysiłki badawcze i rozwojowe poprzez PDF accessibility and PDF standards [grupę roboczą](https://www.tug.org/twg/accessibility/). Istnieje [lista dyskusyjna](https://tug.org/mailman/listinfo/accessibility) która umożliwia zainteresowanym stronom omawianie tworzenia plików PDF z oznaczeniami przy użyciu TeX i LaTeX. W tych dyskusjach warto pamiętać, że LaTeX nie jest w rzeczywistości wykonywalnym programem składu, lecz dużym zbiorem zaawansowanych makr (poleceń) napisanych w niższopoziomowym języku o nazwie TeX. Między starannie przygotowanym dokumentem LaTeX a końcowym złożonym PDF-em znajduje się oprogramowanie zwane silnikiem TeX, którego zadaniem jest „wykonanie” zbioru poleceń LaTeX (tj. makr) użytych do napisania i zbudowania dokumentu — przekształcenie ich w złożoną reprezentację dokumentu zapisaną jako plik PDF. Osoby nowe w ekosystemie TeX/LaTeX są często, i słusznie, zdezorientowane mnogością brzmiących tajemniczo nazw używanych dla napotykanych narzędzi: TeX, LaTeX, pdfTeX, pdfLaTeX, XeTeX, XeLaTeX, LuaTeX i LuaLaTeX. Jeśli czujesz to samo, pomoc jest pod ręką w artykule Overleaf [What’s in a Name: A Guide to the Many Flavours of TeX](/latex/pl/artykuly-szczegolowe/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md) który wyjaśnia pochodzenie i znaczenie wszystkich tych terminów. Silniki TeX, takie jak pdfTeX, XeTeX czy LuaTeX, należą do klasy oprogramowania zwanej *kompilatorami dokumentów*: biorą one twój kod LaTeX i kompilują go do postaci złożonej, „tłumacząc” makra LaTeX (polecenia) z powrotem na niższopoziomowe instrukcje języka TeX, które są „wykonywane”, aby uzyskać wynik składu. Systemy składu oparte na TeX-ie są zdolne do tworzenia wyjątkowo złożonych treści — w tym zaawansowanej matematyki, zapisu nutowego, struktur chemicznych, grafiki i zaawansowanego wielojęzycznego tekstu składanego. Aby zapewnić zgodność tych złożonych dokumentów ze standardami dostępności i przepisami, silniki TeX, wraz ze zbiorem makr LaTeX i pakietami LaTeX, muszą generować odpowiednio oznakowane pliki PDF, osadzając w generowanych plikach PDF bardzo dużą ilość dodatkowych danych. Chociaż silniki TeX mogą generować niezwykle złożone pliki PDF, ich wewnętrzne procesy, algorytmy i funkcje nie mają *wbudowane* funkcji *zaprojektowanych specjalnie* do obsługi tworzenia oznakowanych i dostępnych plików PDF. Zamiast tego obsługa tagowania i dostępności musi być osiągana poprzez złożone programowanie makr, które „wstrzykuje” dodatkowe dane do plików PDF generowanych przez silniki TeX — tworząc sekwencje treści oznaczonej, elementy struktury i struktury danych struktury logicznej przechowywane w `StructTreeRoot`. I właśnie tutaj to „koordynowanie” staje się szczególnie istotne: kod w rdzeniu (kernelu) LaTeX wraz z kodem w tysiącach pakietów i niezliczonych makrach tworzonych przez autorów musiałby bardzo starannie współpracować, aby zapewnić, że wykonanie makr prowadzi do poprawnego oznakowania treści wynikowych dokumentów. To „koordynowanie” musiałoby być niezawodne — niezależnie od tego, jak autorzy zdecydują się łączyć i używać funkcji, poleceń i możliwości LaTeX, jego systemu pakietów oraz mocy makr TeX. ### Potrzeby autorów Dla większości osób LaTeX jest po prostu narzędziem, które pozwala tworzyć pięknie złożone dokumenty, z możliwością wybierania i łączenia pakietów, które pomagają to osiągnąć. Zdecydowana większość autorów LaTeX po prostu chce, aby ich dokumenty „działały”: składały się bez błędów, aby mogli złożyć pracę dyplomową, artykuł, raport albo dokończyć długo oczekiwaną książkę. Nie bez powodu użytkownicy LaTeX oczekują, że wybrany zestaw pakietów LaTeX będzie współistniał w pokoju, współdziałał płynnie i przejrzyście, zapewniając polecenia i funkcje niezbędne do tworzenia dokumentów. Te same oczekiwania pojawiają się prawdopodobnie również przy wymaganiu tworzenia oznakowanych PDF-ów z LaTeX: powinno to „po prostu działać”, transparentnie i przy minimalnej ingerencji autora. Niestety, jesteśmy jeszcze daleko od doświadczenia typu „Hej, presto! oznaczanie dzieje się samo, bez względu na to, jakie dziwne rzeczy robię”. Połączenie technicznych wymagań dostępności i oznakowanego PDF z LaTeX oraz swobodą autorstwa jest z natury złożone i być może nieuniknione jest, że jakaś forma „dyscypliny autora” może być potrzebna, jeśli wyzwania techniczne mają stać się podatne na praktyczną implementację i rozwiązanie. Osobnym, ale powiązanym problemem jest to, że nieprawidłowe tagowanie może nie mieć żadnego wizualnego wpływu na końcowy plik PDF: wizualnie może wyglądać idealnie i prawdopodobnie również będzie się drukował bez problemów, ale autor nieświadomie może mieć „zepsute” tagowanie, wykryte dopiero po późniejszym niepowodzeniu kontroli zgodności/walidacji PDF/A i/lub dalszych praktycznych testach przy użyciu oprogramowania wspomagającego, takiego jak czytniki ekranu. ### Pliki PDF tworzone w Overleaf Overleaf udostępnia swojej społeczności użytkowników edytor LaTeX działający w przeglądarce, a także narzędzia do zarządzania projektami i dokumentami, które ułatwiają wspólne tworzenie — wszystko zbudowane na standardowej instalacji TeX Live. W praktyce Overleaf pozwala użytkownikom „uruchamiać LaTeX zdalnie” za pośrednictwem przeglądarki internetowej, zapewniając warstwę izolacji od złożoności związanych z zarządzaniem i utrzymywaniem pełnego systemu TeX Live. Konsekwencją korzystania przez Overleaf ze standardowej instalacji TeX/LaTeX jest to, że pliki PDF tworzone z kodu LaTeX pisanego w edytorze Overleaf powstają z użyciem dokładnie tych samych technologii, które są obecne w każdej innej instalacji TeX Live w tej samej wersji — w tym w konfiguracjach zainstalowanych przez użytkowników na ich lokalnych urządzeniach. Jedyną różnicą jest to, że silniki TeX, które kompilują i przetwarzają kod LaTeX z Overleaf, działają na zdalnych serwerach, a nie na lokalnych maszynach. Overleaf linearizuje jednak plik PDF wygenerowany przez TeX-a w celu wydajnego pobierania/wyświetlania w przeglądarce, ale ten proces nie ma związku z dostępnością samej treści PDF. Tworzenie dostępnych plików PDF za pośrednictwem Overleaf zależy od możliwości i funkcji wbudowanych w standardowe silniki TeX, a także od dostępności odpowiednich pakietów makr LaTeX, które użytkownicy mogą wykorzystać w ramach swojego dokumentu. Dokumenty LaTeX tworzone w Overleaf muszą pozostać zgodne z innymi instalacjami TeX i LaTeX, ponieważ użytkownicy często muszą eksportować swój projekt LaTeX z Overleaf, aby przesłać go do szerokiego zakresu systemów czasopism wydawniczych. Wprowadzenie do dokumentów LaTeX funkcji specyficznych dla Overleaf lub do podstawowych silników TeX poważnie ograniczyłoby swobodę użytkowników w korzystaniu z ich pracy gdzie indziej. Overleaf rozpoznaje i wspiera potrzebę tworzenia w pełni dostępnych plików PDF generowanych z systemów tworzenia dokumentów TeX/LaTeX: inwestujemy czas w badanie problemów dostępności, eksplorowanie najnowszych rozwiązań w silnikach TeX i eksperymentalnych pakietach LaTeX wspierających oznakowany PDF. Ostatecznie, w chwili pisania tego tekstu, nie istnieje rozwiązanie „od ręki”, którego autorzy LaTeX mogliby użyć (za pośrednictwem `\usepackage`) do płynnego i transparentnego generowania w pełni dostępnych i zgodnych z PDF/UA plików PDF z ogólnych dokumentów LaTeX. Gdy takie rozwiązania staną się dostępne poprzez aktualizacje TeX Live, oczywiście będą dostępne dla społeczności użytkowników Overleaf. ### Niektóre pakiety LaTeX do badania tagowania i dostępności Dla wielu osób [tex.stackexchange](https://tex.stackexchange.com/) jest pierwszym miejscem, do którego zwracają się po pomoc dotyczącą TeX, LaTeX lub ConTeXt. To niesamowite źródło i zawiera wiele pytań na temat [dostępności](https://tex.stackexchange.com/questions/tagged/accessibility?tab=Newest) oraz tworzenia dostępnych plików PDF za pomocą LaTeX. Jeśli czytasz i przeglądasz te pytania oraz następujący po nich strumień odpowiedzi i komentarzy, tylko jeden wniosek jest nieunikniony: obecnie nie ma pełnego, produkcyjnego rozwiązania, które automatycznie tworzyłoby w pełni dostępne, zgodne ze standardami, oznakowane pliki PDF z każdego typu dokumentu LaTeX. Istnieją jednak pewne pakiety obsługujące tagowanie — choć być może w ograniczonym zakresie zastosowań i typów dokumentów. Poniższa lista jest przeznaczona dla czytelników chcących zgłębić tagowanie PDF oparte na LaTeX: * [`tagpdf` pakietu](https://ctan.org/pkg/tagpdf) (Ulrike Fischer): bardzo rozbudowany pakiet zaprojektowany do eksperymentowania z tagowaniem PDF. Obsługuje pdfTeX i LuaTeX oraz udostępnia niezwykle użyteczną i interesującą dokumentację zawierającą doskonałe uwagi na temat technicznych wyzwań związanych z tworzeniem oznakowanych PDF-ów za pośrednictwem silników TeX; zdecydowanie warto ją przeczytać dla każdego, kto chce lepiej zrozumieć związane z tym kwestie. Prawdopodobny przyszły kierunek rozwoju to LuaTeX. * [`axessibility` pakietu](https://ctan.org/pkg/axessibility?lang=en) (Boris Doubrov i Uniwersytet w Turynie): zapewnia dostęp do wzorów w plikach PDF za pośrednictwem technologii wspomagających. * [`dostępności` pakietu](https://ctan.org/pkg/accessibility) (Andy Clifton): tworzy oznakowane i uporządkowane pliki PDF. Uwagi CTAN podają, że pakiet ten jest „skierowany do użytkowników klas dokumentów KOMA-Script”. * [`accsupp` pakietu](https://ctan.org/pkg/accsupp) (Heiko Oberdiek): eksperymentalny pakiet zapewniający lepsze wsparcie dostępności plików PDF. Kolejnym godnym uwagi źródłem jest artykuł z 2018 roku [Implementing PDF standards for Mathematical Publishing](http://web.science.mq.edu.au/~ross/TaggedPDF/PDF-standards-v2.pdf) autorstwa dr. Rossa Moore’a z Wydziału Matematyki Uniwersytetu Macquarie. W tym artykule dr Moore zawiera krótki zarys wyzwań związanych z oznakowaniem plików PDF w LaTeX: > „Główne źródło trudności leży w sposobie, w jaki różne środowiska mogą oddziaływać na siebie nawzajem. W LaTeX istnieje wiele sytuacji, w których jedno środowisko lub struktura nie jest tak naprawdę zakończona, dopóki nie rozpocznie się następne. Zatem nie chodzi tylko o umieszczenie znaczników początku i końca wokół każdego dostarczonego fragmentu treści. Zamiast tego trzeba zrozumieć subtelności tego, jak różne środowiska i inne struktury faktycznie się zaczynają i kończą, w kontekście ustanowionym przez otaczający materiał.” Dr Moore jest również obecnym opiekunem pakietu [`pdfx`](https://ctan.org/pkg/pdfx) oraz ekspertem i pionierem oznakowanego PDF używającego TeX/LaTeX. Jego prace zdecydowanie warto wyszukać — w tym ten film na YouTube, który dostarcza interesujących spostrzeżeń: {% embed url="" %} #### Uwaga dotycząca pakietu pdfx Ta [`pdfx`](https://ctan.org/pkg/pdfx) pakiet (Ross Moore i in.) zapewnia doskonałe wsparcie dla PDF/A-1|2|3b (archiwizacja) oraz innych opcji, ale jeszcze nie tworzy oznakowanych PDF-ów. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/pl/wiecej-tematow/04-an-introduction-to-tagged-pdf-files-internals-and-the-challenges-of-accessibility.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.