Notxor tiene un blog

Defenestrando la vida

Estudiando org-page

Notxor
2019-08-10

Sobre org-page

Son varios los que me han preguntado por el hecho de que utilizo org-page para escribir este blog y el chismático se ha quedado sin soporte. Es decir, que el autor no va a hacerle más casito al tema y no habrá mantenimiento ni corrección de bugs, ni nada. ¿Eso asusta? A mí no (es la respuesta fácil). Pero no porque sea yo especialmente valiente o porque crea que soy mejor que otros que corren a refugiarse en otras alternativas ante el caos y el abandono. Simplemente el chismático funciona y si funciona ¿para qué cambiarlo? Ahora bien, ¿esto implica que te recomiendo la herramienta? Pues dicho así: no, pero un no con matices.

Entiendo que hay quien le teme al barbecho informático percibiéndolo como un retroceso para el uso de una herramienta. No creo yo que sea tan malo, sobre todo en un sistema que está funcionando correctamente. Y no es por no recomendarlo, pero entiendo que es un motivo para pensárselo dos veces antes de lanzarse a iniciar un proyecto con una tecnología que puede que no evolucione.

A ver si soy capaz de explicarme. Cada uno tiene derecho a utilizar el software libre que considere oportuno, pero hay que advertir que el camino no siempre es fácil. He visto quienes se desesperaban con org-page por sus peculiaridades y no terminaban de entender cómo funcionaba, quizás influenciados por los modos de otros chismáticos que generan webs estáticas. He de reconocer que, aunque al final parece que lo he dominado, me costó al principio entender cómo gestionar todo. Yo, a estas alturas, me encuentro cómodo utilizándolo y he encontrado la manera de hacerlo funcionar sin excesivo esfuerzo. Pero ¿es así en todos los casos? No, por esto no te lo recomiendo a no ser que estés dispuesto a hacer un esfuerzo que quizá otros sistemas te ahorran. Además la documentación es más bien escasa y algunas cosas no quedan demasiado claras en esa documentación.

¿Cómo funciona?

Mi intención al escribir esto es también profundizar un poco más en cómo funciona. Mi objetivo es comprenderlo suficientemente por si hiciera falta algo de mantenimiento y me tuviera que buscar las habichuelas. La última actualización de org-page fue el 7 de agosto de 2017, hace más de dos años. Todavía no me he encontrado con la necesidad de arreglar o cambiar nada, pero nunca se sabe. El chismático funciona.

Básicamente, el código fuente se apoya también en otros ficheros que componen las páginas html: las plantillas y lo formatean con css. Para actualizar el blog de forma progresiva, se apoya en git. Todas esas opciones hay que configurarlas adecuadamente para que funcione, pero como ya lo he contado en otros artículos, no voy a hacerlo de nuevo.

Ficheros

No voy a entrar en las plantillas, que al final es lo que proporciona la uniformidad visual al blog. La idea de este artículo es meterse más en el funcionamiento y por ello me quedaré en el código fuente que mueve gestiona todo. El código está distribuido en los siguientes ficheros:

  • op-enhance.el obtiene el tema configurado o utiliza el definido por defecto, mdo.
  • op-export.el comprueba los cambios en el repositorio y genera los html que formarán el sitio.
  • op-git.el gestiona todo el repositorio git.
  • op-template.el genera cada html en base a las plantillas definidas que luego utilizará op-export.el para generar el sitio.
  • op-util.el agrupa funciones útiles para el resto de módulos, como el formateo de fechas o emails.
  • op-vars.el contiene las definiciones de las constantes y variables de todo el sistema
  • org-page.el aquí está el meollo del código fuente y lo que gestiona todo el proceso mediante los comandos o funciones interactivas que se definen aquí.
  • org-page-pkg.el define el nombre del paquete, la versión y las dependencias.

Configuración

Dentro del fichero org-page.el nos encontramos una función fundamental que comprueba que todo esté configurado correctamente:

