> 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/overleaf-learn-latex-pt/base-de-conhecimento/038-fixing-and-preventing-compile-timeouts.md).

# Corrigir e prevenir tempos limite de compilação

Quando clica no **Recompilar** botão no seu projeto Overleaf, inicia um processo que lê os ficheiros do seu projeto e converte-os num PDF formatado. Se surgir um erro de tempo limite de compilação, isso ნიშნავს que o processo de compilação não conseguiu ser concluído dentro do [limite de tempo do seu plano Overleaf](/latex/overleaf-learn-latex-pt/base-de-conhecimento/119-overleaf-plan-limits.md).

Embora seja possível que alguns projetos sejam demasiado grandes ou complexos para produzir um PDF no tempo disponibilizado, os tempos limite de compilação podem muitas vezes ser corrigidos ou evitados.

## Passos para resolver tempos limite de compilação

Siga estes passos para identificar e corrigir problemas comuns que causam tempos limite de compilação:

1. [Verifique erros de compilação e corrija-os usando **Parar no Primeiro Erro** modo](#first-errors)
2. [Experimente **Fast\[draft\]** modo e otimize o tamanho das suas imagens](#second-images)
3. [Avalie o seu projeto quanto a tarefas demoradas](#third-assess)

Além de seguir estes passos, reveja também as sugestões sobre o que fazer em [situações específicas de tempo limite](#anchor-advice) bem como as [boas práticas](#anchor-best) a seguir para evitar tempos limite de compilação.

Embora muitos projetos possam ser compilados no tempo disponibilizado no plano gratuito do Overleaf, se estiver a preparar um documento grande ou complexo, poderá precisar de [subscrever um plano premium](https://www.overleaf.com/user/subscription/plans) para obter mais tempo de compilação.

## Passo 1: Verifique erros de compilação e corrija-os

Alguns erros de compilação, ou o acumular de vários erros, podem bloquear completamente o [processo de compilação do latexmk](https://learn.overleaf.com/learn/Kb/How_does_Overleaf_compile_my_project%3F) e levar a um tempo limite de compilação. Para encontrar e corrigir erros, ative o **Parar no primeiro erro** modo de compilação no **Recompilar** menu pendente:

![Captura de ecrã que mostra como ativar o modo de compilação Parar no primeiro erro](/files/67e82877ac48c6241db49c973a12ca25197d059f)

O [**Parar no primeiro erro**](/latex/overleaf-learn-latex-pt/base-de-conhecimento/149-using-the-stop-on-first-error-compilation-mode.md) O modo de compilação faz exatamente o que seria de esperar: interrompe a compilação imediatamente quando é encontrado um erro. Quando isso acontece, não é gerado nenhum PDF e será apresentada uma mensagem a descrever o erro. Ativar **Parar no primeiro erro** permite encontrar e corrigir cada erro no projeto até o projeto ficar sem erros.

Clicar em cada mensagem de erro levá-lo-á até à linha no código-fonte que está a causar o problema, para que possa corrigir o seu código. Vários erros comuns são explicados em [esta página](/latex/overleaf-learn-latex-pt/nocoes-basicas-de-latex/05-errors.md)e algumas sugestões de depuração em LaTeX são apresentadas em [esta página](/latex/overleaf-learn-latex-pt/perguntas-e-respostas/81-tips-and-tricks-for-troubleshooting-latex.md). Consulte também a [secção neste artigo](#anchor-fatal) que lista alguns **erros fatais de compilação** que causam tempos limite de compilação.

## Passo 2: Tente compilar em modo Fast \[draft]

Incluir muitos ficheiros de imagem, ou ficheiros de imagem grandes, no seu projeto pode aumentar significativamente o tempo necessário para compilar o projeto.

Um método que pode ajudar a descobrir se o processamento de imagens é a causa do tempo limite é tentar compilar em **Rápido \[rascunho]** modo. Para isso, escolha a opção **Rápido \[rascunho]** no **menu Recompilar**. Isto substitui todos os seus gráficos por caixas e faz com que o PDF seja compilado muito mais depressa:

![Definir o modo de compilação draft para um projeto Overleaf](/files/6969da7e114e2a345471275463a7da0f78f5363d)

Se o seu documento for compilado em **Rápido \[rascunho]** modo mas não concluir a compilação em **Normal** modo, a causa poderá ser a existência de muitos ficheiros de imagem ou ficheiros de imagem grandes.

### Otimização de ficheiros de imagem

Se tiver usado vários ficheiros PNG ou JPEG grandes e de alta resolução, o processamento desses ficheiros pode aumentar o tempo necessário para compilar o projeto, por vezes consideravelmente. Certifique-se de:

* Usar ficheiros PDF em vez de ficheiros PNG para diagramas e gráficos.
* Reserve o uso de JPEGs para fotografias.

Para mais conselhos, veja: [Otimizar ficheiros de imagem grandes](/latex/overleaf-learn-latex-pt/base-de-conhecimento/113-optimising-very-large-image-files.md).

## Passo 3: Avalie o seu projeto quanto a tarefas demoradas e erros fatais

Se ambos **Parar no Primeiro Erro** e **Fast\[draft]** os modos de compilação ainda estiverem a levar a um tempo limite de compilação, poderá ser necessário investigar mais para identificar a causa do tempo limite de compilação e (esperemos) resolvê-la.

1\. [Reveja a lista de práticas e pacotes demorados que podem tornar a compilação mais lenta](#anchor-slow)

2\. [Reveja a lista de erros fatais comuns que podem levar a tempos limite](#anchor-fatal)

3\. [Consulte os conselhos para cenários específicos de tempo limite que melhor descrevam a sua situação](#anchor-advice)

### Práticas e pacotes demorados

Algumas práticas e pacotes podem levar a compilações muito lentas, e até a tempos limite.

**Incluir desenhos complexos de TikZ ou pgfplots**

`TikZ` e [`pgfplots`](https://ctan.org/pkg/pgfplots?lang=en) produzem gráficos excelentes, mas podem [demorar muito tempo a compilar](https://tex.stackexchange.com/a/254946/226). Há [várias formas de externalizar as imagens TikZ](/latex/overleaf-learn-latex-pt/perguntas-e-respostas/60-i-have-a-lot-of-tikz-matlab2tikz-or-pgfplots-figures-so-i-m-getting-a-compilation-timeout.-can-i.md) para que o LaTeX não tenha de as redesenhar sempre que cria um novo PDF.

**Usar o pacote mhchem**

Versões recentes do [`mhchem` pacote](https://ctan.org/pkg/mhchem?lang=en) podem demorar mais tempo a compilar. Dependendo da finalidade para que o está a usar, o [`chemformula` pacote](https://ctan.org/pkg/chemformula) pode reduzir o tempo necessário para a compilação. Se já tem usado `mhchem`, pode experimentar substituir diretamente por `chemformula` como substituição:

```latex
% \usepackage{mhchem}
\usepackage{chemformula}
\let\ce\ch
```

* **Nota**: existem diferenças de sintaxe e de funcionalidades entre `mhchem` e `chemformula`, por isso isto pode nem sempre funcionar bem. Por exemplo, `\ce{2H2O}` será apresentada corretamente com `mhchem`, mas com `chemformula` terá de escrever isto como `\ch{2 H2O}` com um espaço após o inicial `2`.

**Incluir chamadas de rastreio ou depuração**

Se tiver um comando `\tracingall` no seu documento, pode estar a escrever uma *grande quantidade* de dados para o `.log`. Registar e processar `\tracingall` dados no ficheiro `.log` pode tornar a compilação extremamente lenta. Recomenda-se remover as `\tracingall` chamadas, ou, se precisar de usar métodos semelhantes para depuração, usar o [`rasto` pacote](http://ctan.org/pkg/trace) .

**Usar o pacote acro**

Utilizadores do [`acro` pacote](https://www.ctan.org/pkg/acro) têm [reportado que a versão 3 é lenta](https://github.com/cgnieder/acro/issues/205) a carregar as declarações de acrónimos. Uma consequência do tempo de compilação aumentado de `acro`é a possibilidade de acionar um tempo limite de compilação; felizmente, há uma solução alternativa: usar a versão 2 do `acro` pacote.

Mudar da versão 3 de volta para a versão 2 pode exigir editar o seu projeto para garantir que é compatível com as opções, funcionalidades e comandos da versão 2. A documentação da versão 2 está disponível, contida em versões anteriores do código-fonte, que podem ser [descarregadas do GitHub](https://github.com/cgnieder/acro/releases/tag/v2.10).

Aqui estão alguns pontos a verificar ao reverter para a versão 2 — esta lista está longe de ser exaustiva:

1. Modifique o principal `.tex` do seu projeto para:
   * mude `\usepackage{acro}` para `\usepackage{acro}[=v2]`
   * mude a chave da opção `include=...` de `\printacronyms` para `include-classes=...`
2. Dentro de qualquer comando `\DeclareAcronym` assegure-se de que a chave da opção `tag=...` é alterada para `class=...`.

Consulte [`acro` a documentação da versão 2.10](https://github.com/cgnieder/acro/releases/tag/v2.10) para comandos e opções disponíveis na versão 2, mas não na versão 3.

**Usar imagens EPS ou SVG**

A utilização de imagens EPS ou SVG pode exigir processamento extra para as converter para o formato PDF. Esse processamento extra aumentará o tempo necessário para compilar o seu projeto.

* Embora o **latex** compilador suporte imagens EPS diretamente, o **pdfLaTeX** compilador não suporta imagens EPS, pelo que é necessário um passo extra para as converter em imagens PDF quando esse compilador é usado. O processamento é tratado pelo `epstopdf` pacote, que usa `Ghostscript` para converter os ficheiros EPS para PDF. Este passo de conversão pode aumentar significativamente o tempo necessário para compilar o projeto.
* Os ficheiros de imagem SVG não são suportados diretamente por qualquer compilador LaTeX e exigem a utilização do `svg` pacote e do comando `\includesvg` que ele fornece. O `svg` pacote usa `inkscape` para converter imagens SVG para PDF. Este passo de conversão pode aumentar significativamente o tempo necessário para compilar o projeto.

Para obter resultados mais rápidos que possam ajudar a evitar tempos limite de compilação, use versões PDF das suas imagens em vez de formatos EPS ou SVG.

**Usar o pacote tabularray**

O `tabularray` pacote oferece uma alternativa aos comandos e ambientes padrão para implementar tabelas em LaTeX. Infelizmente, o `tabularray` pacote funciona muito lentamente, especialmente em tabelas maiores e nas que usam certos tipos de coluna. Atualmente, recomendam-se métodos padrão de definição de tabelas em vez de `tabularray` devido a considerações sobre o tempo de compilação.

**Criar um ciclo infinito num comando**

Durante a compilação, os comandos LaTeX podem, muito ocasionalmente, desencadear um “ciclo infinito”. Os ciclos infinitos são mais frequentemente causados por erros em pacotes ou em comandos definidos pelo utilizador.

Se suspeitar que poderá estar a ocorrer um ciclo, verifique se criou acidentalmente uma [recursiva](https://en.wikipedia.org/wiki/Recursion) definição num dos seus comandos personalizados, como `\newcommand{\foo}{\foo}`.

### Algumas causas de erros fatais de compilação

Abaixo estão algumas causas conhecidas de erros fatais.

**Incluir linhas em branco em comandos de titulação sensíveis**

As classes LaTeX e os modelos de revistas frequentemente fornecem comandos especiais para indicar partes do título de um documento. Estes comandos costumam destinar-se a incluir argumentos simples, e utilizá-los de formas inesperadas pode levar a erros de compilação e até a tempos limite. O mais importante é que comandos como `\author{...}`, `\date{...}` e `\title{...}` não devem conter linhas em branco.

**Incluir demasiados floats fixos**

Se tiver demasiadas tabelas ou figuras a usar o identificador de posicionamento `[H]` do pacote `float` , pode fazer com que o LaTeX entre num ciclo infinito ao tentar encontrar locais adequados para todas elas. Considere substituir todos `[H]` com `[hbt!]` e, se necessário, um ocasional `\clearpage` para escoar todas as tabelas e figuras da fila antes de inserir uma quebra de página.

**Erros no comando \caption e nos ambientes tabulares**

Aqui está uma lista de problemas relacionados com tabelas a ter em conta — em geral, tente ter cuidado ao formatar tabelas!

* `\caption{...}` deve ser sempre colocada *fora* o `tabular` do ambiente, porque pode causar erros fatais se o [`caption` pacote](https://ctan.org/pkg/caption) estiver carregado, como demonstrado no exemplo seguinte:

  ```latex
  \documentclass{article}
  \usepackage{caption}
  \begin{document}

  \begin{table}
      \begin{tabular}{c|c}
          \caption{Legenda}% \caption{...} deve estar FORA do ambiente tabular
          a & b \\
          c & d \\
      \end{tabular}
  \end{table}
  \end{document}
  ```

  [Abra este exemplo **que desencadeia um erro de tempo limite do Overleaf**](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Overleaf+timeout+example\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bcaption%7D%0A%5Cbegin%7Bdocument%7D%0A%0A%5Cbegin%7Btable%7D%0A++++%5Cbegin%7Btabular%7D%7Bc%7Cc%7D%0A++++++++%5Ccaption%7BCaption%7D%25+%5Ccaption%7B...%7D+should+be+OUTSIDE+the+tabular+environment%0A++++++++a+%26+b+%5C%5C%0A++++++++c+%26+d+%5C%5C%0A++++%5Cend%7Btabular%7D%0A%5Cend%7Btable%7D%0A%5Cend%7Bdocument)
* Em contraste, note que o `longtable` ambiente *não* requer `\caption{...}` dentro dele, como demonstrado por um exemplo no nosso [artigo de ajuda sobre tabelas](/latex/overleaf-learn-latex-pt/figuras-e-tabelas/01-tables.md#multi-page-tables).
* `\caption{...}` não deve conter `\\`, `\newline`, `\centering`, `\raggedright` etc.
* Com alguns modelos ou pacotes, `\ref{...}` ou `\cite{...}` dentro de um `\caption` pode precisar de ser precedido por `\protect` para evitar erros fatais; por exemplo, `\protect\cite{...}`.
* Verifique se há `\cmidrule{...}` dentro `tabular` incompletos; este comando requer um intervalo de colunas, por isso terá de escrever `\cmidrule{3-3}` em vez de apenas `\cmidrule{3}` se quiser uma linha horizontal que abranja apenas uma coluna.
* Evite ambientes `tabular` aninhados. Consulte [`makecell` pacote](https://ctan.org/pkg/makecell?lang=en) se quiser adicionar quebras de linha manuais numa célula de tabela, ou o tipo de coluna `p{...}` e/ou o pacote [`tabularx`](https://ctan.org/pkg/tabularx) se estiver à procura de formas de criar colunas que quebrem automaticamente linhas longas.
* Se tiver linhas tabulares que começam com `[...` poderá ser necessário adicionar `\relax` após o `\\` na linha anterior.

**Usar os pacotes soul ou changes**

Se estiver a usar o [`soul`](https://ctan.org/pkg/soul) ou [`changes`](https://ctan.org/pkg/changes) pacote para realçar texto ou riscar texto, então `\cite` e `\ref` pode precisar de ser precedido por `\protect`; por exemplo, `\protect\cite{...}`.

**Usar o tikzpicture**

Verifique se faltam `;` no fim dos comandos path/node e `]` no fim das listas de parâmetros em `tikzpicture`s.

**Usar o pacote breqn**

O [`breqn`](https://ctan.org/pkg/breqn) do pacote `dmath` pode entrar em ciclos infinitos; substitua por `align` e faça quebras de linha manualmente, se necessário.

**Usar o pacote babel**

Algumas [`babel`](https://ctan.org/pkg/babel) opções de idioma alteram o significado de certos caracteres, o que pode causar problemas quando esses caracteres são usados no seu contexto “normal”; por exemplo, no modo matemático. Para evitar isso, tente usar a opção `shorthands=off` ao carregar o babel (por exemplo, `\usepackage[shorthands=off]{babel}`).

**Usar o pacote jabbrv**

Alguns modelos usam o [`jabbrv` pacote](https://github.com/compholio/jabbrv) para abreviar automaticamente títulos de revistas (ver [este exemplo do Overleaf](https://www.overleaf.com/latex/templates/automatic-journal-abbreviations/mxfsdscmvxcr)). Quando um campo de revista no `.bib` ficheiro contém caracteres Unicode acentuados (por exemplo, Biología), isso pode bloquear a compilação e causar um tempo limite no Overleaf. Em vez disso, devem ser usados comandos LaTeX, por exemplo `Biolog{\'i}a` ou pode [alterar o compilador do projeto](/latex/overleaf-learn-latex-pt/base-de-conhecimento/026-changing-compiler.md) para `XeLaTeX` ou `LuaLaTeX`ambos com suporte integrado para leitura de caracteres Unicode.

## Conselhos para algumas situações específicas de tempo limite

### O meu projeto compilava sem erros, mas agora estou a ver um tempo limite de compilação

Uma pequena alteração pode, por vezes, causar um tempo limite de compilação. Para ajudar a identificar a causa do problema e corrigi-lo, tente estes passos:

1. Use [Recompilar do zero](/latex/overleaf-learn-latex-pt/base-de-conhecimento/028-clearing-the-cache.md) para eliminar quaisquer ficheiros gerados desatualizados que possam estar a causar problemas.
2. Use a [funcionalidade Histórico do Overleaf](/latex/overleaf-learn-latex-pt/mais-topicos/49-using-the-history-feature.md) para encontrar as suas alterações mais recentes. Veja a lista de causas de erros fatais de compilação acima.
3. Use a [Parar no Primeiro Erro](/latex/overleaf-learn-latex-pt/base-de-conhecimento/149-using-the-stop-on-first-error-compilation-mode.md) opção para encontrar e corrigir qualquer erro que tenha introduzido por acidente.

É possível que uma pequena alteração tenha levado a um erro fatal de compilação - consulte a [lista de erros fatais de compilação acima](#anchor-fatal) para algumas possíveis causas.

### Acabei de enviar um projeto para o Overleaf e estou a ter um tempo limite de compilação

Pode ser que esteja em falta um ficheiro ou pacote fundamental no seu projeto, ou que este esteja organizado de uma forma que está a causar problemas ao processo de compilação do Overleaf.

* Se um projeto foi compilado sem problemas na sua máquina local mas falha ao compilar no Overleaf, pode ser que esteja a usar uma versão diferente de **TeX Live** no seu próprio computador. Pode [alterar a versão do TeX Live para o seu projeto](https://www.overleaf.com/blog/new-feature-select-your-tex-live-compiler-version) para corresponder mais de perto àquela que compilou com sucesso o seu projeto localmente.
* O projeto que carregou pode não ter uma estrutura de ficheiros ideal para o Overleaf. Se o seu ficheiro tex principal estiver numa pasta, o compilador pode estar a ter dificuldades em localizar algumas dependências de ficheiros. Se o seu ficheiro tex principal estiver numa pasta, tente reestruturar o projeto para que o ficheiro tex principal fique no nível superior do projeto.

Seguir [as instruções acima para localizar e corrigir erros](#first-errors) pode muitas vezes identificar ficheiros em falta, problemas de versão do TeX Live e problemas de organização do projeto.

### Fiz uma cópia de um projeto que estava a compilar, mas agora estou a enfrentar um tempo limite de compilação

Os novos projetos, incluindo cópias de projetos existentes, usarão por predefinição a versão mais recente do TeX Live. Se o seu projeto original estava numa versão mais antiga do TeX Live, é possível que existam incompatibilidades com a versão mais recente que estejam a causar problemas. Experimente [alterar a versão do TeX Live](https://www.overleaf.com/blog/new-feature-select-your-tex-live-compiler-version) na sua nova cópia para corresponder à versão do projeto original.

### Não consigo que o meu projeto seja compilado quando incluo todas as secções, mas cada uma compila bem por si só

Siga [o conselho acima sobre usar a opção de compilação Fast\[draft\]](#second-images) para ver se todo o projeto pode ser compilado em modo Fast\[draft].

Em alguns casos, é possível compilar com sucesso um projeto grande em duas etapas: primeiro executando em modo Fast\[draft] e depois compilando em modo Normal.

Verifique cada secção do seu projeto para identificar possíveis fontes de compilação lenta. Estas podem incluir [ficheiros de imagem grandes que podem ser otimizados](#anchor-optimize), ou outras [práticas ou pacotes demorados](#anchor-slow).

### O meu projeto, por vezes, atinge o tempo limite, mas não compila de forma fiável

O seu projeto pode estar a correr muito perto do tempo máximo de compilação. Siga os conselhos acima para [corrigir erros](#first-errors), [otimizar imagens](#second-images), e [evitar práticas ou pacotes demorados](#third-assess).

## Boas práticas para evitar tempos limite de compilação

É muito melhor evitar que os tempos limite de compilação aconteçam do que ter de lidar com o processo, por vezes stressante, de os corrigir depois de ocorrerem. Estas recomendações deverão ajudá-lo a evitar que os tempos limite de compilação aconteçam, ou a recuperar rapidamente deles quando acontecem.

### Corrija todos os erros de compilação quando acontecem

Os erros de compilação são indicados pelo balão de notificação vermelho ao lado do botão Recompilar, conforme descrito em [esta página](/latex/overleaf-learn-latex-pt/perguntas-e-respostas/81-tips-and-tricks-for-troubleshooting-latex.md). Se clicar no balão vermelho, verá as mensagens de erro. Clicar em cada mensagem de erro levá-lo-á à linha correspondente no código-fonte, para que possa corrigir o seu código. Recomendamos que os erros sejam corrigidos o mais rapidamente possível, pois deixá-los acumular-se pode levar a erros difíceis de depurar e fatais no futuro.

[Esta página](/latex/overleaf-learn-latex-pt/nocoes-basicas-de-latex/05-errors.md) explica vários erros de compilação comuns. Se estiver com dificuldade em compreender uma mensagem de erro, muitas vezes pesquisar online usando o texto do erro levá-lo-á a uma publicação de blogue ou fórum onde o erro é explicado e são oferecidas soluções.

### Etiquete as versões do seu projeto antes de grandes alterações ou marcos importantes

Use a [funcionalidade Histórico do Overleaf](/latex/overleaf-learn-latex-pt/mais-topicos/49-using-the-history-feature.md) para etiquetar as versões do seu projeto, para que possa comparar facilmente o seu projeto atual com versões anteriores. Isto pode ajudá-lo a encontrar rapidamente novas origens de erros de compilação.

### Organize os seus ficheiros

É mais fácil encontrar e corrigir problemas se o seu projeto estiver bem organizado. Além disso, uma boa gestão do projeto pode permitir-lhe compilar secções específicas do seu projeto, tornando mais fácil identificar áreas que possam estar a contribuir para compilações excessivamente longas. Por favor [veja aqui](/latex/overleaf-learn-latex-pt/estrutura-do-documento/07-management-in-a-large-project.md) para obter conselhos sobre a gestão de projetos grandes.

## Mais informações sobre compilação e tempo de compilação

### O que é, afinal, “compilar”?

Compilar é o processo de converter o seu código LaTeX num ficheiro PDF formatado. [Saiba mais sobre como o Overleaf compila projetos LaTeX](/latex/overleaf-learn-latex-pt/base-de-conhecimento/064-how-does-overleaf-compile-my-project.md).

### Limites de utilização razoável

Alguns documentos grandes ou complexos podem demorar mais tempo a compilar do que o limite de tempo de espera do plano gratuito do Overleaf, e podem requerer o tempo de compilação alargado disponível no nosso [planos pagos](https://www.overleaf.com/user/subscription/plans). Alguns projetos podem até precisar de um tempo de compilação superior ao disponível nos nossos planos pagos. Nesses casos, poderá ser necessário descarregar o seu projeto e compilá-lo localmente.

### Ainda está com dificuldades?

Se tiver um tempo limite de compilação que não consiga resolver com os conselhos aqui apresentados, por favor [diga-nos](https://www.overleaf.com/contact).


---

# 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/overleaf-learn-latex-pt/base-de-conhecimento/038-fixing-and-preventing-compile-timeouts.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.