jueves, 18 de septiembre de 2014

Markdown para Python (y II)


El modulo Markdown


Este módulo es una implementación en Python del lenguaje Markdown, del que tratamos sus fundamentos en el capítulo anterior. Es compatible, casi completamente, con la referencia oficial del propio lenguaje.

Los objetivos que persiguen los responsables del proyecto son:

  • Mantener al día el módulo para Python 2.x y Python 3.x (con una capa CLI opcional) apto para ser utilizado en entornos de servidores web; como analizador/convertidor de Markdown que cumple las reglas de sintaxis y el comportamiento del desarrollo original en Perl (markdown.pl), con muy pocas diferencias.
  • Facilitar una API para desarrollar extensiones que permitan cambiar y/o extender el comportamiento del analizador/convertidor.


Además, de soportar la sintaxis básica de Markdown, cuenta con otras características:

  • Soporte Internacional: acepta la entrada en cualquier idioma soportado por Unicode incluyendo texto bidireccional.
  • Extensiones: existen varias extensiones que permiten cambiar y/o extender la sintaxis de base y una API pública para desarrollar extensiones propias.
  • Formatos de salida: básicamente, el módulo puede convertir código Markdown a HTML y XHTML. De momento los formatos de salida soportados (output_format) son los siguientes: ("xhtml": salida con la última versión compatible XHTML (actualmente XHTML 1.1); "html4": salida en HTML 4; "html5": salida en HTML con etiquetas estilo HTML 5; "html": Salida con la última versión compatible HTML.
  • Línea de comandos: el módulo puede utilizarse en los programas como cualquier otro módulo Python y, además, como veremos más adelante con varios ejemplos, es posible ejecutar scripts desde la línea de comandos.

Instalación


Aunque existen otras formas de instalar el módulo Markdown tomaremos el camino más fácil instalando con pip:

- En GNU/Linux:

$ sudo pip3 install markdown


- En Windows:

> pip3 install markdown


Uso básico del módulo


El módulo proporciona las funciones "markdown.markdown" y "markdown.markdownFromFile" de la  clase  markdown.Markdown.

Para ver cómo se utiliza dicho módulo mostraremos algunos ejemplos, a continuación.


(1) En el primer ejemplo se convierte una cadena de texto Markdown a HTML:

import markdown
texto = """ \
##Lenguaje de marcas ligero \
--------------------------- \

Un **lenguaje de marcas ligero** es un tipo de formato de \
texto más o menos estandarizado, que ocupa poco espacio y \
es fácil de editar con un editor de texto.                \

Fuente: \
[Wikipedia](https://es.wikipedia.org/wiki/Lenguaje_de_marcas_ligero) \
"""
html = markdown.markdown(texto)
print(html)

Salida obtenida (en HTML):

<h2>Lenguaje de marcas ligero</h2>
<hr />
<p>Un <strong>lenguaje de marcas ligero</strong> es un tipo de formato
de texto más o menos estandarizado, que ocupa poco espacio y
es fácil de editar con un editor de texto.

</p> <p>Fuente:
<a href="https://es.wikipedia.org/wiki/Lenguaje_de_marcas_ligero">
Wikipedia</a> </p>


(2) En el siguiente ejemplo se lee un archivo de texto Markdown codificado en "utf-8" y se muestra su correspondiente salida en formato HTML.

import markdown, codecs
archivo_entrada = codecs.open("archivo.txt", 
                              mode="r", 
                              encoding="utf-8")
texto = archivo_entrada.read()
html = markdown.markdown(texto)
print(html)


Para obtener la salida equivalente en formato HTML 5:

html5 = markdown.markdown(texto, 
                          output_format="html5")
print(html5)


(3) En este caso la salida codificada en "utf-8" se escribe en un archivo HTML:

archivo_salida = codecs.open("archivo.html", 
                             "w", 
                             encoding="utf-8", 
                             errors="xmlcharrefreplace")

archivo_salida.write(html)


Con la función "markdown.markdownFromFile" se puede leer código Markdown de un archivo de entrada, convertirlo al formato deseado y escribirlo en un archivo de salida.

Línea de comandos


A continuación, varios ejemplos de ejecución desde la línea de comandos:

(1) Convertir texto Markdown a HTML:

$ echo "**Markdown** ***Ligero***" | python -m markdown

Salida:

<p><strong>Markdown</strong> <strong><em>Ligero</em></strong></p>


(2) Convertir el texto Markdown de un fichero de entrada y guardar en un archivo HTML la salida obtenida:

$ python -m markdown entrada.txt > salida.html


(3) Ver otras posibilidades de ejecución consultando la ayuda del propio módulo:

$ python -m markdown --help


(4) Cargar una o varias extensiones Markdown (accesible/s desde PYTHONPATH):

$ python -m markdown -x ruta.del.mod1 -x ruta.del.mod2 ent.txt


(5) Utilizar directamente desde la línea de comandos los ejecutables "markdown_py" en Linux y "markdown_py.bat" en Windows.


- En Linux:

Localizar el archivo "markdown_py" con el comandos which, comprobar que tiene los atributos de ejecución (asignarlos si fuera necesario) y, finalmente, verificar que la ruta del archivo se encuentra en el path del sistema. Si todo es correcto podremos ejecutar:

$ echo "**Hola**" | markdown_py


que convierte el texto Markdown de echo a HTML:

<p><strong>Hola</strong></p>


- En Windows:

Añadir la ruta del archivo "markdown_py.bat" al path del sistema y si todo es correcto se podrán ejecutar líneas como la que sigue que convierte texto Markdown a HTML.

> markdown_py entrada.txt >salida.html


miércoles, 17 de septiembre de 2014

Markdown para Python (I)





Qué es Markdown


Markdown es un lenguaje de marcado ligero creado por John Gruber y Aaron Swart que permite la escritura rápida de textos. Literalmente, hace posible que no se tengan que despegar los dedos del teclado para que podamos concentrarnos en lo esencial: la escritura.

Esta característica lo convierte en un gran aliado a la hora de documentar nuestros proyectos Python (o escritos en otros lenguajes); un trabajo que siempre es necesario abordar pero que suele resultar, a veces, monótono y poco gratificante.

Para mejorar notablemente la productividad Markdown se vale de una serie de caracteres y sentencias que se introducen sutilmente entre el texto con una doble utilidad:

  • Hacer que los textos sean más legibles y publicables.
  • Aplicar un formato rudimentario a los textos que es aprovechado cuando son convertidos a otros formatos conocidos (.pdf, .odt, .rtf, .doc y .html). Por ejemplo, si en un texto Markdown hemos marcado una palabra en cursiva al convertirlo al formato .odt se le aplicará el formato cursiva a la misma palabra o si se convierte a .html se incluirán las etiquetas de cursiva de ese lenguaje para conseguir el mismo resultado.

Los ficheros de Markdown son de texto plano, un formato muy apropiado para mantener la documentación que no suele acompañar al propio código de los programas. Además, es utilizado en software de publicación web como wikis, blogs, etc. y hay editores de texto Markdown (y plugins) que nos facilitarán la tarea de escribir:

  • Linux: gedit, ReText, UberWriter
  • Windows: HippoEDIT, MarkdownPad

Editor Retext


Referencia rápida de Markdown



En adelante, "e" indica lo que se ha de escribir y "r" el resultado a obtener

- Formatos básicos, salto de línea y párrafos


Para escribir en cursiva colocaremos un asterisco o guión bajo delante y detrás del texto; para negrita serán dos y para negrita y cursiva, tres:


e: *Cursiva*
r: Cursiva

e: **Negrita**
r: Negrita

e: ***Cursiva y negrita***
r: Cursiva y negrita


Dos espacios en blanco al final de una línea fuerzan un salto de línea y una línea en blanco indica el final de un párrafo y el comienzo del siguiente.


- Enlaces externos



Para escribir enlaces en nuestros textos seguiremos la sintaxis usada en los siguientes ejemplos:

e: <http://www.correos.es>
r: http://www.correos.es

e: [Markdown](http://es.wikipedia.org/wiki/Markdown "Wikipedia")
r: Markdown

e: <nombre@gmail.com>
r: nombre@gmail.com
 
e: [Antonio](mailto:nombre@gmail.com)
r: Antonio


- Enlaces de referencia


En cualquier lugar de un texto podemos crear una lista de enlaces que pueden estar numerados o identificados por una etiqueta. Esa lista no será visible si convertimos el documento a .HTML pero se usará como índice para hacer referencia a los enlaces en cualquier lugar del documento.


e: Numerados. [Ubuntu][1] y [Firefox][2]
r: Ubuntu y Firefox

e: Etiquetas. Me gusta [Guadalinex][]
r: Me gusta Guadalinex

lista:
[1]: http://www.ubuntu.com "Ubuntu"
[2]: http://www.mozilla.org "Mozilla Firefox"
[Guadalinex]: http://www.guadalinex.org


- Citas



Una cita suele ser un texto pequeño que por su importancia queremos resaltar o diferenciarlo del resto. Para escribir una cita tendremos que dejar una línea en blanco y la comenzaremos con el carácter >. A continuación, se añadirá el texto que aparecerá sangrado por el margen izquierdo. Para una cita anidada emplearemos >>

Ejemplo de cita:

e:
> MarkDown es un lenguaje ligero de marcado de texto que permite escribir sin despegar los dedos del teclado.

r:
      MarkDown es un lenguaje ligero de marcado de texto
      que permite escribir sin despegar los dedos del teclado.


- Formato para código


Es el formato que se aplica a comandos y código fuente de programas que pueden aparecer en un documento.

Una línea de código se puede escribir entre dos acentos graves (`) o bien, anteponiendo al código cuatros espacios en blanco o un salto de tabulación:

e:`chown root:root fichero.txt`

r:
chown root:root fichero.txt

Para varias líneas tendremos que dejar cuatro espacios en blanco, un tabulador o escribir el código entre dos grupos de acentos graves (```) colocados en la línea anterior y posterior al código.

e:

```
a, b = 0, 1
while b < 1000:
     print(b)
     a , b = b, a+b
```

r:

a, b = 0, 1 
while b < 1000: 
    print(b) 
    a, b = b, a+b 


- Listas


Para escribir una lista de elementos podemos utilizar los signos *, +, - seguido de un espacio en blanco (lista de viñetas) o comenzar cada elemento de la lista con un número seguido de un punto, 1. 2. … (lista ordenada). Para escribir una lista dentro de otra dejaremos al principio de cada elemento anidado cuatro espacios o un salto de tabulación.

e:

+ Chocos fritos
+ Secreto ibérico
+ Tortilla de patatas
1. Cerveza
2. Refrescos
3. Café


r:
  • Chocos fritos
  • Secreto ibérico
  • Tortilla de patatas
  1. Cerveza
  2. Refrescos
  3. Café


- Encabezados


Con el carácter almohadilla “#” al principio o final de una línea podemos definir los encabezados de los apartados y subapartados de un documento, desde el nivel 1 “#” al nivel 6 “######”.

Cuando el documento se convierta a .odt (OpenDocument Text) o .html estas líneas tendrán asignado el estilo “Encabezado” o el tamaño de cabecera según el nivel indicado. Estos encabezados los utiliza LibreOffice/OpenOffice para generar un índice de forma automática.

e:
# Encabezado de nivel 1
## Encabezado de nivel 2

r:
Encabezado de nivel 1
Encabezado de nivel 2

Otra forma de definir los encabezados de primer y segundo nivel es “subrayando” con uno o más signos igual “=” o guiones “-” el texto de una línea.

e:
Encabezado Nivel 1
============
Encabezado Nivel 2
--------------------------------

r:
Encabezado Nivel 1
Encabezado Nivel 2


- Línea Horizontal


Para dibujar una línea horizontal escribiremos después de una línea en blanco tres o más asteriscos “*” o signos igual “=”. También, es posible incluir un espacio en blanco entre cada carácter y el siguiente.

e:
***
- - -

r:




- Imágenes


Para insertar una imagen en un documento tenemos que crear un enlace a la misma (indicando su ubicación y nombre) utilizando la siguiente sintaxis:

![Texto Alternativo](/carpeta/imagen.png|URL "Título")

El “Texto Alternativo” se mostrará si la imagen no existe en el lugar indicado. El “Título” es el texto que aparecerá sobre la imagen al pasar el ratón sobre ella, cuando el documento se haya convertido a HTML.

e:
![Papel y lápiz](markdown.png "MarkDown")

r:

- Documentación oficial


Para conocer más detalles y ampliar la información sobre la sintaxis de Markdown consultar la documentación ofrecida por John Gruber:


En el siguiente capítulo:

Después de esta breve introducción, en el siguiente capítulo estudiaremos el módulo Markdown, un desarrollo escrito en Python del lenguaje Markdown disponible para nuestros programas o para ejecutar desde la línea de comandos.