pandoc_basico/README.md

# ¿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

## 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

## 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

    % 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\].

    ---
    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.
    ...
    ---

## 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

    *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~.

## TeX matemático o código incrustado en linea

    El TeX matemático va entre signos$: $2 + 2$.
    
    El código en linea va entre comillas invertidas: `echo 'hello'`

## Enlaces e imágenes

    <http://example.com>
    <foo@bar.com>
    [inline link](http://example.com "Title")
    ![inline image](/path/to/image, "alt text")
    
    [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"

## Notas al pie de página

    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.

## Citas

    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.

## Encabezados

    Encabezado 1
    ========
    
    Encabezado 2
    --------
    
    # Encabezado 1 #
    
    ## Encabezado 2 ##

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

    1. example
    2. example
    
    A) example
    B) example

#### Listas desordenadas

Los items de la lista deben ir marcados con ‘\*’, ‘+’, or ‘-’.

    +   example
    -   example
    *   example

Las listas se pueden anidar de la forma usual:

    +   example
        +   example
    +   example

#### Listas de definición

    Term 1
    
    :   Definition 1
    
    Term 2
    
    :   Definition 2
        Second paragraph of definition 2.

## Blockquotes

    >   blockquote
    >>  nested blockquote

Es necesario añadir lineas en blanco antes y después de los
bloques-cita.

## Tablas

``` 
  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table:  Demonstration of simple table syntax.
```

(Para tablas más complejas consulta la [documentación de
Pandoc](http://pandoc.org/README.html#tables).)

## 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 here}
    ~~~~~~~

Opcionalmente, se puede especificar el lenguaje que corresponde al
bloque de código:

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
    qsort []     = []
    qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
                   qsort (filter (>= x) xs)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Lineas horizontales

3 o mas guiones o asteriscos en una linea (se permiten espacios
intercalados)

    ---
    * * *
    - - - -

## Bloques verbatim

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.