You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

363 lines
9.3 KiB

# ¿Cómo usar esto?
## Muy rápido
Clona el repo en un directorio :
git clone https://bitbucket.org/salvari/pandoc_basico
Renombra el directorio:
mv pandoc_basico miProyecto
Elimina la info de git
rm -rf miProyecto/.git
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*
00_Comienzo.md
10_Capitulo_01.md
20_Capitulo_02.md
30_Conclusion.md
40_apendices.md
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:
target := documento
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 [página de descargas del
proyecto](http://pandoc.org/installing.html). 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:
``` {bash}
cd
mkdir .pandoc
cd .pandoc
git clone https://github.com/jgm/pandoc-templates templates
```
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
9 years ago
## Backslash Escapes
9 years ago
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.
9 years ago
## Bloque de título
9 years ago
Es una forma rápida de indicar el título el autor o autores y la fecha.
Tiene que ir al principio del documento
9 years ago
% título
% autor(es) (separados por :)
% fecha
Alternativamente se puede usar otro estilo para el bloque de título,
mucho más completo, en formato
[YAML](https://en.wikipedia.org/wiki/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 \[1\].
9 years ago
---
title: Título
author:
- Autor Uno <autor.uno@correo.com>
- Otro autor <otroautor@correo.com>
9 years ago
tags: [nothing, nothingness]
date: enero-2016
lang: es-ES
abstract: |
Este es el resumen.
9 years ago
Con dos párrafos.
...
---
9 years ago
## Incrustar TeX y HTML
9 years ago
- 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
9 years ago
## Párrafos y retornos de línea
9 years ago
- 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
9 years ago
## Itálica, negrita, superescrito, subesctrito, tachado
9 years ago
*Itálica* and **negrita** se indican con asteriscos.
9 years ago
Para ~~tachar~~ texto usa tildes dobles.
9 years ago
Superscrito se indica así: 2^ndo^.
9 years ago
Subescrito con tildes simples, así: H~2~O.
9 years ago
Los espacios en el superescrito y el subescrito tienen que ir escapados,
p.ej., H~esto\ es \ un\ subescrito~.
## TeX matemático o código incrustado en linea
9 years ago
El TeX matemático va entre signos$: $2 + 2$.
9 years ago
El código en linea va entre comillas invertidas: `echo 'hello'`
## Enlaces e imágenes
9 years ago
<http://example.com>
<foo@bar.com>
[inline link](http://example.com "Title")
![inline image](/path/to/image, "alt text")
9 years ago
[reference link][id]
[implicit reference link][]
![reference image][id2]
9 years ago
[id]: http://example.com "Title"
[implicit reference link]: http://example.com
[id2]: /path/to/image "alt text"
## Notas al pie de página
9 years ago
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]
9 years ago
[^id]: Las notas de referencia pueden contener varios párrafos.
9 years ago
Los parámetros a continuación deben estar identados.
## Citas
9 years ago
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
9 years ago
Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
9 years ago
Blah blah [@smith04; @doe99].
9 years ago
Smith says blah [-@smith04].
9 years ago
@smith04 says blah.
9 years ago
@smith04 [p. 33] says blah.
## Encabezados
9 years ago
Encabezado 1
========
9 years ago
Encabezado 2
--------
9 years ago
# Encabezado 1 #
9 years ago
## Encabezado 2 ##
Las almohadillas de cierre \# son opcionales. Es necesario añadir una
línea en blanco antes y después de cada cabecera.
9 years ago
## Listas
9 years ago
#### Listas Ordenadas
9 years ago
1. example
2. example
9 years ago
A) example
B) example
#### Listas desordenadas
9 years ago
Los items de la lista deben ir marcados con \*, +, or -.
9 years ago
+ example
- example
* example
Las listas se pueden anidar de la forma usual:
+ example
+ example
+ example
#### Listas de definición
9 years ago
Term 1
9 years ago
: Definition 1
9 years ago
Term 2
9 years ago
: Definition 2
Second paragraph of definition 2.
## Blockquotes
9 years ago
> blockquote
>> nested blockquote
Es necesario añadir lineas en blanco antes y después de los
bloques-cita.
9 years ago
## Tablas
9 years ago
```
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
9 years ago
Table: Demonstration of simple table syntax.
```
9 years ago
(Para tablas más complejas consulta la [documentación de
Pandoc](http://pandoc.org/README.html#tables).)
9 years ago
## Bloques de código
9 years ago
Los bloques de código empiezan con tres o más tildes; y acaban por lo
menos con el mismo número de tildes:
9 years ago
~~~~~~~
{code here}
~~~~~~~
Opcionalmente, se puede especificar el lenguaje que corresponde al
bloque de código:
9 years ago
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
qsort [] = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Lineas horizontales
9 years ago
3 o mas guiones o asteriscos en una linea (se permiten espacios
intercalados)
9 years ago
---
* * *
- - - -
## Bloques verbatim
9 years ago
Todo el texto identado cuatro espacios
Ejemplo Esto es un bloque verbatim y por ejemplo *esto* aparece
tal cual y no en itálica.
## Notas a pie de página
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
# En que me he basado (o copiado si lo prefieres)
- En la [guia de usuario de Pandoc](http://pandoc.org/README.html)
Importante leersela para sacarle todo el jugo a esta herramienta
- En la [chuleta de
Pandoc](https://github.com/dsanson/Pandoc.tmbundle/blob/master/Support/doc/cheatsheet.markdown)
de [David Sanson](https://github.com/dsanson), 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)
<!-- end list -->
1. 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.