Tutorial sobre Pandoc y Markdown en documentos académicos

Objetivos

En este tutorial, primero aprenderá los conceptos básicos de Markdown, una sintaxis fácil de leer y escribir para el texto sin formato, así como Pandoc, una herramienta de línea de comandos que convierte texto sin formato en una serie de tipos de archivos formateados: Docx, HTML, LaTeX, diapositivas y más.

Con Pandoc como su herramienta de composición digital, puede utilizar la sintaxis de Markdown para agregar figuras, una bibliografía, el formato y cambiar fácilmente los estilos de citación de Chicago a MLA (por ejemplo), todo utilizando texto sin formato o también llamado texto plano.

El tutorial no asume ningún conocimiento técnico previo, pero se adapta a la experiencia,  aunque sugerimos técnicas más avanzadas hacia el final de cada sección. Éstos están claramente marcados y pueden ser revisados ​​después de alguna práctica y experimentación.

En lugar de seguir este tutorial de una manera mecánica, le recomiendo que se esfuerce por entender las soluciones ofrecidas aquí como una metodología, que puede adaptarse a su entorno y flujo de trabajo.

La instalación de las herramientas necesarias presenta quizá el mayor obstáculo para la participación. Consigue tiempo suficiente y paciencia para instalar todo correctamente, o hacerlo con un colega que tiene una configuración similar y puedan ayudarse mutuamente. Consulte la sección de Recursos Útiles,  a continuación, si se queda atascado.

Filosofía

Escribir, almacenar y recuperar documentos son actividades centrales para el flujo de trabajo de investigación en las ciencias sociales. Y sin embargo, muchos autores basan su práctica en herramientas y formatos propietarios que a veces no alcanzan incluso los requisitos más básicos de la escritura académica.

Tal vez usted puede sentirse frustrado por la fragilidad de las notas al pie, bibliografías, figuras y borradores de libros de autor en Microsoft Word o Google Docs.

Más que causar frustración personal, esta dependencia de herramientas y formatos propietarios tiene implicaciones negativas a largo plazo para la comunidad académica. En tal entorno, las revistas deben externalizar la tipografía, alejando a los autores de los contextos materiales de publicación y añadiendo más obstáculos innecesarios a la libre circulación del conocimiento.

Cuando utiliza MS Word, Google Docs o Open Office para escribir documentos, lo que ve no es lo que obtiene. Debajo de la capa visible de palabras, frases y párrafos se encuentra una complicada capa de código comprensible sólo para las máquinas. Debido a esa capa oculta, los archivos .docx y .pdf dependen de herramientas propietarias que renderizan (muestran) correctamente lo escrito. Tales documentos son difíciles de buscar, imprimir y convertir en otros formatos de archivo.

Además, el tiempo dedicado a formatear el documento en MS Word o en Open Office se pierde porque todo el formato se quita por el editor durante la publicación. Tanto los autores como los editores se beneficiarían del intercambio de archivos con un formato mínimo, dejando la tipografía en la fase final de composición del proceso de publicación.

Aquí es donde brilla Markdown.

Markdown es una sintaxis para marcar elementos semánticos dentro de un documento explícitamente, no en una capa oculta. La idea es identificar unidades que sean significativas para los seres humanos, como títulos, secciones, subsecciones, notas de pie de página e ilustraciones. Por lo menos, sus archivos siempre serán comprensibles para usted, incluso si el editor que está utilizando deja de funcionar o “sale del mercado”.

Escribir de esta manera libera al autor de la herramienta. Markdown se puede escribir en cualquier editor de texto sin formato y ofrece un rico ecosistema de software que puede hacer que el texto se presente en hermosos  documentos.

Por esta razón, Markdown está disfrutando actualmente de un período de crecimiento, no sólo como medio para escribir artículos académicos, sino como una convención para la edición en general.

Los editores populares de texto de propósito general son, entre muchos,  TextWrangler para Mac,  Sublime  Text, Notepad ++ para Windows, así como Gedit y Kate para Linux. Sin embargo, también hay editores especializados en mostrar y editar Markdown.

Es importante entender que Markdown es simplemente una convención. Los archivos de Markdown se almacenan como texto sin formato, añadiendo adicionalmente la flexibilidad del formato.

