Iniciación al uso de Markdown

Esta sesión nos puede servir para “meter mano” a la sintaxis y que comprendamos la importancia de estructurar bien un documento.

El esquema es la base de la investigación reproducible.

Markdown se concibió para generar documentos para la web (formato html), se trabaja en “texto plano”, es decir, se utiliza los caracteres del alfabeto con algunos signos básicos, como acentos (`, ', ', ^, ~,… ) y asteriscos (*).

Es fácilmente exportable y rápido format as you write.

¿Qué es markdown? ¿para qué sirve? y ¿cómo se usa?

Markdown es un lenguaje de marcas ligero que trata de conseguir la máxima legibilidad y “publicabilidad” tanto en sus forma de entrada como de salida.

Nuestro trabajo se va a centrar en organizar la estructura del documento,como por ejemplo puede ser llevar la bitácora, o Blog , de un proyecto o curso.
Esta estructura funciona como un mapa conceptual, que podemos transformar en otros documentos de trabajo como presentaciones, pdf, etc…
Para ello podemos generar un índice de contenidos, subordinar o enfatizar ideas, crear un índice de recursos (enlaces o referencias) reference links, etc…

En R alt + O sirve para comprimir el documento completo (folding). También podemos comprimir secciones seleccionando el marcador correspondiente al número de línea de cada encabezado.

Beneficios de markdown

  • herramienta de redacción clara y fácil de usar
  • las marcas nos permiten diseñar la estructura del documento
  • trabajamos en distintos niveles, diferenciamos el material generado considerando el punto de vista del autor de la visión del lector en el producto final.
  • nos permite separar las ideas en líneas cortas, (si no generamos líneas en blanco, se mantienen los párrafos).
  • es ligero, fácil de leer, fácil de escribir, compatible con multitud de plataformas (portátiles, teléfonos móviles, tablets, etc)
  • Nos concentramos en lo que escribimos, y ayuda a nuestra concentración / productividad.

¿Qué características debe tener nuestro documento?

  • Organización de las ideas (secciones, capítulos/subcapítulos, partes)
  • Acceso a datos
  • Referencias a artículos y otros documentos.

Podemos usar markdown desde Rstudio o desde otros editores (Markpad, ReText, haroopad, etc), inclusive con editores en línea.

¿Por qué nos gusta trabajar en markdown con Rstudio?

Por que tiene mejores herramientas, lo podemos integrar con R y por que “mola más”.

En resumen

Usar markdown es una forma de trabajar las ideas, no nos preocupamos del formato, definimos objetos y creamos estructuras, lo que nos permite escribir de forma sistemática y facilita la reproducción de nuestro trabajo o el de otros. Posteriormente podemos generar distintos outputs con la estructura creada.

Mira esta figura http://pandoc.org/diagram.jpg

¿Empezamos?

Saltos de párrafo, líneas en blanco, espacios

Las líneas de texto se consideran conectadas en un párrafo salvo que se deje entre ellas una línea en blanco.

Este párrafo se relacionan
las facultades situadas en el 
campus:
Biología,
Ciencias del Deporte,
Físicas,
Enfermería, 
...
Matemáticas,
Veterinaria.
Todas ellas cuentan con instalaciones 
de primera calidad.

Lo que proporciona:

Este párrafo se relacionan las facultades situadas en el campus: Biología, Ciencias del Deporte, Físicas, Enfermería, … Matemáticas y Veterinaria. Todas ellas cuentan con instalaciones de primera calidad. 

Podemos escribir utilizando un retorno de
carro tras cada punto y seguido.
Así, vemos con más facilidad el texto que 
estamos escribiendo.

Este es un nuevo párrafo que, gracias, 
a la línea en blanco ha quedado separado 
del anterior.



No hay límite para separar los párrafos, 
pero no conviene abusar.

  • Los puntos y aparte se generan con dos retornos de carro. Con interlineado doble.

  • Cada línea en blanco puede tener una función adicional: pueden servir para visualizar mejor nuestro texto.

  • Si necesitamos escribir versos, o líneas que se quiebren cuando nos interesa lo conseguimos con dos espacios al final de la línea:

Para la libertad sangro, lucho, pervivo.  
Para la libertad, mis ojos y mis manos,  
como un árbol carnal, generoso y cautivo,  
doy a los cirujanos.

Para la libertad sangro, lucho, pervivo.
Para la libertad, mis ojos y mis manos,
como un árbol carnal, generoso y cautivo,
doy a los cirujanos.

        Miguel Hernández, El hombre acecha, (1938-39)

Tipografía

En un texto es muy importante la selección de las distintas tipografías a utilizar, por ejemplo, cursivas, para palabras en otro idioma. Pero el aspecto del documento debe ser relegado a la plantilla o CSS, evitando un uso innecesario de elementos “embellecedores”, es muy importante la sistemática y el buen uso de los elementos tipográficos.

  • Cursiva

    Es muy sencillo, se usan * o _. Ejemplos:

    cursiva

    ésto también está en cursiva

  • Negritas

    Se usan ** o __. Ejemplos:

    negrita

    también en negrita

  • Pueden usarse combinados:

    negrita y cursiva

    negrita y cursiva al revés

  • Otra opciones tipográficas

    • Superíndices: 360^o^ 360o
    • Subíndices: H~2~O H2O
    • Tachado: ~~tachado~~ tachado
  • Símbolos especiales
    • guiones - -- --- - – —
    • puntos suspensivos ... …
    • Apertura y cierre de comillas: ' " “hola” ‘adiós’

¿Cómo evitar que markdown “interprete” un simbolo?

¿Cómo hacer si queremos mostrar esos caracteres con significado especial?

Fácil: se interpretan literalmente si se precede por una barra invertida; por ejemplo la secuencia ‘*’ mostraría un asterisco en lugar de empezar una sección de texto enfatizado.

Quiero escribir en mi texto: *-*, pero esto es lo que consigo: -. Recurriendo al carácter de escape \ lo consigo sin problemas \*-\*: *-*

Ejercicio

En el siguiente texto, pon en cursiva las palabras “aprender”, y “difícil” y en negrita la palabra “imposible” y en negrita con cursiva “mintiendo”:

Aprender es difícil pero no imposible, y quien diga lo contrario, está mintiendo.

Estructura de documento

Los encabezamientos/secciones/capítulos de libro crean colocando un número de almohadillas # antes del texto correspondiente al nivel de encabezamiento deseado, con un máximo seis niveles. El significado del primer nivel es decisión del autor. Un ejemplo:

# Éste es un encabezamiento de primer nivel 

#### Encabezamiento de cuarto nivel

Citas o blockquote

Se usa el signo> al principio de la línea

> Esta es una anotación de una cita literal, 
  se puede completar en varias líneas.

Esta es una anotación de una cita literal, se puede completar en varias líneas.

también es una forma de

enfatizar una idea que quieres resaltar dentro del texto (resumen, ejercicio).

Puede utilizarse delate de casi todo:

># apartados
>* listas

Listas

Se pueden generar listas no ordenadas, con símbolos como +, *, -. Por ejemplo:

  • Un elemento en una lista no ordenada usando *

  • Otro elemento en una lista

  • Un elemento en una lista no ordenada usando +

  • Otro elemento en una lista

  • Un elemento en otra lista no ordenada usando -

  • Otro elemento en esa lista

Listas numeradas

Se pueden construir con el número correspondiente al orden (o únicamente el 1):

  1. Elemento en una lista enumerada u ordenada
  2. Otro elemento

También se puede numerarse los items con letras mayúsculas o minúsculas, o numeración ordinal:

  • Letras
    • minúsculas
      1. ejemplo
      2. mas ejemplo
    • mayúsculas (necesario el paréntesis en lugar del punto)
      1. ejemplo
      2. otro mas
  • Numeración romana
    • minúsculas
      1. ejemplo
      2. mas ejemplo
    • mayúsculas
      1. ejemplo
      2. otro mas

Listas subordinadas

Si añadimos cuatro espacios antes de un elemento de una lista, lo convertimos en subordinado del nivel del párrafo anterior.

Así:

* Uno
    * Dos
        * Tres
        * Cuatro
    * Otro dos

Proporciona:

  • Uno
    • Dos
      • Tres
      • Cuatro
    • Otro dos

Pueden alternase lista numeradas y no numeradas:

* Uno
    a. Dos
        i. Tres
        i. Cuatro
    b. Otro dos
  • Uno
    1. Dos
      1. Tres
      2. Cuatro
    2. Otro dos

Ejercicio

El siguiente párrafo conviértelo en una lista no ordenada, subordinando los niveles y pon el nombrehomo sapienscon letra cursiva.

    Primer nivel. Reino Animal   
    Segundo nivel. Clase Mamífero   
    Tercer nivel. Orden Primates   
    Cuarto nivel. Familia Hominidae  
    Quinto nivel. Genero Homo  
    Sexto nivel. Especie Homo sapiens

Código lenguaje de programación

Los objetos de R y la sintaxis de R se expresan como código. Para insertar código hay que dejar un espacio con la línea anterior y aplicar la “regla de los cuatro espacios” (dejando cuatro espacios al inicio de línea), markdown lo interpreta como código directamente, y se visualiza con otro tipo de letra. Por ejemplo:

Ésto es código    
Aquí sigue el código

Al dejar de añadir espacios iniciales se sigue trabajando con texto.

Además de los cuatro espacios se puede utilizar el acento grave (`):

