|
|
|
|
@ -0,0 +1,323 @@
|
|
|
|
|
====== ¿Cómo usar esto? ======
|
|
|
|
|
|
|
|
|
|
===== Muy rápido =====
|
|
|
|
|
|
|
|
|
|
Clona el repo en un directorio :
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
git clone https://bitbucket.org/salvari/pandoc_basico
|
|
|
|
|
</code>
|
|
|
|
|
Renombra el directorio:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
mv pandoc_basico miProyecto
|
|
|
|
|
</code>
|
|
|
|
|
Elimina la info de git
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
rm -rf miProyecto/.git
|
|
|
|
|
</code>
|
|
|
|
|
Edita el fichero miProyecto/src/documento.md con tu editor de texto favorito.
|
|
|
|
|
|
|
|
|
|
Ejecuta:
|
|
|
|
|
|
|
|
|
|
* **make** Para generar todos los ficheros de salida y el fichero README.md (equivale a //make all//)
|
|
|
|
|
* **make clean** Para borrar todos los ficheros de salida
|
|
|
|
|
* **make reset** Equivale a //make clean all//
|
|
|
|
|
|
|
|
|
|
===== Más detalles =====
|
|
|
|
|
|
|
|
|
|
El makefile está preparado para procesar **todos** los ficheros con extensión //.md// que haya en el directorio //src//. Esto permite escribir documentos largos y dividirlos en secciones, por ejemplo podríamos tener los siguientes documentos en el directorio //src//
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
00_Comienzo.md
|
|
|
|
|
10_Capitulo_01.md
|
|
|
|
|
20_Capitulo_02.md
|
|
|
|
|
30_Conclusion.md
|
|
|
|
|
40_apendices.md
|
|
|
|
|
</code>
|
|
|
|
|
Al ejecutar make nos crearía **un solo documento de salida** concatenando todos los ficheros. El orden en que los concatena es el orden en el que aparecen al hacer un //ls// por eso se nombran con una numeración al principio que permita ordenarlos a gusto del autor.
|
|
|
|
|
|
|
|
|
|
Si quieres cambiar el nombre del fichero de salida (//documento//) tendrás que editar el makefile y cambiar la línea:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
target := documento
|
|
|
|
|
</code>
|
|
|
|
|
Otras líneas que puedes tocar en el makefile son las que especifican el idioma y los tipos de letra usados.
|
|
|
|
|
|
|
|
|
|
====== ¿Qué es Pandoc? ======
|
|
|
|
|
|
|
|
|
|
Como explican en http:%%//%%pandoc.org, Pandoc es una librería en Haskell para hacer conversión de documentos de un formato markup a otro. Y también es una herramienta de terminal de comandos que usa esa librería.
|
|
|
|
|
|
|
|
|
|
Lo que nos permite Pandoc a la hora de documentar un proyecto es mantener la documentación en un formato abierto y sencillo (markdown) y generar salidas en distintos formatos (pdf, mediawiki, epub, html, etc) con un simple comando.
|
|
|
|
|
|
|
|
|
|
====== ¿Qué necesitas tener instalado? ======
|
|
|
|
|
|
|
|
|
|
* Pandoc
|
|
|
|
|
* make
|
|
|
|
|
* git (no es imprescindible pero muy recomendable)
|
|
|
|
|
* Las plantillas de Pandoc (o //templates//)
|
|
|
|
|
* Un buen editor de texto
|
|
|
|
|
* //LaTeX// para la salida a //pdf// El proceso de instalar //LaTeX// dependerá de tu sistema.
|
|
|
|
|
|
|
|
|
|
===== Instalación de Pandoc =====
|
|
|
|
|
|
|
|
|
|
Los paquetes de Pandoc están disponibles en la [[http://pandoc.org/installing.html|página de descargas del proyecto]]. En el caso de Ubuntu se instala sin más que descargar el paquete y abrirlo con el Centro de Software.
|
|
|
|
|
|
|
|
|
|
===== Instalación de plantillas de Pandoc =====
|
|
|
|
|
|
|
|
|
|
Hay muchas plantillas para generar documentación con Pandoc, puestas a disposición de la comunidad. De momento nos hemos limitado a las plantillas del creador de Pandoc:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
cd
|
|
|
|
|
mkdir .pandoc
|
|
|
|
|
cd .pandoc
|
|
|
|
|
git clone https://github.com/jgm/pandoc-templates templates
|
|
|
|
|
</code>
|
|
|
|
|
Esto dejará las plantillas en el directorio //~/.pandoc/templates// que es uno de los directorios donde Pandoc busca las plantillas.
|
|
|
|
|
|
|
|
|
|
No hay inconveniente en dejar las plantillas en otro directorio, o incluso en el arbol de nuestro proyecto, pero habría que retocar el //makefile// para que Pandoc las encontrara sin problemas.
|
|
|
|
|
|
|
|
|
|
====== Chuletario de Pandoc ======
|
|
|
|
|
|
|
|
|
|
===== Backslash Escapes =====
|
|
|
|
|
|
|
|
|
|
Salvo que estemos dentro de un bloque de código o de “código en linea”, **cualquier carácter de puntuación o espacio** precedido de contrabarra se tratará de forma literal, incluso si ese carácter normalmente indique algún formato.
|
|
|
|
|
|
|
|
|
|
===== Bloque de título =====
|
|
|
|
|
|
|
|
|
|
Es una forma rápida de indicar el título el autor o autores y la fecha. Tiene que ir al principio del documento
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
% título
|
|
|
|
|
% autor(es) (separados por :)
|
|
|
|
|
% fecha
|
|
|
|
|
</code>
|
|
|
|
|
Alternativamente se puede usar otro estilo para el bloque de título, mucho más completo, en formato [[https://en.wikipedia.org/wiki/YAML|YAML]], especificando variables. No puede usarse simultáneamente con el anterior, hay que escoger entre los dos estilos.
|
|
|
|
|
|
|
|
|
|
Se pueden especificar todo tipo de variables ((Ojo por que en el makefile propuesto se especifica el lenguaje, asi que la variable del bloque de título no va a tener efecto en este caso.
|
|
|
|
|
)).
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
---
|
|
|
|
|
title: Título
|
|
|
|
|
author:
|
|
|
|
|
- Autor Uno <autor.uno@correo.com>
|
|
|
|
|
- Otro autor <otroautor@correo.com>
|
|
|
|
|
tags: [nothing, nothingness]
|
|
|
|
|
date: enero-2016
|
|
|
|
|
lang: es-ES
|
|
|
|
|
abstract: |
|
|
|
|
|
Este es el resumen.
|
|
|
|
|
|
|
|
|
|
Con dos párrafos.
|
|
|
|
|
...
|
|
|
|
|
---
|
|
|
|
|
</code>
|
|
|
|
|
===== Incrustar TeX y HTML =====
|
|
|
|
|
|
|
|
|
|
* Los comandos TeX se pasan de forma transparente al Markdown, y afectan solo a la salida de LaTeX y ConTeXt; en el resto de casos se borran
|
|
|
|
|
* El código HTML pasará a la salida sin cambios, pero el Markdown dentro de los bloques HTML se procesa como Markdown
|
|
|
|
|
|
|
|
|
|
===== Párrafos y retornos de línea =====
|
|
|
|
|
|
|
|
|
|
* Un párrafo es una o más líneas de texto separadas por una linea en blanco del resto
|
|
|
|
|
* Una línea que termina con dos espacios, o una línea que termina con un fin de linea escapado (contrabarra seguida de retorno de linea) indica un cambio de linea manual
|
|
|
|
|
|
|
|
|
|
===== Itálica, negrita, superescrito, subesctrito, tachado =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
*Itálica* and **negrita** se indican con asteriscos.
|
|
|
|
|
|
|
|
|
|
Para ~~tachar~~ texto usa tildes dobles.
|
|
|
|
|
|
|
|
|
|
Superscrito se indica así: 2^ndo^.
|
|
|
|
|
|
|
|
|
|
Subescrito con tildes simples, así: H~2~O.
|
|
|
|
|
|
|
|
|
|
Los espacios en el superescrito y el subescrito tienen que ir escapados,
|
|
|
|
|
p.ej., H~esto\ es \ un\ subescrito~.
|
|
|
|
|
</code>
|
|
|
|
|
===== TeX matemático o código incrustado en linea =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
El TeX matemático va entre signos$: $2 + 2$.
|
|
|
|
|
|
|
|
|
|
El código en linea va entre comillas invertidas: `echo 'hello'`
|
|
|
|
|
</code>
|
|
|
|
|
===== Enlaces e imágenes =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
<http://example.com>
|
|
|
|
|
<foo@bar.com>
|
|
|
|
|
[inline link](http://example.com "Title")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[reference link][id]
|
|
|
|
|
[implicit reference link][]
|
|
|
|
|
![reference image][id2]
|
|
|
|
|
|
|
|
|
|
[id]: http://example.com "Title"
|
|
|
|
|
[implicit reference link]: http://example.com
|
|
|
|
|
[id2]: /path/to/image "alt text"
|
|
|
|
|
</code>
|
|
|
|
|
===== Notas al pie de página =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Las notas en linea son como
|
|
|
|
|
esta.^[Nótese que las notas en linea no pueden tener más de un párrafo.]
|
|
|
|
|
Las notas de referencia son como esta.[^id]
|
|
|
|
|
|
|
|
|
|
[^id]: Las notas de referencia pueden contener varios párrafos.
|
|
|
|
|
|
|
|
|
|
Los parámetros a continuación deben estar identados.
|
|
|
|
|
</code>
|
|
|
|
|
===== Citas =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
|
|
|
|
|
|
|
|
|
|
Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
|
|
|
|
|
|
|
|
|
|
Blah blah [@smith04; @doe99].
|
|
|
|
|
|
|
|
|
|
Smith says blah [-@smith04].
|
|
|
|
|
|
|
|
|
|
@smith04 says blah.
|
|
|
|
|
|
|
|
|
|
@smith04 [p. 33] says blah.
|
|
|
|
|
</code>
|
|
|
|
|
===== Encabezados =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Encabezado 1
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
Encabezado 2
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
# Encabezado 1 #
|
|
|
|
|
|
|
|
|
|
## Encabezado 2 ##
|
|
|
|
|
</code>
|
|
|
|
|
Las almohadillas de cierre # son opcionales. Es necesario añadir una línea en blanco antes y después de cada cabecera.
|
|
|
|
|
|
|
|
|
|
===== Listas =====
|
|
|
|
|
|
|
|
|
|
=== Listas Ordenadas ===
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
1. example
|
|
|
|
|
2. example
|
|
|
|
|
|
|
|
|
|
A) example
|
|
|
|
|
B) example
|
|
|
|
|
</code>
|
|
|
|
|
=== Listas desordenadas ===
|
|
|
|
|
|
|
|
|
|
Los items de la lista deben ir marcados con ‘*’, ‘+’, or ‘-’.
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
+ example
|
|
|
|
|
- example
|
|
|
|
|
* example
|
|
|
|
|
</code>
|
|
|
|
|
Las listas se pueden anidar de la forma usual:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
+ example
|
|
|
|
|
+ example
|
|
|
|
|
+ example
|
|
|
|
|
</code>
|
|
|
|
|
=== Listas de definición ===
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Term 1
|
|
|
|
|
|
|
|
|
|
: Definition 1
|
|
|
|
|
|
|
|
|
|
Term 2
|
|
|
|
|
|
|
|
|
|
: Definition 2
|
|
|
|
|
Second paragraph of definition 2.
|
|
|
|
|
</code>
|
|
|
|
|
===== Blockquotes =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
> blockquote
|
|
|
|
|
>> nested blockquote
|
|
|
|
|
</code>
|
|
|
|
|
Es necesario añadir lineas en blanco antes y después de los bloques-cita.
|
|
|
|
|
|
|
|
|
|
===== Tablas =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Right Left Center Default
|
|
|
|
|
------- ------ ---------- -------
|
|
|
|
|
12 12 12 12
|
|
|
|
|
123 123 123 123
|
|
|
|
|
1 1 1 1
|
|
|
|
|
|
|
|
|
|
Table: Demonstration of simple table syntax.
|
|
|
|
|
</code>
|
|
|
|
|
(Para tablas más complejas consulta la [[http://pandoc.org/README.html#tables|documentación de Pandoc]].)
|
|
|
|
|
|
|
|
|
|
===== Bloques de código =====
|
|
|
|
|
|
|
|
|
|
Los bloques de código empiezan con tres o más tildes; y acaban por lo menos con el mismo número de tildes:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
~~~~~~~
|
|
|
|
|
{code here}
|
|
|
|
|
~~~~~~~
|
|
|
|
|
</code>
|
|
|
|
|
Opcionalmente, se puede especificar el lenguaje que corresponde al bloque de código:
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
|
|
|
|
|
qsort [] = []
|
|
|
|
|
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
|
|
|
|
|
qsort (filter (>= x) xs)
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
</code>
|
|
|
|
|
===== Lineas horizontales =====
|
|
|
|
|
|
|
|
|
|
3 o mas guiones o asteriscos en una linea (se permiten espacios intercalados)
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
---
|
|
|
|
|
* * *
|
|
|
|
|
- - - -
|
|
|
|
|
</code>
|
|
|
|
|
===== Bloques verbatim =====
|
|
|
|
|
|
|
|
|
|
Todo el texto identado cuatro espacios
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Ejemplo Esto es un bloque verbatim y por ejemplo *esto* aparece
|
|
|
|
|
tal cual y no en itálica.
|
|
|
|
|
</code>
|
|
|
|
|
===== Notas a pie de página =====
|
|
|
|
|
|
|
|
|
|
<code>
|
|
|
|
|
Referencia[^1], y una nota[^larga]
|
|
|
|
|
|
|
|
|
|
[^1]: Cobbled together from
|
|
|
|
|
<http://daringfireball.net/projects/markdown/syntax> and
|
|
|
|
|
<http://johnmacfarlane.net/pandoc/README.html>.
|
|
|
|
|
|
|
|
|
|
[^larga] Una nota que tiene.
|
|
|
|
|
|
|
|
|
|
Varias lineas
|
|
|
|
|
|
|
|
|
|
{incluso código}
|
|
|
|
|
|
|
|
|
|
Mas lineas
|
|
|
|
|
|
|
|
|
|
Esto ya no es de la nota larga
|
|
|
|
|
</code>
|
|
|
|
|
====== En que me he basado (o copiado si lo prefieres) ======
|
|
|
|
|
|
|
|
|
|
* En la [[http://pandoc.org/README.html|guia de usuario de Pandoc]] Importante leersela para sacarle todo el jugo a esta herramienta
|
|
|
|
|
* En la [[https://github.com/dsanson/Pandoc.tmbundle/blob/master/Support/doc/cheatsheet.markdown|chuleta de Pandoc]] de [[https://github.com/dsanson|David Sanson]], perfecta para referencia rápida
|
|
|
|
|
* Para hacer el makefile me he leido varios tutoriales y copiado descaradamente de varios sitios que olvidé apuntar (lo siento)
|
