> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-pro.ayaka.space/latex/tr/derinlemesine-makaleler/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md). # \expandafter nasıl çalışır: TeX belirteçlerine giriş [Bölüm 1](/latex/tr/derinlemesine-makaleler/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md) [Bölüm 2](/latex/tr/derinlemesine-makaleler/22-how-does-expandafter-work-the-meaning-of-expansion.md) [Bölüm 3](/latex/tr/derinlemesine-makaleler/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) [Bölüm 4](/latex/tr/derinlemesine-makaleler/20-how-does-expandafter-work-from-basic-principles-to-exploring-tex-s-source-code.md) [Bölüm 5](/latex/tr/derinlemesine-makaleler/17-how-does-expandafter-work-a-detailed-macro-case-study.md) [Bölüm 6](/latex/tr/derinlemesine-makaleler/18-how-does-expandafter-work-a-detailed-study-of-consecutive-expandafter-commands.md) ## \expandafter için arka plan: TeX belirteçleri ve belirteç listeleri Nasıl çalıştığını anlamaya yönelik ilk adım olarak `\\expandafter` gerçekte nasıl çalıştığına bakmak için, işleyişi açısından temel olan TeX'in iki bileşenine göz atacağız `\\expandafter`: TeX belirteçleri (tam sayılar) ve belirteç listeleri (tam sayı listeleri). Bu konuları çok daha ayrıntılı incelemek isteyen okurlar, Overleaf tarafından yayımlanan aşağıdaki makaleleri okumak isteyebilir: * [TeX belirteci nedir?](/latex/tr/derinlemesine-makaleler/53-what-is-a-tex-token.md) * [TeX belirteç listesi nedir?](/latex/tr/derinlemesine-makaleler/54-what-is-a-tex-token-list.md)-[TeX makroları gerçekte nasıl çalışır?](/latex/tr/daha-fazla-konu/01-a-six-part-series-how-do-tex-macros-actually-work.md) ### Belirteç verileri nereden geldi? Bu makale boyunca TeX tarafından hesaplanan gerçek belirteç değerlerini—genellikle kullanıcılara erişilebilir olmayan verileri—kullanıyoruz. Bu belirteç-değeri verisinin nasıl elde edildiğini merak eden okurlar için Overleaf, araştırma amacıyla kullandığımız birkaç TeX motorunun özel derlemelerine sahiptir. Bu motorlar, TeX’in iç işleme etkinlikleri hakkında bilgi çıktısı verecek şekilde değiştirilmiştir; bu da ürettiğimiz bazı makaleler için ek arka plan materyali sağlamaya yardımcı olur. Sayısal belirteç değerlerini gösterip tartışarak amacımız, umarız okurların “TeX belirteçlerini” daha iyi anlamalarına yardımcı olacak ayrıntıları sunmak ve bu önemli kavramın biraz daha az kapalı görünmesini sağlamaktır. ## TeX Belirteçleri 101 (ve genişleme kavramları) TeX giriş dosyanızı işlerken metni okur ve tek tek karakterleri ile karakter dizilerini (komutları) sözde *tokenlar*. TeX belirteci, TeX tarafından hesaplanan ve TeX'in mevcut giriş kaynağından okuduğu bir öğe hakkında saklaması gereken verileri “kodlamak” için kullanılan bir tam sayı değeridir. Belirteçleri, TeX'in kaydetmesi gereken verileri bir araya “paketleyen” küçük bilgi paketleri olarak düşünün; böylece bunlar işlemenin sonraki aşamasına aktarılmaya hazır olur. Dahili olarak TeX, bu tam sayı belirteç değerleri üzerinde çalışır—giriş dosyanızda başlangıçta bulunan gerçek harfleri, sembolleri, rakamları vb. kullanmaz: her şey bir belirtece (bir tam sayıya) dönüştürülür ve TeX bunlarla çalışır. ## TeX belirteç değerlerini nasıl hesaplar Burada Knuth’un özgün TeX’inde, e-TeX’te ve pdfTeX’te kullanılan belirteç hesaplamalarına bakıyoruz; diğer TeX motorlarında, özellikle XeTeX ve LuaTeX’te, Unicode kullanımını hesaba katmak için belirteç hesaplamaları biraz farklı olmak zorundadır, ancak hesaplama yöntemleri aşağıda açıklananlara benzerdir. ### Karakter belirteçleri (etkin olmayan karakterler) Etkin olmayan karakterler için belirteç değerlerinin hesaplanması oldukça basittir: $$\text{character token} = 256\times \text{(category code)} + \text{character (ASCII) code}$$ **Örnek**: A harfiyle [kategori kodu](/latex/tr/daha-fazla-konu/43-table-of-tex-category-codes.md) 11, karakter kodu 65, TeX tarafından şu karakter belirteci değeriyle temsil edilir $$256\times 11 + 65 = 2881$$. TeX literatüründe, TeX bir karakteri giriş olarak okuduktan sonra onun kategori kodu değerinin o karaktere “kalıcı olarak bağlandığını” belirten açıklamalarla karşılaşabilirsiniz: yukarıdaki belirteç değeri hesabı bunun neden doğru olduğunu gösterir. Ancak TeX’in sonraki işleme aşamalarında, karakter belirteçlerini “paketinden çıkarıp” bunların oluşturulduğu (karakter kodu, kategori kodu) çiftini ortaya çıkarması mümkündür ve bunu gerçekten de yapar—TeX bu “paketten çıkarma” işlemini yaptığında o karakterin kategori kodunu yine değiştirmez; yalnızca bu bilgiyi sonraki işlemlerinde kullanır. ### Komut belirteçleri TeX’in giriş işleme ve belirteç üretimi süreci iki tür komutu tanır: * kategori kodu 11 olan bir veya daha fazla karakterden oluşturulan komutlar; * o karakterin kategori kodunun 11 olmadığı tek karakterli komutlar: örneğin `\$` ya da `\#`. Her iki durumda da TeX baştaki `\` karakteri hariç tutar ve kalan her karakterin karakter kodunu, TeX’in şu adını verdiği bir tam sayıyı hesaplamak için kullanır: `curcs` (**geç**erli **c**kontrol **s**dizisi). Ardından TeX, `curcs` komut için bir belirteç değeri hesaplamak üzere. #### Kategori kodu 11 olan karakterlerden oluşan komutlar Komutumuzun (baştaki `\` karakteri) bir karakter dizisinden oluştuğunu varsayalım: $$\mathrm{C\_1C\_2C\_3...C\_N}$$ burada $$\mathrm{C}\_i$$ her karakterin karakter kodudur—örneğin, A harfinin karakter kodu 65’tir. TeX tüm karakter kodlarını kullanır $$\mathrm{C}\_i$$ tam sayıyı hesaplamak için `curcs` (bir [karma işlevi](https://en.wikipedia.org/wiki/Hash_function)). TeX, `curcs` belirteç değerini elde etmek için bu değere yalnızca 4095 ekler: $$\text{command token} = \text{curcs + 4095}$$ Şuna dikkat edin: değişken `curcs` TeX’in iç işleme faaliyetlerinde son derece önemli bir rol oynar. #### Tek karakterli komutlar gibi komutları temsil eden belirteçler `\$`, `\#` vb., biraz farklı bir hesaplamaya tabidir: tam sayı `curcs` şimdi daha basit hesaplamadır: $$\text{curcs} = 257 + \text{character (ASCII) code}$$ Örneğin, `\$`, $$\text{curcs}=257 + 36 = 293$$. TeX yine bu değere 4095 ekler (kullanarak $$\text{command token} = \text{curcs} + 4095$$) ve sonuç olarak `\$` bir belirteç değeri elde edilir $$293 + 4095 = 4388$$. Kategori kodu 11 olan karakterlerden oluşan komutlarla karşılaştırıldığında, buradaki tek fark TeX’in ... için değeri hesaplama biçimidir `curcs`. **Not**: tam sayı `curcs` karakter belirteçleri için hesaplanmaz: TeX karakter belirteçleri oluştururken ya da onlarla çalışırken her zaman 0 olarak ayarlanır. #### Etkin karakter belirteçleri TeX’in sözde *etkin karakterler*: kategori kodu 13 verilmiş herhangi bir karakter. Bu özel karakter sınıfı için belirteçler, normal karakterlere kıyasla farklı bir hesaplamaya tabidir. Etkin-karakter mekanizması, TeX’in gerçekte tek karakterli makrolar oluşturmasına olanak tanır; bunları kullanabilirsiniz *olmayan* etkin karakterin önüne bir kaçış karakteri (genellikle `\`): tek başına duran karakter makro davranışını tetikler. Bunun klasik örneği, TeX/LaTeX’in kesilmez boşluklar için kullandığı tilde karakteri (\~) olup şu şekilde tanımlanabilir/etkinleştirilebilir: ``` \catcode`~=13 % ~ karakterine kategori kodu 13 ata \def~{\penalty100000\ } % ~'yi bir makro gibi davranacak şekilde tanımla ``` TeX daha sonra bir `~` karakteri okuduğunda kategori kodunun 13 olduğunu algılar ve onu bir “mini makro” olarak işler. Etkin bir karakteri temsil eden bir belirteci hesaplamak için TeX, hesaplamanın başka bir varyasyonunu uygular `curcs`: $$\begin{align\*} \text{curcs} &= \text{character code} + 1\ \text{active character token} &= \text{curcs} + 4095\ \end{align\*}$$ Örneğin, \~ karakterinin karakter kodu 126’dır; bu da etkin-karakter belirteci değerinin aşağıdaki gibi hesaplandığı anlamına gelir: $$\begin{align\*} \text{curcs} &= 126 + 1\ \text{active character token} &= 127 + 4095\ &=4222\ \end{align\*}$$ Şuna dikkat edin: komutlarda olduğu gibi, etkin karakterleri temsil eden belirteçler > 4095’tir. ### Sonuçlar/notlar * Değeri 4095’i aşan herhangi bir belirteç hemen bir komut belirteci olarak tanımlanabilir—dolayısıyla TeX, belirli bir belirtecin bir karakteri mi yoksa bir komutu mu temsil ettiğini çok kolay anlayabilir. * Herhangi bir belirteç değeri için TeX, ihtiyaç duyduğunda o belirteci “paketinden çıkararak” aslen sizin `.tex` dosyanızda, bir makro tanımında saklanmış ya da başka bir belirteç listesinde yer alan. * adı verilen “ara” nicelik `curcs`—TeX’in komut belirteci değerlerini hesaplamak için kullandığı— TeX’in düşük düzeyli işlemlerinde önemli bir rol oynar. `curcs` bir komutun geçerli anlamını saklamak/aramak için TeX’in kullandığı bir “indeks değeri” gibi davranır. Herhangi bir komut belirteci verildiğinde, $$\mathrm{T}$$, TeX yalnızca ... değerine erişmek için 4095 çıkarır `curcs`: $$\text{curcs} = \mathrm{T}-4095$$ Bu arada, TeX bir komut belirtecinin üretildiği insan tarafından okunabilir karakter dizisini saklar—bu, hata raporlaması ve `\string` ki bunun genişlemesi, bir belirteç değerinin insan tarafından okunabilir sürümüdür. Ancak TeX içinde saklanan bu insan tarafından okunabilir karakter dizileri yalnızca istendiğinde kullanılır/çıktılanır: diğer tüm işlemlerde belirtecin tam sayı değeri kullanılır. ## Bazı gerçek belirteçlere bakmak Belirteç kavramını biraz daha az anlaşılmaz kılmak için aşağıdaki basit makroyu tanımlayacak ve TeX’in ürettiği belirteçlere bakacağız: ``` \def\hello{Greetings, from \TeX. \hskip 10pt} ``` İçin `\hello` makrosu için TeX şu karakterleri kullanır `h`, `e`, `l`, `l`, `o` için 3745 değerini hesaplamak üzere `curcs`; TeX daha sonra 4095 ekleyerek şu belirteç değerini oluşturur $$3745 + 4095 = 7840$$ (Knuth’un TeX’i, e-TeX veya pdfTeX için). temsil etmek üzere bir belirteç oluşturduktan sonra `\hello`, ikinci `\def` komutu TeX’i sonraki belirteçleri okumaya ve bunları, *tanımı* olan `\hello` komutu. Saklanan bu tanım (belirteç listesi), TeX’e ... kullanmasını söylediğinizde geri alınabilir `\hello` komutunu. Aşağıdaki tablo, ... içinde yer alan her öğe (karakter, makro veya ilkel) için oluşturulan gerçek belirteç değerlerini listeler `\hello` makro tanımı—bu belirteçler (tam sayılar) listesi, TeX’in belleğinde sakladığı şeydir (bir ... olarak bilinen veri yapısı olarak [bağlı liste](https://en.wikipedia.org/wiki/Linked_list)). Belirteç listelerini daha ayrıntılı anlamak isteyen okurlar, Overleaf’in şu makalesine yönlendirilir [TeX belirteç listesi nedir?](/latex/tr/derinlemesine-makaleler/54-what-is-a-tex-token-list.md) | | | | ----------------------- | --------------------- | | **TeX belirteç değeri** | **Temsil edilen öğe** | | 2887 | G | | 2930 | r | | 2917 | e | | 2917 | e | | 2932 | t | | 2921 | i | | 2926 | n | | 2919 | g | | 2931 | s | | 3116 | , | | 2592 | | | 2918 | f | | 2930 | r | | 2927 | o | | 2925 | m | | 2592 | | | 5235 | \TeX | | 3118 | . | | 2592 | | | 7943 | \hskip | | 3121 | 1 | | 3120 | 0 | | 2928 | p | | 2932 | t | Yukarıdaki belirteç listesinde karakterlerin kategori kodları 10, 11 veya 12’dir. Örneğin: * karakterlerin kategori kodu 10 ve karakter kodu 32’dir; bu da şu belirteç değerini verir $$256\times 10 + 32 = 2592$$ * `,` ve `.` kategori kodu 12’ye sahiptir ve sırasıyla 44 ve 46 karakter kodlarına sahiptir; bu da şu belirteçleri verir: * için belirteç `,` $$= 256 \times 12 + 44 = 3116$$ * için belirteç `.` $$= 256\times 12+ 46 = 3118$$ TeX daha sonra 7840 belirteciyle (temsil eden `\hello`) karşılaştığında, gerekiyorsa o belirteci “paketinden çıkararak” şunu ayıklayabilir `curcs` basit hesaplama yoluyla $$\text{curcs} = \text{token value} - 4095$$ (yukarıya bakın). ... değerini kullanarak `curcs` TeX, komut belirteci 7840’ın bir makro komutunu temsil ettiğini belirlemek için iç veri tablolarına başvurabilir. Ayrıca, yine ... aracılığıyla `curcs`, TeX ayrıca ... saklanan tanımı arayıp getirebilir `\hello`. TeX’in 7840 belirtecini tam olarak işlemesi gerektiğinde, yani ... çalıştırmak için `\hello` makroyu, artık 7840 belirtecine ihtiyacı kalmaz: o belirteç *işini yapmıştır*—yani, TeX’in makroyu çalıştırmasını tetiklemiştir `\hello`. TeX artık 7840 belirtecini atabilir ve bellekte saklanan tanımı (belirteç listesi) temsil eden belirteçleri getirebilir. Aslında, `\hello` makro komutu (7840 belirteci) *kaldırılmıştır* TeX’in geçerli giriş kaynağından ve *değiştirilmiştir* ... tanımında bulunan belirteçlerle `\hello`. Az önce anlattığımız şey, bunun bir biçimidir *belirteç genişlemesi*. Bu `\TeX` komutu (yukarıda listelenen 5235 belirteç değeri) ... içinde kullanılan `\hello` kendisinin de daha fazla belirteçten oluşturulmuş bir makro olmasıdır—dolayısıyla tanımı da bir belirteç listesi olarak saklanır: | | | | ----------------------- | --------------------- | | **TeX belirteç değeri** | **Temsil edilen öğe** | | 2900 | T | | 19598 | \\\kern | | 3117 | - | | 3118 | . | | 3121 | 1 | | 3126 | 6 | | 3126 | 6 | | 3127 | 7 | | 2917 | e | | 2925 | m | | 19597 | \\\lower | | 3118 | . | | 3125 | 5 | | 2917 | e | | 2936 | x | | 6175 | \hbox | | 379 | { | | 2885 | E | | 637 | } | | 19598 | \\\kern | | 3117 | - | | 3118 | . | | 3121 | 1 | | 3122 | 2 | | 3125 | 5 | | 2917 | e | | 2925 | m | | 2904 | X | Eğer ... komutunu `\hello` onu oluşturan belirteçlerin tam listesiyle, ... dahil olmak üzere değiştirirsek `\TeX` makroyu, oldukça uzun bir liste olurdu—yani, eğer ayrıca *genişletirsek* şu `\TeX` makroyu görürdük: ![Bir TeX makrosunda saklanan belirteç listesi](/files/d434c60ca62d15ffb2e1c0fcb61002b87805ae9d) Esasen, 7840 tek belirteci ( `\hello`) tam olarak genişletildiğinde, karakterleri ve ilkel komutları temsil eden toplam 51 belirteç (tam sayı) üretirdi. Aşağıdaki listede her belirtecin temsil ettiği karakter veya komut, parantez içinde “(...)” ile gösterilmiştir—bunlar TeX’in belirteç listelerinde doğrudan saklanmaz ve okura yardımcı olmak için gösterilmiştir: ``` 2887 (G), 2930 (r), 2917 (e), 2917 (e), 2932 (t), 2921 (i), 2926 (n), 2919 (g), 2931 (s), 3116 (,), 2592 (), 2918 (f), 2930 (r), 2927 (o), 2925 (m), 2592 (), 2900 (T), 19598 (\kern), 3117 (-), 3118 (.), 3121 (1), 3126 (6), 3126 (6), 3127 (7), 2917 (e), 2925 (m), 19597 (\lower), 3118 (.), 3125 (5), 2917 (e), 2936 (x), 6175 (\hbox), 379 ({), 2885 (E), 637 (}), 19598 (\kern), 3117 (-), 3118 (.), 3121 (1), 3122 (2), 3125 (5), 2917 (e), 2925 (m), 2904 (X), 3118 (.), 2592 (), 7943 (\hskip), 3121 (1), 3120 (0), 2928 (p), 2932 (t) ``` İnsan okur için bu yalnızca bir dizi tam sayıdır, ancak TeX için büyük miktarda bilgi kodlar. ## Belirteçleri şimdi oku ve daha sonra için kaydet TeX girişinizi okurken, belirli bir belirteç kümesini tam olarak işlemeyi geciktirmesi gereken (veya bunu yapması için yönlendirildiği) zamanlar olabilir. Bunu yapması istenirse, durması söylenene kadar TeX girişten belirteçler oluşturmaya devam eder, ancak bunları daha sonra kullanılmak üzere saklar—ardından bunları dizgi faaliyetlerinin bir parçası olarak geri alır ve işler. Bu saklanan belirteçler sözde *belirteç listeleri* ki bunlar gerçekte TeX'in tek (dahili) belirteç-veri depolama mekanizmasıdır. Belirteç listelerine örnekleri zaten gördük—yukarıda listelenen `\hello` ve `\TeX` makrolar: bu makroların tanımı TeX’in belleğinde belirteç listeleri olarak saklanır. TeX bu tür belirteç listelerini yalnızca bu makroları çağırmaya karar verdiğinizde işler (eyleme geçirir). Ayrıca her belirtecin (tam sayı değerinin) TeX’in bir makro tanımında saklanan her belirtecin bir karakteri mi yoksa bir komutu mu temsil ettiğini kolayca anlaması için yeterli bilgiyi kodladığını unutmayın. ### Belirteçleri belirteç kayıtlarıyla kaydetme Belirteç depolamanın bir başka örneği, sözde *belirteç kayıtları*: TeX’in kullanıcıların belirteç listelerini saklaması için sağladığı özel dahili depolama alanları. TeX’in ilkel komutu `\toksdef` belirteç kayıtlarını kullanmanın bir yoludur; örneğin, belirteç kaydını kullanmak için `100` ve ona şu komutla başvurmak için `\mylist`: ``` \toksdef\mylist=100 \mylist={some \TeX{} tokens here} ``` `\mylist` aslında, kayıt konumunda saklanan bir belirteç listesine verdiğiniz yalnızca bir addır `100`. Bir makro tanımına benzer şekilde, `\mylist` şu belirteç listesini içerir: | | | | ----------------------- | --------------------- | | **TeX belirteç değeri** | **Temsil edilen öğe** | | 2931 | s | | 2927 | o | | 2925 | m | | 2917 | e | | 2592 | | | 5235 | \TeX | | 379 | { | | 637 | } | | 2592 | | | 2932 | t | | 2927 | o | | 2923 | k | | 2917 | e | | 2926 | n | | 2931 | s | | 2592 | | | 2920 | h | | 2917 | e | | 2930 | r | | 2917 | e | **Not**: ... sonlandırmak için `\TeX` makroyu ve onu takip eden `` karakter için bir çift süslü parantez kullandık `{}` hemen sonra `\TeX`—için belirteçler `{` (379) ve `}` (637) belirteç listesinde saklanır. Başka bir seçenek, bir “kontrol boşluğu” belirteci kullanmaktır `\` ki bu, aşağıda gösterildiği gibi (kalın) belirteç listesinde görünür: | | | | ----------------------- | --------------------- | | **TeX belirteç değeri** | **Temsil edilen öğe** | | 2931 | s | | 2927 | o | | 2925 | m | | 2917 | e | | 2592 | | | 5235 | \TeX | | **4384** | **\\** | | 2932 | t | | 2927 | o | | 2923 | k | | 2917 | e | | 2926 | n | | 2931 | s | | 2592 | | | 2920 | h | | 2917 | e | | 2930 | r | | 2917 | e | Şuna dikkat edin ki, `` karakter şu şekilde temsil edilir: bir *karakter belirteci* değerine sahip $$256\times 10 + 32 = 2592$$ ancak `\` tek karakterli bir *komut belirteci* (4384 değeri) ve yukarıda verilen formüller kullanılarak hesaplanır: \begin{align\*} \text{curcs} & = 257 + \text{character (ASCII) code}\\\ & = 257 + 32\\\ &=289\\\ \text{command token for} \left<\text{\\\space}\right> & = \text{curcs + 4095}\\\ & = 289+4095\\\ &=4384\\\ \end{align\*} Özünde `\mylist={some \TeX{} tokens here}` TeX’e şunu söyler: lütfen aşağıdaki karakterleri/komutları belirteçlere dönüştürmek ve daha sonra kullanmak üzere kaydetmek için giriş dosyamı tara. TeX bunu yapar ve bu belirteçleri, şu yazarak erişebileceğiniz bir bellek konumunda saklar `\the\mylist`, TeX’e belirteç kaydında bulunan belirteçlerin bir kopyasını eklemesini söyleyerek `\mylist`. TeX motorları, belirteç listelerini açıkça oluşturan ve saklayan bir dizi ilkel komut içerir—örneğin `\\everyjob`, `\\everypar`, `\mark`, ve daha niceleri. [Bölüm 1](/latex/tr/derinlemesine-makaleler/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md) [Bölüm 2](/latex/tr/derinlemesine-makaleler/22-how-does-expandafter-work-the-meaning-of-expansion.md) [Bölüm 3](/latex/tr/derinlemesine-makaleler/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) [Bölüm 4](/latex/tr/derinlemesine-makaleler/20-how-does-expandafter-work-from-basic-principles-to-exploring-tex-s-source-code.md) [Bölüm 5](/latex/tr/derinlemesine-makaleler/17-how-does-expandafter-work-a-detailed-macro-case-study.md) [Bölüm 6](/latex/tr/derinlemesine-makaleler/18-how-does-expandafter-work-a-detailed-study-of-consecutive-expandafter-commands.md) --- # 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://ayakaleaf-pro.ayaka.space/latex/tr/derinlemesine-makaleler/19-how-does-expandafter-work-an-introduction-to-tex-tokens.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.