Puedes utilizar pandoc en Linux para convertir entre más de 40 formatos de archivo. Además puede usarlo para crear un sistema simple de documentos como código escribiendo en Markdown, almacenando en gity publicar en cualquiera de sus formatos compatibles.
Conversión de documentos y documentos como código
Si tiene un documento en alguno de pandoc's muchos formatos de archivo compatibles, convertirlo en cualquiera de los demás es pan comido. ¡Es una herramienta útil para tener!
Pero el verdadero poder de pandoc se hace evidente cuando lo utiliza como base de un sistema simple de documentos como código. La premisa de docs-as-code es adoptar algunas de las técnicas y principios del desarrollo de software y aplicarlos a la escritura de documentación, especialmente para proyectos de desarrollo de software. A pesar de esto, puedes aplicarlo al desarrollo de cualquier tipo de documentación.
Los desarrolladores de software usan su editor favorito o entorno de desarrollo integrado (IDE) para escribir sus programas. El código que escriben se guarda en archivos de texto. Estos contienen el código fuente para el programa.
Usan un sistema de control de versiones, o VCS (Git es el más popular), para capturar cambios en el código fuente a medida que se desarrolla y mejora. Esto significa que el programador tiene un historial completo de todas las versiones de los archivos de código fuente. Puede tener acceso rápidamente a cualquier versión anterior de un archivo. Git almacena archivos en un repositorio. Hay un repositorio local en la computadora de cada desarrollador y un repositorio central, compartido y remoto que a menudo está alojado en la nube.
Cuando están listos para producir una versión funcional del programa, usan un compilador para leer el código fuente y generar un ejecutable binario.
Al escribir sus documentos en un lenguaje de marcado ligero basado en texto, puede utilizar un VCS para controlar la versión de su escritura. Cuando esté listo para repartir o publicar un documento, puede utilizar pandoc para generar tantas versiones diferentes de su documentación como necesite, incluidas las sustentadas en la web (HTML), procesado de texto o tipográfico (LibreOffice, Microsoft Word, Texas), Formato de Documento Portable (PDF), libro electronico (ePub), etcétera.
Puede hacer todo esto desde un conjunto de archivos de texto ligeros controlados por versiones.
Instalación de pandoc
Instalar pandoc en Ubuntu, use este comando:
sudo apt-get install pandoc
En Fedora, el comando que necesita es el siguiente:
sudo dnf install pandoc
En Manjaro, debe escribir:
sudo pacman -Syu pandoc
Puede chequear qué versión ha instalado usando el --version opción:
pandoc --version
Utilizar pandoc sin archivos
Si utiliza pandoc sin ninguna opción de línea de comandos, además acepta entrada escrita. Simplemente presione Ctrl + D para indicar que ha terminado de escribir. pandoc espera que escriba en formato Markdown y genera una salida HTML.
Veamos un ejemplo:
pandoc
Hemos escrito algunas líneas de Markdown y estamos a punto de presionar Ctrl + D.
Tan pronto como lo hagamos pandoc genera la salida HTML semejante.
Para hacer algo útil con pandoc, a pesar de esto, verdaderamente necesitamos utilizar archivos.
Conceptos básicos de Markdown
Markdown es un lenguaje de marcado ligero y se le da un significado especial a ciertos caracteres. Puede usar un editor de texto sin formato para crear un archivo Markdown.
Markdown se puede leer fácilmente, puesto que no hay etiquetas visualmente engorrosas que distraigan del texto. El formato en los documentos de Markdown se parece al formato que representa. A continuación se muestran algunos de los conceptos básicos:
- Para enfatizar el texto con cursiva, envuélvalo en asteriscos.
*This will be emphasized* - Para negrita texto, utilice dos asteriscos.
**This will be in bold** - Los encabezados están representados por el signo de número / marca de almohadilla (
#). El texto está separado del hash por un espacio. Use un hash para un encabezado de nivel superior, dos para un segundo nivel, y así sucesivamente. - Para crear una lista con viñetas, comience cada línea de la lista con un asterisco e inserte un espacio antes del texto.
- Para crear una lista numerada, comience cada línea con un dígito seguido de un punto y posteriormente inserte un espacio antes del texto.
- Para crear un hipervínculo, escriba el nombre del sitio entre corchetes (
[]) y la URL entre paréntesis [()] del mismo modo que:[Link to How to Geek](https://www.systempeaker.com/). - Para insertar una imagen, escriba un signo de exclamación inmediatamente antes de los corchetes (
![]). Escriba cualquier texto alternativo para la imagen entre corchetes. Posteriormente, encierre la ruta a la imagen entre paréntesis [()“]. He aquí un ejemplo:.
Cubriremos más ejemplos de todos estos en la próxima sección.
RELACIONADO: ¿Qué es Markdown y cómo se utiliza?
Conversión de archivos
Las conversiones de archivos son sencillas. pandoc Por lo general, puede determinar con qué formatos de archivo está trabajando a partir de sus nombres de archivo. Aquí, vamos a generar un archivo HTML a partir de un archivo Markdown. los -o (salida) la opción dice pandoc el nombre del archivo que queremos crear:
pandoc -o sample.html sample.md
Nuestro archivo de muestra de Markdown, sample.md, contiene la sección corta de Markdown que se muestra en la imagen a continuación.
Se crea un archivo llamado sample.html. Cuando hacemos doble clic en el archivo, nuestro navegador predeterminado lo abrirá.
Ahora, generemos un Formato de documento abierto documento de texto que podemos abrir en Escritor de LibreOffice:
pandoc -o sample.odt sample.md
El archivo ODT tiene el mismo contenido que el archivo HTML.
Un toque limpio es el texto alternativo de la imagen que además se utiliza para generar automáticamente un título para la figura.
Especificar formatos de archivo
los -f (de) y -t (a) las alternativas se usan para decir pandoc los formatos de archivo que desea convertir desde y hacia. Esto puede resultar útil si trabaja con un formato de archivo que comparte una extensión de archivo con otros formatos relacionados. A modo de ejemplo, Texas, y Látex ambos usan la extensión “.tex”.
Además estamos usando el -s (independiente) opción pandoc generará todo el preámbulo de LaTeX necesario para que un documento sea un documento LaTeX completo, autónomo y bien formado. Sin el -s (independiente), la salida seguiría siendo LaTeX bien formada que podría insertarse en otro documento LaTeX, no se analizaría correctamente como un documento LaTeX independiente.
Escribimos lo siguiente:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Si abre el archivo «sample.tex» en un editor de texto, verá el LaTeX generado. Si tiene un editor LaTeX, puede abrir el archivo TEX para ver una vista previa de cómo se interpretan los comandos de composición tipográfica LaTeX. Reducir la ventana para que se ajustara a la imagen de abajo hizo que la pantalla pareciera estrecha, pero, en realidad, estaba bien.
Usamos un editor de LaTeX llamado Texmaker. Si desea instalarlo en Ubuntu, escriba lo siguiente:
sudo apt-get install texmaker
En Fedora, el comando es:
sudo dnf install texmaker
En Manjaro, use:
sudo pacman -Syu texmaker
Conversión de archivos con plantillas
Probablemente esté empezando a comprender la flexibilidad que pandoc proporciona. Puede escribir una vez y publicar en casi cualquier formato. Es una gran hazaña, pero los documentos se ven un poco vanilla.
Con las plantillas, puede dictar qué estilos pandoc utiliza cuando genera documentos. A modo de ejemplo, puedes decir pandoc usar los estilos definidos en un Hojas de estilo en cascada (CSS) archivo con el --css opción.
Hemos creado un pequeño archivo CSS que contiene el texto a continuación. Cambia el espacio por encima y por debajo del estilo del encabezado de nivel. Además cambia el color del texto a blanco y el color de fondo a un tono de azul:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
El comando completo está a continuación; tenga en cuenta que además usamos la opción independiente (-s):
pandoc -o sample.html -s --css sample.css sample.md
pandoc utiliza el estilo único de nuestro archivo CSS minimalista y lo aplica al encabezado de nivel uno.
Otra alternativa de ajuste que tiene disponible cuando trabaja con archivos HTML es incluir marcado HTML en su archivo Markdown. Esto se pasará al archivo HTML generado como marcado HTML estándar.
A pesar de esto, esta técnica debe reservarse para cuando solo está generando salida HTML. Si trabaja con bastantes formatos de archivo, pandoc ignorará el marcado HTML para archivos que no sean HTML y se pasará a ellos como texto.
Además podemos especificar qué estilos se usan cuando se generan archivos ODT. Abra un documento de LibreOffice Writer en blanco y ajuste el encabezado y los estilos de fuente para satisfacer sus necesidades. En nuestro ejemplo, además agregamos un encabezado y un pie de página. Guarde su documento como «odt-template.odt».
Ahora podemos utilizar esto como plantilla con el --reference-doc opción:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Compare esto con el ejemplo de ODT anterior. Este documento utiliza una fuente distinto, tiene encabezados de colores e incluye encabezados y pies de página. A pesar de esto, se generó exactamente a partir del mismo archivo de Markdown «sample.md».
Las plantillas de documentos de referencia se pueden usar para indicar diferentes etapas de la producción de un documento. A modo de ejemplo, puede tener plantillas que tengan marcas de agua «Borrador» o «Para revisión». Se utilizaría una plantilla sin marca de agua para un documento terminado.
Generando archivos PDF
Por defecto, pandoc utiliza el motor LaTeX PDF para generar archivos PDF. La forma más fácil de asegurarse de que se satisfacen las dependencias de LaTeX adecuadas es instalar un editor de LaTeX, como Texmaker.
A pesar de esto, es una instalación bastante grande: Tex y LaTeX son bastante pesados. Si el espacio de su disco duro es limitado, o si sabe que nunca usará TeX o LaTeX, es factible que prefiera generar un archivo ODT. Posteriormente, puede abrirlo en LibreOffice Writer y guardarlo como PDF.
Documentos como código
El uso de Markdown como lenguaje de escritura tiene varias ventajas, incluidas las siguientes:
- Trabajar en archivos de texto sin formato es rápido: Se cargan más rápido que los archivos de procesador de texto de tamaño semejante y además tienden a moverse más rápido por el documento. Muchos editores, incluidos
gedit,Vim, yEmacs, utilice el resaltado de sintaxis con el texto Markdown. - Tendrá una línea de tiempo de todas las versiones de sus documentos: Si almacena su documentación en un VCS, como Git, puede ver fácilmente las diferencias entre dos versiones del mismo archivo. A pesar de esto, esto solo funciona verdaderamente cuando los archivos son de texto sin formato, puesto que eso es con lo que un VCS espera trabajar.
- Un VCS puede registrar quién realizó cambios y cuándo: Esto es especialmente útil si a menudo colabora con otros en proyectos grandes. Además proporciona un depósito central para los propios documentos. Muchos servicios de Git alojados en la nube, como GitHub, GitLab, y BitBucket, disponen niveles gratuitos en sus modelos de precios.
- Puedes generar tus documentos en múltiples formatos: Con solo un par de scripts de shell simples, puede extraer los estilos de CSS y documentos de referencia. Si almacena sus documentos en un repositorio de VCS que se integra con Integración continua y despliegue continuo (CI / CD), se pueden generar automáticamente cada vez que se crea el software.
RELACIONADO: ¿Qué es GitHub y para qué se utiliza?
Pensamientos finales
Hay muchas más opciones y funciones dentro pandoc de lo que hemos cubierto aquí. Los procesos de conversión para la mayoría de los tipos de archivos se pueden modificar y ajustar. Para obtener más información, consulte los excelentes ejemplos en la publicación oficial (y extremadamente detallada) página web pandoc.