esto es código

También puedo marcarlo antes y después con tres acentos seguidos (```)

Esto también es código
a <- log( 10 )

Si indicamos el lenguaje se realza con coloreado de sintaxis highglighting

# Código realzado con un marco
a <- log( 10 )
sqrt( a )

Insertando hipervínculos

Ejercicio

En el siguiente texto, hemos comenzado a hacer una lista de referencias, pero están sin terminar. Para completarlas, haz la lista de referencias y nombra la primera como “lectura interesante” y crea el vínculo a la página http://scientiablog.com/. El segundo link defínelo con el nombre “obligatorio para doctorandos”, para el link:
www.phdcomics.com/comics/most_popular.php

Cuando uno está haciendo la tesis, a veces se aprende leyendo cosas como [esta lectura interesante]

O se despista durante horas con [este comic][obligatorio para doctorandos]

Insertando imágenes

Insertar imágenes es similar la inserción de enlaces. Sólo hay que poner un signo de exclamación ! delante del índice de la imagen:

![](pics/phd050508s.jpg "ambicion")

Se añade una imagen que esta en el subdirectorio pics:

Los índice pueden contener imágenes, como los hipervínculos:

Esta es la imagen ![][ambicion]

[ambicion]: pics/phd050508s.jpg

Las imágenes son tratadas como un carácter y ocupan el lugar que les corresponde avicon y pueden quedar “mezcladas con el texto”.

Desafortunadamente el tamaño de las imágenes no puede ser gestionado por markdown, pero con cualquier programa de edición de imágenes se puede obtener una versión del tamaño deseado, a modo de ejemplo, desde la terminal de sócrates, reducimos el tamaño de una imagen a una dimensión máxima de 100 píxeles de ancho o alto:

convert -geometry 100x100 
        imagen.jpg imageRed.jpg

Fórmulas matemáticas

Markdown ha heredado el potencial de  para generar formulas con una tipografía adecuada y elegante. Con estas podemos escribir lo que deseemos.

Gracias a esta opción podemos distinguir fotográficamente las variables matemáticas o estadísticas de los objetos o variables en R: la variable \(x\) se asocia al objeto x.

La variable $x$ se asocia al objeto `x`.

La fracción 1 entre \(n\) se consigue:

$$\frac{1}{n}$$

\[\frac{1}{n}\]

y su potencia \(n\):

\[\left( \frac{1}{n} \right) ^ 2 \]

$$\left( \frac{1}{n} \right) ^ 2 $$

y la raíz cuadrada:

$$\sqrt{ \left( \frac{1}{n} \right) ^ 2 }$$

\[\sqrt{ \left( \frac{1}{n} \right) ^ 2 }\]

Algunas referencias interesantes sobre notación en :

Ejercicio

El siguiente texto colócalo en forma de lista numerada, con los comentarios en líneas distintas con interlineado simple. Enfatiza las palabras dentro y sin romperlo. Añada un enlace a la palabra huevo e inserte la imagen de una sartén.

Para hacer un huevo frito:
    - Primero se saca un huevo de la 
      nevera (mucho cuidado de no 
      romperlo)
    - Después se calienta aceite en la 
      sartén (mejor si es de oliva)
    - Se casca el huevo dentro del aceite 
      (cuidado que salpicará mucho)
    - Se deja cuajar y se saca con la 
      espumadera (sin romperlo).
¡Qué aproveche!

Citas y referencias bibliográficas

  • Primero hay que especificar el archivo bibliográfico que vamos a usar, insertándolo desde los metadatos.
    cabe escribirlos en el mismo documento, como un inline reference.

  • Los datos de bibliografía puede usarse multitud de formatos.

  • Para crear una cita insertamos el identificador del documento precedido de @

  • El sistema se encargará de generar el apartado de referencias, y tanto estas como las citas ser realizarán con el formato especificado.

Dentro de un texto como dijo @Perez2010 ...

Como se ha demostrado [@Perez2010] ...

Dentro de un texto como dijo Perez (2010) utilizar la cabeza y un modo racional de trabajo puede ahorrar muchos dolores de idem.

Como se ha demostrado (Perez 2010) los autómatas son un alivio en tareas rutinarias.

Referencias

Perez, P. 2010. Este es el título del artículo. Este es el nombre de la revista 6:13–21.