> 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/uk/inshi-temi/18-how-overleaf-created-the-tex-primitive-reference-data.md).

# Як Overleaf створив довідкові дані про примітиви TeX

У цій статті описано методи й техніки, використані для створення двох таблиць перехресних посилань для примітивних команд TeX:

* [Примітиви TeX, перелічені за рушієм TeX](/latex/uk/inshi-temi/46-tex-primitives-listed-by-tex-engine.md) та;
* [Примітиви TeX, перелічені за рушієм CJK TeX](/latex/uk/inshi-temi/45-tex-primitives-listed-by-cjk-tex-engine.md).

Ця інформація надається для читачів, зацікавлених у тонших деталях, але не є передумовою для використання самої таблиці перехресних посилань. Щоб задовольнити потреби різних читачів, ми подаємо дуже коротку підсумкову версію разом із докладнішим поясненням для тих, хто хоче глибше дослідити ці питання.

## Коротка підсумкова/оглядова версія

Щоб побудувати таблицю перехресних посилань, Overleaf обробив вихідний код 9 рушіїв TeX, щоб витягти список примітивів, які підтримує кожен із них: цей процес дав 9 текстових файлів (1 файл на кожен рушій TeX). Ці 9 наборів примітивів було об’єднано, щоб створити «головний список», який фактично був об’єднанням окремих наборів примітивів: усього вийшло близько 1000 унікальних примітивів, розподілених між різними рушіями. Для кожного рушія його власний список примітивів було зіставлено з головним файлом (набором усіх команд), щоб визначити, які з цих \~1000 команд він підтримує: ці порівняння подано в наступних двох таблицях:

* [Дані перехресних посилань на примітиви TeX](/latex/uk/inshi-temi/46-tex-primitives-listed-by-tex-engine.md)
* [Дані перехресних посилань на примітиви TeX (для CJK-рушіїв)](/latex/uk/inshi-temi/45-tex-primitives-listed-by-cjk-tex-engine.md)

## «Побудова програмного забезпечення» 101: що це означає?

У решті цієї статті ми згадуємо поняття «збирання рушіїв TeX», яке може бути незнайомим, якщо ви не програміст або не програмуєте мовами компільованого типу, такими як C чи C++. Для наших цілей збирання програмного забезпечення — тобто рушіїв TeX — це процес створення виконуваної програми TeX з її складових частин — файлів вихідного коду, написаних мовою програмування, що використовується для розробки програми.

## Повна версія: хочете деталей? Читайте далі...

Кожен рушій верстки на основі TeX підтримує «діалект» мови TeX: певний набір примітивних команд, які керують можливостями верстки кожного рушія та слугують будівельними блоками для створення/визначення макросів: користувацьких послідовностей команд. Кожен макрос, чи то написаний для LaTeX, plain TeX або будь-якого іншого пакета макросів, зрештою, побудований із примітивних команд — хоча вам, можливо, доведеться заглибитися дуже далеко, крізь шари додаткових макросів, перш ніж ви дійдете до «базового шару» примітивів TeX. Набір 9 рушіїв TeX, проаналізованих для отримання довідкових даних про примітивні команди, звісно, має багато спільних команд, але кожен рушій TeX також має власні примітивні команди, додані його розробниками, щоб забезпечити підтримку функцій, специфічних для цієї «версії» TeX.

Примітивні команди рушія TeX вбудовані у виконуване програмне забезпечення TeX: примітиви — це не макроси, створені користувачами, а фундаментальні, неподільні/атомарні інструкції, що використовуються для керування поведінкою верстки кожного рушія. Відповідно, найнадійніший спосіб створити остаточний список примітивних команд, які підтримує будь-який рушій TeX, — це вивчити фактичний вихідний код, з якого збираються (компілюються) виконувані програми TeX, і витягти список примітивів, визначених у цьому вихідному коді. Здається, це має бути легко, правда? Однак через 40-річну історію розвитку TeX вивчення/перегляд файлів вихідного коду рушіїв TeX (крім LuaTeX) не є особливо простим. Причина цих складнощів полягає в інструментах, мові програмування (Pascal) і методології (літературне програмування), які Кнут використав для написання оригінального вихідного коду TeX — від якого, зрештою, походять усі інші рушії.

