Adiciona introdução sobre vinhetas.

cap06.Rmd

@@ -16,12 +16,69 @@ source("config.R")
 rty <- "md"
 ```
 
+A documentação de um pacote é indispensável para sua
+distribuição. Tecnicamente falando, não tem como fazer um pacote R sem
+documentação para os objetos exportados. Por mais breve que seja, a
+documentação precisa existir para o pacote ser contruído e, portanto, a
+documentação é uma exigência.
+
+Os usuários consultam a documentação quando sabem exatamente o que
+procurar. Exceto pela sessão *Exemplos*, a documentação não se destina a
+mostrar a conexão entre funções ou seu uso coordenado para solução de
+certos problemas. Isso porque as páginas de ajuda descrevem objetos
+individualmente ou em grupos pequenos fornecendo uma orientação
+específica e não uma visão geral e integrada.
+
+No primeiro contato com um pacote, por outro lado, o que o usuário
+deseja é de uma visão geral dele. Uma espécie de trailer ou enredo. A
+documentação é um documento teodioso de leer para alguém que quer uma
+visão geral, pois ela é como uma descrição de cada personagem e não da
+forma como eles se envolvem.
+
+A palavra *vignette* admite traduções como vinheta, esboço e epsódio. No
+contexto de um pacote R, uma vinheta é uma documentação auxiliar do
+pacote que descreve o uso coordenado das funções que contém (ou
+*datasets*) na solução de um problema ou sobre um tema. É usada para dar
+uma visão geral dos recusos do pacote
+
+As vinhetas não são exigidas nos pacotes, embora seja a melhor forma de
+apresentá-lo. Certamente pela mesma razão, não existe restrição de
+tamanho nem forma e fica como responsabilidade dos autores usar do bom
+senso ao escrever uma vinheta. O que é marcante, no entanto, é que as
+vinhetas fazem mistura de prosa e código. Antes da versão 3.0.0 do R, as
+vinhetas eram documentos Sweave e nas versões mais recentes, vinhetas
+não Sweave foram permitidas.
+
+REVIEW
+
+Diferente de um artigo que é muito formal e da documentação que é muito
+específica, as vinhetas são informais e gerais.
+
+As vinhetas podem ter gráficos e outputs de resultados R, além de
+tabelas e equações. As vinhetas em HTML podem ter vídeos, animações em
+gif, gráficos em javascript e opengl.
+
+Um pacote pode ter mais de uma vinheta.
+
+O usuários leem pouco a documentação e movem-se para a sessão exemplos
+para ver como as funções funcionam.
+Usuários gostam de instruções práticas, discussão e interpração dos
+resultados.
+
 # Adicionando vinheta #
 
-<!---------------------------------------------------------------------- -->
-Brainstorm
+As vinhetas ficam no `inst/doc/` quando o pacote é instalado. Os fontes
+ficam em `vignettes/`
+
+`R CMD check` ou `devtools::check()` avalia as vinhetas, extrai o código
+e avalia sua execussão sequêncial, chunk por chunk.
+
+`R CMD build` vai criar o PDF ou HTML da vinheta e colocar no
+`inst/doc/`, para isso vai rodar a engine declarada (knitr ou Sweave,
+rmarkdown, enfim).
 
-Vignette - vinheta - esboço - episódio.
+A partir da versão 3.0.0, o R admite vignettes engines diferentes do
+Sweave. No caso, permite usar o **knitr** para gerar PDF e HTML.
 
   * <http://r-pkgs.had.co.nz/vignettes.html>
   * <http://kbroman.org/pkg_primer/pages/vignettes.html>
@@ -63,15 +120,26 @@ 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.
+## Exibe todas as vinhetas disponíveis no console.
 vignette()
 
-## Acessa uma vinheta.
-vignette("lala")
+## Abre uma vinheta pelo nome (essa é do pacote roxygen2).
+vignette("rd")
+vignette("rd", package = "roxygen2")
 
-sistem.file("lala", package="lulu")
+## Exibe todas as vinhetas disponíveis no navegador.
+browseVignettes()
 
-browseVignettes("YourPackage")
+## Exibe as vinhetas de um pacote.
+browseVignettes(package = "roxygen2")
+```
+
+```
+## Meta dados de uma vinheta.
+% \VignetteIndexEntry{}      ## Título no index.html
+% \VignetteDepends{}         ## Pacotes do qual depende
+% \VignetteKeyword{palavra1} ## Palavras-chave.
+% \VignetteKeyword{palavra2}
 ```
 
 <!---------------------------------------------------------------------- -->