Los archivos de texto sin formato han estado en nuestro alrededor desde la máquina de escribir electrónica.

La longevidad de este estándar hace que texto llano más sostenible y estable que los formatos propietarios.

Si bien los archivos producidos hace diez años en Microsoft Word y las páginas de Apple pueden causar problemas significativos al abrirse con la última versión, todavía es posible abrir un archivo escrito en cualquier editores de texto sin formato “muertos” de las últimas décadas: AlphaPlus , Perfect Writer, Text Wizard, Spellbinder, WordStar, o SCRIPSIT; elfavorito de Isaac Asimov 2.0, hecho por Radio Shack.

Escribir en texto plano garantiza que sus archivos permanecerán legibles diez, quince, veinte años a partir de ahora. En este tutorial, describimos un flujo de trabajo que libera al escritor del software de procesamiento de texto propietario y de los formatos de archivo frágiles.

Ahora es posible escribir en una amplia gama de documentos en solo un formato –artículos, blogs, wikis, syllabi o cartas de recomendación– usando el mismo conjunto de herramientas y técnicas para buscar, descubrir, respaldar y distribuir nuestros materiales.

Sus notas, entradas de blog, documentación de código y wikis pueden ser escritos en Markdown.

Cada vez más, muchas plataformas como WordPress, Reddit y GitHub apoyan la autoría en Markdown de forma nativa. A largo plazo, su trabajo se beneficiará de estos flujos de trabajo unificados, lo que facilita guardar, buscar, compartir y organizar sus materiales.

Principios

Inspirados por las mejores prácticas en una variedad de disciplinas, esto son los principios guias:

  1. Sostenibilidad. El texto sencillo garantiza la transparencia y responde a las normas de conservación a largo plazo. MS Word puede seguir el camino de Word Perfect en el futuro, pero el texto sin formato siempre será fácil de leer, catalogar, anotar y transformar. Además, el texto sin formato permite un versionado fácil y potente del documento, que es útil en la colaboración y organización de borradores. Sus archivos de texto sin formato serán accesibles en teléfonos celulares, tabletas o, quizás, en un terminal de baja potencia en alguna biblioteca remota. El texto normal es compatible con versiones anteriores y es compatible con el futuro. Sea cual sea el software o hardware, del pasado o del futuro, este será capaz de entender sus archivos de texto sin formato.
  2. Preferencia por los formatos legibles por humanos. Al escribir en Word o Google Docs, lo que ves no es lo que obtienes. El archivo .doc contiene caracteres de formato ocultos generados automáticamente, creando una capa de composición ofuscada que es difícil para el usuario solucionar si hay problemas. Algo tan simple como pegar una imagen o un texto desde el navegador puede tener efectos impredecibles en el formato del documento.
  3. Separación de la forma y el contenido. Escribir y formatear al mismo tiempo es una distracción. La idea es escribir primero, y dar formato más tarde, lo más cerca posible de la hora de publicación. Una tarea como cambiar la forma de citación de Chicago a MLA debe ser indolora. Editores de periódicos que quieren ahorrar tiempo en el formato innecesario y la edición de la copia debe ser capaz de proporcionar a sus autores una plantilla de formato que se encarge de la tipografía.
  4. Apoyo al sector académico. El flujo de trabajo debe manejar las notas de pie de página, las figuras, los caracteres internacionales y las bibliografías con gracia e eficiencia.
  5. Independencia de la plataforma. A medida que los vectores de publicación se multiplican, necesitamos ser capaces de generar una multiplicidad de formatos incluyendo para proyección de diapositivas, la impresión, la web y el móvil. Idealmente, nos gustaría ser capaz de generar los formatos más comunes sin romper las dependencias bibliográficas. Nuestro flujo de trabajo tiene que ser portátil también -sería bueno poder copiar una carpeta a una unidad USB y saber que contiene todo lo necesario para la publicación. Escribir en texto sencillo significa que puede compartir, editar y archivar fácilmente sus documentos en prácticamente cualquier entorno. Por ejemplo, un documento escrito en Markdown puede ser guardado como un PDF, impreso como un folleto, y convertido en HTML para la web, todo desde el mismo archivo. Tanto los documentos impresos como los impresos deben publicarse desde la misma fuente y ser similares, preservando el diseño lógico del material.

Markdown y LaTeX responden a todos estos requisitos. He elegido Markdown (y no LaTeX) porque ofrece la sintaxis más ligera y libre de desorden  y porque cuando se combina con Pandoc permite la mayor flexibilidad en salidas  a otros tipo de documentos (incluidos los archivos .docx y .tex).

Requisitos de Software

Omitiré intencionalmente algunos de los detalles granulares, de plataforma o de sistema operativo relacionados con la instalación del software que se enumera a continuación. Por ejemplo, no tiene sentido proporcionar instrucciones de instalación para LaTeX, cuando las instrucciones canónicas en línea para su sistema operativo siempre se mantendrán más actualizadas y completas. Del mismo modo, la mecánica de la instalación de Pandoc se exploran mejor buscando “instalar Pandoc” en Google, con el primer resultado probable que es la página principal de Pandoc.

Editor de texto sin formato.

Entrar en el mundo de la edición de texto sin formato amplía su elección de herramientas de creación dramáticamente. Buscar en línea “editor de texto markdown” y experimentar con las opciones.

No importa lo que utilice, siempre y cuando sea explícitamente un editor de texto sin formato. Notepad ++ en Windows, TextWrangler en Mac, o GEdit en Linux son opciones fáciles y gratuitas. Recuerde, puesto que no estamos vinculados a la herramienta, puede cambiar editor en cualquier momento.

Terminal de la línea de comando.

Trabajar “en la línea de comandos” equivale a escribir comandos en el terminal. En una Mac sólo tiene que usar su buscador para “Terminal”. En Windows, utilice PowerShell. Es probable que los usuarios de Linux estén familiarizados con sus terminales.

Voy a cubrir los conceptos básicos de cómo encontrar y utilizar la línea de comandos a continuación.

Pandoc.

Las instrucciones de instalación detalladas y específicas de la plataforma están disponibles en el sitio web de Pandoc.

La instalación de Pandoc en su máquina es crucial para este tutorial, así que asegúrese de tomar su tiempo y sigo las instrucciones.

Pandoc fue creado y es mantenido por John MacFarlane, Profesor de Filosofía en la Universidad de California, Berkeley.

Esta es la informática de las humanidades en su mejor momento y servirá como el motor de nuestro flujo de trabajo.

Con Pandoc, podrá compilar el texto y la bibliografía en documentos formateados y flexibles. Una vez que haya seguido las instrucciones de instalación, compruebe que Pandoc está instalado ingresando pandoc –version en la línea de comandos. Suponemos que tiene al menos la versión 1.19.2, publicada en enero de 2017.

Se recomiendan las siguientes dos piezas de software, pero no es necesario para completar este tutorial.

  • Zotero o Endnote. El software de referencia bibliográfica como Zotero y Endnote son herramientas indispensables para organizar y dar formato a las citas en un documento de investigación. Estos programas pueden exportar sus bibliotecas como un archivo BibTeX . Este archivo, en sí mismo es un documento de texto plano con formato de todas sus citas, le permitirá rápidamente y fácilmente citar referencias usando @etiquetas. Cabe señalar que también es posible escribir todas las referencias bibliográficas a mano, utilizando una plantilla como bibliografía.
  • Látex.  Las instrucciones de instalación detalladas y específicas de la plataforma disponibles en el sitio web. Aunque LaTeX no está cubierto en este tutorial, es utilizado por Pandoc para la creación de PDF.  Los usuarios avanzados a menudo convertirán en LaTeX directamente para tener un control más granular sobre la composición del archivo PDF. Los principiantes pueden desear considerar saltar este paso. De lo contrario, escriba latex -v para ver si LaTeX se instaló correctamente (obtendrá un error si no lo fue y alguna información sobre la versión si lo fue).

Markdown Básico

Markdown es una convención para estructurar sus documentos de texto sin formato de forma semántica. La idea es identificar estructuras lógicas en el documento (un título, secciones, subsecciones, notas de pie de página, etc.), marcarlas con algunos caracteres discretos y luego “compilar” el texto resultante con un intérprete de composición que formateará el documento de forma coherente, según un estilo específico.

