Bookdown é um pacote R que facilita a produção de livros e documentos longos com R Markdown

Este é o nosso sétimo artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples e muito útil para produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

Ao longo dos artigos anteriores já tratamos sobre linguagens de marcação da sintaxe básica Markdown; apresentamos o Pandoc, um conversor universal de documentos que possui uma sintaxe Markdown estendida; apresentamos o Limarka, uma ferramenta que ajuda a produzir documentos acadêmicos conforme as normas da ABNT utilizando Markdown; tratamos do R Markdown, que permite produzir documentos dinâmicos a partir da mistura de código de linguagens de programação com texto em Markdown; e apresentamos o R Notebook, que é um modo especial de execução de documentos R Markdown para Literate Programming.

No texto anterior iniciamos um artigo em duas partes sobre o Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown.

O texto anterior se concentrou em apresentar o Bookdown, as dependências necessárias, suas principais características e a estrutura do documento.

Neste artigo, que é uma continuação do anterior, abordamos os elementos da sintaxe estendida, as principais características dos diferentes formatos de saída, os mecanismo de edição e produção e as formas de publicação.

Documentação com Markdown: Livros e documentos longos com Bookdown 2/2

Sumário do artigo

Introdução

Este texto é uma continuação do artigo anterior, no qual apresentamos o Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown.

Apresentamos o Bookdown, suas vantagens e principais características, e as dependências e instalações necessárias.

Tratamos do funcionamento do Bookdown dentro do ambiente R e R Markdown, no software RStudio, descrevemos o processo de criação de um projeto Bookdown e apresentamos sua estrutura.

Nesta segunda parte continuaremos a partir deste ponto, e abordamos os elementos da sintaxe Markdown estendida, as principais características dos diferentes formatos de saída, os mecanismos de edição e produção, e as formas de publicação.

O pacote Bookdown foi criado por Yihui Xie, que também criou os pacotes knitr, rmarkdown, pagedown xaringan, e é coautor dos livros “R Markdown: The definitive guide” e “R Markdown Cookbook”, dentre outros.

Sintaxe Markdown estendida

O Bookdown é um pacote R par escrita de livros e documentos longos com R Markdown. Apresentamos o R Markdown no quarto e no quinto artigos desta série sobre documentação com Markdown.

Conforme vimos, o R Markdown utiliza a sintaxe Markdown com os elementos da sintaxe estendida Pandoc’s Markdown, que apresentamos detalhadamente no primeiro e no segundo artigos desta série, que como já dissemos, é importante que sejam lidos antes.

Embora a sintaxe estendida Pandoc’s Markdown já acrescente muitos elementos e funcionalidades em relação à sintaxe Markdown original, ela ainda carece de uma série de coisas que podem ser úteis para a escrita acadêmica, como por exemplo a possibilidade de numerar e fazer referência a equações matemáticas.

O Bookdown fornece algumas extensões adicionais à sintaxe Markdown, no sentido de preencher algumas lacunas.

Numerar e referenciar expressões matemáticas

Conforme já vimos, a sintaxe em Pandoc’s Markdown para inserir uma equação ou expressão matemática LaTeX/TeX em bloco consiste em utilizar, em um parágrafo isolado, dois $$ (cifrões) como delimitadores. Pode-se utilizar esta forma com o Bookdown, mas as equações não serão numeradas.

Para numerar as equações é necessário colocá-las em “ambientes” de equação LaTeX e atribuir rótulos a elas.

A sintaxe - neste caso, em LaTeX - para colocar uma equação em um “ambiente” de equação (equation) consiste em adicionar \begin{equation} antes e \end{equation} após a equação ou expressão matemática, enquanto a sintaxe para atribuir um rótulo consiste em adicionar (\#eq:rotulo) dentro do ambiente, após a equação.

Para referenciar a equação no meio do texto basta utilizar a sintaxe \@ref(eq:rotulo). Conforme o seguinte exemplo:

Este é um parágrafo antes da equação.

\begin{equation}
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:rotulo1)
\end{equation}

Este é um parágrafo após a equação, que a referencia. Vejam a equação \@ref(eq:rotulo1).

Que produzirá um resultado semelhante a este:

Este é um parágrafo antes da equação.

\[\begin{equation} f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \label{eq:rotulo1} \end{equation}\]

Este é um parágrafo após a equação, que a referencia. Vejam a equação $\eqref{eq:rotulo1}$.

Os rótulos das equações devem começar com o prefixo eq: e devem conter apenas caracteres alfanuméricos, : (dois pontos), - (hífen) e/ou / (barra).

