> 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/fr/articles-approfondis/22-how-does-expandafter-work-the-meaning-of-expansion.md). # Comment fonctionne \expandafter : le sens de l’expansion [Partie 1](/latex/fr/articles-approfondis/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md) [Partie 2](/latex/fr/articles-approfondis/22-how-does-expandafter-work-the-meaning-of-expansion.md) [Partie 3](/latex/fr/articles-approfondis/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) [Partie 4](/latex/fr/articles-approfondis/20-how-does-expandafter-work-from-basic-principles-to-exploring-tex-s-source-code.md) [Partie 5](/latex/fr/articles-approfondis/17-how-does-expandafter-work-a-detailed-macro-case-study.md) [Partie 6](/latex/fr/articles-approfondis/18-how-does-expandafter-work-a-detailed-study-of-consecutive-expandafter-commands.md) ## Introduction au concept d’« expansion » de TeX Après avoir passé en revue [les jetons TeX et les listes de jetons](https://www.overleaf.com/learn/latex/Articles/\expandafter_TeX_tokens?preview=true), le prochain sujet de notre liste de thèmes de fond pour `\expandafter` est le concept de TeX de *expansion*: le processus central de TeX `\expandafter` avec lequel il est conçu pour fonctionner. ### Sur la difficulté d’expliquer l’expansion... Pour la plupart d’entre nous, le concept d’expansion de TeX, ainsi que les raisons/mécanismes qui le sous-tendent, peuvent être déroutants — ils ne sont pas faciles à *entièrement* expliquer de manière simple et concise. Beaucoup des opérations/processus internes de TeX sont liés entre eux de façons assez complexes, ce qui peut poser des difficultés lorsqu’on essaie de « disséquer » certains aspects des opérations de TeX : tenter d’en parler isolément du programme dans son ensemble. L’expansion est certainement un concept qui entre dans cette catégorie parce qu’elle est un *fondamental* élément fondamental du comportement de TeX, et profondément intégré dans tous ses processus internes. Cependant, cet article tente de construire une explication de l’expansion, en offrant une base sur laquelle les lecteurs pourront s’appuyer. Pour expliquer le mécanisme d’expansion de TeX, nous procéderons pas à pas, en examinant un ensemble de sujets liés/pertinents, et en les assemblant pour développer une compréhension de cet élément crucial du comportement de TeX. Plus loin dans l’article, et pour le lecteur plus intrépide qui aime les détails, nous jetterons un coup d’œil à l’intérieur même de TeX, en résumant le code source clé qui pilote le processus d’expansion. ### Points clés sur les jetons TeX Tout au long de la discussion qui suit, il est important de se rappeler que TeX peut obtenir son prochain élément d’entrée à partir de deux sources : 1. **fichiers texte physiques**: en générant *de nouveaux jetons* en lisant/scannant les caractères et les commandes contenus dans ces fichiers, ou 2. **listes de jetons**: en obtenant l’entrée en lisant une liste de jetons existants, *préparés à l’avance*, jetons stockés dans la mémoire de TeX. Rappelons également que TeX utilise les jetons comme un moyen pratique d’« empaqueter » proprement les informations sur tout élément (caractère ou commande) qu’il a lu. Lorsque TeX génère *de nouveaux jetons* il *au moment de la production du jeton*, avoir un accès immédiat aux informations sur l’élément dont il calcule la valeur de jeton. Par exemple, lors de la génération de nouveaux jetons de commande, TeX calcule d’abord une valeur appelée `curcs` qui permet à TeX de rechercher des informations sur la commande dont il est sur le point de produire le jeton. Cependant, si TeX lit des listes de jetons (séquences de *jetons stockés*) il devrait d’abord « dépaqueter » chaque jeton de cette liste avant de pouvoir déterminer ce que représente chaque jeton. Par exemple, TeX pourrait lire des jetons stockés dans le cadre d’une définition de macro : ces jetons auraient été générés à partir d’un texte lu il y a longtemps, converti en jetons puis mis de côté. Le type de jeton (caractère ou commande) détermine ce que signifie réellement le « dépaquetage » chez TeX : * pour *jetons de commande* (la valeur du jeton est > 4095) : calculer `curcs` via $$\text{curcs}=\text{token value}-4095$$ et utiliser `curcs` pour rechercher des informations sur la commande ; * pour *jetons de caractères* (la valeur du jeton est < 4095) : décomposer le jeton de caractère en sa paire constitutive (code du caractère, code de catégorie). ### Au commencement... Pour commencer notre exploration de l’expansion, nous verrons comment les moteurs TeX classent, ou catégorisent, l’ensemble des commandes qu’ils peuvent traiter. Pour le moment, supposons que « expansible » soit simplement une certaine « propriété », encore inexpliquée, d’une commande TeX. ### La notion de commandes « expansibles » Tous les programmes de composition fondés sur TeX (les « moteurs » TeX) comprennent deux principales « classes » de commandes : * les commandes intégrées au moteur exécutable lui-même : les soi-disant *primitives*; * les commandes définies par l’utilisateur : les soi-disant *macros*. Les moteurs TeX utilisent aussi le fait d’« être expansible », un type de « comportement » des commandes, comme mécanisme pour classer toutes les commandes en deux groupes : * commandes expansibles ; * commandes non expansibles. On peut donc considérer que l’ensemble de toutes les commandes (primitives plus macros) peut être classé comme le montre le graphique suivant : ![Schéma montrant la classification de toutes les commandes TeX](/files/db36f14083b931592f60202a1f0a680531343170) Bien que nous ne sachions pas encore ce que signifient réellement l’expansion/le caractère expansible, on peut voir que : * toutes les macros sont classées comme commandes expansibles ; * certaines commandes primitives (intégrées) sont également classées comme expansibles (la grande majorité ne le sont pas). **Note sur les caractères actifs**: En plus des primitives et des macros, il existe une troisième classe d’éléments « expansibles » : les caractères actifs — tout caractère auquel on a attribué le code de catégorie 13 est également considéré comme « expansible » parce qu’il est traité comme une « macro miniature ». #### Comment TeX sait-il si une commande est « expansible » ? D’après notre [discussion sur les jetons TeX](https://www.overleaf.com/learn/latex/Articles/\expandafter_TeX_tokens?preview=true) nous savons que les jetons ne sont rien de plus que des entiers que TeX calcule et utilise pour « empaqueter » des informations sur un élément d’entrée : un caractère ou une commande. Nous avons également noté que, pour n’importe quelle valeur de jeton (entier), TeX peut, si/au besoin, inverser le processus de tokenisation pour « dépaqueter » un jeton et révéler des données sur la commande ou le caractère qu’il représente. En utilisant les données produites lorsque TeX crée un nouveau jeton, ou des données extraites d’un jeton existant — par ex. un jeton stocké dans une macro ou une autre liste de jetons — TeX peut vérifier ses tables internes de stockage de données pour trouver des informations détaillées sur la commande (ou le caractère) représentée par ce jeton. Le graphique suivant résume le processus de création d’un jeton de commande (« empaquetage »), puis, lorsque TeX a besoin d’informations, l’inversion du processus (« dépaquetage » du jeton) pour obtenir des données sur la commande représentée par une valeur de jeton particulière. ![Schéma montrant comment TeX empaquette/dépaquette les jetons](/files/6c9db31d354a370234d221f1c38d9151b2016cac) ### Codes de commande Une partie des informations que TeX stocke sur chaque commande (primitive ou macro) est ce qu’on appelle son *code de commande*: une valeur entière que les moteurs TeX utilisent (en interne) pour classer les commandes — les commandes ayant un comportement/fonctionnalité similaire partagent le même code de commande. **Remarque**: Pour un *non actifs*, caractère individuel, son code de commande est *code de catégorie* celui qui lui a été attribué au moment où il a été lu (scanné) par TeX. Notez aussi que, sauf pour les caractères, les codes de commande sont purement internes à TeX : ils ne sont pas accessibles via des macros ou des commandes primitives — pour voir ces détails, il vous faudra lire le code source de TeX ! Voici quelques exemples de codes de commande : * `\hbox`, `\vbox`, `\vtop`, `\vcenter`, `\box` (et d’autres) sont toutes classées comme commandes de « fabrication de boîtes » et partagent le code de commande 20 ; * `\def`, `\edef`, `\gdef`, `\xdef` sont toutes des commandes de « définition de macro » et partagent le code de commande 97 ; * toutes les macros sont classées avec l’un des codes de commande 111, 112, 113 ou 114 : les différents codes de commande sont déterminés par l’utilisation de `\long` ou `\outer` lors de la définition de la macro : * 111 : code de commande pour une macro non-long, non-outer (par ex., `\def\foo{...}`) * 112 : code de commande pour une macro long, non-outer (par ex., `\long\def\foo{...}`) * 113 : code de commande pour une macro non-long, outer (par ex., `\outer\def\foo{...}`) * 114 : code de commande pour une macro long, outer (par ex., `\long\outer\def\foo{...}`) TeX utilise également les codes de commande pour identifier le sous-ensemble des commandes classées comme « expansibles ». Pour ce faire, TeX associe aux commandes expansibles des valeurs de code de commande supérieures au seuil de 100 (la valeur utilisée par le TeX original de Knuth, e-TeX et pdfTeX). Par conséquent : * *non extensibles* les commandes (la grande majorité) ont un code de commande <= 100 * *expansibles* les commandes ont un code de commande > 100 Ainsi, si TeX recherche les détails d’une commande particulière et détecte un code de commande > 100, TeX sait immédiatement qu’elle est expansible. Toutes les macros et un petit nombre de primitives (commandes intégrées) se voient attribuer un code de commande indiquant qu’elles sont expansibles : mais pourquoi TeX s’embête-t-il avec cette classification « expansible » ? Comme vous pouvez le soupçonner, cela signifie simplement que ces commandes sont quelque peu « spéciales » ; c’est-à-dire qu’elles peuvent être soumises au processus de TeX appelé *expansion*. **Note (caractères)**: À moins qu’un caractère n’ait été défini comme actif (code de catégorie 13), tous les caractères sont non expansibles. Les caractères actifs peuvent être considérés comme des « mini-macros » d’une seule lettre. ## Oui, oui, mais qu’est-ce que l’expansion ??? Nous avons noté que les valeurs de jeton supérieures à 4095 sont utilisées pour représenter des commandes ; par conséquent, TeX peut, si/au besoin, « dépaqueter » ce jeton pour accéder aux informations sur la commande TeX représentée par ce jeton. TeX peut rechercher la valeur du code de commande de cette commande pour déterminer si elle entre dans la catégorie spéciale des commandes expansibles. Mais qu’en fait TeX de cette information et que signifie « être expansible », c’est-à-dire l’expansion, *au juste*? ### Expansion : un terme général pour un ensemble d’opérations À certains moments du traitement par TeX, il doit savoir si un jeton représente une commande expansible : * **Non**: Si ce jeton de commande *ne déclenche pas* relève de la catégorie des commandes expansibles, TeX le « transmet simplement » à l’étape suivante du traitement. * **Oui**: Si ce jeton de commande *contient* relève de la catégorie des commandes expansibles, on peut considérer que TeX doit entreprendre une action qui aboutit à « filtrer » ce jeton particulier en effectuant un processus que TeX appelle « expansion de ce jeton », ou effectuer une expansion. En substance, l’expansion consiste pour TeX à *supprimer* retirer ce jeton de son entrée et *remplacer* le remplacer par des jetons issus du « processus d’expansion » propre à cette commande ou à ce groupe de commandes partageant le même code de commande. Il faut de la pratique et de l’expérience pour savoir quand TeX effectue, ou n’effectue pas, l’expansion de jetons — la page 215 de The TeXbook énumère les situations dans lesquelles des jetons expansibles ne subissent pas d’expansion. En réalité, le processus d’expansion de TeX est complexe et nuancé. #### Quelles commandes sont expansibles ? Si l’on regarde une liste de commandes primitives (intégrées) que les moteurs TeX classent comme expansibles (p. ex. pages 212–215 de The TeXbook), il devient évident qu’en pratique, l’expansion est un terme assez général que TeX utilise pour décrire le comportement d’un groupe de commandes quelque peu éclectique. Les résultats de l’expansion d’une commande particulière (expansible) varient, et on peut le voir en dressant une liste de commandes expansibles — regroupées par fonctionnalité. La sémantique précise des commandes individuelles n’a pas d’importance ici ; ce qui nous intéresse surtout, ce sont les conséquences générales de leurs actions — ce que leur expansion *fait ou permet d’obtenir*. | **Commande** | **Description** | **Comportement de l’expansion** | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Une séquence stockée de jetons de commande/caractère |

