Documentos dinâmicos

A ideia geral de um documento dinâmico é a de que ele pode ser gerado a partir de um código-fonte:

• Da mesma forma que um software possui seu código-fonte, um documento dinâmico é o código-fonte de um relatório.
• É uma combinação de código de computador e as correspondentes narrativas descrevendo o resultado que o código está gerando (números, tabelas, figuras, …).
• Quando compilamos o documento dinâmico, o código de computador é executado, e as saídas são apresentadas. Portanto obtemos um documento final que mistura código e texto.

Como gerenciamos apenas o código-fonte do documento, ficamos livres de etapas manuais como ter que refazer um gráfico ou uma tabela após qualquer alteração na análise.

Literate Programming

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to humans what we want the computer to do.

Donald Knuth

O ideia básica por trás de documentos dinâmicos decorre diretamente do conceito de literate programming (“programação letrada”), um paradigma concebido por Donald Knuth em 1984.

O objetivo da literate programming é criar um documento que “entrelaça” (mistura) texto e código. O texto é legível para humanos e o código é legível para máquinas. A análise é descrita em uma séria de texto e blocos de código (code chunks). Cada bloco de código irá executar uma etapa da análise, e estará diretamente associado ao texto explicativo acima ou abaixo do bloco.

O processo de literate programming ocorre em duas vias, chamadas de weaving e tangling. O importante é que, com um único código-fonte podemos:

• Produzir documentos para humanos (HTML, PDF, …) ⇒ weave
• Produzir “documentos” (scripts) para máquinas (código) ⇒ tangle

Para podermos usar um sistema como esse, é necessário então uma linguagem de documentação para humanos (e.g. \(\LaTeX\) ou Markdown), e uma linguagem de programação que será compilada com o documento (e.g. R ou Python).

Knuth criou inicialmente um sistema chamado WEB para fazer essa mistura dos seus textos em \(TeX\) com a linguagem Pascal. Atualmente muitos outros sistemas existem para misturar códigos com texto em várias linguagens de documentação e de programação.

Literate Programming no R

Com a ascensão do R no início dos anos 2000, Friedrich Leisch criou o Sweave em 2002

• S + weave
• Permite “entrelaçar” textos do \(\LaTeX\) com códigos do R
• Ainda é muito utilizado e já é distribuído como uma função do R dentro do pacote utils

No final de 2011, Yihui Xie criou o pacote knitr como uma extensão do Sweave, e com a proposta de ser mais flexível, fácil e preparado para a Web. Segundo o próprio autor, o knitr é resultado dessa equação:

knitr = Sweave + cacheSweave + pgfSweave + weaver +
    animation::saveLatex + R2HTML::RweaveHTML +
    highlight::HighlightWeaveLatex + 0.2 * brew +
    0.1 * SweaveListingUtils + more

Resumidamente, o knitr possui as seguintes vantagens sob o Sweave:

• knit + R
• Uma re-implementação mais moderna do Sweave
• Permite “entrelaçar” textos do \(\LaTeX\), HTML e Markdown com códigos do R
• Também permite misturar texto com códigos de outras linguagens: Python, awk, C++, shell.
• Adiciona muitas facilidades como
  • Cache
  • Decoração e formatação automática de códigos
  • Geração de gráficos mais direta

Podemos fazer uma comparação entre arquivos \(\LaTeX\) escritos em Sweave e knitr. Exemplos simples podem ser vistos nos arquivos Exemplo0-Sweave.Rnw escrito com Sweave e Exemplo0-knitr.Rnw escrito com a sintaxe do knitr. Para compilar estes documentos, usamos

Sweave("exemplos/Exemplo0-Sweave.Rnw")
library(knitr)
knit("exemplos/Exemplo0-knitr.Rnw", output = "exemplos/Exemplo0-knitr.tex")

Posteriormente, os arquivos .tex gerados podem ser compilados com qualquer distribuição \(\LaTeX\), (e.g TeXLive, MikTeX), por exemplo

pdflatex exemplos/Exemplo0-Sweave.Rnw
pdflatex exemplos/Exemplo0-knitr.Rnw

Os resultados podem ser vistos nos respectivos arquivos: Exemplo0-Sweave.pdf e Exemplo0-knitr.pdf