> 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/mais-topicos/28-inserting-images-es.md). # Inserir imagens es As imagens são elementos essenciais na maioria dos documentos científicos. O LaTeX oferece várias opções para gerir imagens e fazê-las ficar exatamente como precisa. Neste artigo explica-se como incluir imagens nos formatos mais comuns, como torná-las mais pequenas ou maiores e como adicionar referências às imagens dentro do documento. ## Introdução De seguida, um exemplo de como importar uma imagem em LaTeX. ```latex \documentclass{article} \usepackage{graphicx} \graphicspath{ {images/} } \begin{document} O universo é imenso e parece ser homogêneo, a grande escala, por todo o lado onde olhamos. \includegraphics{universe} Há uma imagem de uma galáxia acima \end{document} ``` ![InsertingImagesEx1.png](/files/86ea760edb021bbe46e4147f2ffef24ce25466bf) O LaTeX não tem a capacidade de manipular imagens por si próprio; por essa razão é necessário importar o pacote **graphicx**. Para usar esse pacote, adiciona a seguinte linha no preâmbulo do teu documento ```latex \usepackage{graphicx} ``` O comando `\graphicspath{ {images/} }` indica ao LaTeX que as imagens estão guardadas numa pasta chamada *images* sob o diretório atual. O comando `\includegraphics{universe}` é o responsável por incluir a imagem no documento. Aqui, *universe* é o nome do ficheiro de imagem, sem a extensão; portanto *universe.PNG* torna-se em *universe*. O nome do ficheiro de imagem não deve conter espaços em branco nem múltiplos sinais de pontuação. Nota: *Pode introduzir-se a extensão do ficheiro, mas é recomendável* omití-la. Se a extensão for omitida, isso faz com que o LaTeX procure todos os formatos suportados. Para mais detalhes, consulte a secção [Gerando imagens em alta e baixa resolução](#generando-imgenes-en-alta-y-baja-resolucin). [Abrir um exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## O caminho para a pasta de imagens Ao trabalhar num documento que inclui várias imagens, uma possibilidade para manter o projeto organizado é guardá-las numa pasta separada. No exemplo da introdução isso é conseguido através do comando `\graphicspath{ {images/} }` que diz ao LaTeX que as imagens devem ser procuradas na pasta *images*. O caminho é *relativa* ao diretório de trabalho atual. O caminho para a pasta pode ser ***relativa*** (recomendado) se a pasta estiver no mesmo diretório que o ficheiro .tex principal ou numa das subpastas, ou pode ser ***absoluta*** se for necessário especificar exatamente o caminho. Por exemplo: ```latex %Caminho absoluto no formato do Windows: \graphicspath{ {c:/user/images/} } %Caminho absoluto em formato tipo Unix (Linux, OsX) \graphicspath{ {/home/user/images/} } ``` Note-se que este comando requer uma barra final `/` e que o caminho deve ser colocado entre dois pares de chavetas. Também é possível definir vários caminhos se guardou as imagens em mais do que uma pasta para maior organização. Por exemplo, se existirem duas pastas, uma chamada *images1* e a outra *images2*, usa o comando ```latex \graphicspath{ {images1/}{images2/} } ``` Se não for especificado nenhum caminho, o LaTeX procurará as imagens na pasta atual, onde o ficheiro .tex está guardado. [Abrir exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Alterar o tamanho e rodar uma imagem Se quiser especificar parâmetros adicionais ao importar uma imagem em LaTeX para modificar a largura, a altura, a posição, etc. da imagem, isso é possível através da seguinte sintaxe: ```latex O Overleaf é uma excelente ferramenta profissional para editar online, partilhar e fazer cópias de segurança dos seus projetos \LaTeX. Também oferece uma documentação de ajuda bastante extensa. \includegraphics[scale=1.5]{lion-logo} ``` ![InsertingImagesEx2.png](/files/ecec1c1ad3ba552a44e692ed9abc695ea76f3842) O comando `\includegraphics[scale=1.5]{lion-logo}` inclui a imagem *lion-logo* no documento, o parâmetro extra `scale=1.5` dimensiona a imagem para 1,5 vezes o seu tamanho original. Também é possível redimensionar a imagem para uma altura e largura determinadas. ```latex O Overleaf é uma excelente ferramenta profissional para editar online, partilhar e fazer cópias de segurança dos seus projetos \LaTeX. Também oferece uma documentação de ajuda bastante extensa. \includegraphics[width=3cm, height=4cm]{lion-logo} ``` ![InsertingImagesEx3.png](/files/909ad548dffb50d6e91dba3a541cf7c26fbf8ecb) Como provavelmente já adivinhou, os parâmetros entre os colchetes `[width=3cm, height=4cm]` definem a largura e a altura da imagem. Podem ser usadas [diferentes unidades](#gua-de-referencia) de medida nestes parâmetros. Se for definido apenas o valor de *largura*, a altura será escalada proporcionalmente para manter o aspeto da imagem. Também é possível definir o comprimento da imagem em relação a outros elementos no documento. Por exemplo, se quiser que a imagem tenha a mesma largura que o texto: ```latex O Overleaf é uma excelente ferramenta profissional para editar online, partilhar e fazer cópias de segurança dos seus projetos \LaTeX. Também oferece uma documentação de ajuda bastante extensa. \includegraphics[width=\textwidth]{universe} ``` ![InsertingImagesEx5.png](/files/be7e2c1bdb8b208f6fb693f84db194d1dc31edb2) Em vez de `\textwidth` pode usar qualquer outra das unidades que o LaTeX inclui por defeito: *\columnsep, \linewidth, \textheight, \paperheight, etc*. Consulte a [guia de referência](#gua-de-referencia) para uma melhor descrição das unidades. Há outra opção muito comum ao incluir imagens num documento: poder rodá-las. Isto é muito fácil em LaTeX: ```latex O Overleaf é uma excelente ferramenta profissional para editar online, partilhar e fazer cópias de segurança dos seus projetos \LaTeX. Também oferece uma documentação de ajuda bastante extensa. \includegraphics[scale=1.2, angle=45]{lion-logo} ``` ![InsertingImagesEx4.png](/files/f3bcb60f4acf86e37616805113666926e6ffc9a2) O parâmetro `angle=45` roda a imagem 45 graus no sentido contrário ao dos ponteiros do relógio. Para rodar a imagem no mesmo sentido dos ponteiros de um relógio, use um número negativo. [Abra um exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Posicionar a imagem Na secção anterior explicou-se como inserir uma imagem no seu documento, mas por vezes a combinação de imagens e texto no seu documento pode não resultar como esperava. Para mudar isso é necessário usar um novo ambiente: ```latex No exemplo seguinte, a figura será posicionada logo abaixo desta frase. \begin{figure}[h] \includegraphics[width=8cm]{Plot} \end{figure} ``` ![InsertingImagesEx6.png](/files/71c49f9208e71adb83276a52fb934782ee6aeeea) O ambiente `figure` é usado para mostrar as imagens como elementos flutuantes dentro do documento. Isto significa que basta incluir a sua imagem dentro do ambiente *figure* e já não precisa de se preocupar com onde aparecerá; o LaTeX posicioná-la-á de forma a que encaixe perfeitamente no fluxo do documento. Embora à partida isto pareça muito bom, por vezes pretende-se ter mais controlo sobre onde as imagens aparecerão. Pode usar-se um parâmetro adicional para definir o posicionamento da figura. No exemplo, `begin{figure}[h]`, o parâmetro dentro dos colchetes define a posição da figura *aqui* (aqui, em inglês). De seguida, uma tabela com uma lista de possíveis valores de posicionamento. | Parâmetro | Posição | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | h | Define a posição do elemento flutuante «aqui». Isto é, aproximadamente no mesmo ponto onde aparece no código (no entanto, o posicionamento nem sempre é exato) | | t | Insere a figura no início da página. | | b | Insere a figura no final da página. | | p | Insere os elementos flutuantes numa página separada, que contém apenas figuras. | | ! | Sobrescreve os parâmetros que o LaTeX usa para determinar uma «boa» posição para a imagem. | | H | Define o elemento flutuante precisamente no mesmo local em que aparece no código; é necessário importar o pacote `float`. É, até certo ponto, equivalente a h!. | No exemplo seguinte pode ver-se uma imagem que aparece no início do documento, apesar de o código que a produz se encontrar no final do documento. ```latex Nesta imagem pode ver-se um gráfico de barras que mostra os resultados de um inquérito que envolveu alguns dados importantes estudados ao longo do tempo. \begin{figure}[t] \includegraphics[width=8cm]{Plot} \centering \end{figure} ``` ![InsertingImagesEx7.png](/files/7d3ac1bd4445390cf909915196027b1608ecf060) O comando adicional `\centering` é responsável por centrar a imagem. O valor de alinhamento predefinido é à esquerda. Também é possível envolver o texto à volta da figura. Quando o documento contém imagens pequenas, isso faz com que o texto fique melhor. ```latex \begin{wrapfigure}{r}{0.25\textwidth} %esta figura ficará à direita \centering \includegraphics[width=0.25\textwidth]{mesh} \end{wrapfigure} Há várias formas de traçar uma função de duas variáveis, dependendo da informação em que está interessado. Por exemplo, se quiser ver a malha de uma função para que seja mais fácil ver a derivada, pode usar um gráfico como o da esquerda. \begin{wrapfigure}{l}{0.25\textwidth} \centering \includegraphics[width=0.25\textwidth]{contour} \end{wrapfigure} Por outro lado, se estiver interessado apenas em determinados valores, pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno, como o da esquerda. Por outro lado, se estiver interessado apenas em determinados valores, pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno, pode usar o gráfico de contorno, como o da esquerda. ``` ![InsertingImagesEx8.png](/files/2a80b0ac8e2c7823368fd526495fb906a7e693a4) Para que os comandos no exemplo funcionem, é necessário importar o pacote **wrapfig**. Adicione ao preâmbulo a linha ```latex \usepackage{wrapfig} ``` Uma vez importado o pacote, pode usar-se o ambiente *wrapfigure* através do comando `\begin{wrapfigure}{l}{0.25\textwidth} \end{wrapfigure}`. Note-se que o ambiente tem dois parâmetros adicionais entre chavetas. De seguida, explica-se o código com mais detalhe. **{l}** Define o alinhamento da figura. Use l para a esquerda e r para a direita. Além disso, se estiver a usar a classe book ou outra semelhante, em vez de l e r podem usar-se o para a margem exterior e i para a margem interior da página. **{0.25\textwidth}** Isto define a largura da caixa que contém a imagem. Não é a largura da imagem em si; essa deve ser definida no comando includegraphics. No exemplo são usadas unidades relativas, mas podem ser usadas unidades normais (cm, mm, in, etc.). Consulte o guia de referência para ver uma lista de unidades possíveis. **\centering** Já foi explicado anteriormente, mas no exemplo anterior a imagem será centrada em relação à caixa que a contém, em vez de ser centrada em relação à página. Para informações mais completas acerca do posicionamento de imagens, consulte o artigo [Posicionamento de imagens e tabelas](/latex/overleaf-learn-latex-pt/figuras-e-tabelas/02-positioning-images-and-tables.md) [Abrir exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Adicionar etiquetas, legendas e referências Poder adicionar legendas com uma breve descrição da imagem e etiquetas que depois podem ser usadas para referir a imagem são ferramentas muito úteis quando se trabalha com documentos muito longos. ### Legendas Comecemos com um exemplo de como adicionar uma legenda: ```latex \begin{figure}[h] \caption{Example of a parametric plot ($\sin (x), \cos(x), x$)} \centering \includegraphics[width=0.5\textwidth]{spiral} \end{figure} ``` ![InsertingImagesEx9.png](/files/dc07074b7fe5d282a8ed774c56a513cf2d25545b) É muito fácil, basta adicionar o comando `\caption{Some caption}` e dentro das chavetas escrever o texto a mostrar. O local onde a legenda será impressa depende de onde o comando é inserido; se estiver acima do comando *includegraphics* então a legenda aparecerá sobre a imagem; se estiver abaixo desse comando, então a legenda aparecerá na parte inferior da figura. As legendas também podem ser posicionadas ao lado das figuras. O pacote **sidecap** permite usar um código muito semelhante ao do exemplo anterior para adicionar o texto. ```latex \documentclass{article} \usepackage[rightcaption]{sidecap} \usepackage{graphicx} %package to manage images \graphicspath{ {images/} } \begin{SCfigure}[0.5][h] \caption{Example of a parametric plot. Esta legenda ficará à direita} \includegraphics[width=0.6\textwidth]{spiral} \end{SCfigure} ``` ![InsertingImagesEx10.png](/files/80fe1e5d2341ece51745321392de8830407105c5) Há dois novos comandos neste exemplo: **\usepackage\[rightcaption]{sidecap}** Como provavelmente já sabe, este comando importa o pacote chamado sidecap, mas há um parâmetro adicional: rightcaption. Este parâmetro é o que define o local onde a legenda é impressa. Neste caso, à direita da imagem; também é possível usar leftcaption para mover a legenda para a esquerda. Em documentos que usam classes do tipo livro, adicionalmente podem usar-se as opções outercaption e innercaption para imprimir a legenda na parte exterior ou interior em relação à margem da página. **\begin{SCfigure}\[0.5]\[h] \end{SCfigure}** Define um ambiente semelhante a figure. O primeiro parâmetro é a largura da legenda relativa ao tamanho da imagem. O segundo parâmetro h tem a mesma função que no ambiente figure. Consulte a secção sobre posicionamento de imagens para mais informações. Pode obter-se um controlo mais avançado do formato das legendas, se assim o desejar. Consulte as [leituras adicionais](#lecturas-adicionales) para ver mais referências. ### Etiquetas e referências cruzadas As figuras, tal como muitos outros elementos num documento LaTeX (equações, tabelas, gráficos, etc.), podem ser referidas a partir do texto. Conseguir isso é muito fácil, basta adicionar uma etiqueta ao ambiente *figure* ou *SCfigure*, depois usar essa etiqueta para referir a figura. ```latex \begin{figure}[h] \centering \includegraphics[width=0.25\textwidth]{mesh} \caption{a nice plot} \label{fig:mesh1} \end{figure} Como pode ver na figura \ref{fig:mesh1}, a função cresce perto de 0. Além disso, na página \pageref{fig:mesh1} está o mesmo exemplo. ``` ![InsertingImagesEx11.png](/files/895a732bc86e0e1c449c095284a24951ec6c6946) Há três comandos neste exemplo que geram referências cruzadas. **\label{fig:mesh1}** Define a etiqueta para a figura. Como as etiquetas podem ser usadas em diversos tipos de elementos no documento, é uma boa prática usar um prefixo, tal como fig: no exemplo. **\ref{fig:mesh1}** Este comando imprime o número atribuído à figura. Os números são gerados automaticamente e são atualizados se, posteriormente, for inserida uma figura antes da que é referida. **\pageref{fig:mesh1}** Imprime o número da página onde aparece a imagem referida pela etiqueta. O comando `\caption` que adiciona uma legenda é obrigatório para poder adicionar uma etiqueta e referir a figura. Outra característica importante no LaTeX é a possibilidade de gerar automaticamente uma *lista de figuras*. Isto consegue-se facilmente com: ```latex \listoffigures ``` ![InsertingImagesEx12.png](/files/5c5229ee9b6f64d695e1c8056cfaf8fb75bda2a0) Este comando só funciona com figuras que têm uma legenda, dado que a usa para gerar a tabela. O exemplo anterior lista as imagens usadas no presente artigo. Nota importante: *Quando se usam referências cruzadas em LaTeX, o projeto deve ser compilado duas vezes; caso contrário, as referências, as referências a páginas e a tabela de figuras não funcionarão*. [Abrir um exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Gerando imagens em alta e baixa resolução Por enquanto, quando introduzimos o nome do ficheiro de imagem no comando *\includegraphics* omitimos a extensão do ficheiro. No entanto, isso não é necessário, embora possa ser muito útil. Se a extensão for omitida, o LaTeX procurará qualquer tipo de imagem suportada no diretório de imagens predefinido; a pesquisa será feita numa determinada ordem, a qual pode ser modificada. Isto é muito útil para passar da versão de rascunho do seu documento para a versão final. No rascunho (enquanto escreve o seu artigo, livro, relatório, etc.), é desejável poder usar imagens com baixa resolução (tipicamente em formato .png) para que o documento compile mais rapidamente. Na versão final, por outro lado, prefere-se incluir as imagens em alta resolução, para ter um documento de qualidade. Isto pode ser conseguido através de: * Não especificar a extensão do ficheiro no comando *\includegraphics*, e * Especificando a ordem das extensões no preâmbulo Assim, se tiver duas versões da mesma imagem, por exemplo venndiagram.pdf (em alta resolução) e venndiagram.png (em baixa resolução), pode incluir a seguinte linha no preâmbulo enquanto escreve e depura o documento - ```latex \DeclareGraphicsExtensions{.png,.pdf} ``` O comando anterior garante que, se existirem duas imagens com o mesmo nome mas com extensões diferentes, então o ficheiro .png será usado e, se por alguma razão esse ficheiro desaparecer, a versão em pdf será a opção seguinte. Uma vez escrito o documento, para usar apenas a versão em alta resolução deve alterar-se a linha que determina a extensão para: ```latex \DeclareGraphicsExtensions{.pdf,.png} ``` Pode até melhorar-se a técnica descrita anteriormente; podemos pedir ao LaTeX que gere imagens .png de baixa resolução enquanto o documento é compilado, caso o PDF ainda não tenha sido convertido para PNG. Para conseguir isto, deve incluir-se o seguinte no preâmbulo depois de `\usepackage{graphicx}`. ```latex \usepackage{epstopdf} \epstopdfDeclareGraphicsRule{.pdf}{png}{.png}{convert #1 \OutputFile} \DeclareGraphicsExtensions{.png,.pdf} ``` Se venndiagram2.pdf existir mas não venndiagram2.png, o ficheiro vendiagramm2-pdf-converted-to.png será criado e carregado em seu lugar. O comando *convert #1* é o responsável pela conversão Há algumas coisas a ter em mente se for escolhido este método: * Para que a conversão automática funcione, deve executar-se *pdflatex* com a opção `--shell-escape`. * Para a versão final, não se deve esquecer de comentar a linha `\epstopdfDeclareGraphicsRule`, de modo que apenas sejam carregadas as imagens em alta resolução. Também se deve lembrar de alterar a ordem de precedência. [Abrir exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Guia de referência **Unidades e medidas em LaTeX** | Abreviação | Definição | | ------------ | -------------------------------------------------------------------------- | | pt | Um ponto é a unidade de comprimento predefinida. Aproximadamente 0,3515 mm | | mm | um milímetro | | cm | um centímetro | | em | uma polegada | | ex | a altura de uma **x** com a fonte atual | | em | a largura de uma **m** com a fonte atual | | \columnsep | distância entre as colunas | | \columnwidth | largura de uma coluna | | \linewidth | largura de linha no ambiente atual | | \paperwidth | largura do papel | | \paperheight | altura do papel | | \textwidth | largura do texto | | \textheight | altura do texto | | \unitlength | unidades de comprimento no ambiente *picture* | **Acerca dos tipos de imagens que podem ser usados em LaTeX** **latex** Se o documento for compilado com o comando latex, só podem ser usadas imagens em formato EPS, que é um formato vetorial. **pdflatex** Se o documento for compilado com o comando pdflatex para produzir um PDF, então podem ser usados vários tipos de imagens- ``` JPG: A melhor opção para inserir fotografias PNG: A melhor opção para inserir diagramas (se, por alguma razão, não puder usar um gráfico vetorial) e capturas de ecrã PDF: Apesar do hábito de usar PDF para documentos, em geral um PDF pode consistir apenas numa imagem que pode posteriormente ser importada. EPS: As imagens EPS podem ser incluídas usando o pacote epstopdf (o pacote só precisa de ser instalado no computador; uma vez instalado, não é necessário nenhum comando adicional no ficheiro .tex) ``` **Gráficos vetoriais ou mapas de bits?** As imagens podem ser incluídas quer em formato de mapas de bits quer em gráficos vetoriais. Em geral, não se deve preocupar com isso, mas se houver a opção de escolher um formato, deve ter-se em conta que, para um gráfico vetorial, o melhor é guardá-lo em formato PDF ou EPS, enquanto para um mapa de bits os formatos JPG ou PNG são os recomendados. Isto porque um mapa de bits dentro de um ficheiro em formato PDF ou EPS requer muito espaço de armazenamento. [Abrir exemplo no Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/52f4102815577d644c0017fb/download/zip\&templateName=InsertingImages\&compiler=pdflatex) ## Leituras adicionais Para mais informações, consulte: * [Posicionamento de imagens e tabelas](/latex/overleaf-learn-latex-pt/figuras-e-tabelas/02-positioning-images-and-tables.md) * [Listas de tabelas e figuras](/latex/overleaf-learn-latex-pt/figuras-e-tabelas/03-lists-of-tables-and-figures.md) * [Documentos de uma face e de dupla face](/latex/overleaf-learn-latex-pt/formatacao/08-single-sided-and-double-sided-documents.md) * [Comprimentos em LaTeX](/latex/overleaf-learn-latex-pt/formatacao/01-lengths-in-latex.md) * [**floatrow** pacote para gestão avançada de legendas de elementos flutuantes (tabelas e figuras)](http://tug.ctan.org/tex-archive/macros/latex/contrib/floatrow/floatrow.pdf) * [**sidecap** documentação do pacote, para legendas de figuras laterais](ftp://ctan.tug.org/tex-archive/macros/latex/contrib/sidecap/sidecap.pdf) * [**epstopdf** documentação do pacote (conversão de PDF para EPS)](https://www.google.com/url?sa=t\&rct=j\&q=\&esrc=s\&source=web\&cd=3\&cad=rja\&ved=0CEEQFjAC\&url=http%3A%2F%2Fmirror.hmc.edu%2Fctan%2Fmacros%2Flatex%2Fcontrib%2Foberdiek%2Fepstopdf.pdf\&ei=N4v2UpK7D4eHqQHz2IDACg\&usg=AFQjCNG9CxIXjrbc22kl-8QweEXeEauFew\&sig2=qamKo3qpid8CEqzsHhpIrQ\&bvm=bv.60983673,d.aWM) --- # 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/mais-topicos/28-inserting-images-es.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.