> 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/formatacao/10-counters.md).

# Contadores

## Introdução aos contadores LaTeX

A composição tipográfica baseada em LaTeX é uma forma especializada de programação: está a usar uma linguagem de composição tipográfica (comandos LaTeX) para fornecer “instruções” que resultam numa saída: o documento LaTeX compilado na forma de um ficheiro PDF. Tal como em qualquer empreendimento de programação, é provável que precise de o LaTeX armazenar temporariamente valores inteiros para reutilização posterior no seu documento (código) — poderá querer:

* compor tipograficamente esses inteiros armazenados no seu documento
* fornecer numeração automática de certos elementos do seu documento
* usá-los como variáveis para controlar código condicional (ou ciclos)
* alterar e atualizar os seus valores incrementando/decrementando por um certo valor fixo
* redefini-los para valores completamente diferentes

Estas atividades de processamento de inteiros são extremamente comuns em linguagens de programação “normais”, como Javascript, C, Lua ou qualquer outra linguagem à sua escolha, nas quais tipicamente declara (cria um nome para) uma variável (para conter um inteiro) e depois lhe atribui um valor. A linguagem de composição tipográfica LaTeX oferece capacidades semelhantes, embora implementadas de uma forma bastante diferente, como veremos abaixo.

Em essência, um contador LaTeX é o nome de uma “variável LaTeX” usada para armazenar valores inteiros que podem ser usados para as atividades listadas acima, e muito mais além disso. O próprio LaTeX usa numerosos contadores internos que fornecem numeração de páginas, secções, tabelas, figuras, listas com marcadores/numeradas, etc. Este artigo explica como aceder e modificar esses contadores e como criar e usar novos.

## Comandos LaTeX para trabalhar com contadores

Aqui está uma lista dos comandos de contadores do LaTeX ligada à sua descrição nas secções seguintes.

Criar e incrementar contadores:

* [`\newcounter{somecounter}[anothercounter]`](#newcountersomecounteranothercounter)
* [`\setcounter{somecounter}{number}`](#setcountersomecounternumber)
* [`\addtocounter{somecounter}{number}`](#addtocountersomecounternumber)
* [`\stepcounter{somecounter}`](#stepcountersomecounter)
* [`\refstepcounter{somecounter}`](#refstepcountersomecounter)

Aceder e imprimir valores de contadores:

* [`\arabic{somecounter}`](#arabicsomecounter)
* [`\roman{somecounter}`](#romansomecounter)
* [`\Roman{somecounter}`](#romanoutput)
* [`\alph{somecounter}`](#alphsomecounter)
* [`\Alph{somecounter}`](#alphoutput)
* [`\fnsymbol{somecounter}`](#fnsymbolsomecounter)
* [`\value{somecounter}`](#valuesomecounter)

Outros comandos de contadores:

* [`\counterwithin{somecounter}{anothercounter}`](#counterwithinsomecounteranothercounter)
* [`\counterwithout{somecounter}{anothercounter}`](#counterwithoutsomecounteranothercounter)

### Criar e incrementar contadores

#### \newcounter{somecounter}\[anothercounter]

Usado para definir um novo contador. O segundo argumento, entre `[]`, é opcional, mas quando usado define `*somecounter*` como um novo contador que é reiniciado quando `*anothercounter*` é incrementado. `\newcounter` é frequentemente usado na sua forma mais simples `\newcounter{*somecounter*}` que cria `*somecounter*` e inicializa-o com 0.

* **Nota**: Para cada contador criado pelo `\newcounter` comando, ele *também* define um comando que pode ser usado para compor tipograficamente o valor do contador. Por exemplo, `\newcounter{*mycounter*}` define um comando chamado `\the*mycounter*`. Um exemplo é mostrado no seguinte fragmento de código LaTeX, que pode abrir no Overleaf, como um documento completo, usando o link fornecido:

```latex
\newcounter{mycounter}
\setcounter{mycounter}{42}
Pode agora escrever \verb|\themycounter| para obter \themycounter.
```

[Abra este fragmento LaTeX no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bmycounter%7D%0A%5Csetcounter%7Bmycounter%7D%7B42%7D%0AYou+can+now+write+%5Cverb%7C%5Cthemycounter%7C+to+obtain+%5Cthemycounter.%0A%5Cend%7Bdocument%7D)

Este exemplo produz $$\text{You can now write }\verb|\themycounter|\text{ to obtain 42.}$$

* **Nota**: Se `*mycounter*` já tiver sido definido, o LaTeX emitirá o erro `c@mycounter already defined`, como demonstrado pelo exemplo seguinte, que pode abrir no Overleaf.

```latex
\newcounter{mycounter}
...muito código... mas esquecemo-nos e escrevemos \verb|\newcounter{mycounter}| novamente
\newcounter{mycounter}
```

[Abra este ***código que gera erro*** no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bmycounter%7D%0A...lots+of+code...+but+we+forget+and+write+%5Cverb%7C%5Cnewcounter%7Bmycounter%7D%7C+again%0A%5Cnewcounter%7Bmycounter%7D%0A%5Cend%7Bdocument%7D)

#### \setcounter{somecounter}{number}

Define `*somecounter*` para conter o valor `*number*`.

* **Nota**: `*number*` pode ser positivo ou negativo.

Um exemplo é mostrado no seguinte fragmento de código LaTeX, que pode abrir no Overleaf, como um documento completo, usando o link fornecido:

```latex
\noindent Crie um novo contador \texttt{myvar} e atribua-lhe o valor \texttt{42}.
\vspace{10pt}

\newcounter{myvar}
\setcounter{myvar}{42}

\noindent Escrever \verb|\themymar| compõe tipograficamente \texttt{\themyvar}.
\vspace{10pt}

\noindent De seguida, vamos alterar \texttt{myvar} para \texttt{-42}, escrevendo \verb|\setcounter{myvar}{-42}|
\setcounter{myvar}{-42}. Agora, escrever \verb|\themyvar| produz \texttt{\themyvar}.
```

[Abra este fragmento LaTeX no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Create+a+new+counter+%5Ctexttt%7Bmyvar%7D+and+assign+it+the+value+%5Ctexttt%7B42%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnewcounter%7Bmyvar%7D%0A%5Csetcounter%7Bmyvar%7D%7B42%7D+%0A%0A%5Cnoindent+Writing+%5Cverb%7C%5Cthemymar%7C+typesets+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+Next%2C+we%27ll+change+%5Ctexttt%7Bmyvar%7D+to+%5Ctexttt%7B-42%7D%2C+writing+%5Cverb%7C%5Csetcounter%7Bmyvar%7D%7B-42%7D%7C%0A%5Csetcounter%7Bmyvar%7D%7B-42%7D.+Now%2C+writing+%5Cverb%7C%5Cthemyvar%7C+outputs+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cend%7Bdocument%7D)

#### \addtocounter{somecounter}{number}

Aumenta o contador `*somecounter*` em `*number*`.

* **Nota**: `*number*` pode ser positivo, para aumentar o valor do contador, ou negativo, para o diminuir. Por exemplo:

```latex
\addtocounter{somecounter}{-1} % decreases somecounter by 1
```

Um exemplo é mostrado no seguinte fragmento de código LaTeX, que pode abrir no Overleaf, como um documento completo, usando o link fornecido:

```latex
\noindent Crie um novo contador \texttt{myvar} e atribua-lhe o valor \texttt{42}.
\vspace{10pt}

\newcounter{myvar}
\setcounter{myvar}{42}

\noindent Escrever \verb|\themymar| compõe tipograficamente \texttt{\themyvar}.
\vspace{10pt}

\noindent De seguida, vamos alterar \texttt{myvar} para \texttt{142} escrevendo \verb|\addtocounter{myvar}{100}|\addtocounter{myvar}{100}. Agora, escrever \verb|\themyvar| produz \texttt{\themyvar}.
```

[Abra este fragmento LaTeX no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+addtocounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Create+a+new+counter+%5Ctexttt%7Bmyvar%7D+and+assign+it+the+value+%5Ctexttt%7B42%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnewcounter%7Bmyvar%7D%0A%5Csetcounter%7Bmyvar%7D%7B42%7D+%0A%0A%5Cnoindent+Writing+%5Cverb%7C%5Cthemymar%7C+typesets+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+Next%2C+we%E2%80%99ll+change+%5Ctexttt%7Bmyvar%7D+to+%5Ctexttt%7B142%7D+by+writing+%5Cverb%7C%5Caddtocounter%7Bmyvar%7D%7B100%7D%7C%5Caddtocounter%7Bmyvar%7D%7B100%7D.+Now%2C+writing+%5Cverb%7C%5Cthemyvar%7C+outputs+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cend%7Bdocument%7D)

#### \stepcounter{somecounter}

Incrementa `*somecounter*` em 1. Um exemplo é mostrado no seguinte fragmento de código LaTeX, que pode abrir no Overleaf, como um documento completo, usando o link fornecido:

```latex
Se criarmos um novo contador escrevendo \verb|\newcounter{mycounter}|
\newcounter{mycounter} então o contador \texttt{mycounter} é criado e
inicializado a zero, como pode ver se escrever \verb|\themycounter|:
\texttt{mycounter} armazena atualmente: \themycounter.

Se agora escrevermos \verb|\stepcounter{mycounter}|\stepcounter{mycounter} então
\verb|\themycounter| contém agora o valor \themycounter.
```

[Abra este fragmento LaTeX no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+stepcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0AIf+we+create+a+new+counter+by+writing+%5Cverb%7C%5Cnewcounter%7Bmycounter%7D%7C%0A%5Cnewcounter%7Bmycounter%7D+then+the+counter+%5Ctexttt%7Bmycounter%7D+is+created+and+%0Ainitialized+to+zero%2C+as+you+can+see+if+you+write+%5Cverb%7C%5Cthemycounter%7C%3A%0A%5Ctexttt%7Bmycounter%7D+currently+stores%3A+%5Cthemycounter.+%0A%0AIf+we+now+write+%5Cverb%7C%5Cstepcounter%7Bmycounter%7D%7C%5Cstepcounter%7Bmycounter%7D+then+%0A%5Cverb%7C%5Cthemycounter%7C+now+contains+the+value+%5Cthemycounter.%0A%5Cend%7Bdocument%7D)

#### \refstepcounter{somecounter}

Aumenta `*somecounter*` em 1 e torna-o visível para o mecanismo de referenciação, definindo também o valor para que possa usar `\label` depois.

**Exemplo usando \refstepcounter**

O exemplo seguinte usa `\refstepcounter` para criar um novo contador para uma `exemplo` ambiente e usa `\label` e `\ref` para ilustrar a referenciação usando a variável do contador. `exemplo` counter variable.

```latex
\documentclass{article}

\newcounter{example}[section]
\newenvironment{example}[1][]{\refstepcounter{example}\par\medskip
   \noindent\textbf{Exemplo~\theexample. #1} \rmfamily}{\medskip}

\begin{document}
\section{Três exemplos}
\begin{example}
Crie uma etiqueta neste primeiro exemplo \verb|\label{ex:1}|\label{ex:1}. Este é o primeiro exemplo. O contador \texttt{example} será reiniciado no início de cada nova \verb|\section| do documento.
\end{example}

\begin{example}
E aqui está outro exemplo numerado. Crie uma segunda \verb|\label{ex:2}|\label{ex:2} para posteriormente referenciar este. No Exemplo \ref{ex:1} lemos... alguma coisa.
\end{example}

\begin{example}
E aqui está outro exemplo numerado: use \verb|\theexample| para compor tipograficamente o número atualmente atribuído ao contador \texttt{example}: é \theexample.
\end{example}

\section{Outra secção}
Acabámos de iniciar uma nova secção, o que significa que o contador \texttt{example} foi definido para \theexample.
Vamos referenciar exemplos da secção anterior (Exemplos \ref{ex:1} e \ref{ex:2}). Esta é uma secção de preenchimento sem qualquer finalidade, exceto conter texto. O contador \texttt{section} desta secção pode ser composto tipograficamente usando \verb|\thesection|: está atualmente atribuído ao valor de \thesection.

\begin{example}
Este é o primeiro exemplo nesta secção: o contador \texttt{example} foi incrementado e está agora definido para \theexample.
\end{example}
\end{document}
```

[Abra este `\refstepcounter` exemplo no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=An+example+using+refstepcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%0A%5Cnewcounter%7Bexample%7D%5Bsection%5D%0A%5Cnewenvironment%7Bexample%7D%5B1%5D%5B%5D%7B%5Crefstepcounter%7Bexample%7D%5Cpar%5Cmedskip%0A+++%5Cnoindent%5Ctextbf%7BExample%7E%5Ctheexample.+%231%7D+%5Crmfamily%7D%7B%5Cmedskip%7D%0A%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BThree+examples%7D%0A%5Cbegin%7Bexample%7D%0ACreate+a+label+in+this+first+example+%5Cverb%7C%5Clabel%7Bex%3A1%7D%7C%5Clabel%7Bex%3A1%7D.+This+is+the+first+example.+The+%5Ctexttt%7Bexample%7D+counter+will+be+reset+at+the+start+of+each+new+each+document+%5Cverb%7C%5Csection%7C.%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7Bexample%7D%0AAnd+here%27s+another+numbered+example.+Create+a+second+%5Cverb%7C%5Clabel%7Bex%3A2%7D%7C%5Clabel%7Bex%3A2%7D+to+later+reference+this+one.+In+Example+%5Cref%7Bex%3A1%7D+we+read...+something.+%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7Bexample%7D%0AAnd+here%27s+another+numbered+example%3A+use+%5Cverb%7C%5Ctheexample%7C+to+typeset+the+number+currently+assigned+to+the+%5Ctexttt%7Bexample%7D+counter%3A+it+is++%5Ctheexample.%0A%5Cend%7Bexample%7D%0A%0A%5Csection%7BAnother+section%7D%0AWe%27ve+just+started+a+new+section+meaning+that+the++%5Ctexttt%7Bexample%7D+counter+has+been+set+to+%5Ctheexample.++%0AWe%27ll+reference+examples+from+the+previous+section+%28Examples+%5Cref%7Bex%3A1%7D+and+%5Cref%7Bex%3A2%7D%29.++This+is+a+dummy+section+with+no+purpose+whatsoever+but+to+contain+text.+The+%5Ctexttt%7Bsection%7D+counter+for+this+section+can+be+typeset+using+%5Cverb%7C%5Cthesection%7C%3A+it+is++currently+assigned+the+value+of+%5Cthesection.%0A%0A%5Cbegin%7Bexample%7D%0AThis+is+the+first+example+in+this+section%3A+the+%5Ctexttt%7Bexample%7D+counter+has+been+stepped+and+now+set+to+%5Ctheexample.+%0A%5Cend%7Bexample%7D%0A%5Cend%7Bdocument%7D)

**Resumo do código**

Neste exemplo, o novo ambiente `exemplo` é definido; este ambiente tem 3 comandos específicos para contagem:

* `\newcounter{example}[section]`: Cria um novo contador chamado `exemplo` que será reiniciado para 0 sempre que o `contador section` for aumentado. Pode colocar qualquer outro contador em vez de `contador section` ou omitir o parâmetro se não quiser que o seu contador seja reiniciado automaticamente.
* `\refstepcounter{example}`: Aumenta o `exemplo` contador em 1 e torna-o visível para o mecanismo de referenciação, para que possa usar `\label` depois.
* `\theexample`: Imprime o valor atual do contador `exemplo`.

Para mais informações sobre ambientes definidos pelo utilizador, consulte [o artigo sobre a definição de novos ambientes](/latex/overleaf-learn-latex-pt/comandos/02-environments.md#defining-a-new-environment)

### Aceder e imprimir valores de contadores

As discussões seguintes baseiam-se nos padrões predefinidos do LaTeX, antes de qualquer personalização aplicada por pacotes carregados pelo utilizador.

#### \arabic{somecounter}

Apresente a representação de `*somecounter*` como numerais arábicos: 1, 2, 3...

#### \roman{somecounter}

Apresente a representação de `*somecounter*` como um numeral romano em minúsculas: i, ii, iii...

* **Nota**: Se `*somecounter*` $$\leq$$ `0` não é produzida qualquer saída. Além disso, converter *extremamente* valores inteiros grandes para numerais romanos em minúsculas pode demorar muito tempo a concluir — e produz uma longa sequência de `m` caracteres (representando o número `1000`).
* **DICA**: Se estiver interessado no algoritmo que o TeX usa para converter números arábicos em numerais romanos, pode ler sobre isso neste artigo sobre [Algoritmos para Numerais Romanos](https://www.hanshq.net/roman-numerals.html#tex).

#### \Roman{somecounter}

Apresente a representação de `*somecounter*` como um numeral romano em maiúsculas: I, II, III...

* **Nota**: Se `*somecounter*` $$\leq$$ `0` não é produzida qualquer saída. Além disso, converter *extremamente* valores inteiros grandes para numerais romanos em maiúsculas pode demorar muito tempo a concluir — e produz uma longa sequência de `M` caracteres (representando o número `1000`).
* **DICA**: Se estiver interessado no algoritmo que o TeX usa para converter números arábicos em numerais romanos, pode ler sobre isso neste artigo sobre [Algoritmos para Numerais Romanos](https://www.hanshq.net/roman-numerals.html#tex).

#### \alph{somecounter}

Apresente a representação de `*somecounter*` como uma letra minúscula onde a=1, b=2, c=3...

* **Nota**: `*somecounter*` deve estar no intervalo `1` $$\leq$$ `*somecounter*` $$\leq$$ `26`, caso contrário irá desencadear o erro `! Erro LaTeX: Counter too large.`

#### \Alph{somecounter}

Apresente a representação de `*somecounter*` como uma letra maiúscula onde A=1, B=2, C=3...

* **Nota**: `*somecounter*` deve estar no intervalo `1` $$\leq$$ `*somecounter*` $$\leq$$ `26`, caso contrário irá desencadear o erro `! Erro LaTeX: Counter too large.`

#### \fnsymbol{somecounter}

Apresente a representação de `*somecounter*` como um símbolo de nota de rodapé onde 1 =∗, 2 =†...

* **Nota**: `*somecounter*` deve estar no intervalo `1` $$\leq$$ `*somecounter*` $$\leq$$ `9`, caso contrário irá desencadear o erro `! Erro LaTeX: Counter too large.`

|                          |                                                   |
| ------------------------ | ------------------------------------------------- |
| Valor de `*somecounter*` | Caráter composto tipograficamente por `\fnsymbol` |
| 1                        | \*                                                |
| 2                        | †                                                 |
| 3                        | ‡                                                 |
| 4                        | §                                                 |
| 5                        | ¶                                                 |
| 6                        | ∥                                                 |
| 7                        | ∗∗                                                |
| 8                        | ††                                                |
| 9                        | ‡‡                                                |

#### Exemplo de impressão de valores de contadores

O exemplo seguinte demonstra a utilização dos comandos `\arabic{*somecounter*}`, `\roman{*somecounter*}`, `\Roman{*somecounter*}`, `\alph{*somecounter*}`, `\Alph{*somecounter*}`, e `\fnsymbol{*somecounter*}`.

```latex
\newcounter{somecounter}
\setcounter{somecounter}{9}
\begin{itemize}
    \item \verb|\arabic{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \arabic{somecounter}
    \item \verb|\roman{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \roman{somecounter}
    \item \verb|\Roman{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \Roman{somecounter}
    \item \verb|\alph{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \alph{somecounter}
   \item \verb|\Alph{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \Alph{somecounter}
    \item \verb|\fnsymbol{somecounter}| compõe tipograficamente o valor de \texttt{somecounter} de \thesomecounter{} como \fnsymbol{somecounter}
\end{itemize}
```

[Abra este fragmento LaTeX no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Converting+counter+values\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bsomecounter%7D%0A%5Csetcounter%7Bsomecounter%7D%7B9%7D%0A%5Cbegin%7Bitemize%7D%0A++++%5Citem+%5Cverb%7C%5Carabic%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as+%5Carabic%7Bsomecounter%7D+%0A++++%5Citem+%5Cverb%7C%5Croman%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Croman%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5CRoman%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5CRoman%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5Calph%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Calph%7Bsomecounter%7D%0A+++%5Citem+%5Cverb%7C%5CAlph%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5CAlph%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5Cfnsymbol%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Cfnsymbol%7Bsomecounter%7D%0A%5Cend%7Bitemize%7D%0A%5Cend%7Bdocument%7D)

Este exemplo produz a seguinte saída:

![Exemplo de conversão de contadores em LaTeX](/files/c47b037b0f533f3f539afc956183fe198a6d816d)

#### \value{somecounter}

O objetivo deste comando, conforme descrito no código-fonte LaTeX, é “Aceder ao valor do contador como um número TeX”: ou seja, usa `\value{somecounter}` em situações em que o LaTeX espera processar um valor numérico.

**(Opcional) notas de contexto sobre o comando \value**

É tentador pensar que o comando `\value{*somecounter*}` irá *diretamente* compõe tipograficamente o valor de `*somecounter*`, mas não é esse o caso. Destina-se a ser usado dentro de outros comandos para aceder ao valor do contador como um número TeX, em oposição ao comando `\thesomecounter` que produz a representação impressa de `*somecounter*`.

No código-fonte LaTeX, `\value` é definido como:

```latex
\def\value#1{\csname c@#1\endcsname}
```

Consequentemente, `\value{*somecounter*}` cria uma instância da sequência de controlo interna do LaTeX `\c@somecounter` que contém o valor do contador `*somecounter*`.

**Exemplo**

O exemplo seguinte mostra um caso básico de utilização de `\value`.

```latex
\noindent Comece por declarar dois novos contadores:
\begin{verbatim}
\newcounter{first}
\newcounter{second}
\end{verbatim}

\newcounter{first}
\newcounter{second}

\noindent Algum tempo depois no seu código, define os seus valores:
\begin{verbatim}
\setcounter{first}{100}
\setcounter{second}{50}
\end{verbatim}

\setcounter{first}{100}
\setcounter{second}{50}
\noindent Depois escreve mais código \LaTeX{}...\vspace{10pt}

\noindent Em determinado momento, poderemos querer adicionar o valor do contador \texttt{second} ao contador \texttt{first}. Uma forma de o fazer é usar \verb|\value| para obter o valor \textit{atual} armazenado no contador \texttt{second}:

\begin{verbatim}
\addtocounter{first}{\value{second}}
\end{verbatim}

\addtocounter{first}{\value{second}}\noindent O valor de \texttt{first} pode ser apresentado por \verb|\thefirst|: \thefirst. Também podemos escrever \verb|\the\value{first}| que também compõe tipograficamente \the\value{first}. No entanto, escrever \verb|\value{first}| irá gerar o erro \texttt{Missing number, treated as zero} porque \LaTeX{} então tenta executar o comando interno \verb|\c@first|. Descomente a linha seguinte para gerar o erro:
\begin{verbatim}
%\value{first}
\end{verbatim}
%\value{first}
```

[Abra este fragmento de código no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+the+value+command\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Start+by+declaring+two+new+counters%3A%0A%5Cbegin%7Bverbatim%7D%0A%5Cnewcounter%7Bfirst%7D%0A%5Cnewcounter%7Bsecond%7D++++%0A%5Cend%7Bverbatim%7D%0A%0A%5Cnewcounter%7Bfirst%7D%0A%5Cnewcounter%7Bsecond%7D%0A%0A%5Cnoindent+Sometime+later+in+your+code+you+set+their+values%3A%0A%5Cbegin%7Bverbatim%7D%0A%5Csetcounter%7Bfirst%7D%7B100%7D%0A%5Csetcounter%7Bsecond%7D%7B50%7D++++%0A%5Cend%7Bverbatim%7D%0A%0A%5Csetcounter%7Bfirst%7D%7B100%7D%0A%5Csetcounter%7Bsecond%7D%7B50%7D++%0A%5Cnoindent+Then+you+write+more+%5CLaTeX%7B%7D+code...%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+At+some+point+we+might+want+to+add+the+value+of+counter+%5Ctexttt%7Bsecond%7D+to+counter+%5Ctexttt%7Bfirst%7D.+One+way+to+do+that+is+using+%5Cverb%7C%5Cvalue%7C+to+obtain+the+%5Ctextit%7Bcurrent%7D+value+stored+in+the+%5Ctexttt%7Bsecond%7D+counter%3A%0A%0A%5Cbegin%7Bverbatim%7D%0A%5Caddtocounter%7Bfirst%7D%7B%5Cvalue%7Bsecond%7D%7D%0A%5Cend%7Bverbatim%7D%0A%0A%5Caddtocounter%7Bfirst%7D%7B%5Cvalue%7Bsecond%7D%7D%5Cnoindent+The+value+of+%5Ctexttt%7Bfirst%7D+can+be+output+by+%5Cverb%7C%5Cthefirst%7C%3A+%5Cthefirst.+We+can+also+write+%5Cverb%7C%5Cthe%5Cvalue%7Bfirst%7D%7C+which+also+typesets+%5Cthe%5Cvalue%7Bfirst%7D.+However%2C++writing+%5Cverb%7C%5Cvalue%7Bfirst%7D%7C+will+generate+the+error+%5Ctexttt%7BMissing+number%2C+treated+as+zero%7D+because+%5CLaTeX%7B%7D+then+tries+to+execute+the+internal+command+%5Cverb%7C%5Cc%40first%7C.+Uncomment+the+following+line+to+generate+the+error%3A%0A%5Cbegin%7Bverbatim%7D%0A%25%5Cvalue%7Bfirst%7D%0A%5Cend%7Bverbatim%7D%0A%25%5Cvalue%7Bfirst%7D%0A%5Cend%7Bdocument%7D)

Este exemplo produz a seguinte saída:

![Exemplo usando o comando \value](/files/aeac3b5172bc4934a0e1d6e1816ffbb454fabeb6)

### Outros comandos de contadores

Aqui descrevemos os comandos `\counterwithin` e `\counterwithout` que tiveram origem no [`chngcntr` pacote](https://ctan.org/pkg/chngcntr) mas que agora foram integrados no próprio LaTeX — veja [LaTeX News, abril de 2018](https://www.latex-project.org/news/latex2e-news/ltnews28.pdf). O `chngcntr` [documentação do pacote](https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/contrib/chngcntr/chngcntr.pdf) faz os seguintes comentários que ajudam a compreender o propósito destes comandos:

Ligado `\counterwithin`:

> É por vezes desejável alterar um contador que foi definido por `\newcounter{<ctr>}` para se comportar como se tivesse sido definido como `\newcounter{<ctr>}[<within>]`. O pacote fornece o comando `\counterwithin{<ctr>}{<within>}` que consegue isso.

Ligado `\counterwithout`:

> Do mesmo modo, o comando `\counterwithout{<ctr>}{<within>}` altera um contador que foi criado por `\newcounter{<ctr>}[<within>]` para se comportar como se tivesse sido criado por `\newcounter{<ctr>}`.

Essencialmente, estes dois comandos fornecem um método para ligar (`\counterwithin`) ou desligar (`\counterwithout`) dois contadores depois de terem sido definidos.

**\counterwithin{somecounter}{anothercounter}**

Reinicia `*somecounter*` para 0 sempre que `*anothercounter*` é incrementado, um mecanismo que liga os dois contadores. Para além de criar uma ligação, este comando redefine o que é composto tipograficamente por `\the*somecounter*`: em vez de apresentar o valor do contador `*somecounter*` produz `<valor de anothercounter>**.**<valor de somecounter>`. A forma com estrela (`\counterwithin*{somecounter}{anothercounter}`) não redefine o formato de impressão de `*somecounter*`, como o exemplo seguinte demonstra — selecione a ligação abaixo do código para o abrir no Overleaf:

```latex
\documentclass{article}
\begin{document}
\section{Um exemplo curto}
\newcounter{example}
\counterwithin{example}{section}
\newcounter{exampletwo}
\counterwithin*{exampletwo}{section}
\setcounter{example}{100}
\setcounter{exampletwo}{100}
\begin{itemize}
\item \verb|\theexample| compõe tipograficamente \theexample
\item \verb|\theexampletwo| compõe tipograficamente \theexampletwo
\end{itemize}
\end{document}
```

[Abra este `\counterwithin` exemplo no Overleaf](https://www.overleaf.com/docs?engine=\&snip_name=Example+of+starred+version+of+counterwithin\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BA+short+example%7D%0A%5Cnewcounter%7Bexample%7D%0A%5Ccounterwithin%7Bexample%7D%7Bsection%7D%0A%5Cnewcounter%7Bexampletwo%7D%0A%5Ccounterwithin%2A%7Bexampletwo%7D%7Bsection%7D%0A%5Csetcounter%7Bexample%7D%7B100%7D%0A%5Csetcounter%7Bexampletwo%7D%7B100%7D%0A%5Cbegin%7Bitemize%7D%0A%5Citem+%5Cverb%7C%5Ctheexample%7C+typesets+%5Ctheexample%0A%5Citem+%5Cverb%7C%5Ctheexampletwo%7C+typesets+%5Ctheexampletwo%0A%5Cend%7Bitemize%7D%0A%5Cend%7Bdocument%7D)

Este exemplo produz a seguinte saída:

![Utilizar o comando \counterwithin](/files/b465d3c512f8ce56c4038197be0119e56fa379ed)

Pode usar `\counterwithin` com os contadores padrão fornecidos pelo LaTeX, tais como:

* `contador section`: usado por `\section` comando
* `equation` usado pelo `equation` ambiente

ou com contadores que tenha criado.

**Exemplo de \counterwithin e \counterwithin\***

O código seguinte fornece um exemplo mais completo da utilização de `\counterwithin` e `\counterwithin*`; selecione a ligação abaixo do código para o abrir no Overleaf:

```latex
\documentclass{article}
\counterwithin{equation}{section}
\newcounter{example}
\counterwithin*{example}{section}
\newenvironment{example}[1][]{%
\stepcounter{example}%
\par\vspace{5pt}\noindent
\fbox{\textbf{Exemplo~\thesection.\theexample}}%
\hrulefill\par\vspace{10pt}\noindent\rmfamily}%
{\par\noindent\hrulefill\vrule width10pt height2pt depth2pt\par}
\begin{document}
\section{Primeira equação}
Algum texto introdutório...
\begin{example}
\begin{equation}
    f(x)=\frac{x}{1+x^2}
\end{equation}
\end{example}

\subsection{Mais detalhes}
\begin{example}
Aqui discutimos
\begin{equation}
    f(x)=\frac{x+1}{x-1}
\end{equation}
... mas não dizer nada
\end{example}

\subsubsection{Ainda mais detalhes}
\begin{example}
\begin{equation}
    f(x)=\frac{x^2}{1+x^3}
\end{equation}
\begin{equation}
    f(x+\delta x)=\frac{(x+\delta x)^2}{1+(x+\delta x)^3}
\end{equation}
\end{example}

\section{Terceira equação}
\begin{example}
A função seguinte...
\begin{equation}
    f_1(x)=\frac{x+1}{x-1}
\end{equation}
..é uma função
\begin{equation}
    f_2(x)=\frac{x^2}{1+x^3}
\end{equation}
\begin{equation}
    f_3(x)=\frac{3+ x^2}{1-x^3}
\end{equation}
\end{example}
\end{document}
```

[Abra este `\counterwithin` exemplo no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Example+of+using+counterwithin\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Ccounterwithin%7Bequation%7D%7Bsection%7D%0A%5Cnewcounter%7Bexample%7D%0A%5Ccounterwithin%2A%7Bexample%7D%7Bsection%7D%0A%5Cnewenvironment%7Bexample%7D%5B1%5D%5B%5D%7B%25%0A%5Cstepcounter%7Bexample%7D%25%0A%5Cpar%5Cvspace%7B5pt%7D%5Cnoindent%0A%5Cfbox%7B%5Ctextbf%7BExample%7E%5Cthesection.%5Ctheexample%7D%7D%25%0A%5Chrulefill%5Cpar%5Cvspace%7B10pt%7D%5Cnoindent%5Crmfamily%7D%25%0A%7B%5Cpar%5Cnoindent%5Chrulefill%5Cvrule+width10pt+height2pt+depth2pt%5Cpar%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BFirst+equation%7D%0ASome+introductory+text...%0A%5Cbegin%7Bexample%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%7D%7B1%2Bx%5E2%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%0A%5Csubsection%7BMore+detail%7D%0A%5Cbegin%7Bexample%7D%0AHere+we+discuss%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%2B1%7D%7Bx-1%7D%0A%5Cend%7Bequation%7D%0A...+but+don%27t+say+anything%0A%5Cend%7Bexample%7D%0A%0A%5Csubsubsection%7BEven+more+detail%7D%0A%5Cbegin%7Bexample%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%5E2%7D%7B1%2Bx%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%2B%5Cdelta+x%29%3D%5Cfrac%7B%28x%2B%5Cdelta+x%29%5E2%7D%7B1%2B%28x%2B%5Cdelta+x%29%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%0A%5Csection%7BThird+equation%7D%0A%5Cbegin%7Bexample%7D%0AThe+following+function...%0A%5Cbegin%7Bequation%7D%0A++++f_1%28x%29%3D%5Cfrac%7Bx%2B1%7D%7Bx-1%7D%0A%5Cend%7Bequation%7D%0A..is+a+function%0A%5Cbegin%7Bequation%7D%0A++++f_2%28x%29%3D%5Cfrac%7Bx%5E2%7D%7B1%2Bx%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cbegin%7Bequation%7D%0A++++f_3%28x%29%3D%5Cfrac%7B3%2B+x%5E2%7D%7B1-x%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%5Cend%7Bdocument%7D)

Este exemplo produz a seguinte saída:

![Utilizar o comando \counterwithin](/files/e5df685093d7d4c11886a0ca6cd936589e7778ff)

**Resumo do código**

* `\newcounter{example}`: Isto cria um novo contador para ser usado no nosso ambiente, também chamado `exemplo`
* `\counterwithin*{example}{section}`: Isto associa o nosso `exemplo` contador com o `contador section` contador usado no `\section` comando: cada vez que emitimos um `\section` comando o `exemplo` contador é reposto a zero. Note que usámos a versão com estrela `\counterwithin*` para evitar a redefinição de `\theexample`
* De seguida, criamos um novo ambiente também chamado `exemplo`. Dentro desse ambiente usamos `\stepcounter{example}` para incrementar o contador do ambiente. Note também que escrevemos `\textbf{Exemplo~\thesection.\theexample}` para apresentar **Exemplo** `<número da secção>.<número do exemplo>`

```latex
\newenvironment{example}[1][]{%
\stepcounter{example}%
\par\vspace{5pt}\noindent
\fbox{\textbf{Exemplo~\thesection.\theexample}}%
\hrulefill\par\vspace{10pt}\noindent\rmfamily}%
{\par\noindent\hrulefill\vrule width10pt height2pt depth2pt}
```

**\counterwithout{somecounter}{anothercounter}**

`\counterwithout{*somecounter*}{*anothercounter*}` remove a ligação entre `*somecounter*` e `*anothercounter*` para que sejam independentes. Para qualquer par de contadores, pode alternar entre usar `\counterwithout` e `\counterwithin`, como o exemplo seguinte mostra para os contadores `exemplo` e `contador section` — pode abrir este exemplo no Overleaf usando a ligação fornecida abaixo do código.

```latex
\section{Primeira equação}
\begin{example}
\begin{equation}
    f(x)=\frac{x}{1+x^2}
\end{equation}
\end{example}

\subsection{Segunda equação}
\begin{example}
\begin{equation}
    f(x)=\frac{x+1}{x-1}
\end{equation}
\end{example}
\vspace{6pt}\noindent Note como o contador \texttt{example} é reiniciado no início da Seção \ref{sec:n0}.
\section{Terceira equação}
\label{sec:n0}
\begin{example}
\begin{equation}
    f(x)=\frac{x+1}{x-1}
\end{equation}
\end{example}
\vspace{6pt}\noindent Aqui, escrevemos \verb|\counterwithout{example}{section}| para que \texttt{example} deixe de ser reiniciado no início de uma seção. Nas Seções \ref{sec:n1} e \ref{sec:n2} o contador \texttt{example} continua aumentando. \counterwithout{example}{section}
\section{Quarta equação}
\label{sec:n1}
\begin{example}
\begin{equation}
    f(x)=\frac{x^2+x^3}{1+x^3}
\end{equation}
\end{example}
\section{Quinta equação}
\label{sec:n2}
\begin{example}
\begin{equation}
    f(x,k)=\frac{x^2-x^k}{1+x^3}
\end{equation}
\end{example}
```

[Abra este `\counterwithout` exemplo no Overleaf](<https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Example+of+using+counterwithout\&snip=\documentclass{article}&#xA;\counterwithin{equation}{section}&#xA;\newcounter{example}&#xA;\counterwithin*{example}{section}&#xA;\newenvironment{example}\[1]\[]{%&#xA;\stepcounter{example}%&#xA;\par\vspace{3pt}\noindent&#xA;\fbox{\textbf{Example~\thesection.\theexample}}%&#xA;\hrulefill\par\vspace{3pt}\noindent\rmfamily}%&#xA;{\par\noindent\hrulefill\vrule+width10pt+height2pt+depth2pt\par}&#xA;\begin{document}&#xA;\section{First+equation}&#xA;\begin{example}&#xA;\begin{equation}&#xA;++++f(x)=\frac{x}{1+x^2}&#xA;\end{equation}&#xA;\end{example}&#xA;&#xA;\subsection{Second+equation}&#xA;\begin{example}&#xA;\begin{equation}&#xA;++++f(x)=\frac{x+1}{x-1}&#xA;\end{equation}&#xA;\end{example}&#xA;\vspace{6pt}\noindent+Note+how+the+\texttt{example}+counter+is+reset+at+the+start+Section+\ref{sec:n0}.+&#xA;\section{Third+equation}&#xA;\label{sec:n0}&#xA;\begin{example}&#xA;\begin{equation}&#xA;++++f(x)=\frac{x+1}{x-1}&#xA;\end{equation}&#xA;\end{example}&#xA;\vspace{6pt}\noindent+Here,+we+wrote+\verb|\counterwithout{example}{section}|+so+that+\texttt{example}+is+no+longer+reset+at+the+start+of+a+section.+In+Sections+\ref{sec:n1}+and+\ref{sec:n2}+the+\texttt{example}+counter+keeps+increasing.+\counterwithout{example}{section}&#xA;\section{Fourth+equation}&#xA;\label{sec:n1}&#xA;\begin{example}&#xA;\begin{equation}&#xA;++++f(x)=\frac{x^2+x^3}{1+x^3}&#xA;\end{equation}&#xA;\end{example}&#xA;\section{Fifth+equation}&#xA;\label{sec:n2}&#xA;\begin{example}&#xA;\begin{equation}&#xA;++++f(x,k)=\frac{x^2-x^k}{1+x^3}&#xA;\end{equation}&#xA;\end{example}&#xA;\end{document}>)

Este exemplo produz a seguinte saída:

![Usando o comando counterwithout](/files/ca2431c68f2e2a66a54362fd6b601e95cc98fe7b)

## Exemplo

### enumerate

O `enumerate` o ambiente de lista usa quatro *contador* variáveis que acompanham o valor atual do rótulo em cada nível:

|           |                                      |
| --------- | ------------------------------------ |
| **Nível** | **`enumerate`** variável de contador |
| Nível 1   | `enumi`                              |
| Nível 2   | `enumii`                             |
| Nível 3   | `enumiii`                            |
| Nível 4   | `enumiv`                             |

Estes contadores podem ser alterados usando o `\setcounter` comando. Veja o exemplo abaixo — que não é necessariamente a melhor solução (veja o [O Overleaf lista](/latex/overleaf-learn-latex-pt/nocoes-basicas-de-latex/04-lists.md) artigo para mais informações):

```latex
Este exemplo mostra uma forma de alterar a numeração de uma lista; aqui, alterando o valor do contador \texttt{enumi} para fazer com que a numeração da lista comece em 4 (ele é incrementado pelo comando \verb|\item|):

\begin{enumerate}
\setcounter{enumi}{3}
\item Algo.
\item Algo mais.
\item Outro elemento.
\item O último item na lista.
\end{enumerate}
```

[Abra este exemplo no Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Modifying+an+enumerate+counter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BIntroduction%7D%0AThis+example+shows+one+way+to+change+the+numbering+of+a+list%3B+here%2C+changing+the+value+of+the+%5Ctexttt%7Benumi%7D+counter+to+start+the+list+numbering+at+4+%28it+is+incremented+by+the+%5Cverb%7C%5Citem%7C+command%29%3A%0A%0A%5Cbegin%7Benumerate%7D%0A%5Csetcounter%7Benumi%7D%7B3%7D%0A%5Citem+Something.%0A%5Citem+Something+else.%0A%5Citem+Another+element.%0A%5Citem+The+last+item+in+the+list.%0A%5Cend%7Benumerate%7D%0A%5Cend%7Bdocument%7D)

Este exemplo produz a seguinte saída:

![Modificando um contador do enumerate](/files/dfa0c2e4e518a2312117200525d253c9e83ce88f)

## Contadores padrão no LaTeX

| Utilização                    | Nome                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Para a estrutura do documento | <p>- parte<br>- capítulo<br>- seção<br>- subseção<br>- subsubseção<br>- parágrafo<br>- subparágrafo<br>- página</p> |
| Para objetos flutuantes       | <p>- equação<br>- figura<br>- tabela</p>                                                                            |
| Para notas de rodapé          | <p>- nota de rodapé<br>- mpfootnote</p>                                                                             |
| Para o `enumerate` ambiente   | <p>- enumi<br>- enumii<br>- enumiii<br>- enumiv</p>                                                                 |

## Leitura adicional

Para mais informações, consulta:

* [Ambientes](/latex/overleaf-learn-latex-pt/comandos/02-environments.md)
* [Comandos](/latex/overleaf-learn-latex-pt/comandos/01-commands.md)
* [Listas](/latex/overleaf-learn-latex-pt/nocoes-basicas-de-latex/04-lists.md)
* [Numeração de páginas](/latex/overleaf-learn-latex-pt/formatacao/03-page-numbering.md)
* [Secções e capítulos](/latex/overleaf-learn-latex-pt/estrutura-do-documento/01-sections-and-chapters.md)
* [Expressões matemáticas](/latex/overleaf-learn-latex-pt/matematica/01-mathematical-expressions.md)
* [Inserção de imagens](/latex/overleaf-learn-latex-pt/mais-topicos/27-inserting-images.md)
* [Tabelas](/latex/overleaf-learn-latex-pt/figuras-e-tabelas/01-tables.md)
* [Preparando exames em LaTeX](/latex/overleaf-learn-latex-pt/especifico-da-area/09-typesetting-exams-in-latex.md)
* [Escrever o seu próprio pacote](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/03-writing-your-own-package.md)
* [Escrevendo a sua própria classe](/latex/overleaf-learn-latex-pt/ficheiros-de-classe/04-writing-your-own-class.md)
* [A introdução não tão curta ao LaTeX2ε](http://www.ctan.org/tex-archive/info/lshort/)


---

# 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/formatacao/10-counters.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.