As referências para equações funcionam melhor para os formatos de saída LaTeX / PDF e não são bem suportadas nos formatos de saída Word ou e-book. Nos formatos de saída HTML, o Bookdown só irá numerar as equações que possuam rótulos.

Para que uma equação não seja numerada, basta não utilizar o “ambiente” de equação, envolvendo-a apenas com $$, conforme a sintaxe Pandoc’s Markdown, ou então utilizando o ambiente equation*, envolvendo-a com \begin{equation*} e \end{equation*}. Ainda seria possível adicionar \nonumber ou \notag às equações para que não sejam numeradas. As mesmas regras valem para outros “ambientes” matemáticos, como eqnarray, gather, align, etc.

No exemplo a seguir é utilizado o ambiente align que, por padrão, atribui um número a cada linha:

Este é um parágrafo antes da equação.

\begin{align} 
g(X_{n}) &= g(\theta)+g'({\tilde{\theta}})(X_{n}-\theta) \notag \\
\sqrt{n}[g(X_{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right) \sqrt{n}[X_{n}-\theta ] (\#eq:rotulo2)
\end{align} 

Este é um parágrafo após a equação, que a referencia. Vejam a equação \@ref(eq:rotulo2).

No sentido de manter apenas um número foi utilizado o argumento \notag na primeira linha, de modo que o resultado seria semelhante a este:

Este é um parágrafo antes da equação.

\[\begin{align} g(X_{n}) &= g(\theta)+g'({\tilde{\theta}})(X_{n}-\theta) \notag \\ \sqrt{n}[g(X_{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right) \sqrt{n}[X_{n}-\theta ] \label{eq:rotulo2} \end{align}\]

Este é um parágrafo após a equação, que a referencia. Vejam a equação $\eqref{eq:rotulo2}$.

Também é possível utilizar o ambiente split “dentro” do ambiente equation para que todas as linhas compartilhem o mesmo número, conforme o seguinte exemplo:

Este é um parágrafo antes da equação.

\begin{equation} 
\begin{split}
\mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\
 & =(X'X)^{-1}X'\mathrm{Var}(y)((X'X)^{-1}X')'\\
 & =(X'X)^{-1}X'\mathrm{Var}(y)X(X'X)^{-1}\\
 & =(X'X)^{-1}X'\sigma^{2}IX(X'X)^{-1}\\
 & =(X'X)^{-1}\sigma^{2}
\end{split}
(\#eq:rotulo3)
\end{equation}  

Este é um parágrafo após a equação, que a referencia. Vejam a equação \@ref(eq:rotulo3).

E o resultado seria semelhante a este:

Este é um parágrafo antes da equação.

\[\begin{equation} \begin{split} \mathrm{Var}(\hat{\beta}) & =\mathrm{Var}((X'X)^{-1}X'y)\\ & =(X'X)^{-1}X'\mathrm{Var}(y)((X'X)^{-1}X')'\\ & =(X'X)^{-1}X'\mathrm{Var}(y)X(X'X)^{-1}\\ & =(X'X)^{-1}X'\sigma^{2}IX(X'X)^{-1}\\ & =(X'X)^{-1}\sigma^{2} \end{split} \label{eq:rotulo3} \end{equation}\]

Este é um parágrafo após a equação, que a referencia. Vejam a equação $\eqref{eq:rotulo3}$.

Teoremas e provas

Teoremas e provas são normalmente utilizados ​​em artigos e livros de matemática.

No campo da matemática:

Uma prova é um argumento lógico de que uma afirmação é verdadeira;

Um teorema é uma afirmação provada verdadeira. Esta afirmação é especial;

Lemas são afirmações provadas que ajudam a provar afirmações mais importantes (teoremas);

Quando um teorema ou uma prova ajudam a concluir que outras afirmações são verdadeiras, estas últimas são chamadas de corolários do teorema.

Do ponto de vista do Bookdown, um “teorema” é apenas uma espécie de “ambiente” numerado e rotulado, não precisa ser necessariamente um teorema matemático. Enquanto uma “prova” é igualmente uma espécie de “ambiente”, mas sem numeração.

A sintaxe para adicionar um teorema é baseada nos “fenced Div blocks” do Pandoc, que consiste em cercar um bloco de conteúdo por conjuntos pelo menos pelos três :::, com atributos relativos a este bloco sendo adicionados após o primeiro conjunto de :::, entre chaves {}. Para adicionar um teorema deve-se “abrir o bloco” com ::: {.theorem}, conforme o seguinte exemplo:

::: {.theorem}
Este é um ambiente de `teorema` que pode conter **qualquer** Sintaxe _Markdown_.
:::

Existem outros tipos de “ambientes” de teorema, além do theorem propriamente dito, conforme Tabela 1.

Ambiente Nome impresso Prefixo
theorem Theorem thm
lemma Lemma lem
corollary Corollary cor
proposition Proposition prp
conjecture Conjecture cnj
definition Definition def
example Example exm
exercise Exercise exr
hypothesis Hypothesis hyp

Ambientes de teorema do Bookdown

Para escrever outros ambientes de teorema, basta substituir o ::: {.theorem} por outros nomes de ambiente conforme Tabela 1, como ::: {.lemma}, ::: {.corollary} e assim por diante.

Também pode ser dado um nome ao teorema, adicionado o atributo name="nome do teorema" dentro das chaves {} que abrem o bloco.

Para que o teorema para ser referenciado ele deve receber um rótulo. Para adicionar um rótulo deve-se adicionar um ID (identificador) dentro das chaves {} que abrem o bloco, utilizando a sintaxe #rotulo. Para referenciar o teorema no texto deve-se utilizar a sintaxe \@ref(prefixo:rotulo), utilizando os prefixos listados na Tabela 1.

Conforme o seguinte exemplo:

::: {.theorem #pitagoras name="teorema de Pitágoras"}
Para um triângulo retângulo, se $c$ denota o comprimento da hipotenusa e $a$ e $b$ denotam os comprimentos dos outros dois lados, temos

$$a^2 + b^2 = c^2$$
:::

Este é um parágrafo que referencia o teorema \@ref(thm:pitagoras).

Que produzirá um resultado semelhante a este:

Theorem 2.1 (teorema de Pitágoras) Para um triângulo retângulo, se $c$ denota o comprimento da hipotenusa e $a$ e $b$ denotam os comprimentos dos outros dois lados, temos

\[a^2 + b^2 = c^2\]

Este é um parágrafo que referencia o teorema (2.1).

A palavra “Theorem”, em inglês, é adicionada automaticamente antes do número e do nome (se houver) do teorema pelo Bookdown, é possível modificar isso e traduzir “Theorem” para “Teorema” (assim como com todos os outros tipos de ambiente de teoremas e de provas, ou legendas de figuras e tabelas, dentre outras coisas), através do parâmetro language no arquivo de configuração _bookdown.yaml, como veremos adiante.

Os teoremas são numerados por capítulos, por padrão. Se não houver capítulos eles serão numerados por seções. Se todo o documento não for numerado (number_sections = FALSE estiver definido no parâmetro output do cabeçalho YAML ou no arquivo _output.yaml), todos os teoremas serão numerados sequencialmente.

Os ambientes de “prova” possuem sintaxe semelhante aos ambientes de teorema, também podem ser nomeados usando o atributo name, com a única diferente de que, como não são numerados, não é possível fazer referência a eles, mesmo se for fornecido um ID.

Os tipos de ambientes de prova atualmente suportados são proof (prova), remark (observação) e solution (solução).

Títulos especiais

Existem dois tipos especiais de títulos de primeiro nível que serão processados ​​de forma diferente no bookdown: Partes e Apêndices.

Parte é um título não numerado que começa com o token (PART). Esses tipos de cabeçalhos são traduzidos em títulos de partes. Seo livro ou documento longo produzido possuir um grande número de capítulos, é possível organizá-los em partes, por exemplo:

# (PART) Parte I {-} 

# Capítulo 1

# Capítulo 2

# (PART) Parte II {-} 

# Capítulo 3

O título da parte deve ser escrito antes do título do primeiro capítulo desta parte, ambos os títulos no mesmo documento .Rmd. Você pode usar (PART\*) em vez de (PART) para que um título de parte não seja numerado.

Apêndice é um título não numerado que começa com (APPENDIX), indicando que todos os capítulos após este cabeçalho são apêndices, por exemplo:

# Capítulo 1

# Capítulo 2

# (APPENDIX) Apêndice {-} 

# Apêndice A

# Apêndice B

O estilo de numeração dos apêndices será alterado automaticamente para os formatos de saída LaTeX / PDF e HTML (geralmente na forma A, A.1, A.2, B, B.1, etc). Este recurso não está disponível para e-book ou formato de saída Word.

Referências de texto

É possível atribuir um texto a um rótulo e fazer referência a este texto utilizando o rótulo em outro local do documento.

A sintaxe para uma referência de texto é (ref:rotulo) texto, onde rotulo é um rótulo exclusivo em todo o documento para o texto texto.

A referência de texto deve estar em um parágrafo separado, com linhas vazias antes e depois. O parágrafo não deve ser dividido em várias linhas e não deve terminar com um espaço em branco. Conforme o seguinte exemplo:

Este é um parágrafo normal

(ref:rotulo) Este é um texto que pode ser referenciado, e pode usar *sintaxe* **Markdown**.

Este é outro parágrafo normal

Para inserir o texto da referência para inserir (ref:rotulo) onde for necessário. As referências de texto podem ser usadas em qualquer parte do documento. Podem ser úteis quando for necessário reutilizar um fragmento de texto em vários lugares.

Uma referência de texto pode ser usada não apenas em parágrafos, pode ser utilizada na legenda de uma figura, por exemplo:

Este é um parágrafo normal

(ref:grafico1) Um gráfico de dispersão da base de dados `carros` usando gráficos R **base**.

```{r grafico1, fig.cap='(ref:grafico1)'}
plot(cars)
```

Numerar e referenciar figuras

Por padrão, as figuras não têm legendas na saída gerada pelo knitr, no R Markdown, o que significa que serão inseridas onde quer que tenham sido geradas no código R.

Se for atribuída uma legenda de figura a um chunk de código por meio da opção de chunk fig.cap, os gráficos R ou figuras produzidas pelo chunk serão colocados em “ambientes” de figura, que serão automaticamente rotulados e numerados, e também podem ser referenciados.

O rótulo de um ambiente de figura é gerado a partir do rótulo do chunk, por exemplo, se o rótulo do chunk for rotulo1, o rótulo da figura será fig:rotulo1 (o prefixo fig: é adicionado antes do rótulo). Para fazer referência a uma figura, basta utilizar a sintaxe \@ref(rotulo), onde rotulo é o rótulo da figura, no exemplo fig:rotulo1 a forma de referenciá-la seria \@ref(fig:rotulo1).

Para fazer referência cruzada a figuras geradas a partir de um chunk, o rótulo do chunk deve conter apenas caracteres alfanuméricos (a-z, A-Z, 0-9), barras / ou traços -.

Numerar e referenciar tabelas

A forma mais comum de gerar uma tabela a partir de um chunk é com a função knitr::kable().

Assim como as figuras, as tabelas com legendas também são numeradas e podem ser referenciadas. A função kable() irá gerar automaticamente um rótulo para um “ambiente” de tabela, que consiste no prefixo tab: mais o rótulo do chunk, por exemplo, o rótulo da tabela para um chunk com o rótulo rotulo2 será tab:rotulo2.

ara fazer referência a uma tabela, basta utilizar a sintaxe \@ref(rotulo), onde rotulo é o rótulo da tabela, no exemplo tab:rotulo2 a forma de referenciá-la seria \@ref(tab:rotulo2).

Para fazer referência cruzada a tabelas geradas a partir de um chunk, o rótulo do chunk deve conter apenas caracteres alfanuméricos (a-z, A-Z, 0-9), barras / ou traços -.

Para poder fazer referência cruzada a uma tabela Markdown, ela deve ter uma legenda “rotulada” na forma Table: (\#rotulo) Legenda da tabela, onde rotulo deve ter o prefixo tab: antes do rótulo em si.

Referências cruzadas

Além de expressões matemáticas, teoremas, figuras e tabelas, também é possível fazer referência a seções usando a mesma sintaxe \@ref(rotulo), em que rotulo é o ID (identificador) da seção.

Por padrão, o Pandoc irá gerar um ID para todos os títulos de seção, por exemplo, uma seção # Inteligência Urbana receberá um ID inteligencia-urbana.

É recomendável atribuir manualmente um ID a um título de seção no sentido certificar-se de não se esquecer de atualizar o rótulo de referência após eventualmente alterar o título da seção.

Para atribuir um ID a um título de seção, basta adicionar {#id} ao final do título da seção. Outros atributos de títulos de seção podem ser definidos usando a sintaxe Pandoc’s Markdown.

Formatos de saída

O pacote bookdown oferece suporte principalmente a três tipos de formatos de saída: HTML, LaTeX / PDF e e-book.

Os formatos de saída podem ser especificados no cabeçalho de metadados YAML do primeiro arquivo .Rmd do livro ou no denominado _output.yml.

Conclusão

Neste artigo apresentamos o Bookdown, que é um pacote R de código aberto que facilita a escrita de livros e documentos longos com o R Markdown. Esta foi a segunda parte de um artigo de duas partes, e abordamos os elementos da sintaxe estendida, as principais características dos diferentes formatos de saída, os mecanismo de edição e produção e as formas de publicação.

Além do blog, a plataforma Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências

Categorias: