Personalizando documentos

Lost in translation

Habitualmente tenemos mucha información que se ha construido con diferentes programas. Bajo determinadas circunstancias pandoc puede darnos una solución, en otras ocasiones debemos recurrir a herramientas específicas. Utilizaremos la terminal del sistema para realizarlas tareas de conversión de formatos. Debemos asegurarnos de estar en el directorio adecuado o indicar la ruta del fichero a cambiar.

Veamos distintos tipos de formatos y el procedimiento a seguir en cada caso. Utilizaremos como ejemplos los documentos incluidos en el fichero editColaConversion.zip

Fichero html

Este tipo de ficheros pueden llevarse a formato markdown, bien sea desde un servidor web o desde un fichero local. Usaremos el fichero ejemploHTML.html; descárgarlo en tu ordenador y guárdalo en el directorio del proyecto editColaConversion.

Abre la terminal del sistema y ejecuta este comando:

pandoc ejemploHTML.html -o ejemploHTML.md

Se muestra a continuación parte del contenido del fichero ejemploHTML.md resultante:

::: {.container-fluid .main-container}
::: {#header .fluid-row}
Analfabetismo científico--técnico {#analfabetismo-científicotécnico .title .toc-ignore}
=================================

#### **La Verdad* domingo 23 de julio de 1989* {#la-verdad-domingo-23-de-julio-de-1989 .date}
:::

::: {#introduccion .section .level1}
Introducción
============

Pese a que la ciencia y la técnica son el núcleo y motor de la cultura
moderna, la mayor parte de nosotros somos científica y técnicamente
analfabetos. Esto vale no sólo para los pueblos de culturas
tradicionales: también vale para naciones altamente industrializadas,
tales como los EEUU y la Gran Bretaña.
:::

::: {#antecedentes .section .level1}

Por defecto, la conversión de las cabeceras se hace siguiendo el estilo Setext:

A level-one header
==================

A level-two header
------------------

Sin embargo, puede que prefieras el estilo ATX:

## A level-two header

### A level-three header

Si es el caso, deberás añadir el parámetro --atx-headers tal y como se muestra a continuación:

pandoc --atx-headers ejemploHTML.html -o ejemploHTML.md

También podemos transformarlo al vuelo desde el servidor web:

pandoc http://ares.inf.um.es/00Rteam/pub/editCola/recursos/editColaConversion/ejemploHTML.html -o ejemploHTML.md

Fichero docx

A menudo nos encontraremos con documentos escritos en Word que necesitaremos convertir a formato markdown para poder trabajar con ellos desde el editor de texto de RStudio o para incluirlos como parte de nuestros documentos. Sin embargo, como veremos a continuación, el proceso de conversión con pandoc no siempre será capaz conservar todos los detalles del documento original. La calidad del resultado obtenido dependerá de la estructura y los elementos que contenga el fichero docx.

Tomemos como el ejemplo el fichero ejemploWord.docx. El parámetro --extract-media permite indicar dónde crear una carpeta media que contendrá los elementos multimedia incluidos en el fichero de Word. El punto . hace referencia al directorio de trabajo, pero siempre puedes señalar otra ruta:

pandoc --extract-media . ejemploWord.docx -o ejemploWord.md

En caso de que tu fichero ejemploWord.docx no contuviera algún elemento multimedia, como una imagen, bastaría con apuntar el fichero de entrada y el de salida:

pandoc ejemploWord.docx -o ejemploWord.md

Si ahora nos fijamos en el documento ejemploWord.md podremos notar que hemos perdido la información relativa al título y al autor del documento, que sí se encontraba en el fichero ejemploWord.docx:

R Markdown
----------

Este es un documento R Markdown. Markdown es un lenguaje de marcado
ligero para la creación de documentos HTML, PDF y MS Word. Para más
detalles sobre el uso de R Markdown consulta
<http://rmarkdown.rstudio.com>.

Al hacer clic en el botón **Knit** se generará un documento que incluye
tanto el contenido como la salida de cualquier bloque de código R
incrustado dentro del documento. Puedes incrustar un trozo de código R
como este:

    summary(cars)
    ##      speed           dist       
    ##  Min.   : 4.0   Min.   :  2.00  
    ##  1st Qu.:12.0   1st Qu.: 26.00  
    ##  Median :15.0   Median : 36.00  
    ##  Mean   :15.4   Mean   : 42.98  
    ##  3rd Qu.:19.0   3rd Qu.: 56.00  
    ##  Max.   :25.0   Max.   :120.00

Fichero pdf

Debemos considerar que los documentos de tipo pdf son una especie de “contenedor gráfico” capaz de incluir una enorme variedad de elementos; motivo que limita severamente las posibilidades de conversión a otros formatos.

Una opción consiste en convertir el pdf a texto plano con el programa pdftotext. Veamos un ejemplo con el fichero ejemploPDF.pdf:

pdftotext ejemploPDF.pdf ejemploPDF.txt

Si además queremos que el programa intente respetar, dentro de lo posible, la disposición del texto original, debemos añadir el parámetro -layout:

pdftotext -layout ejemploPDF.pdf ejemploPDFlyt.txt

Ejecuta ambas líneas de código y observa las diferencias entre los ficheros ejemeploPDF.txt y ejemploPDFlyt.txt.

En alguna ocasión nos podrá interesar abrir estos documentos como un fichero de imagen con el fin de realizar alguna tarea de edición. Si además, quieres usar software ibre, puedes recurrir a LibreOffice o Inkscape, entre otras alternativas posibles.

Conectando elementos en el documento

La inclusión de referencias cruzadas es de fundamental importancia cuando se está redactando un documento científico-técnico. Para ello contamos con un procedimiento relativamente sencillo: el uso de etiquetas o labels. Estas etiquetas pueden emplearse para referenciar diferentes elementos dentro del documento: secciones, tablas, figuras, ecuaciones, referencias bibliográficas, etc. Analizaremos este procedimiento de trabajo utilizando los documentos de tipo bookdown, disponibles tras la instalación del paquete de R con el mismo nombre.

Manos a la obra

Referencias cruzadas (acceso) Las referencias a distintos elementos del documento es una constante en la elaboración de memorias e informes científico–técnicos. Detallaremos los métodos más relevantes que tenemos a nuestra disposición.
Referencias bibliográficas (acceso) Revisaremos algunos conceptos básicos relacionados con las referencias bibliográficas e incidiremos, con mayor profundidad, sobre temas relacionados con buenas prácticas y gestión de bases de datos.

Resumen

En los módulos anteriores ya vimos cómo escribir textos, elaborar documentos de calidad y manejar muchos de los elementos que forman parte de los mismos: tablas, imágenes, figuras, fórmulas matemáticas, etc. Al término de esto módulo, serás capaz referenciar todos esos elementos, dando coherencia interna a tu documento. También serás capaz de incorporar información de otras fuentes a través de diferentes métodos.

Referencias

Pandoc es el motor último que transforma los ficheros .md o .Rmd en los formatos que nosotros elijamos. Si quieres avanzar más puedes:
- Acceder al portal web de Pandoc.
- Consultar la guia de usuario de Pandoc, también disponible en versión pdf.
Documentación sobre el manejo de referencias bibliográficas con \(\LaTeX\) en Wikibooks.