Capítulo 1 Introducción

El paquete bookdown (Xie 2018a) de R (R Core Team 2018) permite escribir libros empleando R Markdown de forma fácil. Sin preocuparse mucho por los detalles de composición se pueden crear libros en distintos formatos (HTML / LaTeX / PDF / EPUB / …). Además de permitir emplear las extensiones Markdown de Pandoc (notas al pie de página, tablas, citas, ecuaciones LaTeX, …), se pueden emplear extensiones Markdown para libros (leyendas de figuras y tablas, numeración y referencias cruzadas de figuras / tablas / secciones / ecuaciones / teoremas / ejemplos / …, widgets HTML, …).

Este libro es una pequeña guía para la escritura de libros con este paquete (incluyendo algunos detalles para la escritura en otros idiomas distintos del inglés), pero se supone que el lector ya tiene conocimientos de RMarkdown. En el Apéndice A se incluye algo de información sobre este lenguaje, pero la recomendación sería buscar fuentes adicionales de información si no se conoce, empezando por la web http://rmarkdown.rstudio.com/ y las fuentes descritas en dicho apéndice. También recomendamos consultar fuentes externas para obtener documentación detallada sobre los distintos temas, como por ejemplo los libros (disponibles de forma gratuita en línea):

Ejemplos de este tipo de libros1 se tienen en https://bookdown.org (el listado completo está disponible aquí). Además de este, otros libros en castellano que se puede utilizar como ejemplo son:

Si ya se dispone de contenido en otros formatos sobre el tema del libro, el primer paso sería su conversión a formato RMarkdown. Para ello se puede emplear Pandoc (ver Apéndice B), siguiendo los pasos descritos en la Sección B.2.

1.1 Requisitos

  1. Disponer de una versión reciente de RStudio. Descargar la última versión si la versión actual es anterior a la 1.0.0.

  2. Instalar el paquete bookdown de R:

    # stable version on CRAN
install.packages('bookdown')
# or development version on GitHub
# devtools::install_github('rstudio/bookdown')

  3. Para compilar los libros en pdf bookdown emplea XeLaTeX. En windows es recomendable instalar MiKTeX, o actualizarlo (ejecutando MiKTeX Update) si ya está instalado. En Mac OS X se puede instalar MacTeX y en Linux TeXLive2.

1.2 Primeros pasos

Si se emplea RStudio (recomendado), lo más cómodo sería crear un proyecto nuevo mediante el menú File > New Project > New Directory > Book project using bookdown. Alternativamente se podría usar como plantilla algún libro publicado (este se puede descargar aquí). Por ejemplo, el proyecto que crea por defecto RStudio está disponible en el repositorio de GitHub rstudio/bookdown-demo y se puede descargar como fichero Zip. Posteriormente se pueden ir modificando (añadiendo o eliminando) los ficheros .Rmd correspondientes a los distintos capítulos.

Si se abre el proyecto en RStudio, se puede compilar empleando el boton Build Book3 en la pestaña Build. Por defecto se generará el libro (en los distintos formatos) en la carpeta _book y al terminar se abrirá automáticamente la versión HTML. El libro se generará (de forma simultánea en los formatos deseados) a partir de una serie de documentos R Markdown, cada uno correspondiente a un capítulo.

Nota: Si se produce un error, puede ser necesario4 eliminar manualmente los ficheros de salida (e.g.
book_filename.Rmd o book_filename.md) para poder volver a compilar.

1.3 Estructura del libro

La estructura del libro se corresponde con un conjunto de directorios y ficheros, los principales serían:

  • Un fichero inicial de RMarkdown index.Rmd con diferentes configuraciones generales (título, autor, fecha, …) y donde se puede incluir un prólogo/preámbulo/prefacio.

  • Un fichero de RMarkdown .Rmd para cada capítulo, definido por el título de primer nivel #. Los capítulos se ordenarán siguiendo el orden alfabético de los nombres de los ficheros5.

  • Archivo _bookdown.yml de configuración donde se espefican parámetros opcionales para la compilación del libro.

  • Archivo _output.yml de configuración con las opciones del formato de salida.

  • Archivos style.css y preamble.tex con especificaciones de las opciones de estilo de los libros en formato HTML e LaTeX, respectivamente.

  • Archivo book.bib con las referencias biliográficas en formato BibTeX.

Se pueden incluir directorios adicionales, por ejemplo una carpeta images que contenga las imágenes estáticas y una carpeta de data con los archivos de datos a usar.

Bibliografía

Xie, Yihui. 2018a. Bookdown: Authoring Books and Technical Documents with R Markdown. https://CRAN.R-project.org/package=bookdown.

R Core Team. 2018. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.

Xie, Yihui, JJ Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. CRC Press. https://bookdown.org/yihui/rmarkdown/.

  1. Los libros de Hadley Advanced R y R packages serían ejemplos con una versión “preliminar” de este paquete.↩

  2. Aunque el autor del paquete bookdown recomienda instalar TinyTeX.↩

  3. Alternativamente se puede ejecutar la función render_book() en el directorio del proyecto.↩

  4. Esto debería hacerse automáticamente si se incluye la opción delete_merged_file: true en el fichero de configuración _bookdown.yml.↩

  5. Evitar espacios (y acentos) en los nombres de los ficheros de los capítulos.↩