Por qué prefiero rST sobre Markdown

Por qué prefiero rST

No voy a dejar de sostener esta postura

• Publiqué la nueva versión de "Logic for Programmers" v0.2. Esta versión incluye soporte para epub, resolución de restricciones y contenido sobre especificaciones formales.
• También escribí mi segundo libro, "Learn TLA+", con Sphinx. Sphinx usa un marcado particular llamado reStructured Text (rST).
• rST tiene una curva de aprendizaje más pronunciada que Markdown. Después de escribir varios libros en Markdown, sentí que necesitaba algo mejor y me cambié a rST.

Por qué rST es mejor

• Markdown es una representación ligera de HTML, mientras que rST es una representación de peso intermedio de un árbol de documento abstracto.
• Cómo crear una imagen en Markdown:

  ![alttext](example.jpg)
  

• Cómo crear una imagen en rST:

  .. image:: example.jpg
     :alt: alttext
  

• rST es extensible. Se pueden agregar nuevos objetos de texto.
• Sphinx puede manejar cross-referencing. Por ejemplo, si pones un ancla foo en un documento y :ref:image <foo>`` en otro, Sphinx inserta la URL correcta.
• rST permite estructurar el código de transformación junto con el resto del proceso de build.

Un caso de uso

• "Logic for Programmers" es un libro relacionado con matemáticas, así que necesita ejercicios para los lectores.
• Quiero colocar los ejercicios y sus soluciones uno al lado del otro en el documento, pero para los lectores las soluciones deben aparecer al final del libro.
• Para esto, escribí una extensión propia para ejercicios.

  .. in chapter.rst
  .. exercise:: Fizzbuzz
     :name: ex-fizzbuzz
     An exercise
     .. solution:: ex-fizzbuzz
        A solution
  .. in answers.rst
  .. solutionlist::
  

• En HTML, los ejercicios y las soluciones se renderizan en línea.
• En epub y latex, mediante una transformación se mueven los nodos de solución debajo de solutionlist, y se adjuntan nodos de referencia a cada ejercicio.

"Pero odio la sintaxis"

• Mucha gente opina que la sintaxis de rST es fea.
• Es entendible no querer usar una buena herramienta solo porque no te gusta la sintaxis.
• También existen otros generadores de documentos como asciidoc, MyST, Typst, Pollen y pandoc-extended markdown.
• Los generadores de documentos basados en Markdown suelen agregar su propia etapa de preprocesamiento para soportar nuevos casos de uso.
• Hay LSP y treesitter para Markdown y rST, pero no para gitbook-markdown, md-markdown o leanpub-markdown.

La próxima semana no habrá newsletter

• Voy a estar en Hong Kong.

Actualización 2024-07-31

• Agregué una breve explicación sobre "Logic for Programmers".
• El libro trata sobre cómo la lógica formal puede ser útil en la ingeniería de software cotidiana.
• Incluye una introducción básica a las matemáticas y ocho aplicaciones diferentes.
• Sigue en etapa alfa, pero ya tiene más de 20,000 palabras e incluye mucho contenido útil.

Resumen de GN⁺

• rST es una herramienta de documentación más potente que Markdown.
• Usado con Sphinx, ofrece la capacidad de transformar y extender el árbol del documento.
• Es útil para escribir libros como "Logic for Programmers".
• Mucha gente considera fea la sintaxis de rST, pero también existen otras alternativas.
• Puede ser útil para quienes estén interesados en la ingeniería de software relacionada con la lógica formal.

[GN⁺]

Opiniones de Hacker News

• La mayor ventaja de Markdown es que es fácil de leer y fácil de escribir
• Puede que Markdown no sea la mejor herramienta para escribir un libro, pero sí es ideal para redactar texto con formato rápidamente
• Usaría LaTeX para escribir un libro, y Markdown es adecuado para tomar notas, documentación rápida y escribir comentarios
• reStructuredText (reST) es algo tosco por sí solo, pero combinado con Sphinx es muy bueno
  • Sphinx es una opción adecuada para sitios de documentación grandes y profesionales
  • Sphinx permite personalizar fácilmente los elementos comunes del sitio
  • Garantiza que los enlaces internos siempre se resuelvan
  • Tiene una API de extensiones y temas bien definida
  • Existen varias extensiones y temas en PyPI
• Markdown es una representación ligera de HTML, mientras que reST es una representación de peso intermedio de un árbol de documentos abstracto
• Markdown fue diseñado para convertir texto con formato de mensajes de correo electrónico y publicaciones de Usenet
• Las herramientas de reST carecen de funciones para generar archivos RST automáticamente
• Markdown permite hacer tareas simples con rapidez y, si hace falta, insertar HTML sin procesar
• MyST permite usar sintaxis Markdown mientras ofrece las capacidades de reStructuredText
• La documentación en las páginas de proyectos de GitHub puede ser compleja, y usar Sphinx junto con Markdown puede ser útil
• El autor menciona rST en el contexto de componer tipográficamente su libro
• reST no es un competidor de MarkDown, sino un formato que apareció antes que MarkDown
• Markdown y reST tienen básicamente el mismo objetivo
• Tanto Markdown como reST son fáciles de leer y rápidos de escribir
• Markdown terminó usándose más ampliamente por razones históricas
• Markdown puede definir tipos de bloques personalizados y transformar el árbol del documento
• Jupyter Book es un buen ejemplo de cómo usar Markdown para renderizar a otros destinos, como PDF