Markdown vs HTML

Cuando necesito colocar texto con formato en ZinjaI o en PSeInt uso html. Por ejemplo, en ventanas y paneles de ayuda, o en enunciados de ejercicios autocontenidos. Uso html porque wxWidgets tiene un componente propio e independiente para mostrarlo. Lo de "propio e independiente" es porque no se basa en embeber un navegador real (para eso también hay), sino que la misma wx parsea y renderiza por su cuenta. Obviamente esto limita muchísimo ese html (nada de css, nada de javascript, nada complicado), pero hace que sea mucho más liviano y me evita grandes dependencias. Hasta ahora venía escribiendo "a mano" los htmls, total el html que soporta es tan simple y limitado que es fácilmente manejable. Pero...

Pero: (a) me cansé de escribir los htmls, simple y manejable no significa necesariamente cómodo y rápido; y (b) quería independizar el contenido de su presentación. En html, para (b) tenemos css, pero ya dije que el control básico de wx no lo soporta. En wx, la alternativa para texto con formato es el típico control de texto enriquecido, pero si es para contenido solo-lectura resulta mucho más simple de usar el control de html.

Hace un tiempo descubrí "formatos" de texto plano como markdown o rst, y me parecieron geniales. Son como estándares (a veces de facto) para escribir txts de forma que se puedan leer en plano (digamos que con el block de notas) sin que el "marcado" moleste, pero que también se pueda procesar ese marcado para aplicarles formato real. Es decir, el "marcado" que se usa para indicar estilos es bastante natural e intuitivo, y muchísimo menos intrusivo que las alternativas (que latex por nombrar algo diametralmente opuesto). Markdown fue uno de los primeros formatos de este tipo en popularizarse. Una imagen vale más que mil palabras:

 A la izquierda, el "fuente" markdown (texto), a la derecha

el html generado (con una pequeña hoja de estilos adicional).

Busqué en su momento alguna biblioteca para integrar en ZinjaI y no encontré. Considerando que todo lo que tiene que hacer la biblioteca es procesamiento de cadenas, buscaba algo liviano y sin dependencias. Encontré bibliotecas monstruosas y/o en otros lenguajes que no eran C ni C++ (como python, ruby, haskell, etc). No iba a generar dependencia con ootra biblioteca más, ni mucho menos con otro lenguaje. Así que en ese momento desistí. La que más cerca estaba era una tal "sundown", pero estaba desmantenida, así que no parecía una buena inversión a futuro.

Sin embargo, recientemente descubrí que alguien tomo la posta de sundowm y comenzó a mantener un fork llamado "hoedown". Está escrita en C estándar y parece muy bien diseñada. El parseo del "fuente" markdown es independiente del formato en que se va a generar la salida. Trae un un generador html muy básico (tan básico que genera justo lo que necesito para el control de wx), soporte para plugins, y hasta parece fácil de modificar. Así que le hice un wrapper de 5 lineas para interactuar desde C++, y como primera prueba la integré en PSeInt para la generación de los enunciados en los ejercicios autocontenidos. Funciona muy bien, así que de a poco iré reemplazando todas las páginas de ayuda de ZinjaI y PSeInt por markdown.

Arriba: el nuevo enunciado con markdown. Abajo: el enunciado original con html. El editor de texto es

 kwrite, que tiene un excelente resaltado de sintaxis para markdown. ZinjaI lo tendrá cuando migre a wx 3.

Como contrapartida ante tanta simpleza, el formato de markdown soporta pocas cosas: títulos, listas, código, links, imágenes y no mucho más; las tablas por ejemplo requieren una extensión. Pero me recontra alcanza para el uso que le doy (con html no hacía más que eso). Y además puedo embeber fragmentos de html si hay algo que con markdown no puedo generar.

Así que ahora tengo una forma más cómoda y flexible de escribir las ayudas y demás documentación. Mi esperanza es que esto sirva para que la ayuda se actualice con más frecuencia, y se completen las partes que faltan. Se que casi nadie lee la ayuda, y muchas veces me preguntan cosas que ya están documentadas ahí, pero para cambiar eso necesito que la ayuda en verdad sea útil. Ya lo dijo Rich Bowen, no hay que responder las consultas "tontas" con el clásico RTFM: "si querés que los usuarios lean el fucking manual, escribí mejor el fucking manual".