Las convenciones de Markdown vienen en varios “sabores” diseñados para su uso en contextos particulares, como blogs, wikis o repositorios de código. El sabor de Markdown usado por Pandoc está diseñado para uso académico. Sus convenciones se describen en la página de Markdown de Pandoc. Sus convenciones incluyen el bloque “YAML”, que contiene algunos metadatos útiles.

Ahora vamos a crear un documento simple en Markdown. Abra un editor de texto sin formato de su elección y empiece a escribir. Debe tener un aspecto como este:

El Markdown con sabor a Pandoc almacena cada uno de los valores anteriores y los “imprime” en la ubicación apropiada de su documento de salida una vez que esté preparado para componer.

Más tarde aprenderemos a agregar otros campos más potentes al bloque YAML. Por ahora, supongamos que estamos escribiendo un artículo que contiene tres secciones, cada una de las cuales se subdivide en dos subsecciones. Deje una línea en blanco después de los últimos tres guiones en el bloque YAML y pegue lo siguiente:

Adelante e ingrese un texto ficticio también. El espacio vacío es significativo en Markdown: no sangrar sus párrafos. En su lugar, separar los párrafos utilizando una línea en blanco. Las líneas en blanco también deben preceder a los encabezados de sección.

Puede utilizar asteriscos para añadir énfasis en negrita o en cursiva a sus palabras, como esto: *cursivas* y **negrita**. También debemos añadir un enlace y una nota de pie de página a nuestro texto para cubrir los componentes básicos de un documento promedio. Tipo:

Cuando el texto del enlace y la dirección son los mismos, es más rápido escribir <www.eff.org> en lugar de [www.eff.org] (www.eff.org).

Guardemos nuestro archivo antes de avanzar más.

Cree una nueva carpeta que alojará este proyecto. Es probable que tenga algún sistema de organización de sus documentos, proyectos, ilustraciones y bibliografías.

Pero a menudo, su documento, sus ilustraciones y bibliografía viven en diferentes carpetas, lo que los hace difíciles de rastrear.

El objetivo es crear una carpeta única para cada proyecto, incluyendo todos los materiales relevantes. La regla es general traida de viejos tiempo de un proyecto, un papel, una carpeta.

El nombre su archivo podría ser  algo como documento1.md, donde “md” significa markdown.

Una vez que su archivo se guarda, vamos a agregar una ilustración. Copie una imagen (cualquier imagen pequeña) en su carpeta, y añada lo siguiente en algún lugar del cuerpo del texto:

En este momento, su docuemto.md debe ser similar al siguiente. Puede descargar este archivo .md de muestra aquí.

As we shall do shortly, this plain text file can be rendered as a very nice PDF:

Como lo haremos en breve, este archivo de texto plano se puede representar como un muy buen PDF:

Pantalla del PDF realizada por Pandoc
Pantalla del PDF realizada por Pandoc

Si desea obtener una idea de cómo este tipo de marcado se interpretará como formato HTML, intente este sandbox en línea y juegue con varios tipos de sintaxis.

Recuerde que ciertos elementos de Markdown con sabor a Pandoc (como el bloque de título y las notas a pie de página) no funcionarán en este formulario web, que sólo acepta los conceptos básicos.

En este punto, deberías dedicar un tiempo a explorar algunas de las otras características de Markdown como las citas (referenciadas por> símbolo), las listas de viñetas que comienzan con * o, los saltos de línea verbatim que comienzan con | (útiles para la poesía), tablas y algunas de las otras funciones que aparecen en la página de marcado de Pandoc.

Preste especial atención al espacio vacío y al flujo de párrafos. La documentación lo pone sucintamente cuando define un párrafo como “una o más líneas de texto seguidas por una o más líneas en blanco”.

Observe que las “nuevas líneas son tratadas como espacios” y que “si necesita un salto de línea dura, ponga dos o más espacios al final de una línea “.

La mejor manera de entender lo que eso significa es experimentar libremente. Usa el modo de vista previa de tu editor o simplemente ejecute Pandoc para ver los resultados de sus experimentos.

Sobre todo, evite el deseo de formatear. Recuerde que está identificando unidades semánticas: secciones, subsecciones, énfasis, notas de pie de página y figuras. Incluso *cursivas*  y **negrita** en Markdown no son realmente marcas de formato, pero indican diferentes niveles de énfasis. El formateo ocurrirá más adelante, una vez que conozca el lugar y los requisitos de publicación.

Hay programas que le permiten ver una vista previa en vivo de la salida de Markdown a medida que edita su archivo de texto plano, que detallamos a continuación en la sección Recursos útiles.

Sin embargo, pocos de ellos apoyan notas de pie de página, citas y bibliografías. Para sacar el máximo provecho de Pandoc, le recomendamos que se pegue con archivos de texto simples y sencillos almacenados localmente en su computadora.

Ponerse en contacto con su terminal

Antes de comenzar a publicar nuestro archivo documento1.md en otros formatos, necesitamos orientarnos con el trabajo en la línea de comandos usando el programa terminal de su computadora, que es la única (y mejor) manera de usar Pandoc.

La línea de comandos es un lugar amistoso, una vez que te acostumbras. Si ya está familiarizado con el uso de la línea de comandos, no dude en saltarse esta sección. Para otros, es importante entender que ser capaz de usar su terminal directamente le permitirá usar una amplia gama de poderosas herramientas de investigación que no podría usar de otra manera, y puede servir como base para trabajos más avanzados.

Para los propósitos de este tutorial, necesita aprender sólo unos comandos muy simples.

En primer lugar, abra una ventana de línea de comandos. Si está utilizando una Mac, abra Terminal en el directorio ‘Aplicaciones/Utilidades’. En Windows, utilizará PowerShell. En Windows 7 o posterior, haga clic en Inicio, escriba “powershell” en “Buscar programas y archivos” y pulse enter. Para una introducción detallada al uso de la línea de comandos, vea el excelente Curso de Línea de Comando de Zed A. Shaw.

Una vez abierta la terminal, deberías ver una ventana de texto y un prompt que se parece a esto:

El tilde indica su directorio “home”, y de hecho puede escribir

en cualquier punto para regresar a su directorio de inicio o “home”. No escriba el signo de dólar, simplemente simboliza el símbolo del sistema de su terminal, prometiéndole que escriba algo en su terminal (en contraposición a escribirlo en su documento); recuerde pulsar enter después de cada comando.

Es muy probable que su carpeta “Documentos” se encuentre aquí. Escriba

(pwd: print working directory) y presione enter para mostrar el nombre del directorio actual). Utilice $ pwd cuando se sienta perdido.

El comando $ ls (= listar), que simplemente lista los archivos en el directorio actual. Por último, puede usar $ cd (= cambiar el directorio) como $ cd NOMBRE_DIRECTORIO (donde NOMBRE_DIRECTORIO es el nombre del directorio al que desea navegar). Puede utilizar $ cd .. para subir automáticamente un nivel en la estructura de directorios (el directorio principal del directorio en el que se encuentra actualmente). Una vez que comience a escribir el nombre del directorio, utilice la tecla Tab para completar automáticamente el texto, especialmente útil para nombres de directorio largos o nombres de directorios que contengan espacios.

Estos tres comandos de terminal: pwd, ls y cd son todo lo que necesita para este tutorial. Practicarlos durante unos minutos para navegar por la carpeta de documentos y pensar en cómo han organizado sus archivos. Si lo desea, siga con su gestor de archivos gráfico regular.

Uso de Pandoc para convertir Markdown a un documento de MS Word

Ahora estamos listos para componer! Abra su ventana de terminal, use $ pwd y $ cd para navegar a la carpeta correcta de su proyecto. Una vez allí, escriba el comando $ ls en el terminal para listar los archivos. Si ve su archivo .md y sus imágenes, está en el lugar correcto. Para convertir .md en .docx escriba:

Abra el archivo MS Word para comprobar los resultados. Si usa Open o Libre Office puede ejecutar:

Si eres nuevo en la línea de comandos, imagina leyendo el comando anterior diciendo algo como: “Pandoc, crea un archivo MS Word de mi archivo Markdown”. La parte -o es una “bandera”, que en este caso dice algo como “en lugar de decirme explícitamente el origen y los formatos de archivo de destino, sólo adivina mirando la extensión de archivo.” Muchas opciones están disponibles a través de tales banderas en Pandoc. Puede ver la lista completa en el sitio web de Pandoc o escribiendo:

En el terminal.

Intente ejecutar el comando:

Ahora vaya de nuevo al directorio de su proyecto. ¿Puedes decir lo que pasó?

Los usuarios más avanzados que tienen instalado LaTeX pueden experimentar  la conversión de Markdown en archivos .tex o en formato .pdf especialmente formateado. Una vez instalado LaTeX, se puede crear un archivo PDF formateado con la misma estructura de comandos

Con el tiempo, podrá ajustar el formato de los documentos PDF especificando un archivo de estilo LaTeX (guardado en el mismo directorio) y ejecutando algo como:

Trabajo con bibliografías

En esta sección, agregaremos una bibliografía a nuestro documento y luego convertiremos de Chicago a formatos MLA.

Si no está usando un alimentador de referencia como Endnote o Zotero, debería hacerlo. Preferimos a Zotero, porque, al igual que Pandoc, fue creado por la comunidad académica y como otros proyectos de código abierto se publica bajo la GNU General Public License.

Lo más importante para nosotros, su gestor de referencia debe tener la capacidad de generar bibliografías en formato de texto sin formato, para mantenerse en línea con nuestro principio de “todo en texto plano”.

Sigue adelante y abre un gestor de referencia de tu elección y añade algunas entradas de muestra. Cuando esté listo, busque la opción de exportar su bibliografía en formato BibTeX (.bib). Guarde su archivo .bib en su directorio de proyecto, y darle un título razonable como “proyecto.bib”.

La idea general es mantener sus fuentes organizadas bajo una base de datos bibliográfica centralizada, generando archivos .bib específicos y mucho más pequeños que vivirán en el mismo directorio que su proyecto. Sigue adelante y abre tu archivo .bib con el editor de texto sin formato de tu elección.

Su archivo .bib debe contener varias entradas que se parecen a esto:

Rara vez tendrás que editarlos a mano (aunque puedas). En la mayoría de los casos, simplemente “exportará” el archivo .bib de Zotero o de un gestor de referencia similar.

Tómese un momento para orientarse aquí. Cada entrada consta de un tipo de documento, “artículo” en nuestro caso, un identificador único (fyfe_digital_2011) y los metadatos pertinentes sobre título, volumen, autor, etc.

Lo que más nos interesa es el ID único que sigue inmediatamente al soporte  en la primera línea de cada entrada. La identificación única es lo que nos permite conectar la bibliografía con el documento principal. Deje este archivo abierto por ahora y vuelva a su archivo documento1.md.

Edite la nota al pie en la primera línea de su archivo documento1.md para que se parezca a los ejemplos siguientes, donde @name_title_date puede reemplazarse con uno de los ID únicos del archivo proyecto.bib.

Una referencia formateada de este modo se traducirá correctamente como una cita de estilo en línea o de pie de página [@name_title_date, 67] .

Una vez que ejecute la reducción a través de Pandoc, “@ fyfe_digital_2011” se ampliará a una cita completa en el estilo de su elección. Puede utilizar la sintaxis @citation de la forma que mejor le parezca: en línea con su texto o en las notas a pie de página.

Para generar una bibliografía simplemente incluya una sección llamada #bibliography al final del documento.

Ahora, vuelva a su encabezado de metadatos en la parte superior de su documento1 .md y especifique el archivo de bibliografía que se va a usar, así:

Esto le indica a Pandoc que busque su bibliografía desde el archivo proyecto.bib, en el mismo directorio que su documento1.md. Veamos si esto funciona. Guarde su archivo, cambie a la ventana de terminal y ejecute:

La mayúscula S indica “inteligente”, un modo que produce “salida tipográficamente correcta, convirtiendo citas rectas en citas rizadas, a los guiones, y a las elipses.

El fltro “pandoc-citeproc” analiza todas sus etiquetas de citas.

El resultado debe ser un archivo MS Word correctamente formateado.

Si tiene instalado LaTeX, convierta en .pdf utilizando la misma sintaxis para resultados más bonitos.

No se preocupes si las cosas no son exactamente como le gusta, recuerda que vas a ajustar el formato de una vez y después, lo más cerca posible de la hora de publicación.

Por ahora sólo estamos creando borradores basados en valores razonables por defecto.

