> 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/es/articulos-en-profundidad/53-what-is-a-tex-token.md).
# ¿Qué es un "token de TeX"?
## Motivación para una serie sobre tokens de TeX y conceptos relacionados
En este artículo se analiza la motivación y la metodología utilizadas para producir una serie de artículos sobre tokens de TeX y conceptos relacionados [Una nueva serie de artículos: tokens de TeX y conceptos relacionados—¿pero por qué (y cómo)?](https://www.overleaf.com/blog/521-a-new-series-of-articles-tex-tokens-and-related-concepts-but-why-and-how) Como se señala en ese artículo, a lo largo de esta serie basamos nuestras discusiones y explicaciones en las ideas obtenidas a través de una compilación personalizada del programa original de TeX de Knuth—usándolo para producir una serie de artículos que pretende ofrecer descripciones sencillas y explicaciones fáciles de seguir de los conceptos clave de TeX.
## Introducción: ¿cuál es nuestro objetivo?
En este artículo averiguamos exactamente qué es un token de TeX siguiendo el recorrido del procesamiento desde los caracteres del archivo de entrada hasta la creación real de tokens de TeX. En la práctica, es bastante complejo, así que hemos reducido el proceso a sus elementos esenciales, procurando que sea fácil de seguir y entender sin sacrificar la precisión técnica.
Empezamos presentando algunos conceptos internos importantes de TeX: *primitivas*, *códigos de comando* y *modificadores de comando*. A partir de ahí, usamos un ejemplo de macro muy simple para ver exactamente cómo TeX procesa el comando `\def` y el token resultante que TeX crea para representar ese comando.
Terminamos con una breve mirada a cómo TeX crea tokens para representar caracteres y cómo el `\catcode` catcode de un carácter sí queda permanentemente asociado a un token de carácter—algo que a menudo se menciona en libros sobre TeX, pero aquí vemos exactamente cómo se consigue.
El siguiente gráfico muestra el recorrido que resumiremos: del texto de entrada a los tokens de TeX:
## Pero primero: primitivas y códigos de comando
Todo motor TeX (Knuthian TeX, pdfTeX, XeTeX, LuaTeX) entiende una serie de comandos integrados: los llamados *primitivas*—los comandos fundamentales, bloques de construcción básicos que sustentan la programabilidad de TeX. Se llaman “primitivas” porque, a diferencia de las macros definidas por el usuario, no se construyen a partir de otros comandos y no pueden reducirse más a instrucciones más simples. Para el TeX de Knuth hay aproximadamente 320 primitivas—aunque hay que señalar que otros motores TeX como pdfTeX, XeTeX y LuaTeX han añadido nuevos comandos al programa original de Knuth y contendrán primitivas que no están presentes en el software TeX de Knuth.
Internamente, TeX asigna un *código de comando* a todos los comandos—ya sean macros definidas por el usuario o primitivas integradas. Estos códigos de comando no son accesibles para el usuario de TeX; simplemente forman parte de la mecánica interna del procesamiento de TeX, pero resulta útil conocerlos para la discusión posterior sobre los tokens de TeX.
Los grupos de comandos que tienen funcionalidad relacionada comparten el mismo código de comando. Por ejemplo, los `\def`, `\gdef`, `\edef` y `\xdef` primitivos se usan para definir macros y comparten el código de comando 97 (en el TeX de Knuth). Claramente, esos 4 comandos de definición de macros crean macros de una manera ligeramente diferente; por consiguiente, durante el procesamiento, TeX necesita una forma de distinguirlos.
Un código de comando por sí solo (como 97) no puede decirte qué comando de creación de macros se está considerando; así que, como cabría esperar, a cada comando de TeX se le asigna una información adicional llamada su *modificador de comando* (véanse los ejemplos abajo).
### Modificadores de comando: dos tipos
Los modificadores de comando se dividen en dos categorías a las que nos referiremos como “Tipo 1” y “Tipo 2”; TeX no usa esta terminología, simplemente es conveniente hacerlo así aquí:
* **Tipo 1**: Valores enteros simples que TeX puede, si es necesario, usar para distinguir entre comandos que comparten el mismo código de comando.
* **Tipo 2**: Un valor entero que es una ubicación numérica en la memoria de TeX y le indica a TeX a dónde debe ir para buscar información de ese comando. Por ejemplo, esto se aplica a los comandos definidos por el usuario (macros), donde el modificador de comando le dice a TeX dónde se almacena en memoria la definición de la macro.
#### Modificadores de comando de tipo 1 (un ejemplo)
Como se señaló, en el TeX de Knuth los cuatro comandos primitivos para definir macros: `\def`, `\gdef`, `\edef`, `\xdef` todos comparten el código de comando 97: se diferencian mediante sus modificadores de comando, que se enumeran en la siguiente tabla:
| Comando | Código
de comando
| Modificador
de comando
|
| ------- | --------------------------- | -------------------------------- |
| `\def` | 97 | 0 |
| `\gdef` | 97 | 1 |
| `\edef` | 97 | 2 |
| `\xdef` | 97 | 3 |
Como segundo ejemplo, Knuth decidió implementar los comandos `\openout`, `\write`, `\closeout`, `\special`, `\immediate` y `\setlanguage` como “extensiones” de TeX, únicamente para mostrar cómo se pueden añadir nuevos primitivos a TeX. En este caso, esos comandos en realidad no comparten una “funcionalidad similar”, salvo que Knuth decidió agruparlos con fines de explicar cómo ampliar TeX. Esos 6 comandos se clasifican como “extensiones” y se agrupan con el valor de código de comando 59, pero cada uno tiene un modificador de comando apropiado para diferenciarlo de los demás:
| Comando | Código
de comando
| Modificador
de comando
|
| -------------- | --------------------------- | -------------------------------- |
| `\openout` | 59 | 0 |
| `\write` | 59 | 1 |
| `\closeout` | 59 | 2 |
| `\special` | 59 | 3 |
| `\immediate` | 59 | 4 |
| `\setlanguage` | 59 | 5 |
#### Modificadores de comando de tipo 2 (una breve explicación)
Aunque todos los modificadores de comando son enteros, los modificadores de Tipo 2 necesitan algo más de explicación. En TeX, estos modificadores de comando se denominan “punteros” porque apuntan a una ubicación en memoria donde TeX puede encontrar información adicional para ese comando. Esto puede sonar un poco vago, pero la manera en que TeX usa estos punteros para buscar información es bastante variada y una explicación más amplia distraería del objetivo central de este artículo. Un ejemplo puede ayudar: las macros. Cuando se define un comando macro, TeX necesitará almacenar el texto de sustitución en algún lugar de la memoria. Como veremos abajo, las macros definidas por el usuario tienen códigos de comando entre 111 y 114, con un modificador de comando que es un puntero a memoria que le dice a TeX dónde se almacena su texto de sustitución (la definición de la macro).
### Códigos de comando: expandibles y no expandibles
En el código fuente de Knuth para TeX los códigos de comando van de 0 a 120—obsérvese que algunos códigos dentro de ese rango son de uso interno especializado y no se asignan a comandos accesibles para el usuario. Conviene señalar que otros motores TeX como pdfTeX, XeTeX y LuaTeX han añadido nuevos comandos al conjunto original de Knuth y contendrán más primitivas, y códigos de comando correspondientes; sin embargo, los principios expuestos aquí son fundamentales para todos los motores basados en TeX derivados del código fuente de Knuth.
El conjunto de códigos de comando se divide en dos grupos principales:
* *comandos no expandibles*: tienen códigos de comando menores o iguales a 100;
* *comandos expandibles*: tienen códigos de comando mayores que 100, hasta un valor máximo de 120. El rango de 101 a 120 incluye macros definidas por el usuario, además de comandos como `\csname`, `\\expandafter` y `\\the`.
Los comandos no expandibles normalmente asignan un valor a un parámetro interno o producen directamente material que puede componerse. Los comandos expandibles normalmente “inyectan” un flujo de tokens en la actividad de procesamiento actual de TeX o modifican el orden del procesamiento de tokens.
Como se señaló anteriormente, a todas las macros (comandos definidos por el usuario) se les asignan códigos de comando entre 111 y 114: los distintos valores reflejan si la macro fue definida como `\long`, `\outer`, ambas o ninguna. Aquí hay un ejemplo:
| Tipo de macro | Ejemplo | Comentario |
| -------------------- | ---------------------------------- | -------------------------------- |
| No larga, no externa | `\\def\\ohyeah{....}` | `\\ohyeah` código de comando=111 |
| Larga, no externa | `\\long\\def\\ohyeah{....}` | `\\ohyeah` código de comando=112 |
| No larga, externa | `\\outer\\def\\ohyeah{....}` | `\\ohyeah` código de comando=113 |
| Larga, externa | `\\long\\outer\\def\\ohyeah{....}` | `\\ohyeah` código de comando=114 |
Como recordatorio sobre los modificadores de comando, cuando se define una macro, TeX almacenará la definición de la macro en alguna ubicación de la memoria: esa ubicación (un puntero) se convertirá en el modificador de comando para el comando de macro, que se almacenará con un código de 111 a 114 dependiendo de cómo se definió. El nombre real asignado a una macro definida por el usuario realmente no importa: después de procesar la entrada, a todas se les asignará un código de comando que varía de 111 a 114 y, en última instancia, todos los comandos que TeX lee de tu entrada, ya sean primitivas o macros definidas por el usuario, se convierten finalmente en una representación numérica llamada un *token*.
## El recorrido desde el texto de entrada hasta los tokens de TeX
En esta sección usaremos un ejemplo de macro muy simple para ver exactamente cómo TeX procesa el comando `\def` para crear un token que represente el `\def` comando. El procesamiento detallado de TeX puede ser extremadamente complejo, así que no estamos utilizando parámetros de macro ni delimitadores porque eso añadiría complejidad y distraería de nuestro recorrido.
Supongamos que tu archivo de entrada de TeX contiene la siguiente línea:
```latex
\\def\\ohyeah{Overleaf is cool!}
```
Cuando TeX comienza a procesar esta línea de entrada, comprueba el `\catcode` de cada carácter y ve que el primer carácter es `\` (primer carácter de `\def`). Detecta (lo busca en una tabla interna) que `\` tiene `\catcode` 0, lo que significa que introduce el comienzo de una *secuencia de control*. Por supuesto, puedes redefinir cualquier carácter para que tenga `\catcode` 0, pero asumiremos que se están usando las definiciones convencionales de plain TeX o LaTeX.
En sentido estricto, el término *secuencia de control* tiene dos subcategorías: *palabra de control* y *símbolo de control*:
* *palabra de control*: una secuencia de caracteres con `\catcode` letra (11);
* *símbolo de control*: un solo carácter cuyo `\catcode` es *no* letra (11).
En este punto, el `\` carácter de escape ha cumplido su función y ya no se utiliza. Al detectar un carácter de escape, la respuesta de TeX es empezar a leer todos los caracteres subsiguientes de la entrada con el fin de detectar una palabra de control o un símbolo de control.
Después del carácter inicial `\`, TeX detecta inmediatamente el `d`: un carácter cuyo `\catcode` es 11, lo que le indica a TeX que ha encontrado la primera letra de una *palabra de control*secuencia de control. *no* debes `\catcode` letra (11). Todos los caracteres subsiguientes (después del inicial `\`) con `\catcode` 11 (letra) se consideran para formar el nombre de una palabra de control: es decir, el nombre de un comando—quizá una macro o una primitiva, pero TeX aún no tiene idea de qué tipo de comando es. En este punto, simplemente es una cadena de caracteres.
Así, en nuestro ejemplo TeX avanza felizmente, comprobando cada carácter, hasta que llega al carácter inicial `\` de `\\ohyeah` que también tiene `\catcode` 0. TeX reconoce que ha avanzado demasiado y devuelve amablemente ese `\` de vuelta al flujo de texto para que se convierta en el siguiente carácter que se verá durante el análisis posterior del texto. En este punto, TeX ha identificado una cadena (`def`) que sabe que forma el texto de una palabra de control compuesta por tres caracteres, cada uno con `\catcode` 11 (`d`, `e` y `f`). Lo que ahora necesita hacer TeX es averiguar qué `def` significa: ¿qué hace? Como quizá ya habrás adivinado, TeX necesita encontrar el código de comando y el identificador de comando de `def` para poder determinar qué hacer con este comando.
## Haciendo un hash de ello
Habiendo detectado una palabra de control (`def`), lo primero que hace TeX es “convertir” la cadena de caracteres (`def` en nuestro ejemplo) en un número entero usando algo llamado función hash. No necesitamos preocuparnos demasiado por los detalles; bastará con una visión general. En esencia, TeX examina cada carácter de la palabra de control que acaba de detectar y usa el valor del código ASCII (o el valor Unicode para XeTeX/LuaTeX) de cada carácter para calcular un número llamado valor hash: es simplemente un entero.
Como parte de este proceso de cálculo del hash, TeX también comprobará si la cadena de caracteres de la palabra de control recién detectada ya le es conocida. El texto legible por humanos de todos los comandos, ya sean primitivos o macros definidas por el usuario, se almacena en un área interna llamada el *pool de cadenas*. `\\def\\ohyeah{Overleaf is cool!}` está definiendo un nuevo comando llamado `\\ohyeah` y TeX (en una fase posterior) no solo necesitará calcular un valor hash para `ohyeah` (*sin* el carácter inicial `\` carácter), sino también almacenar la forma de cadena de texto (legible por humanos) por si necesita usarla para informar de errores (u otras tareas).
Si quieres más detalles sobre los procesos de manejo de cadenas de TeX, he escrito sobre ello en mi [blog personal](http://www.readytext.co.uk/?p=3590).
El resultado final es que la cadena de caracteres que representa el comando `def` se convierte en el valor numérico 1218 (ese es el valor real calculado por TeX). En este punto, los caracteres individuales `d`, `e` y `f` ya no forman parte de la historia principal—han sido leídos de la entrada y han cumplido su función: a partir de ahora todo trata sobre enteros y *tokens*—¡pronto veremos qué es realmente un token! Internamente, TeX se refiere a estos números de valor hash como la *secuencia de control actual* pero en el código fuente ese término se abrevia en una variable llamada `curcs`. El código fuente de TeX está lleno de nombres de variables muy cortos, a menudo bastante crípticos.
Pero ¿qué hace TeX *realmente* con este valor entero recién creado de 1218? ¿Cómo averigua TeX que la cadena original `def`, ahora representada por el entero 1218, realmente se refiere a una instrucción para definir una macro? La respuesta es que TeX tiene una especie de “archivador” interno donde almacena el significado y el valor actuales de cada comando que conoce en ese momento—ya sea una macro definida por el usuario o una primitiva integrada. La razón por la que TeX se tomó la molestia de convertir `def` en el valor hash 1218 (ahora almacenado en la variable llamada `curcs`) es usarlo para buscar la *significado* de `def`. TeX, por supuesto, repetirá este ejercicio de cálculo del hash para todas las palabras de control que detecte en la entrada—aunque, por supuesto, distintas palabras de control producen distintos valores enteros de la función hash: esa es toda la idea.
El “archivador” interno de TeX se llama la *tabla de equivalencias* y es el tema de la siguiente sección.
### Consultando la tabla de equivalencias
Para recapitular, veamos lo que hemos aprendido hasta ahora:
* `\` introduce el comienzo de una secuencia de control (ya sea una *símbolo de control* o una *palabra de control*).
* Si el primer carácter después del `\` tiene `\catcode` 11 (letra), entonces es el comienzo de una *palabra de control*.
* Para *palabras de control* TeX escanea para comprobar todos los caracteres de entrada subsiguientes que tienen `\catcode` 11 y dejará de escanear en cuanto encuentre el primer carácter que no *no* tenga un `\catcode` de 11.
* La cadena de caracteres de entrada (que sigue al `\`) que tienen `\catcode` 11 se consideran una *palabra de control* que el usuario ha escrito: un comando que le pide a TeX “hacer algo”.
* Para comenzar el proceso de “hacer algo”, TeX convierte la cadena de caracteres de la palabra de control en un entero. Lo hace utilizando una denominada función hash que devuelve un entero.
* El entero (valor hash calculado) se denomina *secuencia de control actual*, pero TeX le da el nombre más corto de `curcs`.
* En nuestro ejemplo, la palabra de control `def` se convierte en el valor 1218—que se almacena en una variable llamada `curcs`: es decir, `curcs=1218`.
Ahora TeX necesita averiguar qué significa la *secuencia de control actual* realmente—¿qué hace TeX con ella?
#### Una nota sobre la agrupación: la necesidad de guardar y restaurar información
Aquí haremos un pequeño desvío para recordarnos que TeX tiene la capacidad de guardar y restaurar información: es decir, dispone de alguna forma de “memoria” integrada.
Cualquiera que haya escrito incluso la macro más simple debería conocer el mecanismo de agrupación de TeX—por ejemplo, usando `\def` para crear macros dentro de un grupo. A menos que apliques el `\global` prefijo a `\def`las macros creadas dentro de un grupo, el valor o significado de esa macro solo persiste dentro de ese grupo (y los que estén dentro de él): su definición se pierde cuando el grupo termina. Por ejemplo, si defines una macro simple dentro de un grupo, así:
```latex
{\\def\\foo{Hello}}
```
y tratas de usar `\\foo` fuera del grupo
```latex
{\\def\\foo{Hello}}% \\foo definido dentro de un grupo (nota: sin usar \\global)
\\foo %<--- ya no está definido, ahora es indefinido
```
entonces obtenemos el famoso error: `Secuencia de control indefinida`. `\\foo` solo tiene significado dentro del grupo (y sus subgrupos) en el que fue definida. Además, cuando redefinimos una macro dentro de un grupo, el nuevo valor puede perderse cuando el grupo termina y se restaura el significado anterior (que existía fuera del grupo).
```latex
\\def\\foo{Goodbye}
\\foo\\par% Imprime Goodbye
{\\def\\foo{Hello}% Redefinida dentro de un grupo:
{Dentro del grupo de 2º nivel: \\foo\\par}}% Usada dentro del grupo de 2º nivel: \\foo imprime Hello
Fuera del grupo se restaura el valor antiguo: \\foo\\par% Imprime Goodbye
```
El propósito de estos ejemplos sencillos es señalar que TeX tiene algún tipo de “mecanismo de almacenamiento” o “memoria” que guarda y restaura el “significado” de los comandos—y, por supuesto, lo tiene. Lo insinuamos en la sección anterior: ese “mecanismo de almacenamiento” o “archivador” es una gran tabla interna llamada la *tabla de equivalencias*. Es ahí donde TeX almacena el significado o los valores actuales de todos los comandos que conoce en ese momento—las primitivas integradas y las macros definidas por el usuario.
### La tabla de equivalencias: por analogía
Para explicar la tabla de equivalencias procederemos por analogía. Seguiremos usando la noción de un archivador con miles de pequeños cajones, cada uno etiquetado con un entero único. En esta etapa del procesamiento, TeX dice, en efecto:
“De acuerdo, tengo este valor entero de 1218 que acabo de calcular y guardar en una variable llamada `curcs`. Ahora necesito averiguar qué significa: para hacerlo iré y miraré en el cajón número 1218 de mi archivador para ver qué dice ahí.”
TeX usa 1218 para localizar el cajón correcto y allí encuentra una pequeña nota que contiene tres piezas de información cuyos nombres son los usados en el código fuente de TeX:
* **`eq_level:`** el nivel de agrupación en el que se definió esta entrada (nivel 1 = definida globalmente). Vimos antes los efectos de la agrupación en acción: aquí, en la tabla de equivalencias, es donde se almacena esa información del nivel de agrupación;
* **`eq_type:`** el código de comando de esta entrada;
* **`equiv:`** “valor” actual de esta entrada—puede ser un entero simple como el modificador de comando mencionado arriba, o un puntero a un área de memoria; por ejemplo, la ubicación de memoria de la colección de tokens que representa la definición de una macro.
Así, nuestro valor hash de 1218 (guardado en la variable `curcs`) se ha usado, en la práctica, como la *clave* para acceder a un cajón que contiene el significado y el valor actuales del comando que originalmente escribimos como la cadena de letras `\def`.
Dentro del código fuente del programa TeX, el `eq_type` para cualquier comando se almacena usando una variable llamada `curcmd` y el valor de `equiv` se almacena en una variable llamada `curchr`.
### ¿Qué dice la tabla de equivalencias para def?
Como se señaló, el valor hash calculado para cualquier comando se guarda en una variable llamada `curcs`; por tanto, para `def` tenemos `curcs=1218`. Al mirar la ubicación 1218 en la tabla de equivalencias, TeX encontrará la siguiente información:
* `curcmd`=97. Este es el código de comando para `\def`;
* `curchr`=0. Este es el modificador de comando para `\def`.
`\def` es un comando primitivo (integrado) de TeX y, salvo que haya sido redefinido en algún lugar, la tercera y última pieza de información debería ser `eq_level=1` indicando que el significado de `\def` está definido globalmente y no se restringe a algún nivel de agrupación inferior. Internamente, el valor de `eq_level` asociado a un comando desempeña un papel extremadamente importante dentro del mecanismo de agrupación de TeX, pero no lo consideraremos más.
La siguiente gráfica resume la explicación que hemos recorrido:
## Tokens de TeX para comandos
Tras haber recorrido las explicaciones anteriores, el cálculo real de los tokens de TeX para las secuencias de control resulta ser realmente muy simple. TeX usa el valor de `curcs` (1218) de la función hash para crear un entero simple al que llama un *token*token. `curcs` es:
```c
curtok = 4095 + curcs
```
TeX almacena el valor del token actual (calculado más recientemente) en una variable llamada `curtok`.
Así que, en conclusión, el token de TeX que representa la `\def` comando es `4095 + 1218 = 5313`. Y eso es todo para los tokens de TeX que representan secuencias de comandos: simplemente son un número entero que se calcula a partir de un valor de la tabla hash más 4095.
## Tokens de TeX para caracteres
Cuando TeX necesita crear un token que represente un carácter utiliza el siguiente cálculo, igualmente sencillo:
```c
curtok = 256*catcode + (ASCII value of character)
```
Ten en cuenta que se utilizan cálculos ligeramente distintos para motores compatibles con Unicode como LuaTeX.
Por ejemplo, el token de TeX que representa un carácter de espacio con `\catcode` 10 y valor ASCII 32 es:
```c
256*10 + 32 = 2592
```
### Listas de tokens que contienen caracteres
Cuando creas una lista simple de tokens con, por ejemplo,
```latex
\\toks100={Hello}
```
TeX creará la siguiente lista de tokens y la almacenará en memoria para su uso posterior:
* H→ 256 × 11 + 72 = 2888
* e→ 256 × 11 + 101 = 2917
* l→ 256 × 11 +108 = 2924
* l→ 256 × 11 +108 = 2924
* o→256 × 11 + 111 = 2927
En lo más profundo de la memoria de TeX, el registro de tokens 100 proporcionará acceso a la ubicación de almacenamiento de “Hello”, guardada como 5 valores de token: 2888, 2917, 2924, 2924, 2927. Observa que estos tokens combinan el código ASCII de cada carácter y el valor de su `\catcode`en el momento en que se convierten en tokens (se tokenizan). Una vez que los caracteres han sido convertidos en tokens de carácter, el `\catcode` valor asociado a ellos es permanente y se almacena dentro de los tokens para usarse más tarde cuando el usuario diga, por ejemplo, `\\the\\toks100`.
Como se señaló, un token de carácter se calcula a partir de `256*catcode + (ASCII value)` mientras que un token de secuencia de control se calcula a partir de `4095 + curcs` donde `curcs` es el valor hash de la palabra de control (cadena de texto de un comando escrito por el usuario) detectada en la entrada por TeX. Conviene señalar que los tokens de carácter siempre son menores que 4095. Por tanto, TeX puede determinar fácilmente si un token concreto representa una secuencia de control (un comando) o un carácter y luego averiguar qué secuencia de control o carácter y `\catcode` par está codificado en ese token.
---
# 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/es/articulos-en-profundidad/53-what-is-a-tex-token.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.