Зазначимо виняток для LuaTeX, оскільки його основний код рушія було переписано мовою C, щоб усунути використання Pascal та інших застарілих складнощів, описаних нижче (Web2C); отже, хоча вихідний код LuaTeX значний, спосіб його «пакування» та поширення значно зрозуміліший порівняно з іншими рушіями TeX. Внаслідок цього, а також з огляду на робочі процеси/процедури, що використовуються для збирання їх із вихідного коду, зручно поділити рушії TeX на дві категорії:

1. LuaTeX: спеціальний (сучасніший) процес збирання
2. Усі інші рушії: застарілий процес збирання (Web2C)

## Контекст застарілого коду: чому збирання (більшості) рушіїв TeX є складним

Як ми побачимо нижче, Кнут опублікував свій оригінальний вихідний код TeX як один монолітний файл під назвою `tex.web` який Кнут і надалі оновлює раз на 7 років, щоб виправити всі залишкові помилки — нові можливості ніколи не додаються, це суто робота з виправлення помилок.

Розширення вихідного коду TeX (`.web`) навряд чи буде знайоме, і ви можете запитати, якою мовою Кнут написав TeX? Відповідь — Pascal, але `.web` розширення потребує трохи докладнішого пояснення. Кнут розробив методологію програмування, яку він назвав [літературним програмуванням](https://en.wikipedia.org/wiki/Literate_programming) у якій вихідний код програми та документація поєднуються й випускаються як один складений файл (код плюс документація) з розширенням `.web`: цей тип файлів називають файлом WEB. Нижче ми трохи докладніше пояснимо файли WEB.

### Створення нових рушіїв TeX: вимоги Кнута

Хоча Кнут уже давно зробив свій вихідний код TeX (`tex.web`) вільно доступним для всіх, він, як має повне на це право, висунув ключову вимогу: його вихідний код (`tex.web`) не можна безпосередньо редагувати/змінювати й поширювати під назвою програми «TeX». У вихідному коді він пише:

```
% Ця програма є об’єктом авторського права (C) 1982 D. E. Knuth; усі права застережено.
% Копіювання цього файла дозволено лише якщо (1) ви — D. E. Knuth, або якщо
% (2) ви абсолютно нічого не змінюєте у своїй копії. (Система WEB забезпечує
% внесення змін через допоміжний файл; основний файл має залишатися незмінним.)
```

а також:

```
Якщо цю програму змінено, отриману систему не слід називати
`\TeX'; офіційна назва `\TeX' сама по собі зарезервована
для програмних систем, які повністю сумісні одна з одною.
Для
допомоги у визначенні того, чи заслуговує конкретна реалізація на те, щоб бути
відомою як `\TeX' [пор. звіт Стенфордського факультету комп’ютерних наук CS1027,
листопад 1984 р.].
```

По суті: не вносіть зміни шляхом редагування та поширення змінених версій основного вихідного коду TeX і не продовжуйте називати його `tex.web`. Якщо ви хочете вносити зміни, наприклад додавати нові примітиви тощо, тоді ви повинні застосовувати ці зміни, роблячи «внесення змін через допоміжний файл», і дати своїй програмі «похідної від TeX» назву, яка відрізняє її від «TeX», який у друкованому вигляді ($$\mathrm\TeX$$) є торговою маркою Американського математичного товариства.

### Спадщина застарілого

Хоча були спроби повністю переписати TeX сучасними мовами програмування та методологіями — такими як дві ініціативи на основі Java [Нова система верстки](https://en.wikipedia.org/wiki/New_Typesetting_System) та [εχTEX](http://www.extex.org/) та інші, наприклад [одна на Clojure](https://www.infoq.com/news/2015/01/implementing-tex-in-clojure), жодна не була повністю успішною. Історія проєктів та ініціатив, спрямованих на подальший розвиток TeX, є цікавою темою, і читачі можуть [відвідати UK TeX FAQ](https://texfaq.org/FAQ-enginedev) для додаткової інформації.

Ті не-LuaTeX ініціативи, які також були успішними, такі як e-TeX, pdfTeX, XeTeX та інші рушії, будували *безпосередньо поверх* оригінального коду Кнута: беручи його вихідний код і «застосовуючи зміни», щоб отримати новий рушій з додатковими можливостями — такими як додавання нових примітивів, створення PDF-виводу, підтримка введення тексту UTF-8 тощо. Хоча цей шлях призвів до помітних успіхів, він також означає, що ці похідні рушії успадковують застарілий код і методи розробки, які Кнут створив 40 років тому.

Головний висновок тут такий: окрім LuaTeX, більшість рушіїв TeX, похідних від оригінального вихідного коду Кнута, створюються шляхом взяття одного монолітного файла (зазвичай `tex.web`) і застосування змін, які генерують ще один монолітний файл, що містить вихідний код ядра цього нового рушія. Досвідчені читачі можуть захотіти перейти далі до приміток [щодо pdfTeX і XeTeX](#aside-xetex-and-pdftex).

### Дещо додаткової історії/контексту TeX

Момент народження TeX був [зафіксований у щоденнику Кнута як 30 березня 1977 року](/latex/uk/dokladni-statti/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md#the-genesis-of-tex-a-brief-history), тобто понад 40 років тому. Усередині TeX — надзвичайно складна програма, вихідний код якої Кнут доклав великих зусиль, щоб [документувати з винятковою докладністю](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373). Для цього Кнут розробив стиль програмування, який він назвав [літературним програмуванням](https://en.wikipedia.org/wiki/Literate_programming) у якому вихідний код програми та документація об’єднуються й випускаються як складений файл з розширенням `.web` (який називають файлом WEB). Кнут обрав Pascal як мову програмування для написання свого програмного забезпечення TeX і, не дивно, використав мову верстки TeX для написання кінцевої документації. Відповідно, основний вихідний код TeX Кнута опубліковано як один монолітний файл під назвою `tex.web`: суміш вихідного коду Pascal і коду верстки TeX для документації.

Якщо програма написана з використанням стилю/методології літературного програмування Кнута (як TeX, MetaFont, BibTeX та інші), вам потрібно попередньо обробити файл WEB, щоб витягти документацію або вихідний код. Щоб отримати доступ до документації програми, ви обробляєте файл WEB (наприклад, `tex.web`) за допомогою утиліти під назвою [WEAVE](http://tug.org/texinfohtml/web2c.html#weave-invocation) , яка виводить документацію як `.tex` файл, який можна зверстати. Щоб витягти вихідний код мовою Pascal, ви використовуєте іншу утиліту під назвою [TANGLE](http://tug.org/texinfohtml/web2c.html#tangle-invocation) , яка виводить файл із розширенням `.p` що містить вихідний код Pascal.

На момент написання (початок 2019 року) найновіша версія TeX Кнута — 3.14159265, датована січнем 2014 року. Знову ж таки, зауважте, що вихідний код TeX Кнута міститься лише в одному файлі, що налічує близько 25 000 рядків коду TeX/Pascal!

### Від Pascal до C

За 40+ років, що минули від народження TeX, Pascal вийшов із моди, і сьогодні мало хто, якщо такі взагалі є, замислюється над збиранням TeX із його оригінального вихідного коду Pascal. Щоб обійти використання Кнутом Pascal, було розроблено робочий процес під назвою [Web2C](http://tug.org/texinfohtml/web2c.html) який було створено приблизно 1987 року; у ньому вихідний код TeX мовою Pascal механічно (тобто за допомогою програмного забезпечення) перетворюється на еквівалентний код C, який потім використовується для компіляції TeX і збирання виконуваної програми. Це працює добре, але єдиний недолік полягає в тому, що згенерований механічно вихідний код C не призначений для випадкового людського перегляду: він *надзвичайно* багатослівний і майже непроникний, оскільки призначений для компіляторів, а не для людей — ось знімок екрана, що показує невеликий фрагмент коду C, згенерованого з вихідного коду Pascal TeX:

![](/files/299f57ac45301bb9a15d07271af8226f788f0d11)

### Ще один кнутизм: файли змін WEB

Як зазначено вище, щоб розвивати оригінальний вихідний код Кнута, ви «застосовуєте зміни» або, словами Кнута, робите «внесення змін через допоміжний файл»: але що це фактично означає? Знайомтеся з *механізмом файла змін*.

### Файли змін: механізм створення нових рушіїв TeX

Розробники, які хочуть у якийсь спосіб розширити TeX Кнута, тобто розвивати його оригінальну роботу, зазвичай хочуть створити цілком нову «версію» TeX або надати *розширення* яке можна додати до будь-якого рушія TeX. Прикладами розширень є [SyncTeX](https://github.com/jlaurens/synctex) та [EncTeX](https://ctan.org/pkg/enctex?lang=en)— SyncTeX, наприклад, є дуже корисним розширенням, яке тепер включено до всіх рушіїв TeX. Потреба в EncTeX значною мірою була витіснена еволюцією рушіїв TeX, що підтримують Unicode, — але зауважте, що EncTeX вбудовано в pdfTeX.

Незалежно від того, чи бажання полягає у створенні нової «версії» TeX (тобто похідної від оригінального TeX Кнута), чи у створенні розширення, його розробники починають з оригінального вихідного коду Кнута і застосовують модифікації, необхідні для створення нового рушія TeX (або розширення-додатка). Однак, як зазначено вище, будь-хто, хто хоче змінити поведінку TeX, має робити це за допомогою «внесення змін через допоміжний файл», тому що ці зміни/модифікації не можна застосовувати шляхом *безпосереднього* редагування оригінального вихідного коду Кнута: розробники зобов’язані використовувати так звану систему WEB *механізмом файла змін*. Код для модифікації TeX Кнута пишеться мовою WEB і зберігається в одному або кількох файлах коду (які називають *файлами змін*), які потім *об’єднуються* з оригінальним, незміненим, головним вихідним кодом Кнута. Цей процес об’єднання створює новий складений файл WEB, який тепер містить *основний* вихідний код нового/зміненого програмного забезпечення на базі TeX. *Файли змін* часто мають розширення `.ch` але на практиці вони можуть мати будь-яке розширення, бажане розробниками.

#### Як використовувати/застосовувати файли змін?

Нині найпростіший спосіб застосувати файли змін і модифікувати «головний» файл WEB — це скористатися утилітою під назвою [TIE](https://ctan.org/pkg/tie). Наприклад, припустімо, що ви хотіли б модифікувати TeX Кнута, додавши, скажімо, пару нових примітивів, або хотіли б змінити поведінку наявного (стандартного) примітиву TeX. Ви б написали свій код (мовою Pascal!) за допомогою системи літературного програмування WEB і зберегли б його у файл під назвою, скажімо, `myprim.ch`. Наступний крок — об’єднати ваш код (у `myprim.ch`) з головним вихідним файлом Кнута `tex.web` і створити новий складений файл WEB, який представлятиме те, що ми назвемо `mytex.web`. Для цього просто виконайте програму TIE ось так:

```
tie -m mytex.web tex.web myprim.ch
```

Якщо об’єднання успішне, це призведе до появи нового файла WEB, `mytex.web`, залишаючи головний вихідний файл Кнута `tex.web` повністю незмінним, як і вимагається.

Тепер припустімо, що комусь іншому подобаються зміни, які ви внесли, і він хоче модифікувати вашу роботу, щоб додати свої зміни поверх або на додачу до того, що зробили ви. Замість того щоб поширювати вашу змінену версію TeX (`mytex.web`) ви вирішуєте публікувати/ділитися лише файлом змін, `myprim.ch`. Будь-хто, хто хоче розвивати вашу роботу, тепер може створити й поділитися своїм файлом змін під назвою, скажімо, `moreprim.ch` який певним чином розширює ваш код. Будь-хто інший, хто хоче скористатися обома файлами змін, тепер може згенерувати новий складений файл WEB, об’єднавши *обидва* файли змін із оригінальним файлом Кнута, щоб створити ще одну програму TeX, яку назвемо, скажімо, `newmytex.web`:

```
tie -m newmytex.web tex.web myprim.ch moreprim.ch
```

### Справжні системи TeX: кілька файлів змін

Опис TIE вище насправді дуже близький до того, як багато рушіїв TeX збираються на практиці: вони починають із `tex.web` Кнута і додають послідовність файлів змін, щоб згенерувати вихідний файл WEB для цього рушія. Кожен рушій TeX вимагає власного набору файлів змін, які потрібно застосовувати/обробляти (об’єднувати) у суворо визначеному порядку: якщо порядок порушити, процес об’єднання зазнає невдачі, тому що кожен файл змін у послідовності спирається на зміни, внесені файлами змін, що стоять раніше в ланцюжку.

Ось приклад запуску TIE, що застосовує кілька файлів змін до `tex.web` Кнута, щоб згенерувати `ktex.web`— складений файл WEB із модифікаціями TeX Кнута, які роблять його готовим (придатним) для перетворення в C через процес Web2C. Також зауважте наступне:

* `tex.ch` — це дуже великий файл змін, який, серед іншого, модифікує TeX для використання Kpathsea;
* розширення SyncTeX додається через кілька файлів змін.

```
tie -m ktex.web tex.web tex.ch enctex.ch synctex-def.ch0 synctex-mem.ch0 synctex-mem.ch2 synctex-rec.ch0 synctex-rec.ch1 synctex-rec.ch2 tex-binpool.ch
Це TIE, версія CWEB 2.4.
Авторське право (c) 1989,1992 THD/ITI. Усі права застережено.
(tex.web)
(tex.ch)
(enctex.ch)
(synctex-def.ch0)
(synctex-mem.ch0)
(synctex-mem.ch2)
(synctex-rec.ch0)
(synctex-rec.ch1)
(synctex-rec.ch2)
(tex-binpool.ch)
....500....1000....1500....2000....2500....3000....3500....4000....4500
....5000....5500....6000....6500....7000....7500....8000....8500....9000
....9500....10000....10500....11000....11500....12000....12500....13000
....13500....14000....14500....15000....15500....16000....16500....17000
....17500....18000....18500....19000....19500....20000....20500....21000
....21500....22000....22500....23000....23500....24000....24500....
(Помилок не виявлено.)
```

#### До речі: XeTeX і pdfTeX

Для повноти слід зазначити, що процес збирання pdfTeX і XeTeX фактично не починається з `tex.web`Кнута; натомість він починається з файлів під назвами `pdftex.web` та `xetex.web` відповідно: ймовірно, тому що зміни настільки масштабні, що має сенс поширювати/публікувати файли WEB, які вже містять дуже значні модифікації, внесені до оригінального коду Кнута.

### Приклад: e-upTeX

Японська спільнота TeX розробила низку рушіїв TeX, призначених для врахування складностей верстки японського тексту:

* **pTeX**: рушій TeX Кнута, розширений для підтримки японської верстки;
* **e-pTeX**: комбінація e-TeX і pTeX (плюс кілька примітивів, запроваджених pdfTeX);
* **upTeX**: версія pTeX, обізнана з Unicode, плюс розширення для кращої роботи з CJK (китайською, японською та корейською);
* **e-upTeX**: комбінація (об’єднання) e-TeX і upTeX.

#### Створення складеного вихідного файла для e-upTeX

Щоб створити складений вихідний файл WEB для e-upTeX (із SyncTeX), ви починаєте з `tex.web` Кнута, але потрібно застосувати **26** окремі файли змін, у такому порядку, щоб отримати один складений файл, з якого можна витягти список примітивних команд:

```
etex.ch, tex.ch0, tex.ch, tex.ech, etex.ch0,
ptex-base.ch, uptex-m.ch, euptex.ch0, eptex.ech,
etex.ch1, euptex.ch1, synctex-def.ch0, synctex-ep-mem.ch0,
synctex-mem.ch0, synctex-e-mem.ch0, synctex-ep-mem.ch1,
synctex-p-rec.ch0, synctex-rec.ch0, synctex-rec.ch1,
synctex-e-rec.ch0, synctex-p-rec.ch1, fam256.ch,
pdfstrcmp-eup-pre.ch, pdfutils.ch, pdfstrcmp-eup-post.ch,
tex-binpool.ch
```

#### Застосування файлів змін: які файли і в якому порядку?

Як зазначено, критично важливо застосовувати/обробляти файли змін у суворому порядку — але як дізнатися, які файли потрібні і в якому порядку їх обробляти? На щастя, цю важливу інформацію записано у файлах, що містяться в дистрибутиві TeX Live, а дослідження вихідного коду TeX Live виявило правила, які визначають вимоги до збирання для кожного рушія TeX. Дотримуючись цих правил, Overleaf змогла відновити складений вихідний файл WEB для кожного рушія TeX і витягти список примітивів для подальшої обробки даних.

## І нарешті: як витягти список примітивів?

Після побудови складеного файла WEB завдання витягнення списку примітивів за допомогою регулярних виразів є простим, оскільки всі примітивні команди визначаються («реєструються») за допомогою однієї функції Pascal під назвою `primitive(...)`. Ось кілька реальних прикладів, узятих із `tex.web` вихідного коду Кнута:

```
primitive("lineskip",assign_glue,glue_base+line_skip_code)
primitive("baselineskip",assign_glue,glue_base+baseline_skip_code)
primitive("parskip",assign_glue,glue_base+par_skip_code)
primitive("abovedisplayskip",assign_glue,glue_base+above_display_skip_code)
primitive("belowdisplayskip",assign_glue,glue_base+below_display_skip_code)
primitive("abovedisplayshortskip",assign_glue,glue_base+above_display_short_skip_code)
...
...
```

Як бачите, функція `primitive(...)` дуже добре піддається обробці тексту за допомогою регулярних виразів: назва примітиву, що реєструється, міститься в лапках (`"..."`) разом із додатковими даними, які класифікують поведінку кожного примітиву (ми не будемо розглядати це докладно). Після витягнення списку примітивів для кожного рушія ці дані було оброблено деякими Lua-скриптами, щоб згенерувати HTML із табличними результатами.

### Повертаючись до LuaTeX

Ми вже зазначали, що LuaTeX не використовує точно ті самі процеси збирання, що й інші 8 рушіїв TeX. Коротко розглянувши процес Web2C, перетворення Pascal у C та механізм файлів змін, тепер ми можемо пояснити, чим LuaTeX відрізняється: розробники LuaTeX вирішили відмовитися від громіздкого процесу перетворення Pascal у C — як зазначено в [Довіднику з LuaTeX](http://www.pragma-ade.com/general/manuals/luatex):

> ...фреймворк компіляції — це web2c, і ми продовжуємо його використовувати, але без кроку перетворення Pascal у C.

Основний рушій LuaTeX було переписано мовою C, що означає, що його процес збирання є дещо стандартнішим і, безперечно, значно зручнішим. Одним із корисних наслідків є те, що примітиви, які підтримує LuaTeX, акуратно винесено в окремий вихідний файл C, що суттєво полегшило завдання доступу до них і їх переліку.

Строго кажучи, слід також зазначити, що деякі файли вихідного коду LuaTeX використовують варіант методології літературного програмування Кнута, який називається [CWEB](https://en.wikipedia.org/wiki/CWEB), що ґрунтується на C, а не на Pascal.

### Не лише файли WEB: потрібен інший вихідний код

Після генерування складеного вихідного файла WEB для будь-якого рушія TeX (крім LuaTeX) вихідний код Pascal потрібно витягти та перетворити на код C, але це ще не повне рішення. Окрім коду C, згенерованого з вихідного WEB-коду (Pascal⮕C), більшість рушіїв TeX також покладаються на (вимагають) низку додаткових допоміжних файлів вихідного коду (бібліотек), які зазвичай написані мовою C — таких як [Kpathsea](https://www.tug.org/kpathsea/). Допоміжні вихідні файли (бібліотеки) реалізують функціональність, яку не потрібно або неможливо писати у WEB (Pascal). Усе, що написано мовою WEB для TeX, має використовувати мову Pascal, яка згодом витягується й перетворюється на згенерований машиною код C: якщо вам не потрібно цього робити, навіщо взагалі писати це не відразу мовою C або C++.


---

# 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/uk/inshi-temi/18-how-overleaf-created-the-tex-primitive-reference-data.md?ask=<question>&goal=<endgoal>
```

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