En pratique, l’expansion d’une macro signifie insérer une liste de jetons à lire par TeX. Cela implique :

En effet, l’expansion de macro supprime le jeton de macro retirée de l’entrée et le remplace par les jetons contenus dans la définition.

| | | Modifier l’ordre de l’expansion | Filtrage/brassage des jetons | | | Empêcher l’expansion (oui, de façon surprenante, elle est classée comme commande expansible) | Retarder l’expansion (une sorte de filtrage des jetons) | | | Lié à l’entrée d’une nouvelle source de jetons via des fichiers source — oui, `\scantokens` dans cette catégorie en raison de son utilisation de soi-disant « pseudo-fichiers » | Servir de source de nouveaux jetons | | | Commencer une expression conditionnelle | Commencer le « filtrage » des jetons : décider quels jetons suivants traiter. | | | Terminer une expression conditionnelle | Arrêter le « filtrage » des jetons : décider quels jetons traiter | | | Construire/générer un jeton de commande | Convertir une série de jetons en un seul jeton de commande | | | Convertir quelque chose en une séquence de jetons | Générer des jetons (qui représentent une quantité ou une valeur interne) | | | `\the` a diverses utilisations, dont l’insertion de jetons ; `\detokenize` convertit une liste de jetons en une liste de jetons de caractère ; `\unexpanded` empêche l’expansion des jetons | Insérer/générer des jetons ou contrôler l’expansion | | | Commandes pour accéder à des listes de jetons ayant des usages spécialisés | Accéder à une source de jetons stockés (listes de jetons) | D’après la liste ci-dessus, est-il possible d’extraire des « comportements généraux » de cet ensemble de commandes — afin d’affiner davantage notre compréhension de l’expansion ? À une approximation raisonnable, les résultats de l’expansion d’une commande se ramènent à quelques activités clés : * génération de jetons * insertion de jetons * filtrage de jetons * modifier/contrôler l’expansion du jeton suivant ### Et enfin : le sens de l’expansion ? On peut considérer que l’expansion d’un jeton de commande (y compris des caractères actifs) implique que TeX **supprimer** retire ce jeton de commande de l’entrée et **remplacer** remplace ce jeton par d’autres jetons issus de son comportement d’expansion : génération/insertion de jetons, filtrage de jetons ou modification/contrôle de l’expansion du jeton suivant. Une fois qu’un jeton a été expansé, TeX continuerait à lire/traiter tous les jetons pouvant résulter du processus d’expansion. Quand, exactement, et où TeX effectuera l’expansion est une question bien différente : en raison des subtilités et des complexités du traitement de TeX, nous ne pouvons pas espérer l’aborder complètement dans cet article, mais nous pouvons donner un aperçu du comportement principal de traitement des entrées de TeX. ## L’expansion et la structure de TeX On peut soutenir que la meilleure façon de voir comment/où TeX distingue les commandes expansibles des commandes non expansibles est d’examiner le code source de TeX. En interne, TeX est un logiciel extrêmement complexe ; par conséquent, il est peu pratique de tenter une description complète des nombreux comportements nuancés inhérents au fonctionnement de TeX. Comme indiqué, le moment exact où TeX effectuera réellement l’expansion en lisant des jetons est « quelque peu complexe » ; par conséquent, la discussion qui suit suppose que TeX est dans un état où l’expansion doit avoir lieu. Les situations où TeX lirait/créerait des jetons sans effectuer d’expansion comprennent la création/le stockage de jetons pour la `\def` commande de définition de macro ou le stockage de jetons dans un `\toks` registre. Le diagramme suivant fournit un aperçu simplifié des parties centrales de la structure de TeX qui traitent de l’entrée et du traitement des jetons : l’objectif est de mettre en évidence la manière dont les jetons expansibles et non expansibles sont « filtrés » pendant le traitement des entrées de TeX. Le langage de programmation C est utilisé pour décrire les différentes fonctions clés, mais, espérons-le, la structure de base devrait être claire même si vous n’êtes pas familier avec le langage C. ![](/files/6e77ef52eeba771b1ec7b3008fd89269952cb1fd) ### Explication du diagramme de la structure de TeX En gros, le traitement de TeX est piloté par une fonction appelée `maincontrol()` que, dans le code source de TeX, Knuth désigne comme le « chef de l’exécutif » et décrit ainsi : > « Nous arrivons maintenant à la `maincontrol` routine, qui contient le commutateur principal qui fait que toutes les différentes parties de TeX font ce qu’elles ont à faire, dans le bon ordre… c’est le grand point culminant du programme… Nous sommes maintenant au centre du réseau, le système nerveux central qui touche la plupart des autres parties et les relie entre elles. » La description suivante est quelque peu simplifiée, mais donne une idée de la structure sous-jacente des logiciels fondés sur TeX : comment les commandes expansibles sont identifiées (« interceptées ») et filtrées pendant le traitement des entrées de TeX. En substance, pendant la toute première étape du traitement des entrées, TeX utilise la valeur du code de commande de la commande (jeton) courante pour détecter les commandes expansibles (macros, primitives expansibles et caractères actifs) ; si l’une d’elles est identifiée, ces commandes sont « interceptées » et « prétraitées » — en étant expansées. Grâce à ce processus de filtrage (expansion), TeX retire les commandes expansibles de l’entrée et les remplace par des jetons issus de leur comportement d’expansion respectif. Une fois le processus d’expansion terminé, TeX lira tous les jetons produits par cette expansion. Seuls les éléments non expansibles passent à l’étape suivante du traitement de TeX : le « big switch » où TeX exécutera toutes les commandes primitives non expansibles et composera les caractères. ### Comprendre maincontrol() Le `maincontrol()` fonction contient un grand soi-disant [instruction switch](https://en.wikipedia.org/wiki/Switch_statement)— Knuth l’appelle le « big switch » — que TeX utilise pour exécuter toutes les *non extensibles* commandes primitives : celles dont le code de commande est <=100. Pour exécuter une commande (ou un caractère) particulière, cette instruction « big switch » utilise une combinaison du mode courant de TeX : * mode vertical interne/externe, ou * mode horizontal restreint/de paragraphe, ou * mode mathématique en ligne/affiché *plus* la valeur du code de commande de chaque primitive ou caractère — le code de commande d’un *non actifs* caractère est sa *code de catégorie* valeur. Pour mémoire, les 6 modes de TeX se voient attribuer une valeur entière que TeX peut utiliser pour sauvegarder et restaurer son mode courant lorsqu’il passe d’une forme de composition à une autre — mathématiques, paragraphes, boîtes, etc. Voici les entiers attribués aux différents modes de TeX : | | | | | ------------------------------- | --------------------------------------------------- | ------------------ | | **Mode** | **Signification** | **Valeur du mode** | | Vertical externe | Entre les paragraphes (construction des pages) | 1 | | Vertical interne | Immédiatement à l’intérieur d’une `\vbox{...}` | -1 | | Horizontal | Lors de la composition/construction des paragraphes | 102 | | Horizontal restreint | Immédiatement à l’intérieur d’un `\hbox{...}` | -102 | | Mathématique affichée | Composition *affiché* équations/formules | 203 | | Mathématique en ligne (formule) | Composition *markdown en ligne* équations/formules | -203 | Remarquez l’utilisation de valeurs négatives pour le complément des différents modes, comme le mode vertical interne par rapport au mode vertical externe. Lors du traitement des commandes en `maincontrol()`, TeX utilise la valeur absolue du mode courant — c’est-à-dire qu’il ignore le signe négatif. Ainsi, par exemple, si TeX se trouve dans l’un de ses modes horizontaux et doit traiter un caractère avec le code de catégorie 11, il utiliserait la somme $$102 + 11 = 113$$ dans son « big switch » pour bifurquer vers le code qui traite ces caractères dans l’un ou l’autre mode horizontal (construction de paragraphes ou à l’intérieur d’un `\hbox`). #### Obtenir le jeton suivant Le `maincontrol()` fonction appelle la fonction `getxtoken()` pour obtenir le jeton d’entrée suivant ; à son tour, `getxtoken()` appelle la fonction d’entrée de plus bas niveau `getnext()`. Après `getnext()` a terminé son travail et a défini la valeur de la clé *variables globales*, `getxtoken()` vérifie si l’élément tout juste lu représente une macro ou une primitive expansible. Quelques notes sur `getnext()` et `getxtoken()`: * **`getnext()`**: c’est la fonction d’entrée centrale de TeX. Elle lit et traite des caractères saisis à partir d’un fichier physique ou lit des jetons à partir d’une liste de jetons. Notez que `getnext()` ne calcule pas réellement les valeurs des jetons mais elle définit un certain nombre de variables clés *globales* variables (par ex. le code de commande et `curcs`) qui seront utilisées plus tard dans le traitement. * **`getxtoken()`**: « get expanded token » utilise `getnext()` pour lire le prochain élément d’entrée. Il teste ensuite le code de commande de l’élément tout juste lu pour vérifier si cet élément représente une commande expansible : si oui, il est expansé ou la macro est appelée. Pour les éléments non expansibles, `getxtoken()` calcule une valeur de jeton et ces détails sont transmis à l’étape suivante du traitement : le « big switch » où les primitives non expansibles sont exécutées et les caractères sont composés. En substance, c’est via `getxtoken()` que tous les éléments expansibles sont « filtrés » avant d’être traités dans `maincontrol()`: cela fait que le « big switch » de TeX ne traite que les commandes primitives non expansibles. Nous soulignons une fois de plus que le diagramme ci-dessus est une simplification, car d’autres parties du traitement de TeX provoqueront également l’expansion de jetons ; par exemple : * lorsque TeX recherche (scanne) des valeurs numériques, il déclenchera l’expansion dans sa recherche d’entiers (en appelant `getxtoken()`) ; * la commande primitive `\romannumeral` provoque l’expansion — voir l’article [Expansion à l’aide de `\romannumeral`](https://www.texdev.net/2011/07/05/expansion-using-romannumeral/) pour un usage nuancé de ce fait ; * Le `\edef` (« définition développée ») la commande de définition de macro force une expansion complète ; * TeX effectuera l’expansion de jetons à certains moments lors du traitement du préambule d’un `\halign` ou `\valign` (les deux commandes sont liées aux algorithmes de composition de tableaux de TeX). [Partie 1](/latex/fr/articles-approfondis/19-how-does-expandafter-work-an-introduction-to-tex-tokens.md) [Partie 2](/latex/fr/articles-approfondis/22-how-does-expandafter-work-the-meaning-of-expansion.md) [Partie 3](/latex/fr/articles-approfondis/21-how-does-expandafter-work-tex-uses-temporary-token-lists.md) [Partie 4](/latex/fr/articles-approfondis/20-how-does-expandafter-work-from-basic-principles-to-exploring-tex-s-source-code.md) [Partie 5](/latex/fr/articles-approfondis/17-how-does-expandafter-work-a-detailed-macro-case-study.md) [Partie 6](/latex/fr/articles-approfondis/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://overleaf-pro.ayaka.space/latex/fr/articles-approfondis/22-how-does-expandafter-work-the-meaning-of-expansion.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.