Cambiando estilos de citas

El estilo de citas predeterminado en Pandoc es Chicago Fecha-Autor.

Podemos especificar un estilo diferente usando una hoja de estilo, escrita en el “Lenguaje de Estilo de Cita” (otra convención de texto sin formato, en este caso para describir estilos de citas) y denotada por la extensión de archivo .csl.

Afortunadamente, el proyecto CSL mantiene un repositorio de estilos de citas comunes, algunos incluso adaptados para revistas específicas. Visite http://editor.citationstyles.org/about/ para encontrar el archivo .csl para descargar modern-language-association.csl  (Modern Language Association) y guárdelo en el directorio del proyecto como mla.csl. Ahora necesitamos decirle a Pandoc que utilice la hoja de estilo MLA en lugar de la opción predeterminada de Chicago. Hacemos esto actualizando el encabezado YAML:

Ahora simplemente utilice el mismo comando:

Analiza el comando en inglés mientras escribe. En mi cabeza, traduzco lo anterior en algo así como: “Pandoc, ser inteligente sobre el formato, y la salida de un documento de Word utilizando el filtro de citas en mi archivo Markdown (como se puede adivinar de la extensión)”.

En los estilos de citación considere agregar usar el archivo .csl personalizados para revistas en su campo o profesión.

Resumen

Ahora debería ser capaz de escribir documentos en Markdown, crear borradores en varios formatos, agregar bibliografías y cambiar fácilmente los estilos de citas.

Una mirada final al directorio del proyecto revelará una serie de archivos “fuente”:  su archivo documento1.md, el archivo proyecto.bib, su archivo mla.csl y algunas imágenes. Además de los archivos fuente, debería ver algunos archivos “de salida” que creamos durante el tutorial: documento1.docx o proyecto.pdf.

Debería tratar los archivos de origen como una versión autorizada de su texto, y los archivos de destino como descartables “impresiones” que puede generar fácilmente con Pandoc sobre la marcha.

Todas las revisiones deben ir a documento1.md.

El archivo documento1.docx está allí para la limpieza y el formateo en la etapa final.

Por ejemplo, si la revista requiere manuscritos de doble espacio, puede rápidamente doblar espacio en Open Office o Microsoft Word. Pero no pase demasiado tiempo formateando. Recuerde, todo se despoja cuando su manuscrito se va a imprimir.

El tiempo dedicado a un formato innecesario puede utilizarse mejor para pulir la prosa del borrador.

Recursos útiles

Si tiene problemas, no hay mejor lugar para empezar a buscar apoyo que el sitio de Pandoc de John MacFarlane y la lista de correo afiliada. Al menos dos sitios de tipo “Pregunta y Respuesta” pueden plantear preguntas sobre Pandoc: Stack Overflow and Digital Humanities Q&A.

Las preguntas también se pueden hacer en vivo, en Freenode IRC, canal #Pandoc, frecuentado por un grupo amistoso de asiduos.

A medida que aprenda más sobre Pandoc, también puede explorar una de sus características más potentes: filtros.

Aunque sugerimos comenzar con un editor simple, muchos (70+, de acuerdo a este post) otros están disponibles en línea, ya menudo libre de costo.

De los autónomos, me gustóMou, Write Monkey, y Sublime Text.

Recientemente han surgido varias plataformas basadas en la Web que proporcionan interfaces gráficas y sofisticadas para la escritura colaborativa y el seguimiento de versiones con Markdown. Estos incluyen: prose.io, Authorea, Penflip, Draft, and StackEdit.

Pero el ecosistema no se limita a los editores. Gitit e Ikiwiki apoyan la creación en Markdown con Pandoc como analizador.

A esta lista podemos encontrar una serie de herramientas que generan páginas web rápidas y estáticas,Yst, Jekyll, Hakyll, y el script de bash  del historiador Caleb McDaniel.

Finalmente, se están formando plataformas de publicación completas alrededor del uso de Markdown.

Markdown en la plataforma de mercado Leanpub podría ser una interesante alternativa al modelo de publicación tradicional.

Y yo mismos estoy experimentando con la publicación de documentos en GitHub y readthedocs.org (herramientas que usualmente se usan para documentación técnica.

 

Deja un comentario

Deja un comentario

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.