Adiciona rascunho com brainstorm de vinhetas.

cap06.Rmd

@@ -16,3 +16,175 @@ source("config.R")
 rty <- "md"
 ```
 
+# Adicionando vinheta #
+
+<!---------------------------------------------------------------------- -->
+Brainstorm
+
+Vignette - vinheta - esboço - episódio.
+
+  * <http://r-pkgs.had.co.nz/vignettes.html>
+  * <http://kbroman.org/pkg_primer/pages/vignettes.html>
+  * <http://yihui.name/en/2012/09/r-package-markdown-vignettes/>
+  * <https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-package-vignettes>
+  * <http://rmflight.github.io/posts/2014/07/vignetteAnalysis.html>
+  * <http://www.stats.uwo.ca/faculty/murdoch/ism2013/5Vignettes.pdf>
+  * <https://www.statistik.lmu.de/~leisch/Sweave/Sweave-Rnews-2003-2.pdf>
+  * <http://www.magesblog.com/2012/01/survey-writing-package-vignette.html>
+  * <https://tagteam.harvard.edu/hub_feeds/1981/feed_items/1395647>
+  * <https://stat545-ubc.github.io/packages00_index.html>
+  * <https://cran.r-project.org/web/packages/knitr/vignettes/knitr-markdown.html>
+
+O jeito antigo de fazer pacote:
+
+  * <http://biostat.mc.vanderbilt.edu/wiki/Main/HowToCreateAnRPackage>
+  * <http://leg.ufpr.br/~paulojus/embrapa/Rembrapa/Rembrapase37.html>
+
+O que são as vinhetas?
+
+  - Documentação extendida do pacote? De certa forma sim.
+  - Uma documentação menos pontual e mais geral? Sim.
+  - Substitui um artigo? Não, pois artigos não exibem código;
+  - É uma propaganda do pacote? Sem dúvida.
+  - A melhor forma de apresentar uma introdução geral do pacote.
+  - Pode dar detalhes técnicos que não caberiam na documentação.
+  - Pode demonstrar aspectos que não documentação não seria possível
+    porque lá só tem código de input.
+  - Uma vinheta é livre para ter figuras, links, gifs, tabelas, listas,
+    até app shiny e gráficos dinâmicos como o googleVis.
+
+Elas ficam no diretório `vignettes/`. São parte do sistema de
+ajuda/documentação do pacote.
+
+As entradas com % no YAML são ignoradas pelo LaTex e processadas pelo R
+para gerar links na home da documentação (suponho).
+
+A vantagem do HTML é que uma index pode dar acesso às várias vinhetas de
+um pacote. Torna fácil para o usuário iniciante.
+
+```{r, eval=FALSE}
+## Exibe as vinhetas disponíveis.
+vignette()
+
+## Acessa uma vinheta.
+vignette("lala")
+
+sistem.file("lala", package="lulu")
+
+browseVignettes("YourPackage")
+```
+
+<!---------------------------------------------------------------------- -->
+
+A coisa que mais fácil ajuda você a conhecer as funcionalidades de um
+pacote é sem dúvida a sua vinheta (*vignette*). Um pacote pode ter
+várias vinhetas, cada uma exibindo um tema diferente de funcionalidades.
+
+Produzir a vinheta de um pacote é tão fácil quanto as demais partes
+dele. Usaremos os recursos disponíveis no *devtools* mais uma vez.
+
+A vinheta será escrita em
+`r renderUrl("RmarkDown","http://rmarkdown.rstudio.com/",rty)`. Escrever
+vinhetas têm uma excelente
+`r renderUrl("documentação","http://r-pkgs.had.co.nz/vignettes.html",rty)`.
+
+A vantagem de escrever em MarkDown é a velocidade, praticidade e poder
+obter vinhetas em html e pdf facilmente.
+
+```{r, eval=FALSE, include=FALSE}
+## DESCRIPTION antes do use_vignette().
+cat(readLines("./meupacote/DESCRIPTION"), sep = "\n")
+```
+```{r, eval=FALSE}
+library(devtools)
+
+## Cria a primeira vinheta do pacote.
+use_vignette("minhaVinheta1")
+```
+```{r, echo=FALSE}
+if (file.exists("./meupacote/vignettes/minhaVinheta1.Rmd")){
+    file.remove("./meupacote/vignettes/minhaVinheta1.Rmd")
+}
+library(devtools)
+use_vignette("minhaVinheta1", pkg = "./meupacote/")
+```
+```{r, echo=FALSE}
+## DESCRIPTION depois do use_vignette().
+cat(readLines("./meupacote/DESCRIPTION"), sep = "\n")
+```
+
+O comando `use_vignette()` cria o diretório `vignettes/` com um arquivo
+`.Rmd` com o nome que você usou. Além disso ele adiciona ao campo
+`Suggests` no `DESCRIPTION` os pacotes `knitr` e `rmarkdown`,
+necessários para gerar a vinheta.
+
+```{r, echo=FALSE}
+## Mostra diretório e arquivos criados.
+cat(system("tree --charset=ascii ./meupacote/ | head -n -2",
+           intern = TRUE), sep = "\n")
+```
+
+Esse arquivo é criado já com conteúdo para poder orientá-lo. No topo do
+arquivo tem uma parte de meta dados escrita em YAML (*yet another markup
+language*) que detalha as informações do documento e definem o processo
+de sua criação.
+
+```{r, echo=FALSE}
+## Mostra o YAML da vinheta original.
+cat(readLines("./meupacote/vignettes/minhaVinheta1.Rmd")[1:10],
+    sep = "\n")
+
+## Nada entrou no .Rbuildignore.
+## cat(readLines("./meupacote/.Rbuildignore"),
+##     sep = "\n")
+```
+
+Edite à vontade esse arquivo fazendo a melhor propaganda possível do seu
+pacote. Tome cuidado com os pacotes que vai usar. É indicado que eles
+estejam nos campos do seu `DESCRIPTION`, senão no `Imports`, pelo menos
+no `Suggests`. Abaixo o arquivo que criamos, que está muito simples,
+logicamente, mas é apenas para marcar território mesmo.
+
+TODO trocar essa vinheta por uma da função `baskara()` com os métodos.
+
+```{r, include=FALSE}
+file.copy(from = "aux/minhaVinheta1.Rmd",
+          to = "meupacote/vignettes/minhaVinheta1.Rmd",
+          overwrite = TRUE)
+```
+```{r, echo=FALSE, comment=NA}
+## Mostra a vinheta mínima.
+cat(readLines("./meupacote/vignettes/minhaVinheta1.Rmd"),
+    sep = "\n")
+```
+
+Para produzir a vinheta, use o comando `build_vignettes()`. Ele vai
+gerar as vinhetas de cada arquivo e levá-las para outro diretório, como
+pode ser visto abaixo. Caso você não tenha um dos seguintes pacotes:
+`evaluate`, `formatR`, `highr`, `knitr`, `mime`, `stringi`; será
+necessário instalá-los.
+
+```{r, eval=FALSE}
+build_vignettes()
+```
+```{r, eval=FALSE, echo=FALSE, comment=NA, highlight=FALSE}
+## FIXME: Não existe como sair desse erro! De usar o output do
+## build_vignettes().
+x <- capture.output(build_vignettes("./meupacote/"))
+cat(x, sep = "\n")
+
+sink("aux.txt")
+build_vignettes("./meupacote/")
+sink()
+```
+```
+Building meupacote vignettes
+Moving minhaVinheta1.html, minhaVinheta1.R to inst/doc/
+Copying minhaVinheta1.Rmd to inst/doc/
+```
+
+TODO Incluir a vinheta do `pitagoras()` ou outra funcionalidade com
+output em PDF.
+
+Por fim, basta executar `check()` e `build()` mais uma vez para incluir
+as vinhetas no `.tar.gz` do seu pacote.