Relación entre R Markdown, Knitr, Pandoc y Bookdown

90

¿Cuál es la relación entre la funcionalidad de R Markdown, Knitr, Pandoc y Bookdown?

Específicamente, ¿cuál es la 'división del trabajo' entre estos paquetes al convertir documentos de marcado con código R incorporado (por ejemplo, .Rnwo .Rmd) en resultados finales (por ejemplo, .pdfo .html)? Y si Knitr se utiliza para procesar RMarkdown, ¿qué hace el rmarkdownpaquete y en qué se diferencia del markdown package?

RobinL
fuente

Respuestas:

135

Pandoc

Pandoc es un conversor de documentos. Puede convertir desde varios formatos de marcado diferentes a muchos otros formatos, como .doc, .pdfetc.

Pandoc es una herramienta de línea de comandos sin GUI. Es una pieza de software independiente, separada de R. Sin embargo, viene incluido con R Studio porque rmarkdowndepende de él para la conversión de documentos.

Pandoc no solo convierte documentos, sino que también agrega funcionalidad además del lenguaje de rebajas base para permitirle admitir resultados más complejos.

R Markdown

R Markdown se basa en Markdown:

Markdown (lenguaje de marcado)

Markdown es un lenguaje de marcado ligero con sintaxis de formato de texto plano diseñado para que se pueda convertir a HTML y muchos otros formatos. Un archivo de rebajas es un archivo de texto sin formato al que normalmente se le da la extensión .md.

Como otros lenguajes de marcado como HTML y Latex, es completamente independiente de R.

No existe un estándar de Markdown claramente definido. Esto ha llevado a la fragmentación, ya que diferentes proveedores escriben sus propias variantes del lenguaje para corregir fallas o agregar características faltantes.

Markdown (paquete R)

markdownes un paquete de R que convierte .Rmdarchivos a HTML. Es el antecesor de rmarkdown, que ofrece mucha más funcionalidad. Ya no se recomienda su uso.

R Markdown (lenguaje de marcado)

R Markdown es una extensión de la sintaxis de Markdown. Los archivos de R Markdown son archivos de texto sin formato que normalmente tienen la extensión de archivo .Rmd. Están escritos usando una extensión de la sintaxis de rebajas que permite que el código R se incruste en ellos de una manera que luego se pueda ejecutar.

Debido a que se espera que sean procesados ​​por el rmarkdownpaquete, es posible utilizar la sintaxis de rebajas de Pandoc como parte de un archivo de rebajas de R. Esta es una extensión de la sintaxis de rebajas original que proporciona funcionalidad adicional como HTML / Latex sin formato y tablas.

R Markdown (paquete)

El paquete R rmarkdownes una biblioteca que procesa y convierte .Rmdarchivos en varios formatos diferentes.

La función principal es la rmarkdown::renderque se apoya en los hombros de pandoc . Esta función 'procesa el archivo de entrada al formato de salida especificado usando pandoc. Si la entrada requiere tejido, knitr::knitse llama antes de pandoc.

El objetivo del paquete RMarkdown es simplemente proporcionar valores predeterminados razonablemente buenos y una interfaz compatible con R para personalizar las opciones de Pandoc. .

Los metadatos YAML que se ven en la parte superior de los archivos RMarkdown son específicamente para pasar opciones rmarkdown::renderpara guiar el proceso de compilación.

Tenga en cuenta que RMarkdown solo se ocupa de la sintaxis de rebajas. Si desea convertir un archivo .Rhtmlo un .Rnwarchivo, debe utilizar las funciones de conveniencia integradas Knitr, como knitr::knit2htmlyknitr:knit2pdf

Knitr

Knitr toma un documento de texto sin formato con código incrustado, ejecuta el código y 'une' los resultados al documento.

Por ejemplo, convierte

La función principal es knitr::knity, de forma predeterminada, esto buscará en el documento de entrada e intentará adivinar de qué tipo es: Rnw, Rmd, etc.

Esta función principal realiza tres roles: - Un analizador de código fuente, que mira el documento de entrada y detecta qué partes son el código que el usuario desea evaluar. - Un evaluador de código, que evalúa este código - Un renderizador de salida, que escribe los resultados de la evaluación en el documento en un formato que es interpretable por el tipo de salida sin procesar. Por ejemplo, si el archivo de entrada es un .Rmd, el renderizado de salida marca la salida de la evaluación del código en .mdformato.

Conversión entre formatos de documentos

Knitr no convierte entre formatos de documentos, como convertir un .mden un .html. Sin embargo, proporciona algunas funciones de conveniencia para ayudarlo a usar otras bibliotecas para hacer esto. Si está utilizando el rmarkdownpaquete, debe ignorar esta funcionalidad porque ha sido reemplazada por rmarkdown::render.

Un ejemplo es el knitr:knit2pdfque: 'Teje el documento Rnw o Rrst de entrada y lo compilará en PDF usando texi2pdf o rst2pdf'.

Una fuente potencial de confusión es knitr::knit2html, que "es una función conveniente para unir la fuente de descuento de entrada y llamar markdown::markdownToHTMLpara convertir el resultado a HTML". Esta es ahora una funcionalidad heredada porque el markdownpaquete ha sido reemplazado por el rmarkdownpaquete. Vea esta nota .

Bookdown

El paquete bookdown está construido sobre R Markdown y hereda la simplicidad de la sintaxis de Markdown, así como la posibilidad de múltiples tipos de formatos de salida (PDF / HTML / Word /…).

Ofrece características como salida HTML de varias páginas, numeración y referencias cruzadas de figuras / tablas / secciones / ecuaciones, inserción de partes / apéndices e importó el estilo GitBook ( https://www.gitbook.com ) para crear un HTML elegante y atractivo. páginas del libro.

RobinL
fuente
2
Encontré esto muy confuso, así que he hecho todo lo posible aquí. Edite o agregue una respuesta diferente si tengo algo mal ...
RobinL
6
Un aspecto que encuentro confuso es la documentación de los parámetros que se pasan a cada paso de la cadena de herramientas. Casi no hay ayuda interactiva (como el autocompletado) y uno tiene que adivinar qué parámetros deben llamarse en los encabezados yaml, o mediante knitr_opts(siempre olvido cómo se llama), o mediante argumentos personalizados de pandoc, o mediante archivos yam adicionales, o un archivo personalizado plantilla pandoc ... A veces se siente un poco como una jungla, especialmente cuando agregas LaTeX a la cadena.
baptiste
3
@baptiste Estoy completamente de acuerdo. Y esta es exactamente la razón por la que prefiero los documentos RNW con LaTeX desnudo. Sin pandocpaso intermedio , menos magia, menos confusión. Solo la curva de aprendizaje de LaTeX, ciertamente empinada. En mi opinión, Rmarkdown es genial cuando estás satisfecho con las cosas simples predeterminadas. Pero tan pronto como tienes que modificarlo, la complejidad aumenta rápidamente.
CL.
3
Esta es la mejor explicación que he encontrado de todo esto. Es muy confuso para los principiantes o incluso para aquellos con años de experiencia en R y látex por separado como yo. Excelente post.
StatsStudent
2
@StatsStudent Creo que una versión anterior de la hoja de trucos de rstudio rmarkdown tenía un diagrama que fue bastante útil para comprender los diferentes pasos para crear resultados desde rmarkdown. ¿Quizás una respuesta aquí podría funcionar con un diagrama?
Mark Neal