5.1 Construyendo el libro

Para conformar todos los archivos Rmd en un libro, puede llamar a la función render_book() en bookdown. A continuación se presentan los argumentos de render_book():

render_book(input, output_format = NULL, ...,
  clean = TRUE, envir = parent.frame(),
  clean_envir = !interactive(), output_dir = NULL,
  new_session = NA, preview = FALSE,
  encoding = "UTF-8")

El argumento más importante es output_format, que puede tomar una cadena de caracteres del formato de salida (por ejemplo,'bookdown::gitbook'). Puede dejar este argumento vacío, y el formato de salida por defecto será el primer formato de salida especificado en los metadatos YAML del primer archivo Rmd o un archivo YAML por separado _output.yml, como se mencionó en la sección 4.4. Si va a generar múltiples formatos de salida para un libro, se recomienda especificar todos los formatos en _output.yml.

Una vez que todos los formatos se especifican en el _output.yml, es fácil escribir un script en R o en Shell o Makefile para compilar el libro. A continuación se muestra un ejemplo sencillo del uso de un script de Shell para compilar un libro a HTML (con el estilo GitBook) y PDF:

#!/usr/bin/env Rscript

bookdown::render_book("index.Rmd", "bookdown::gitbook")
bookdown::render_book("index.Rmd", "bookdown::pdf_book")

El script de Shell no funciona en Windows (no es estrictamente cierto), pero espero que se entienda la idea.

El argumento ... se pasa a la función de formato de salida. Los argumentos clean y envir se pasan a rmarkdown::render(), para decidir si se deben limpiar los archivos intermedios, y especificar el entorno para evaluar el código en R, respectivamente.

El directorio de salida del libro se puede especificar a través del argumento output_dir. Por defecto, el libro se genera en el directorio _book. Esto también se puede ajustar por medio del campo output_dir en el archivo de configuración _bookdown.yml, de modo que no se tiene que especificar varias veces para la presentación de un libro a múltiples formatos de salida. El argumento new_session se explicó en la sección @ref(#new-session). Al configurar preview = TRUE, sólo los archivos Rmd especificados en el argumento input se compilan, lo que puede ser conveniente al previsualizar un determinado capítulo, ya que no se vuelve a compilar el libro entero, sino cuando se publica un libro, este argumento sin duda se debe establecer a `FALSE.

Al reproducir el libro en múltiples formatos en la misma sesión de R, hay que tener cuidado porque el siguiente formato podrá tener acceso a los objetos R creados a partir del formato anterior. Se recomienda reproducir el libro con un ambiente limpio para cada formato de salida. El argumento clean_envir se puede utilizar para limpiar todos los objetos en el entorno especificado por envir. De forma predeterminada, es TRUE para las sesiones de R no interactivos (por ejemplo, en modo batch). Note que incluso clean_envir = TRUE en realidad no garantiza que la sesión R esté limpia. Por ejemplo, los paquetes cargados cuando se reproduce el formato anterior permanecerán en la sesión para el siguiente formato de salida. Para asegurarse de que cada formato se reproduce en una sesión de R completamente limpia, debe iniciar una nueva sesión de R para generar cada formato, por ejemplo, utilizar la línea de comandos

Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')"
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')"

Una serie de archivos de salida se generarán mediante render_book(). A veces es posible que desee limpiar el directorio del libro y empezar todo de nuevo, por ejemplo, eliminar los archivos de caché que se generaron de forma automática desde knitr. La función clean_book() fue diseñada para este propósito. Por defecto, esta le indica qué archivos posiblemente son los de salida y que pueden borrarse. Si usted ha revisado esta lista de archivos, y está seguro de que ningún archivo se identificó erróneamente como archivo de salida (claramente no desea borrar un archivo de entrada que haya creado manualmente), puede eliminar todos ellos usando bookdown::clean_book(TRUE). Como la eliminación de archivos es una operación relativamente peligrosa, le recomendamos que conserve su libro a través de herramientas de control de versiones como GIT, o un servicio que soporte copias de seguridad y restauración, con el fin de no perder algunos archivos para siempre una vez los elimine por error.