(defun op/verify-configuration ()
  "Ensure all required configuration fields are properly configured, include:
`op/repository-directory': <required>
`op/site-domain': <required>
`op/personal-disqus-shortname': <optional>
`op/personal-duoshuo-shortname': <optional>
`op/export-backend': [optional](default 'html)
`op/repository-org-branch': [optional] (but customization recommended)
`op/repository-html-branch': [optional] (but customization recommended)
`op/site-main-title': [optional] (but customization recommanded)
`op/site-sub-title': [optional] (but customization recommanded)
`op/personal-github-link': [optional] (but customization recommended)
`op/personal-google-analytics-id': [optional] (but customization recommended)
`op/theme': [optional]
`op/highlight-render': [optional](default 'js)"
...)

Las variables para una correcta configuración las encontramos ahí. Hay otras que se pueden definir, pero básicamente las necesarias son esas:

;;; Para el blog en org-mode
(require 'org-page)
(setq op/repository-directory "~/proyectos/blog-org-page/")
(setq op/site-domain "https://notxor.nueva-actitud.org")
(setq op/site-main-title "Notxor tiene un blog")
(setq op/site-sub-title "Defenestrando la vida")
(setq op/theme-root-directory "/home/notxor/proyectos/themes-org-page") ;; Temas propios
(setq op/theme (quote notxor))   ;; Ajustes personales del tema
(setq op/tag-rss t)              ;; Hacer que se creen los feed por etiquetas.
(setq op/hashover-comments t)
(setq op/personal-github-link "")
(setq op/site-preview-directory "~/public_html")
(setq op/confound-email nil)     ;; Evitar el ofuscado del email, porque lo hace mal.

Si comparamos los dos listados se puede apreciar que hay algunas variables que son fundamentales que no están en el listado que luego configuro en mi sitio. Al contrario, hay otras que el creador considera fundamentales, como op/personal-google-analytics-id, que yo no configuro (y de hecho he eliminado los enlaces al correspondiente javascript en las plantillas sin que el sistema se vea perjudicado. Además configuro el sistema de comentarios hashover.

Interacción

Pero lo fundamental del código son los comandos que se definen y que son los que el usuario termina utilizando y los que disparan todos los automatismos para generar el sitio final:

Comandos

  • op/do-publication realiza la publicación de los cambios en el repositorio git para actualizar el sitio.
  • op/new-repository inicia un repositorio y nuevo blog.
  • op/insert-options-template establece una cabecera estándar para el artículo que se está escribiendo. Normalmente no es necesario, a no ser que se quiera convertir en post un fichero org que no se ha iniciado como tal.
  • op/new-post crea una nueva entrada para el blog.
  • op/do-publication-and-preview-site además de generar el sitio con los cambios realizados levanta el servidor http para pruebas que viene con emacs.

Funciones no interactivas:

  • op/verify-configuration comprueba la configuración mínima y lanza los errores que encuentre.
  • op/generate-readme genera un fichero readme para el blog nuevo.
  • op/generate-index genera un fichero index para el blog nuevo.
  • op/generate-about genera un fichero about para el blog nuevo.

Básicamente, el usuario sólo utiliza el comando new-repository cuando inicia el blog y después, para cada actualización utilizará op/new-post y op/do-publication... y no hay nada más.

Conclusión

Un primer vistazo superficial al código fuente de org-page te da una idea de lo sencillo que es su funcionamiento. Mirando detenidamente el código he podido apreciar cierta tendencia al código choricero con funciones muy largas y no demasiado bien documentadas, por lo que espero que me costará trabajo terminar de entender qué hacen algunas de ellas.

Mi intención es mantenerme yo el código para mi uso personal. De momento, no tengo intención de iniciar un fork ni nada parecido, no me han ocurrido errores y tampoco veo que haya características que necesite de forma perentoria. Mientras el código funcione no creo que lo toque, pero si lo hago, me plantearía el hecho de publicarlo continuando con org-page, poniéndome en contacto con el creador para actualizar mediante patch y recurriendo al fork sólo en caso de que no haya más remedio para publicar los cambios.

Espero que los que me han preguntado sobre el futuro de org-page y de mi blog como usuario, hayan quedado satisfechos con la explicación de mi postura.

Categoría: emacs org-mode org-page

Comentarios

Debido a algunos ataques mailintencionados a través de la herramienta de comentarios, he decidido no proporcionar dicha opción en el Blog. Si alguien quiere comentar algo, me puede encontrar en esta cuenta de Mastodon, también en esta otra cuenta de Mastodon y en Diaspora con el nick de Notxor.

Si usas habitualmente XMPP (si no, te recomiendo que lo hagas), puedes encontrar también un pequeño grupo en el siguiente enlace: notxor-tiene-un-blog@salas.suchat.org

Disculpen las molestias.